Workflow Usage Guide

Programmatic Creation of Workflow

The UI-Workflow will support the creation of a Workflow through its own interface and will not require the programmatic creation of a Workflow.
A developer, however, may choose to programmatically create the Workflow.

Each Workflow is defined using a series of JSON files, starting with the setup.json and the workflow.json.

The workflow.json file might look something like this example taken from the Example InputTask Workflow.

{
  "id": "6def19f6-b64d-44ca-b679-3852470a227a",
  "name": "Example InputTask",
  "description": "This workflow presents an InputTask.",
  "versionTag": "1.0",
  "historyTimeToLive": 90,
  "deploymentId": null,
  "active": false,
  "setup": {
    "asyncBefore": false,
    "asyncAfter": false
  },
  "nodes": [
    "/startEvent/7c3f0fa3-9159-4398-9bf7-e1337ac9bbb8",
    "/inputTask/1c2645ea-cc99-49f4-ba7d-6961c33dab8c",
    "/endEvent/d2abf134-5a9b-4f69-a63e-b2ff46ac43c2"
  ],
  "initialContext": {}
}

The setup.json is generally an empty object JSON file like: {}.

Each Node described in the workflow.json is described by the Node Type and the UUID in a URL path like structure.

The Nodes themselves are written out as a JSON file and are identified not by the file name but instead by the UUID specified in the id property of the JSON file and are stored within the sub-directory named nodes/.

Using the above example workflow.json the sub-directory nodes/ contains the following JSON files:

start.json:

{
  "id": "7c3f0fa3-9159-4398-9bf7-e1337ac9bbb8",
  "name": "Start",
  "description": "Start of Example InputTask workflow.",
  "type": "MESSAGE_CORRELATION",
  "deserializeAs": "StartEvent",
  "expression": "/events/workflow/example-inputtask/start"
}

inputTask.json:

{
  "id": "1c2645ea-cc99-49f4-ba7d-6961c33dab8c",
  "name": "InputTask Process",
  "description": "Perform the InputTask.",
  "deserializeAs": "InputTask",
  "inputs": [
    {
      "fieldId": "field_1",
      "fieldLabel": "Field 1",
      "defaultValue": "default",
      "inputType": "SELECT",
      "options": [
        "default",
        "example",
        "other"
      ],
      "required": true
    },
    {
      "fieldId": "field_2",
      "fieldLabel": "Field 2",
      "defaultValue": "",
      "inputType": "TEXT",
      "required": false
    },
    {
      "fieldId": "submit",
      "fieldLabel": "Submit",
      "inputType": "SUBMIT",
      "required": true
    }
  ]
}

end.json:

There is also a triggers/ sub-directory with a file called startTrigger.json that is used to help provide the mechanism for starting the Workflow.
In the case of the Example InputTask Workflow, this triggers/startTrigger.json looks like:

The Workflow must be stored in a FWZ file and uploaded into the system using the appropriate UI-Workflow create or import Workflow interface.

It is recommended to creating and including the optional fwz.json file when compressing, such as this one:

The supported compression formats are ZIP, Tar Gzip, and Tar Bzip2.

Terminology

The first letter of a word is capitalized to a specific implementation of something or the word with specific meaning whereas the fully uncapitalized version is referring the generally use of the word. For example, “Workflow” refers to a workflow object, model, instance, or the project, whereas “workflow” refers to the general meaning of the word.

