Scripted system services

You can use a scripted system service (SSS) to add custom functionality to your application by writing your own scripts. For example, if you want to use a third-party library to manipulate data or generate unique identifiers, you can write a script that calls these utilities.

You can also share your scripted system service with others by adding it to Grexx Marketplace. Unlike external system services, you can build a scripted system service entirely from your Studio.

Tip:

Creating a scripted system service requires high-code programming skills. You will need to be familiar with JavaScript and Node.JS.

Create a scripted system service

To create a new scripted system service, add a new casetype to your Studio and set the Type to Scripted. Then, add your code to the Code tab.

• Your code must include a root level function named run. When the system service is initiated (by creating a new system service case), Grexx Platform calls the run function.
• The run function expects a dictionary of input parameters and returns a dictionary of output parameters. These are defined by creating attributes and adding them to the start and result forms, as described below.
• To fetch data from a case, dataset, form, or task, or to perform an activity from your scripted system service, use the Grexx Platform JavaScript library to call the Grexx API. To view the documentation, append docs/api/js to the URL of any of your application environments (for example, https://my-site-dev.grexx.today/docs/api/js). Note that you must grant the scripted system service rights to those objects as described below.
• You can add any dependencies that your system service relies on to the Dependencies tab in package.json format. For security reasons, postinstall scripts are disabled. Dependencies requiring specific build steps may not run correctly.

Tip:

Scripted system services currently support Node.js v22 (v22.14.0 LTS) with npm v10.9.2.

Configure attributes and forms

Add attributes to the casetype to define both the input values required to run the system service, and the output values returned by the system service. Each attribute defines the data type for the input or output value. For more information, see Attributes.

You must specify an external reference for each attribute (from Edit attribute > Advanced) that corresponds to the input and output parameters in your code.

Add the attributes that define the inputs to your system service to the Start form, and the attributes that define the outputs to the Result form. You will use these forms when running the system service.

Tip:

The attributes that you have added to the forms are displayed as input and output parameters (using the attribute's external reference) on the Code tab.

Add test cases

To verify that your scripted system service works as intended, you can add automated tests to the Test cases tab. For example, you can use test cases to verify the behavior of a function by checking that it returns the correct values (the "happy path"), and to verify that custom errors are returned as expected.

To create a test, specify the input value(s) and the output that should be returned if the system service is behaving as intended. Note that it is not currently possible to specify a thrown error as an expected output. If a test case throws an error, the test will fail and the error will be shown in the actual output.

To run your test cases for your system service, open the Test cases tab and click Run tests. You can also run individual test cases using the "run" icon in the grid. Select a test to view the actual output and the logs.

Configure API rights

If your scripted system service makes calls to the Grexx API, you need to grant the system service rights to access any datasets, forms, and activities that it uses. Open the Rights tab and enable Enable restful API access. You can then select the relevant datasets, forms, and activities.

Note that although this grants the scripted system service rights on the selected elements, the system service is not listed on the Rights tab of the corresponding dataset, form, or activity.

Configure view rights

Unlike other types of casetype, you cannot add direct or indirect roles to a scripted system service. This is because scripted system services are designed to be called by another case (using a casetype activity as described below) and the system service case is closed as soon as the process is complete. As a result, your application users interact with a scripted system service case entirely via the parent case.

You can specify the platform roles that have permission to view the details of a system service case from the Rights tab. This is useful for users that need to be able to debug issues with the scripted system service when your application is running in a DTAP environment.

Use a scripted system service

To use a scripted system service in your application. Identify the casetype from which you want to call the system service (such as your application's homepage or a standard casetype such as Employee or Order) and add a casetype activity to it. Use mappings to populate the fields on the system service's Start form by setting the mapping To type to Task in and selecting the relevant Start form field. You may also want to add a trigger to execute or execute and submit the casetype activity.

When the activity is submitted (either manually by a user or automatically), the system service is invoked with the input values provided on the start form. Once the system service code has been executed, the output values are added to the Result form and the system service case is closed.

You can access the values from the Result form by adding mappings to the When done stage of the casetype activity. Set the mapping From type to Task out and then select the relevant Result form field.

For more information about configuring casetype activities, see Add cases. For more information about closing cases and using the values from a result form, see Close cases.

View logs

You can view the logs from running your scripted system service in any of your DTAP environments:

• From the casetype view for the scripted system service. Note that this view is not configurable and is only visible to users in a platform role that has been granted View rights on the scripted system service, as described above.
• From Developer Tools. For more information see, Debug your application.

Example scripted system service

The following code is for a scripted system service that uses the Lodash library to manipulate strings. The library has been added as a dependency using the import name _.

function run(params) {
    const text = params.text || "No input text supplied";
    switch(params.type) {
        case "camelCase":
            // Note that lodash is automatically imported as _ (see "Import names")
            return {result: _.camelCase(text)};
            break;
        case "kebabCase":
            return {result: _.kebabCase(text)};
            break;
        case "reverseCharacters":
            return {result: text.split("").reverse().join("")};
            break;
        case "titleCase":
            // You can return custom errors. This works in the same way as custom errors in an activity.
            // errorDebugMessage is shown in Dev and Test environments. ErrorPublicMessage is shown in Acceptance and Production environments.
            return {
                "isError": true,
                "errorDebugMessage":"The service could not handle the request because title case has not been implemented.",
                "errorPublicMessage":"The service could not handle the request.",
            };
            break;
        default:
            // When you throw an error, the error will be deferred back to Grexx Platform.
            throw new Error("The type of casing you requested does not exist.");
            break;
    }
}

This scripted system service requires the following attributes:

• text of type string. This attribute should be included on the Start form.
• type of type string. This attribute should be included on the Start form.
• result of type string. This attribute should be included on the Result form.

You could add test cases for this scripted system service, such as:

Input	Expected output
{"text":"convert-to-camel-case","type":"camelCase"}	{"result":"convertToCamelCase"}
{"text":"shouldBeHyphenated","type":"kebabCase"}	{"result":"should-be-hyphenated"}
{"text":"capitalize this string","type":"titleCase"}	{"errorDebugMessage":"The service could not handle the request because title case has not been implemented.","isError":true,"errorPublicMessage":"The service could not handle the request."}