roadiejs-flow

Go with the flow of the crowd.

Usage no npm install needed!

<script type="module">
  import roadiejsFlow from 'https://cdn.skypack.dev/roadiejs-flow';
</script>

README

roadiejs-flow

A plugin for RoadieJS

A BPEL-inspired workflow control solution, featuring human-tasks, parallel flows and an extensible 'activity' architecture.

Contents

API

createFlowFromRequest

Creates a new flow (based on a flow template) and then goes on to run it, returning once one of these conditions is reached:

  • The finish activity is reached
  • An activity requiring human input is reached
  • An error occurs
Request

POST /flows

{
  "templateId": "roadiejs.hr.newEmployee",
  "params": {
    "managerId": "Walter.White"
  }
}
Name Notes
templateId The name of a flow-template from which the new flow should be generated.
params Optional. Any values that are required by activities in the flow (e.g. docIds, username, default values etc.)
Response

Status 200

{
  "flowId": "5579d9351872a3070b470e83",
  "flowState": "pending",
  "forHumans": [],
  "immediatePendingActivityId": "showStreetCreateUi",
  "message": "There is currently 1 activity pending"
}
Name Notes
flowId The system-generated flowId
flowState The current state of the overall flow. Can be pristine, running, pending, failed, dirty, lost or finished
forHumans An array of human-readable messages
immediatePendingActivityId On receiving a createFlowFromRequest request, a new flow will be created (based on a flow-template) and run. If during this run, the flow reaches an activity that requires immediate human input, then the id of that pending activity will be available here.
message A simple string summarising the current state of the freshly created flow.

stopFlowFromRequest

Deletes the specified flow.

Request

DELETE /flow/:flowId

Parameter Notes
flowId The system-generated flowId to delete
Response

Status 200

setDataAndProgress

Sets the data object of a currently pending activity and then restarts the flow.

Request

PUT /flows/:flowId/data

Parameter Notes
flowId The system-generated flowId to update
Response

Status 200

{
  "flowId": "5579f6141872a3070b470e86",
  "flowState": "finished",
  "forHumans": [],
  "message": "Flow has reached finished activity"
}
Name Notes
flowId The system-generated flowId
flowState The current state of the overall flow. Can be pristine, running, pending, failed, dirty, lost or finished
forHumans An array of human-readable messages
message A simple string summarising the state of the flow after the update.

getActivity

Returns data, config and current status information for the specified activity, along with contextual information about the wider flow.

Request

GET /flows/:flowId/:activityId

Parameter Notes
flowId An id associated with a currently-running flow.
activityId An element id which uniquely identifies an activity within a flow.
Response

Status 200

{
  "id":"createEmployeeUi",
  "flowId":"5579d9351872a3070b470e83",
  "state":"pending",
  "data": {
    "employeeNumber":20077,
    "status": "Permanent"
  },
  "type":"showUi",
  "typeConfig":{},
  "audience":[],
  "activityConfig":{
    "uiId":"streetCreateUi"
  },
  "flow":{
    "id":"5579d9351872a3070b470e83",
    "templateId":"roadiejs.hr.newEmployee",
    "state":"pending",
    "namespace":"roadiejs",
    "blueprintName":"hr",
    "blueprintVersion":1,
    "blueprintLocalVersion":0
  },
  "lastStarted":"2015-06-11T18:53:41.490Z",
  "lastCompleted":"2015-06-11T18:53:41.492Z"
}
Path Notes
id The activityId that was requested
flowId The system-generated flowId that was requested
state The current state of the activity. Can be pristine, running, pending, dirty, ready, failed or finished
data An object containing data pertinent to the activity. Can be set by other activities
type The type of activity
typeConfig roadie.activities[activity.activityType].properties,
audience Who is part to this activity?
activityConfig The config of the activity, as defined in its element
flow
flow.id The system-generated flowId that was requested
flow.templateId The flow-template that originally used to produced the flow
flow.state The current state of the overall flow. Can be pristine, running, pending, failed, dirty, lost or finished
flow.namespace The namespace of the blueprint which defines the flow
flow.blueprintName Name of the blueprint which defines the flow
flow.blueprintVersion Version of the blueprint which defines the flow
flow.blueprintLocalVersion The local version of the blueprint which defines the flow
lastStarted Timestamp of when the activity was last started
lastCompleted Timestamp of when the activity last completed
messages A list of messages attached to the activity

Elements

category

Registers a category with which flows can then be associated. Note that categories are registered 'globally' and are not namespaced. This allows multiple blueprints to contribute flows to common categories like 'Administration', 'HR' etc.

  • It's possible multiple blueprints can conflict over registering a categoryId. Currently first-installed-wins.
