Local Environment

When you are done writing your extension, you can try it out by using our local runner, which is a jar file that allows you to execute the script on your local machine just as if they were running on an instance.

Execute extension locally with command:

java -jar standalone.jar <path_to_js> <path_to_type_definition> <path_to_data_definition>

This references the js file you want to test, and possibly two more files that define the data types in the system and the data values a test recipient has. These are optional, but recommended.

If they are not provided the user will have no data and all types are assumed to be strings.

Except for the js file we simply ignore files that do not exist. If you need a data file but no type file simply provide a non-existing file name for the middle parameter.

When running the extension locally, we log additional details to standard output to provide as much insight to the code as possible, and the context which you are running it in. The logger helper also writes to standard output.

Some details logged when running locally:

• Id and type of extension being run
• Environment the extension is being run on, based on the types file
• Any warnings about types not being declared for value in the data file.
• If the http mock mode is enabled, and with what
• Required fields that would be pre-loaded on an instance
• End report specifying what data has been changed to a recipient (In some extension types these are not possible)

We recommend that you make sure that there are no warnings before you put the script live.

You currently have to define your own type and data definition files, or download and modify our examples.

When logging at the printed logs anything before the “----- running ----” line are information that the standalone runner produces. It’s mainly information you should use to make sure that you configured the data correctly. The last line is the result of the execution.

Type Definition

Since the script is running locally on your machine we have no knowledge of which data fields are available and what types they have. We will therefore assume that all fields are strings to make it easy to get started, but this means that you cannot use the types. To control this you can create the type definition file. This file simply maps fields to types ensuring that we return the fields in the correct type rather than as strings.

See the below example that should cover everything. Nothing is required so “{}” could be a fully valid json to provide which means that everything will get default behaviour.

{
  "recipient": {
    "AGE": "number",
    "FIRSTNAME": "string",
    "CREATED": "date",
    "VISITED_STORES": {
      "prim": "ID",
      "ID": "number",
      "DATE": "timestamp",
      "STORE": "string"
    },
    "PURCHASE": {
      "prim": "LINE",
      "LINE": "string",
      "DATE": "timestamp",
      "PRICE": "number"
    }
  },
  "global": {
    "YEAR": "number",
    "STORES": {
      "ID": "number",
      "NAME": "string",
      "ESTABLISHED": "date"
    }
  }
}

Here you can see Person Data, One-to-Many Data, Global Data, and Global Data Table fields having types be defined.

Simple fields declare Person Data and Global Data, maps declare One To Many and Global Data.

For One-to-Many Tables, note the special field prim, which defines the name of the primary key field of the table. It is required if your code writes to One To Many tables, since we need to perform a uniqueness check on the primary field.

This does not have to declare everything you use, but note that anything not here is still simply treated as strings. Defining data types ensures your script works the same way locally as in Agillic.

Data Definition

Data definition defines the Person Data, One-to-Many Table data that your recipient has, as well as Global Data and Global Data Tables on the instance. While not required, it is highly recommended to provide as much data as possible, so that when deploying to your instance, most testing is already done with relevant data values.

Be aware that types of the values here are enforced. Dates should be strings in the format dd.MM.yyyy and timestamps in the format dd.MM.yyyy HH:mm:ss.

Beyond recipient and global data values, there are additional configuration attributes for more advanced extensions.

We log the http settings before running the script.

Example data file:

Limitations

1. No uniqueness or restriction checks for Person Data is made
2. The context is not included in the log statements
3. Caches do not persist