Skip to content


Subversion checkout URL

You can clone with
Download ZIP

Create Jobs

Thanasis Polychronakis edited this page · 6 revisions

kickq.create( jobName, optData, optOptions, optCallback )

The kickq.create() method requires an argument, the jobName a string and accepts 3 optional arguments. It returns a Promise/A+ compatible Object (The When.js library is used).

The Arguments

Arg0 :: jobName

Type: string Default: Required!

The Job Name will effectively create a queue where all the created jobs line up. The Job Name will be used to create keys in redis and files in logs, spaces are ok, be sensible about the value of this argument.

Arg1 :: optData

Type: * Default: null

Any type of arbitrary information can be passed on each new job that is created. The optData argument can by of any type that can survive JSON serialization.

Arg2 :: optOptions

Type: Object Default: null

A key/value Object literal containing Job specific options. All the available configuration options can be found in the Configuring Kickq page. All Job related configuration options can be edited either using the kickq.config() method or directly on each job creation.

Arg3 :: optCallback

Type: Function(err, jobItem) Default: null

An optional callback when the operation finishes. The callback gets invoked with two arguments, err and jobItem:

  • err {null | Kickq.Error} The error argument can null or an instance of the Kickq.Error Object. Kickq provides Error Objects when an error occurs and not strings! Read more about it in the Kickq Errors page.
  • jobItem {kickq.JobItem} The Job Item is an Object Literal containing a specific structure of key/value pairs. Read more about it on the Kickq Job Item page.

The Returned Promise

kickq.create() will return a promise which exposes the .then(onResolve, onReject) function. The resolved function gets a Job Item as an argument and the rejected function gets a Kickq Error Object.

kickq.create('a job')
    function(jobItem){ /* success */},
    function(err){ /* fail */}

Danger Zone

optData, optOptions and optCallback are all optional, this will work:

kickq.create('job name');

But this will result in unexpected behavior:

kickq.create('job name', opts);

// Do this instead if no data:
kickq.create('job name', null, opts);


var kickq = require('kickq');

var data = {some:'stuff'};

// this is delayed by x amount of time from scheduling time
var opts = {delay: 1000 };

kickq.create('job name', data, opts, function(err, jobItem) {
  // err if not null, something went wrong
  // jobItem A job item, see bellow.

Read more about the callback's argument jobItem in The Job Item.

Create a hotjob

A hotjob is a job that the initiator waits with a callback for the job completion. A timeout ensures that the callback will eventually be called.

 * Callback when the job completes.
 * That includes failed or successfull processing.
 * @param {Kickq.JobItem} job A response object.
function fnOnJobComplete(jobItem) {};

 * Callback for when the job eventually fails or timeouts.
 * @param  {kickq.error.JSON|kickq.error.Timeout}  err The error object.
function fnOnJobFailed(err) {};

var opts = {
  hotjob: true,
  hotjobTimeout: 10000 // 10 seconds, default set via kickQ.config()
kickq.create('job name', data, opts, function(err, jobItem, hotjobPromise) {
  jobItem.hotjobPromise === hotjobPromise; // same reference

  hotjobPromise.then(fnOnJobComplete, fnOnJobFailed);

Set hotjob Flag on Job Types

Set a default hotjob flag per job type via config:

var kickq = require('kickq');

  jobFlags: {
    'job name': {
      hotjob: true,
      hotjobTimeout: 10000 // 10 seconds

Create a Job With Retries

var opts = {
  retry: true,
  retryCount: 5 // times, default for job set via kickQ.config()
kickq.create('job name', data, opts);

Or set a default retry flag per job type via config:

var kickq = require('kickq');

  jobFlags: {
    'job name': {
      retry: true,
      retryCount: 5,
      retryInterval: 1800 // (half an hour)

kickq.create() Returns a Promise

// data, options and callback are all optional
var createPromise = kickq.create('job name');

createPromise.then(handleResolve, handleFail);

function handleResolve(jobItem) {

function handleFail(err) {
  // do something with err

Create Multiple Jobs

var createPromises = [];

createPromises.push( kickq.create('job one') );
createPromises.push( kickq.create('job two') );
createPromises.push( kickq.create('job three') );
createPromises.push( kickq.create('job four') );

  jobs[0].name === 'job one';
  jobs[1].name === 'job two';
  jobs[2].name === 'job three';
  jobs[3].name === 'job four';
Something went wrong with that request. Please try again.