Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

Named Services

 

Use the named services feature to define background processes for an app that other apps and JSA can communicate with in an asynchronous manner.

You can write apps that define services and REST API endpoints that other apps can interact with. JSA data that is manipulated by one app can be accessed, and represented, or reworked by another app. Information that is generated by one app can be reused by other apps to add value to the original data. Your apps are no longer restricted to working with the data that is provided by the JSA REST API alone.

The named services feature also provides developers with greater flexibility when they want to use web services frameworks. Named service processes do not need to run as part of the Flask web service that is built into the JSA application framework. You can choose to install and use a different method (for example, Node.js) to run the named service process from within the application container. The Flask process can be disabled by setting the load_flask field in your app's manifest file.

If your named service defines a process, it can also define a port through which JSA can communicate with the service. If no port is defined, then the service is treated as a headless background process that runs continuously.

Note

Named-service-endpoint URIs are not constructed by using the console IP address. The named-service-endpoint URIs display a relative path with respect to the console, for example, /console/plugins/1001/app_proxy:resourceservice/resource/{resource_id}.

How Named Services Are Defined

The services object in an app's manifest.json file is used to define a named service. Fields within the services block are used to define:

  • The service's name and version. These fields are mandatory.

  • Optional REST API endpoints for the service.

  • An optional port number to which your background processes binds internally. For example, port 80 if you are running an HTTP server.

  • A command that starts the background process.

  • Supervisord configuration options. The JSA application framework uses supervisord to monitor and control service background processes.

How Apps Communicate with a Named Service

When you install an app that is configured with a named service, the service is registered with JSA. Other apps and JSA can now make calls to the background processes.

You can add a named_service field in any of the following app object configuration blocks in your app's manifest file to use the service:

  • Area type

  • Rest method type

  • Configuration page type

  • GUI action type

  • Page script type

  • Custom column type

  • Fragments type

For an example of how the named_service field is used, see A Sample Named Service App.

If you use a JavaScript client, the first step in this process uses a JavaScript library (app/static/qjslib/qappfw.js) that is supplied in the SDK. The library queries JSA for apps that implement the named service.

For information on the JSA App Framework JavaScript library, see App Framework JavaScript Library.

After all the apps that match the named service and version are returned, the caller can decide which ones to call. Calls proxy through JSA and call the named service either directly, or via a port.

JSA uses the value in the named_service fields to locate and register the named service that an app object wants to interact with.