Library Usage

aws-swf uses the official Node.js aws-sdk for the low-level API calls. You can find the full API reference here

aws-swf provide classes to wrap higher-level concepts of the AWS SWF API :

• ActivityPoller
• ActivityTask
• Decider
• DecisionTask
• Workflow
• WorkflowExecution

Creating an SWF client object

var swf = require("aws-swf");
var swfClient = swf.createClient({
    accessKeyId: "... access key id here ...",
    secretAccessKey: "... secret key here ..."
});

If no config is passed to createClient, we'll use the config.js file written by swf-set-credentials.

var swf = require("aws-swf"),
    swfClient = swf.createClient();

Creating an ActivityPoller

An ActivityPoller polls Amazon SWF for new tasks to be done.

An ActivityTask is instantiated by an ActivityPoller when it receives a task from SWF.

It is passed to your callback and adds the respondCompleted() and respondFailed() methods.

Example :

var swf = require("aws-swf");

var activityPoller = new swf.ActivityPoller(swfClient, {
    
   "domain": "test-domain",
   "taskList": { "name": "test-taskList" },
   "identity": "ActivityPoller-1"
   
}, function (activityTask, cb) {
   
   console.log('A new task is available !');
   // Do something here...
   
   // sends "RespondActivityTaskCompleted" to SWF
   // result: Maximum length of 32768.
   activityTask.respondCompleted(result, function (err) {
      cb(true); // free the poller for new activities
   }); 
   
   // or :
   
   // sends "RespondActivityTaskFailed" to SWF
   // parameters: 
   // reason (string or undefined): Maximum length of 256
   // details (string or undefined): Maximum length of 32768
   activityTask.respondFailed(reason, details, function (err) {
       cb(true); // free the poller for new activities
   });
   
});

activityPoller.start();

It is not recommanded to stop the poller in the middle of a long-polling request, because SWF might schedule an ActivityTask to this poller anyway, which will obviously timeout. The .stop() method will wait for the end of the current polling request, eventually wait for a last activity execution, then stop properly :

// on SIGINT event, close the poller properly
process.on('SIGINT', function () {
   console.log('Got SIGINT ! Stopping activity poller after this request...please wait...');
   activityPoller.stop();
});

Creating a Decider

A Decider will poll Amazon SWF for new decision tasks.

A DecisionTask is instantiated by a Decider when it receives a decision task from SWF.

var swf = require("aws-swf");

var myDecider = new swf.Decider(swfClient, {
    
   "domain": "test-domain",
   "taskList": {"name": "my-workflow-tasklist"},
   "identity": "Decider-01",
   
   "maximumPageSize": 500,
   "reverseOrder": false // IMPORTANT: must replay events in the right order, ie. from the start
   
}, function (decisionTask, cb) {
    
    // do something here and send decisions...
    
    decisionTask.complete_workflow_execution("details of ending here ?", function (err) {
        
    });
    
    cb(true); // to continue polling
});

It is not recommanded to stop the poller in the middle of a long-polling request, because SWF might schedule an ActivityTask to this poller anyway, which will obviously timeout. The .stop() method will wait for the end of the current polling request, eventually wait for a last activity execution, then stop properly :

// on SIGINT event, close the poller properly
process.on('SIGINT', function () {
   console.log('Got SIGINT ! Stopping decider poller after this request...please wait...');
   myDecider.stop();
});

Using the simplified history (experimental)

A getSimpleWorkflowHistory is available on the decisionTask instance, which gives a simpler way to write deciders...

var workflowHistory = decisionTask.getSimpleWorkflowHistory();
/*
workflowHistory = {
    input: "...workflow input data...",
    activities: [
        {
            input: "...activity input data...",
            activityId: "theActivityId",
            lastEvent: "..."
            result: "..."
        }
    ]
}
*/

Starting a Workflow

var swf = require("aws-swf");

var workflow = new swf.Workflow(swfClient, {
   "domain": "test-domain",
   "workflowType": {
      "name": name,
      "version": version
   },
   "taskList": { "name": "my-workflow-tasklist" },

   "executionStartToCloseTimeout": "1800",
   "taskStartToCloseTimeout": "1800",

   "tagList": ["music purchase", "digital"],
   "childPolicy": "TERMINATE"
});

To start a new workflowExecution :

var workflowExecution = workflow.start({ input: "{}"}, function (err, runId) {

   if (err) {
      console.log("Cannot start workflow : ", err);
      return;
   }

   console.log("Workflow started, runId: " +runId);

});