XTK Jobs (xkt:job, xkt:jobInterface)

This section describes how long running jobs are handled in ACC and ACC api. There are 2 schemas for jobs

• xtk:job which represents an acutal job, and which is implemented by several objects such as nms:delivery
• xtk:jobInterface which contains methods to submit jobs and get their statuses. Other schemas do not actually implement the xtk:jobInterface interface

In term of SOAP calls, running a job is simply executing a SOAP call synchronously or asynchronously in a separate thread or process. However, calls must be made on both the xtk:jobInterface and job entity schema. The SDK provides a helper interface to submit and handle jobs

Simple Jobs

Simple jobs are non-static methods with no parameters, such as the nms:delivery#Prepare method which is used to prepare a delivery. Such jobs can be executed synchronously (xtk:jobInterface#Execute) or asynchronously (xtk:jobInterface#Submit). Both methods return a job id which can be used to retreive (poll) more about the job.

First, we need to retreive a delivery, which is the object upon which to run the Prepare method, but also implements xtk:job interface. The Prepare method requires a complete delivery object, so we use SelectAll

  const  queryDef = {
    schema: "nms:delivery",
    operation: "get",
    select: { node: [ { expr: "@id" } ] },
    where: { condition: [ { expr:`@internalName='DM19'` } ] }
  }
  const  query = NLWS.xtkQueryDef.create(queryDef);
  await query.selectAll();
  const delivery = await query.executeQuery();

Now we can create a job for the Prepare method using the client.jobInterface function which returns a XtkJobInterface object. We pass it a job specification containing the schema, method, and object

  const job = await client.jobInterface({
    xtkschema: 'nms:delivery',
    method: 'Prepare',
    object: delivery
  });

Finally we can submit the job and get it's status, progress, result, etc.

  await job.submit();
  var status = await job.getStatus();

Soap calls

The SubmitSoapCall method allows to run more complex jobs with parameters. The principle is the same, for instance calling the PrepareProof method which takes a boolean parameter

  const job = await client.jobInterface({
    xtkschema: 'nms:delivery',
    method: 'PrepareProof',
    object: delivery,
    args: [ false ]
  });

Job Status

The status of a job is made of 3 pieces of information

• The job status code
• Job logs
• Job properties which are arbitrary key value pairs and also contain progress information

For convenience, the SDK provides a getStatus function which will fetch and return the full job status object with strong typing. When getStatus is called several time, each call will fetch the most recent status, and new logs since the previous call.

Status code	Description
0	Being edited
2	Running: execution is in progress
3	Canceling: a cancel request was submitted and the job will be canceld as soon as possible
4	Canceled
5	Finished: the job has finished successfully and getResult can be called
6	Error: the job failed. Details about the error can be found in the logs
7	Pause pending: a pause request was submitted and the job will be paused as soon as possible
8	Pause: the job is paused
9	Purge pending: a purge request was submitted and the job will be purged as soon as possible

You can get the status of a job, given a job id as follow

  const jobId = 'ABC';
  const job = new XtkJobInterface(client, { jobId });
  const status = await job.getStatus(12, 500);

Job Progress

The progress of a job is available as 2 integers: current and max which represent the current progression and max value for progression. Both values are returned by the getStatus call as properties (i.e. properties.progress.current and properties.progress.max). The SDK provides the getProgress function to retreive the progress as a percentage (and a valid number)

  // Returns progress as a percentage in the [0..1] range
  var progressPercent = job.getProgress();

Job Result

Typically, a client would call the getStatus method every few seconds to get updates on the progress. When a job is finished and successfull, one can get the result using the getResult function

  var result = await job.getResult();

Jobs & Static methods

Version 1.1.41 and above support submitting jobs on static methods.

• Set the jobId parameter with the entity primary key. In the example below, the jobId is the id of the webApp to publish
• Do not pass an object parameter. The method is static, there's no object.

  const job = await client.jobInterface({
    xtkschema: 'nms:webApp',
    jobId: 9876,
    method: 'Publish',
    args: [
      { where: { condition: { expr: "@id=9876" } } },
      { type: "byte", value: "10" }
    ]
  });

  const jobId = await job.submitSoapCall();