Description of what service are and how to use them to connect with external apps.

Services are components that run along with your app. They have their own resources and the main purpose is to extend the features of the platform.

The most common use case is to connect your app with other apps by sending, receiving and fetching data using their APIs. For example, you can have a service to send and receive http requests or to generate PDF files

Services configuration

All services share some settings, however each service will have additional settings. You should check their documentation to know what they mean.

Here we will describe common settings.

Label

This is the human-readable name of the service. It doesn’t have any usage during the execution of the app.

Name

This is the internal name of the service and it will be used in the Javascript API.

The name cannot contain special characters or spaces. Only letters and numbers.

One thing to keep in mind is that changing the name of the service could have some side effects in scripts that were referencing the service. For example if the name was http and it is changed to something like httpNew, you might need to change calls like svc.http.* to svc.httpNew.*. In the near feature we will provide some tools to help on these cases, but for know it must be done manually.

Instance type

The http service has 2 instance types. It can be dedicated or shared. If shared, you don need to configure the deployments properties of the service. A platform component will be used. For the case of the dedicated one specific component will be deployed for the exclusive usage of the app. This option will have extra costs.

Initial status

This is the initial status of the service when it is pushed or synced for the first time. This means it only has effect the first time. Once the service is pushed or synced, the status it has will be kept and you should change it from the app monitor.

This flag is specially useful when you build template apps that will be cloned, but you don’t want services to be deployed until they are configured. This way the initial status can be set to Undeployed and it won’t be active until it is configured and deployed.

Service properties

For all configured services we have some properties that can be useful in some scenarios for developers. These properties are allocated on the svc.<serviceName> namespace where serviceName is the name of the service. Some of them are service-specific but there are also a couple of generic properties. These generic properties are:

_name

This is the internal name of the service and it will be used in the Javascript API.

_configuration

Here we will find a JSON representation for the service-specific configuration.

_token

This is the token used to validate messages between the service and the platform.

For example if you have an service called fullcontact you can see all the properties like this:

sys.logs.info(JSON.stringify(svc.fullcontact));

Or having an service called ftp you can print the _token:

sys.logs.info(svc.ftp._token);

Services usage

Functions

Service functions can be called from any script. They are under the namespace svc.<serviceName> where serviceName is the name of the service. For example if an service with name pdfGenerator provides a function called generatePdf() it can be called from any script using svc.pdfGenerator.generatePdf().

For example this is a get request using the http service:

const resquest = 'https://www.slingr.io/';
var response = svc.http.get({url:request});
log(JSON.stringify("Response: " + response));

If there are errors during the execution of the function, an exception will be thrown. By default the exception will stop the execution of the script and the error will be logged, but you can handle it if you want:

You should check each service’s documentation to see which functions are available.

Callbacks

There are some functions that provides callbacks that allow to receive an async response easily. For example when generating a pdf file through a pdf generator you can put a callback to do something when the img is returned:

 
try {
  let userName = sys.context.getCurrentUserRecord().label();
  let callbackData = {company: record, currentUserEmail: sys.context.getCurrentUserRecord().field('email').val()};
  let response = svc.pdf.generatePdf({}, callbackData, {
    responseArrived: function(event, data) {
      // event data
      sys.logs.info('Response arrived:');
      sys.logs.info('event: '+JSON.stringify(event));
      // callback data
      sys.logs.info('Record ID: '+data.company.id());
      sys.logs.info('User email: '+data.currentUserEmail);
    }
  }); 
  sys.logs.info("Pdf response: "+JSON.stringify(response));
} catch(e) {
   sys.logs.error('Error when try to generate a pdf file: '+sys.exceptions.getMessage(e));
}

When callbacks are allowed, two parameters are available at the end:

  • callbackData: this is an object you can send that you will get back when the callback is processed. This is important because in the function that processes the callback you won’t have access to any variable outside the function. For example in the code above you won’t be able to reference the variable userName because it is outside the callback function. The reason for this is that as the callback is async the context is lost, which is different from regular Javascript code, so keep that in mind.
  • callbacks: this is a map where you can listener for different callbacks. The example above only listens to the responseArrived callback, but the Mandrill service can send more callbacks based on different events. Functions in this callback have two parameters:
    • event: this is the event information which is exactly the same as the event available in listeners. Please check the docs for service listeners.
    • data: this is the callback data that was sent when the function was called.

You should check each service’s documentation to see which are the available callbacks for each function.

Events

Events indicates that something happened in the service or external app that must be notified. It could be generated by the external app itself or the service might detect something and send an event to the app. For example, it could be that a message was sent to a channel in Slack or the FTP service detected that there is a new file in the folder it is watching.

Events can be handled trough service listeners. Each service provides its own events, so you should check their documentation.

Back to top