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

Packages are a simple way to import a set of metadata into your app. The main purpose is to facilitate the implementations of functionalities that could be predefined, saving a lot of time to the developers.

The most common cases are to import utils libraries to perform common operations or to connect your app with other apps by sending, receiving and fetching data using their APIs. Packages will contain all the logic necessary for using a http service and consume those external APIs. For example there are packages for Slack, Google Contacts, Google Calendar and other popular cloud services so your app can easily take advantage of the features offered by those apps.

Packages installation and management

Available packages for the application are shown in a section called marketplace . From there the package README.md can be read and the package installed. Once the package is installed, you can check if there are new versions of it and update it.

Packages configuration

All packages share some settings, however each package 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 package. It doesn’t have any usage during the execution of the app.

Name

This is the internal name of the package 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 package could have some side effects in scripts that were referencing the package. For example if the name was slack and it is changed to something like slackmaster, you might need to change calls like pkg.slack.* to pkg.slackmaster.*. In the near feature we will provide some tools to help on these cases, but for know it must be done manually.

Version

This is the current version of the package.

Upgrade policies

This is the expected behaviour of the package when the package versions are updated. Version have this format X.Y.Z. Available options are :

  • Compatible version: will show updates when the Y or Z values are updated
  • Bug fixes: will show updates when the Z value is updated
  • Manual: updates won’t be shown on new versions
  • Latest: will show updates on any update

Package-specific configuration

Apart from the common settings you should check each package’s documentation to see which are the settings that can be configured. These settings are usually credentials and some configurations to determine the behavior of the package.

Packages may be environment-dependent, so you should try to use environment variables to configure things like credentials in order to use different accounts for production and development.

Package dependencies configuration

Packages that have services dependencies, require to select a service instance to be used by the package. This selected service will be the target of imported listeners too.

Secure packages-specific configuration

It is highly recommended to use environment variables to store sensitive information like passwords, keys, etc. Then a specific configuration property can point to an environment variable. Please refer to Environment variables for more information.

Data store

Sometimes a package will need to generate and store information in the runtime. For example, if we are using the Git hub package, when the user authenticates we need to store the credentials and store them somewhere in a secure way. For this, the package will store the information encrypted in the app storage.

Packages usage

When a package is added it will provide some new features related to the app:

  • Script libraries: these functions can be called from any script. These functions belongs to the script libraries imported by the package.
  • Events: these are events triggered by the package that can be processed through Package listeners. This way when you create a listener for packages you will see the package and its events so you can process them.
  • Listeners: these listeners may be useful to listen to some events, process them and do something like triggering a package event. Something typical would be to have a listener to process webhooks that arrive to a http service validate it, format the content and then trigger the package event related to the webhook.
  • Ui services: these ui services provide useful functionality client side, for example, to allow oauth 2.0 connections to an external service from the app runtime.
  • Flow steps: These flow steps can be used in any flow of the application.

All these elements can be explored in the metadata tree of the builder in the packages section.

Script libraries

Package libraries can be called from any script. They are under the namespace pkg.<packageName> where packageName is the name of the package. For example if an package with name slack provides a library called messages, a function sendMessage() can be called from any script using pkg.slack.messages.sendMessage().

For example this is a call to send a message using the Slack endpoint:

const msg = action.field('message').val();
pkg.slack.messages.sendMessage({channel: '#test', message: msg});

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:

const msg = action.field('message').val();
try {
  pkg.slack.messages.sendMessage({channel: '#test', message: msg});
} catch (e) {
  sys.logs.warn('There was a problem sending a message through Slack: '+sys.exceptions.getMessage(e));
}
// execution will continue even if the message to Slack couldn't be sent

You should check each package’s documentation to see which libraries and functions are available.

Back to top