Example
{
  "element": "category",
  "id": "admin",
  "config": {
    "label": "Administration",
    "description": "General administration tasks",
    "less": {
      "base-color": "#5CB85C"
    }
}
Config
Name Type Notes
label string A short label for the category.
description string A description of what the category's all about.
less object Less-style CSS variables for controlling the appearance of the category

flow

Registers a new flow for the blueprint.

Example
{
  "element": "flow",
  "id": "newTeacher",
  "config": {
    "category": "employees",
    "label": "Create a new teacher",
    "description": "All the necessaries for when a new teacher joins the school",
    "instigators": ["newTab"]
  }
}
Config
Name Type Notes
category string The id of a category which this flow is best associated.
label string A short label to identify the flow
description string A description of what the flow's all about.
instigators [string] An array of strings which describes how the flow might be started. To be taken from newTab, search.

activity

Adds a new activity to a flow (must be a child of a flow element).

Example
{
  "element": "activity",
  "id": "saveData",
  "path": "newDepartment",
  "config": {
    "activityType": "saveData",
    "config": {
      "sourceDataActivityId": "showDepartmentUi",
      "method": "post",
      "schema": "departments"
    }
  }
}
Config
Name Type Notes
activityType string Name of the type of activity to run.
config object Values to configure the behaviour of the activity once it's reached. The actual values required here will depend on what activityType is defined.

goto

Activities are stitched together as a directed graph via goto elements. As such they need to be defined as child elements of an activity element.

  • Because of the state value, it is possible for a single activity element to have multiple gotos.
Example
{
  "element": "goto",
  "path": "newDepartment.saveData",
  "config": {
    "state": "finished",
    "targetActivityId": "finish"
  }
}
Config
Name Type Notes
state string Defines the circumstances of when a goto should be followed. If the associated activity completes without error, flow will follow gotos defined with a finished state. If however an activity fails, then flow will follow a goto with a failed state.
targetActivityId string The id of an activity defined on the same flow to which flow should transfer to on completion (successful or otherwise) of the activity.

Activities

start

The entry-point of where the flow is to start. If not explicitly supplied, attempts will be made to infer it. Probably best to explicitly define it...

Example
{
  "element": "activity",
  "id": "start",
  "path": "maintainTeacherFlow",
  "config": {
    "activityType": "start",
    "config": {}
  }
}
Config
  • No config's required.

finish

A single end-point that indicates the end of the flow. No need to explicitly define, can be inferred through gotos.

Example
{
  "element": "activity",
  "id": "finish",
  "path": "maintainTeacherFlow",
  "config": {
    "activityType": "finish",
    "config": {}
  }
}
Config
  • No config's required.

saveData

Takes the data stored in the specified activity's data object and then persists it to the defined schema. Will trigger data-tasks as normal.

Example
{
  "element": "activity",
  "id": "saveData",
  "path": "maintainTeacher",
  "config": {
    "activityType": "saveData",
    "config": {
      "sourceDataActivityId": "showTeacherUi",
      "method": "put",
      "schema": "teachers",
      "docIdPath": "teacherNumber"
    }
  }
}
Config
Name Type Notes
sourceDataActivityId string The id of an activity within the current flow, that is storing the data to persist.
method string Should a new document be created with the data, or should an existing document be updated? One of post, put or patch.
schema string The id of a schema defined in the blueprint into which the new/updated document is headed.
docIdPath string Path to a key in the source activity's data object that contains the documents docId. Only used when method is set to either put or patch.

grabBlueprintData

Used to find a document from the supplied schema, and set the data object of the target activity.

Example
{
  "element": "activity",
  "id": "grabBlueprintData",
  "path": "maintainDepartment",
  "config": {
    "activityType": "grabBlueprintData",
    "config": {
    "targetActivityId": "showDepartmentUi"
    }
  }
}
Config
  • No config need be defined in the activity...
Notes

This activity is configured via parameters created as part of the flow.

Name Type Notes
sourceDocId string A value expected to be found in the key field of the source schema.
sourceSchema string The schema from where the document should be fetched.

setDefaults

Sets default values on an activity's data object. Supports a {{...}} syntax for function-based defaults.

Example
{
  "element": "activity",
  "id": "setDefaults",
  "path": "newEmployee",
  "config": {
    "activityType": "setDefaults",
    "config": {
      "targetActivityId": "newEmployeeCreateUi",
      "defaults": {
        "agencyStaff": "No",
        "employementStatus": 1,
        "startDate": "{{DATE(1900-01-01)}}",
        "entryDate": "{{TODAY}}",
      }
    }
  }
}
Config
Name Type Notes
targetActivityId string Name of an activity in the current flow where default values should be set.
defaults object Used as a key/value map to set default values. Set literally, unless value is of form {{FUNCTION_NAME}}, whereby a function will be used. Supported functions listed below.
Default functions

As above, if the value of the key/value map is of the form {{FUNCTION_NAME}}, then a function will be used to derive the value. Some functions may require a parameter string to be passed in the form {{FUNCTION_NAME(paramStringHere)}}.

Function name Parameter string Notes
NOW Sets the value to new Date().
DATE String to be passed to newDate() Sets the value to the the specified date.
TODAY Same as NOW, but hours, minutes and milliseconds are set to 0.

License

MIT