Skip to main content

External system services

You can use an external system service (ESS) to add custom functionality to Grexx Platform. You need to register once as a developer and then you can add as many services as you want.

You are responsible for running your own hardware and software for each ESS. The requests to your service can be done natively from any Grexx Platform environment as described below. The request is then placed on our special ESS Message Bus. You can pull requests for your ESS from the ESS Message Bus and return the response messages. These response messages will then be converted to native Grexx Platform data and the system service case will be closed.

Note:

Please note the semi-synchronous behavior of ESS execution.

ESS descriptor​

Your ESS will get its own descriptor under your namespace. For example, if you have the namespace johnsapps, you can create ESS Descriptors such as johnsapps.ibancheck, johnsapps.complexwebservice, johnsapps.anyothercoolstuff.

The second part of the descriptor (ibancheck, complexwebservice and anyothercoolstuff in these examples) is called the ESS Service Name. You can create as many ESS Descriptors as you like within your own namespace. With your credentials, you can pull for requests for any descriptor under your namespace.

The namespace and the ESS Service Name must each comply with the following regular expression: [a-zA-Z0-9]+

Architecture​

Inside the Grexxboxx​

The ESS casetype​

For each ESS that you develop, you must create a new casetype. This casetype must be of the type system service and you must enter your ESS Descriptor in the system service name field.

Any ESS must be modeled as a casetype. Each request/run of the ESS is a case. The input and output fields must be attributes in the ESS casetype. All filled attributes will be used as the input for the ESS request. All attributes can also be returned in the ESS response.

Upon receiving the response from the ESS, the data will be mapped to the casedata and the case will be closed. This gives the Studio developer the option to use any fields in the result form in mappings and to use the close event of the case to trigger other activities.

The ESS attributes​

All fields needed in the ESS (input/output fields) must be attributes on the ESS casetype. The data type of the attributes defines how the data is sent to or received from the ESS. It is your choice whether attributes are present on the start form, the result form, both, or neither. All populated attributes will be sent as input data for the ESS request and the ESS response will be mapped to the casedata without regarding any forms.

In the ESS request, the fields will be defined by the External reference of the attribute. Make sure this is populated, otherwise the attribute will not be present in the request data. Within the scope of the casetype, the external reference must be unique.

The ESS request data format​

Upon the successful start of an ESS case, the ESS request is created. The request is in JSON format and contains all the fields in the casedata that have an external reference and a non-null value. The key in the JSON is the external reference and is case sensitive.

The format of each value depends on the data type used in the attribute. For example, a multivalue attribute will result in an array value and an integer attribute will also be represented as an integer in JSON. This data object is wrapped inside another object containing some metadata that can be used. The format is as follows:

{  
 "id": "00000000-0000-0000-0000-000000000000",  
 "service": {  
 "namespace": "johnsapps",  
 "name": "ibancheck"  
 },  
 "platform": 1234,  
 "case": "1:1234:4567",  
 "data": \[  
 ...the data array...  
 \]  
}

The case ID given is the ID of the ESS case. The ID is a valid UUID which must be used together with the case ID and platform ID in the response message.

The ESS response data format​

The response should be in a very similar format to the request:

    {
      "id": "00000000-0000-0000-0000-000000000000",
      "platform": 1234,
      "case": "1:1234:4567",
      "data": [
        ...the data array...
      ]
    }

The data array​

The data object is an array of objects. Each object contains two keys: reference and values. reference contains the external reference of the attribute. values is another array containing all the values of the attribute. If the attribute is multivalue, this array could contain multiple values; if the attribute is single-value, this array contains one attribute. If the attribute is not filled, the values key may not be present. If the values key is not present in the response message, the value of the given attribute will be reset.

Response format in case of error​

You can create an error response which will be handled as an error in the Grexxboxx. Your content body should be:

{  
 "publicMessage": "Error message which will be shown in production",  
 "debugMessage": "Error message which will be shown in dev/test and sysadmin",  
  "...": "..."  
}

publicMessage and debugMessage are required. You can add any extra keys as additional context for your error message. You will be able to see those keys when retrieving the error from the sysadmin boxx.

Additionally you should send the responseType header with the value error.

Note:

The Node.js library has this functionality built in. You can use message.reject() instead of message.resolve() to return an error.

Start building your ESS​

Prerequisites:

  • You will need to know at least a little bit about Git. For more information, see https://git-scm.com/book/en/v2
  • You will need to be familiar with your chosen programming language.

To get started:

  1. Download the programming environment of your choice. We recommend using Node.js with a compatible IDE, such as Visual Studio Code. You will also need Git.
  2. Send an email to the service desk to retrieve your credentials. (WAIT)
  3. Send an email to the service desk to retrieve a GitLab project. (WAIT)
  4. Check the example in the Grexx ESS library of your choice, for example https://www.npmjs.com/package/grexxconnect-ess.
  5. Fill in the necessary methods and your credentials.
  6. Run it!

From your Studio:

  1. Create a new system service casetype using the namespace that you received from the service desk.
  2. Configure the start form and result form with the correct attribute fields. Make sure your attributes have external references.
  3. Compile and execute this casetype. You will see the request coming in on your local ESS instance.

If the ESS is doing what you expect, you can deploy it:

  1. Push the code to your GitLab project.
  2. Make sure you have enough test coverage to pass your pipelines in GitLab.
  3. Once you pass the pipelines, a Docker container is built automatically.
  4. Inform the service desk or devops that your container should be deployed. (WAIT)

Connecting the two: the ESS message bus​

For NodeJS​

See the documentation and use this package: https://www.npmjs.com/package/grexxconnect-ess

For Python​

See the documentation and use this package: https://pypi.org/project/grexxconnect-ess/

For Java​

We have ported the connector to Java but it's not available (yet) via a maven repository. Contact the dev team for more information.

Registering a namespace and retrieving credentials​

For credentials contact the service desk at [email protected]

Future plans​

  • Make it possible to give a response in two steps: first a receipt confirmation and secondly the response itself. This allows for async ESS handling without the (currently) required timeout of 30 secs in the user process.
  • Use service discovery to auto-suggest ESS names and namespaces in the studio.