JobQueue

The global JobQueue variable returns functions relating to job queues.

allQueues

Returns an array of available job queues.

var queues = JobQueue.allQueues;

if (queues.length > 0)
  Debug.showDialog(queues.length + " queues open. First one is " + queues[0].name);

byName

This method returns the job queue with the given name (if it exists). If no such queue exists, it will throw an error.

var queue = JobQueue.byName("myQueue");

Debug.showDialog("Queue " + queue.name + " has " + queue.allJobs().length + " jobs.");

The job queue object

The above methods return one or more job queue objects. These can be interacted with in the following ways.

allJobs

The allJobs function returns an array of incomplete jobs currently in the queue.

var queue = JobQueue.byName("myQueue");
Debug.showDialog("Queue " + queue.name + " has " + queue.allJobs().length + " unfinished jobs.");

enabled

This is a boolean property indicating whether the queue is currently enabled. Queues are enabled and disabled from Cuesta. No jobs can be claimed from a disabled queue.

var enabledQueues = JobQueue.allQueues.filter(function(q) { return q.enabled; });
Debug.showDialog(enabledQueues.length + " enabled queues.");

name

The name property returns the name of the queue.

var firstQueue = JobQueue.allQueues[0];
Debug.showDialog("The first queue is " + firstQueue.name);

addJob

This method pushes a new job onto the queue.

var queue = JobQueue.byName("myQueue");
queue.addJob({ topic: "some-topic", payload: { numbers: [23, 34, 45] } });

The available properties of the job object are:

• topic the topic of the job. Manatees can claim jobs by topic. Default is null
• priority the priority of the job (default is 100). Numerically lower values represent higher priority. Default is 100.
• payload an optional value (of any type) to be passed to the Manatee that claims the job. Default is null
• note a note to attach to the job. This is optional.
• name a name for the job.

claimJob

This method claims a job from the queue. It will block until a job is available or until the timeout elapses. After successfully claiming a job, a ‘job run’ is created and can be seen in Cuesta.

If a job cannot be claimed within the timeout, an error is thrown.

var queue = JobQueue.byName("myQueue");
var job = queue.claimJob();
var result = myJobExecutionLogic(job.payload);
job.complete(result);

// or

var emailJob = queue.claimJob({ topic: 'emailsToSend', timeoutSeconds: 120 });
sendTheEmail(emailJob.payload);
emailJob.complete();

// or

var job = queue.claimJob({ minPriority: 10, maxPriority: 20 });

The available properties of the claim options object are:

• topic the topic of the job to claim. Default is null (any topic)
• timeoutSeconds the number of seconds to wait for a job to be available before timing out and throwing an error. Default is 30 seconds.
• autoRelease a boolean value indicating whether the job should be released automatically when the flow completes. Default is false. When set to true, the last claimed job will be automatically set to completed when the flow completes normally and to failed if an unhandled exception is thrown.
• pollIntervalMs the number of milliseconds to wait between polling the queue for a job. Default is 5000 (5 seconds).
• minPriority the minimum numerical priority of the job to claim. Default is ‘no limit’.
• maxPriority the maximum numerical priority of the job to claim. Default is ‘no limit’.

allClaimed

This function returns an array of all jobs that have been claimed from the queue by this Manatee (identified by user and host). The resulting array is sorted by priority.

var queue = JobQueue.byName("myQueue");
Debug.showDialog("I have claimed " + queue.allClaimed().length + " jobs ready for processing");

The job object

Job objects are returned by the queue.claimJob() and queue.allJobs() functions. They can be interacted with in the following ways.

complete

This method marks the job as successfully completed and attaches the given result to the job (if any).

var queue = JobQueue.byName("myQueue");
var job = queue.claimJob();
var result = myJobExecutionLogic(job.payload);
job.complete(result, 'Nothing went wrong');

The arguments to this method are:

• result the result of the job execution (any javascript value can be passed). This is optional.
• message a message to attach to the job run. This is optional.

fail

This method marks the job as failed and attaches the given error to the job (if any).

var queue = JobQueue.byName("myQueue");
var job = queue.claimJob();
try {
  job.complete(thisVariableIsNull.result); // Throws a null reference exception before the method can be called
} catch (e) {
  job.fail(e.stack);
}

isClaimed

This property returns the current claim status of the job (true/false).

var queue = JobQueue.byName("myQueue");
var claimedJob = _.find(queue.allJobs(), function(j) { return j.isClaimed; });
Debug.showDialog("A job is currently " + (claimedJob ? "claimed" : "not claimed"));

id

This property returns the id of the job.

var queue = JobQueue.byName("myQueue");
var claimedJob = queue.claimJob();
Debug.showDialog("The currently claimed job has id " + claimedJob.id);

topic

This property returns the topic of the job.

var queue = JobQueue.byName("myQueue");
var claimedJob = queue.claimJob({ topic: 'emailsToSend' });
Debug.showDialog("The currently claimed job has topic " + claimedJob.topic);

priority

This property returns the priority of the job.

var queue = JobQueue.byName("myQueue");
var claimedJob = queue.claimJob({ priority: 100 });
Debug.showDialog("The currently claimed job has priority " + claimedJob.priority);

payload

This property returns the payload of the job. It is the javascript value that was passed to the job when it was created.

var queue = JobQueue.byName("myQueue");
var claimedJob = queue.claimJob();
Debug.showDialog("The currently claimed job has payload " + JSON.stringify(claimedJob.payload));

enabled

This property returns the enabled status of the job. When a job is set to disabled in Cuesta, this property will return false.

Only enabled jobs can be claimed.

var queue = JobQueue.byName("myQueue");
var disabledJobs = queue.allJobs().filter(function(j) { return !j.enabled; });
Debug.showDialog(disabledJobs.length + " disabled jobs.");

delete

This function deletes the job from the queue.

var queue = JobQueue.byName("myQueue");
var job = _.first(queue.allJobs());
if (job) job.delete();

Background tasks

Beware that the job queue api cannot be used from a background task. The following example shows such illegal use

var t = Task.run(function() {
    // NOTE: This will throw an error!
    var queue = JobQueue.byName("myQueue");
    var job = queue.claimJob();
    if (job) {
        job.complete();
    }
});

t.wait(1000);