Basic Usage of the Execution Context API

Some basic usage of the API are shown below.

Accessing Input Data

To access the source object id in case the Job is triggered by an event.

const sourceId = context.jobRequestMessage().sourceEvent().objectId();

Access input parameter, in case the Job is triggered via a REST call or a Scheduled Task.

const value = context.input().firstParam("name-of-param")
// or
const valueAsList = context.input().param("name-of-param")

Access input header in case the Job is triggered via a REST call.

const value = context.input().firstHeader("name-of-header")
// or
const valueAsList = context.input().header("name-of-header")

Get input data if available (in case triggered via REST call)

const data = context.input().data().contentAsString();

Environment

Environment variables can be declared in the Administration UI as shown below:

Figure 1. Environment Variables

From the code environment variables can be accessed via:

const foo = context.environment().get('foo');

Note that one environment variable may depend on other environment variables, by using macros. The value is resolved on retrieval.

Configuration Properties

Configurations can also be associated with meta-data in the form of key/value pairs.

See image below how to access these:

To get a property from the Configuration, see the example below:

const foo = context.property('foo')

If there is no property set with the given name, the API will check for an environment variable with the same name.

Calling the 3DEXPERIENCE™ API

The 3DEXPERIENCE™ REST API is provided via the context object as shown below:

const dsAPI = context.dsxAPI();

To be able to use the 3DX REST API, you will from the API get the service to be used. For example, the 3D-Space service.

Once you have the service, you can claim the tenant session object for the service. All of this requires that you have configured an Agent on the current Event/REST mapping or Scheduled Task.

The tenant session object is used whenever a remote call is made against the 3DX platform.

Code example:

const dsAPI = context.dsxAPI();
const spaceService = dsAPI.getSpaceService();
const session = dsAPI.getTenantSession(spaceService);

Per default, the session will be initialized with the Security Context as defined on the Event/REST mapping or Scheduled Task. If that is undefined, the API will try to fetch a default security context. However, note that this may not be reliable as it may vary over time, thus, in such case you should manually set the security context on the session object like shown below:

const session = dsAPI.getTenantSession(spaceService);
session.setSecurityContext('VPLMProjectLeader.Company Name.My Collab Space');

Please go to this page to read more about the usage of the 3DEXPERIENCE™ REST API.

Execution Result

You can mark the job as failed in two ways.

Throw an exception from the executing code
Set the failed flag on the "result" object

For the latter, see the example below:

// Set result of job execution
context.result()
  .failed(true)
  .code(123)
  .message('Remote system not responding')
  .detailedMessage('........ some more details ............')

Along with the result, you can store the following properties

code: An integer value representing the result of the execution. Typically 0 is used for successful jobs and 1 for failures. Other result codes can be used to describe the result better, and could be used for filtering or similar
message: A shorter string describing the problem briefly
detailedMessage: Details around the result. For example, it could contain the error message as received from the remote system.

If the configuration does not set a result-code, then the code might be set to the following pre-defined result codes:

0: Successful execution
1: Failed execution
800: Syntax errors
820: Configuration not found
840: Resolving input failed
850: Unexpected error
860: Current extension is not properly configured
900: Bad request / input
999: Job was cancelled (and no other exit code was set)

If the script neither throws an exception nor sets the failed flag to true, the execution is treated as being a successful execution.

To force the script to exit/terminate directly without processing anything further in the script, you can call context.exit().

Remember to store the status of the execution on the result object prior to calling exit.

Fail and Resolve

In case a job is failing, the executing logic may in some cases determine the reason automatically. In such cases, the code can also set the resolved flag with the resolution as part of the execution.

The API to use for this is shown below:

context.result()
    .failed(true)
    .code(503)
    .markResolved(true, 'The remote system is not reachable!');

Store Output

To store output from a job execution, you can do this in two different ways.

The easiest way to store string-based data is to do:

context.result().data('<foo><bar>test</bar></foo>', 'application/xml')

Or like below for JSON:

const json = JSON.stringify({result: 'Succeeded', status: 'Engineering item updated'});
context.result().data(json, "application/json");

You can also use the "Data Storage API" from the "context" object.

const storageAPI = context.dataStorage();

storageAPI.store(storageAPI.newStringDataBuilder()
          .data(json)
          .contentType('application/json')
          .name('result.json')
          .dataType('OUTBOUND').build());

The "Data Storage API" offers some more control over how you can store (and also load / access) data.

Under the hood, the API available on the "result" object uses the Data Storage API.

You can also store binary data using this API, please consult the API docs for all details.

JSON in JavaScript

Parse JSON string into JS object:

const data = context.input().data();
const obj = JSON.parse(data.contentAsString());
const productDescription = obj.something.results[0].ProductDescription;

Serialize object into JSON string:

const json = JSON.stringify({
    result: 'Succeeded',
    status: 'Engineering item updated'
});