Active: The state of a Workflow such that it is available for execution or use.
Async After: Designate that asynchronous continuation after a Node is in use. This can be used to start operating asynchronously for some path. When both Async Before and Async after are set, then the Node is part of a sequence of asynchronous Nodes.
Async Before: Designate that asynchronous continuation before a Node is in use. This can be used to continue operating asynchronously for some path.
Camunda: A specific product that acts as a Workflow Engine.
Compress File Task: A specific Task type that operates the compression of some file. These files are generally accessed and stored directly by the Workflow Engine.
Database Connection Task: A specific Task type that establishes a connection to some database server.
Database Disconnect Task: A specific Task type that establishes a disconnect from some database server.
Database Query Task: A specific Task type that executes a query on an already connected database server. The output of the query is often stored in either a Variable or as a file on the Workflow Engine system.
Deployment: A Workflow that is added to the Workflow Engine and is available for operation by that engine. The structure and format is specific to the engine.
Deployment ID: The identifier used by the Workflow Engine for a deployed workflow.
Directory Task: A specific Task type that performs a directory related operation such as the creation or the deletion of a directory. These directories are generally accessed and stored directly by the Workflow Engine.
Email Task: A specific Task type that sends an e-mail.
Embedded Subprocess: A specific Subprocess type that embeds a Workflow within the parent Workflow. An Embedded Subprocess must have a new Start Event and a new End Event.
Embedded Variable: See Variable.
End Event: A specific Event type that explicitly designates the end of a Workflow. This may be required by a Workflow Engine, such as Camunda.
Event: A general type of a Node that operates based on some event. The two prominent types of an Event are Message Event and Timer Event.
Event Subprocess: A specific Subprocess type that operates an embedded a Workflow within the parent Workflow and only executes based on some event. An Event Subprocess must have a new Start Event and a new End Event. An Event Subprocess does not execute in the same flow of the parent Workflow nor does it directly alter the paths taken by the parent Workflow.
Exclusive Gateway: A specific Gateway type that exclusively chooses one path over multiple defined paths based on some condition. The condition operates using an exclusive-or operation (XOR). An Exclusive Gateway will execute only a single path.
File Task: A specific Task type that performs a file related operation such as the creation or the deletion of a file. These files are generally accessed and stored directly by the Workflow Engine.
FTP Task: A specific Task type that performs an FTP (File Transfer Protocol) action, such as uploading a file to a specified server.
FWZ: An acronym for the “FOLIO Workflow Zip” format, which is used for importing and exporting a workflow.
Gateway: A general type of a Node that performs changes the flow of a Workflow.
Graph: Used to either refer to the visual representation of the workflow or to reference a specific node.
ID: The identifier used to specifically identify a Workflow specifically by mod-workflow and ui-workflow. This is different from “Identifier” and “Deployment ID”.
Identifier: The use of Identifier, rather than ID, is used to designate an identifier for the Workflow that is associated with the Workflow Engine. This is intentionally fully written out to avoid conflicting with the ID used specifically for mod-workflow and ui-workflow.
Inactive: The state of a Workflow such that it is unavailable for execution or use.
Inclusive Gateway: A specific Gateway type that exclusively chooses one path over multiple defined paths based on some condition. The condition operates using an inclusive-or operation (OR). An Inclusive Gateway can execution multiple paths.
Input Variable: A specific type of Variable that a Node accepts from the previous node.
Local Variable: A specific type of Input Variable or Output Variable that has a limited scope. Often times a scope may be limited to a process or sub-process. This is specific to the Camunda Workflow Engine.
Message Event: A specific Event type that operates based on a message, such as on a REST request. These are often used to manually trigger or to programmatically trigger the start of a Workflow.
Move To Last Gateway: A specific Gateway type that is used by the Camunda Workflow Engine to join multiple paths at the end of a Gateway.
Move To Node Gateway: A specific Gateway type that is used by the Camunda Workflow Engine to designate a path being selected managed by a Gateway.
Node: See Workflow Item.
Node Type: A specific type of Node.
Output Variable: A specific type of Variable that a Node provides to Nodes that the current Node transitions into.
Parallel Gateway: A specific Gateway type that operates multiple provided Workflow paths simultaneously.
Process Variable: A specific type of Input Variable or Output Variable that is maintained throughout the entire workflow process. This is specific to the Camunda Workflow Engine.
Receive Task: A specific Task type that references a message. This is often used to block or wait until a proper message is received.
Request Task: A specific Task type that makes an HTTP request to a server. The response is generally stored in a Variable.
Script Task: A specific Task type that operates using a scripting language supported by a particular Workflow Engine, such as JavaScript or Ruby.
Start Event: A specific Event type that explicitly designates the start of a Workflow. This may be required by a Workflow Engine, such as Camunda.
Subprocess: A general type of a Node that contains a set of Nodes that operate within some level of isolation. This generally establishes a new scope and Local Variables defined within this scope are not available outside. This is often used for loops or transactions.
Task: A general type of a Node that performs some task or action.
Timer Event: A specific Event type that operates based on a time, such as a Cron Job. These are often used to automatically trigger the start of a Workflow.
Transaction Subprocess: A specific Subprocess type that operates an embedded a Workflow within the parent Workflow as a transaction. A Transaction Subprocess must have a new Start Event and a new End Event. A Transaction Subprocess may provide additional Node paths to follow on failure or on cancellation of the transaction.
Variable: Various types of variables are supported and are generally called Embedded Variables. These are named variables used as abstract storage or symbol for something determined at runtime. The different types are Input Variable, Local Variable, Output Variable, and Process Variable.
Version: The specific version of that Workflow. Each Workflow may have its own version. Neither mod-workflow nor ui-workflow do anything with the version at this time and is informative for the user.
Workflow: Generally referred to as the flow or progress of work done, but is often times used to referred to a specific implementation. This may also be used to refer to this system or the series of modules (mod-workflow, ui-workflow, mod-camunda, etc...) as a whole or in general.
Workflow Engine: The service used to execute or perform the Workflow, such as mod-camunda.
Workflow Item: Sometimes called a node, this is a specific action, operation, or change in flow of a Workflow.