Configure jobs

The developer platform allows your app to handle tasks that may take a longer time to complete by using jobs. In scenarios involving bulk actions, such as data import, export, or batch processing, implementing a job in your app can help streamline the process.

This app can perform tasks with longer runtimes upto 2 minutes. In this approach, the task is executed asynchronously, and the response returns only a status indicating the current state of the task.

To configure a job in your app, you need to define and invoke a job object.

This section explains how to:

For a demonstration of this feature, see our collection of sample apps with the jobs.

Job object

The job object consists of details related to the job. A job object is an instance of a job you define in manifest.json. Whenever you want to perform a long-running task, invoke the defined job.

  • idstring

    Identifier of the job object, generated when the job is invoked.

  • namestring

    Name of the job defined in the manifest.json.

  • tagstring

    Term or phrase related to the job provided by the user that can be used while retrieving a job’s history.

  • start_timeinteger

    Timestamp of when the job was started, specified in the unix timestamp format.

  • end_timeinteger

    Timestamp of when the job ended, specified in the unix timestamp format.

    Note: The end_time attribute is present only if the status value is success, failed, or timeout.

  • statusstring

    Current status of the job.

    Possible values: pending, in-progress, success, failed, timeout

  • status_messagestring

    Status message of the job, describing the progress of the task.

Define job

In the manifest.json file, define a job as an empty object with a unique name.

Note:

The following are the limitations and norms for defining a job name.

  • Since the job name is case-sensitive, while calling for the job in interfaces, ensure the name is in the same case as defined in the manifest.json.
  • The job name can be alphanumeric and may include the underscore (_) special character.
  • Avoid starting the job name with a number.
  • Ensure the job name does not contain spaces between characters.
  • The name should be between 2 and 40 characters in length.

Invoke a job

To invoke a job, use the client.job.invoke interface. Ensure that you invoke a job using the job name defined in the manifest.json. You can associate a tag name with the particular instance of the job by passing the tag value as a part of the client.job.invoke method.

Additionally, you can use the options field to pass payloads, if required. Due to storage limitations of options payloads, with the maximum storage being 100 KB, you can use object store for larger storage. Upload the file with payloads, using upload method and retrieve the file while invoking a job to process the higher number of payloads.

Front-end or client-side file
client.job.invoke('bulkTicket', "tag", options) 

Options:
{
   // Developer method params | payload
}
Notes:

While defining the tag name for the job, adhere to the following limitations and norms.

  • The tag name should be case-sensitive.
  • It can be alphanumeric and may include the special characters underscore ( _ ) and hyphen ( - ).
  • Ensure the tag name does not contain any spaces between characters.
  • The tag name should be between 2 to 50 characters in length.

Retrieve a job

To fetch the details of a specific job use the client.job.get method, which returns the job object in response.

Front-end or client-side file
client.job.get('1PFgHsXkjJtPfU94zB8aQxKLmAa')
Notes:
  • The rate limit is 50 requests per minute and can be extended if required.
  • The end_time attribute is included in the response only if the job has either successfully completed or failed.

Retrieve a list of jobs

To retrieve the list of jobs, use the client.job.history method. To filter the jobs returned in the response, you can use the following parameters in the options object.

Front-end or client-side file
client.job.history(options)

options:
{
  "tag": "first_quarter",
  "page": 2,
  "limit": 10
}

options object parameters

ParametersDescription
tagTerm or phrase given by the developer in the tag field while invoking the job.
pagePage of the list of jobs to be retrieved.

limit

Number of job objects to be retrieved.

Note: The maximum value for the limit attribute is 20 per page.

Note:The rate limit is 50 requests per minute, and it can be extended if required.

Update the status message of a job

To update the status message of a job, use the $.job.updateStatusMessage method. This method helps you set a custom status message reflecting the current progress of the job instance.

Server.js file
$job.updateStatusMessage("message")
Notes:
  • The status is "in-progress" when the app calls the $.job.updateStatusMessage method.
  • The rate limit is 50 requests per minute, and it can be extended, if required.
  • Ensure that the status message does not exceed 500 characters to avoid any part of message getting cut off.

Once the $.job.updateStatusMessage method is processed successfully, a 200 status code is returned.