Workflow REST API
From AlfrescoWiki
Contents |
[edit] Workflow Service
?? Do we want a list of differetn workflow engines?
[edit] Workflow Definition
[edit] Representations
[edit] Simple Representation
Contains the Workflow Definition Id and some simple display information. E.g:
{
"data":
{
"url": "api/workflow-definitions/{workflow definition id}",
"name": "some name"
}
}
or as a list:
{
"data":
[
{"url": "api/workflow-definitions/id1", "name": "name1"},
{"url": "api/workflow-definitions/id2", "name": "name1"},
... // workflow definitions.
]
}
[edit] Detailed Representation
Contains workflow definition Id, detailed display data and Ids for all sub-components (e.g. tasks).
{
"data":
{
"url": "api/workflow-definitions/{workflow definition id}",
"name": "some name"
"version": "some version"
"title": "some title"
"description": "some description"
"startTaskDefinition": "api/task-definitions/{start task definition Id}",
"taskDefinitions":
[
"api/task-definitions/{start task definition Id}",,
"api/task-definitions/{task definition Id1}",,
"api/task-definitions/{task definition Id2}",
... //task definition URLs.
]
}
}
[edit] Methods
GET /api/workflow-definitions/
<= Workflow Definitions[]
Returns a representation of all deployed workflow definitions.
Defaults to a list of simple representations.
GET /api/workflow-definitions/{Workflow Definition Id}
<= Workflow Definition
Returns a representation of the workflow definition specified by the Workflow Definition Id
Defaults to detailed representation (see above).
POST /api/workflow-definitions
=>Workflow Definition
<=Workflow Definition
Deploys a workflow definition and returns a representation of the newly deployed workflow definition.
Posted value could be a file location, node ref or a full stringrepresentation of the process definition, e.g.
{"file": "file path"} or
{ "nodeRef": "nodeRefId"} or
detailed representation (see above).
Default return value is a detailed representation (see above).
PUT /api/workflow-definitions
=>Workflow Definition
<=Workflow Definition
Updates (redeploys) the specified workflow definition.
Posted value can be file, node ref or JSON representation as above.
Default return value is a detailed representation.
DELETE /api/workflow-definitions/{workflow definition Id}
<=Workflow Definition
Deletes (undeploys) the specified workflow definition.
Deleted value specified as Id, eg:
{
"workflowDefinitionId": "some Id"
}
Default return value is a simple representation.
[edit] Workflow Instance
[edit] Representations
[edit] Simple Representation
Just contains the Id of the Workflow Instance and some basic display data (description).
{
"data":
{
"url": "api/workflow-instances/{workflow instance id}",
"description": "some description",
"definition": "api/workflow-definitions/{workflow definition Id}"
}
}
or as a list:
{
"data":
[
{
"url": "api/workflow-instances/id1",
"description": "description1",
"definition": "api/workflow-definitions/{definition Id1}"
},
{
"url": "api/workflow-instances/id2",
"description": "description2",
"definition": "api/workflow-definitions/{definition Id2}"
},
... //workflow instances
]
}
[edit] Detailed Representation
Contains the Id, detailed display data (properties) and ids for all the sub-components (e.g. paths, task instances, etc).
{
"data":
{
"url": "api/workflow-instances/{workflow instance Id}",
"description": "some description",
"isActive": true/false,
"context": "context NodeRef URL",
"endDate":
{
"iso8601" : "2009-11-17T13:51:42.125Z"
}
"initiator": "initaitor NodeRef URL",
"startDate":
{
"iso8601" : "2009-11-14T13:51:42.125Z"
}
"package": "package NodeRef URL"
"definition":
{
"url": "api/workflow-definitions/{workflow definition Id}",
"name": "some name"
"version": "1.0"
"title": "some title"
"description": "some description"
"startTaskDefinition": "api/task-definitions/{start task id}",
"taskDefinitions":
[
... //task definition URLs
]
}
}
}
[edit] Methods
GET api/workflow-instances
<= Workflow Instance[]
Returns a representation of all workflow instances.
Defaults to a list of simple representations.
GET api/workflow-instances?state=active|cancelled|completed
<= Workflow Instance[]
Returns a representation of all workflow instances.
Defaults to a list of simple representations.
Takes an optional 'state' parameter which filters the returned list of instances to include only the active instances, cancelled instances or completed instances.
GET /api/workflow-definitions/{Workflow Definition Id}/workflow-instances
<= Workflow Instance[]
Returns representations of all instances of the specified workflow definition.
Defaults to a list of simple representations.
GET /api/workflow-definitions/{Workflow Definition Id}/workflow-instances?stat=active|cancelled|completed
<= Workflow Instance[]
Returns representations of all instances of the specified workflow definition.
Defaults to simple representations.
Takes an optional 'state' parameter which filters the returned list of instances to include only the active instances, cancelled instances or completed instances.
GET api/workflow-instances/{instance Id}
<= Workflow Instance
Returns a representation of the workflow instance with the specified Id.
Defaults to detailed representation.
POST api/workflow-instances
=>Workflow Definition
<=Workflow Instance
Creates a new Workflow instance and returns a representation of it.
Posted value needs to specify a workflow definition and various other params, e.g.:
{
"workflowDefinition": "workflow definition Id",
"packageContainer": "package container NodeRef URL", //optional
//Either
"packageContent": "package content NodeRef URL", //optional
//Or
"packageContents":
[
"package content 1 NodeRef URL",
"package content 2 NodeRef URL",
...
]
"parameters": // Start task parameters
{
"param1 name": "param1 value",
"param2 name": param2IntValue,
...
}
}
Default returns a detailed representation of workflow instance.
DELETE api/workflow-instances/{Instance Id}
<=Workflow Instance
Deletes the specified Workflow instance and returns a representation of it.
Default returns a simple representation of deleted workflow instance.
POST api/workflow-instances/cancellationQueue
->Workflow Instance Id
<=Workflow Instance
Puts the specified Workflow instance on a queue of instances to be cancelled. (Effectively cancels this workflow instance).
Default returns a simple representation of cancelled workflow instance.
[edit] Workflow Path
[edit] Representation
Contains path Id and detailed display data (e.g. full node information).
{
"data":
{
"url": "api/workflow-instances/{workflow instance Id}/paths/{path Id}",
"workflowInstance": "api/workflow-instances/{workflow id}}",
"isActive": true/false,
"node":
{
"name": "node name",
"title": "node titel",
"description": "node description",
"type": "node type",
"isTaskNode": true/false,
"transitions":
[
{
"id": "transition Id", //Should this be a URL?
"title": "transition title",
"descirption": "transition description",
"isDefault": true/false
},
...
]
}
}
}
A list of workflow paths is represented as follows:
{
"data":
[
... //Workflow path representations as above.
]
}
[edit] Methods
GET api/workflow-instances/{instance Id}/paths
<= Workflow Paths[]
Returns representations of all the workflow paths associated with the specified workflow instance.
Defaults to a list of representations.
GET api/workflow-instances/{instance Id}/paths/{path Id}
<= Workflow Path
Returns a representation of the specified workflow path.
Defaults to a representation.
POSTapi/workflow-instances/{instance Id}/paths/{path Id}/transitionExecutorQueue
=> Transition Id
<= Workflow Path
Posts a new transition to the transition executor queue(evvectively signalling the Workflow Path to progress to the specified transition). Returns a representation of the updated workflow path.
Defaults to a detailed representation.
POSTapi/workflow-instances/{instance Id}/paths/{path Id}/eventExecutorQueue
=> Event Id
<= Workflow Path
Posts a new event to the event executor queue (effectively signalling the Workflow Path to fire the specified custom event). Returns a representation of the updated workflow path.
Defaults to a detailed representation.
[edit] Workflow Timer
[edit] Representations
{
"data":
{
"url": "api/workflow-instances/{instance Id}/timers/{timer Id}",
"name": "timer name",
"error": "error string",
"dueDate":
{
"iso8601" : "2009-11-17T13:51:42.125Z"
}
"path": "api/workflow-instances/{workflow instance Id}/paths/{workflow path Id}",
"taskInstance": "api/task-instances/{task instance Id}"
}
}
[edit] Methods
GET api/workflow-instances/{instance Id}/timers
<= Workflow Timers[]
Returns representations of all the workflow timers associated with the specified workflow instance.
[edit] Task Definition
[edit] Representations
[edit] Simple Representation
The Task Definition Id and some basic display data (name, description).
{
"data":
{
"url": "api/task-definitions/{task definition Id}",
"name": "task definition name",
}
}
or as a list:
{
"data":
[
{
"url": "api/task-definitions/{task definition Id}",
"name": "task definition name",
},
... //More task definitions.
]
}
[edit] Detailed Representation
The Task Definition Id and detailed display data. Full list of 'field definitions'. (Description of what properties/associations/etc are defined by this task definition. These will be very similar to the field definitions used by the Forms API).
{
"data":
{
"url": "api/task-definitions/{task definition Id}",
"name": "task definition name",
"title": "task definition title",
"description": "task definition description",
"parentName": "parent task definition name", // parent url?
"typeDefinition": "api/{some type definition url}" // Need data dictionary REST API.
"node":
{
"name": "node name",
"title": "node titel",
"description": "node description",
"type": "node type",
"isTaskNode": true/false,
"transitions":
[
{
"id": "transition Id",
"title": "transition title",
"descirption": "transition description",
"isDefault": true/false
},
...
]
}
}
}
[edit] Methods
GET api/task-definitions
<= Task Definitions[]
Returns representations of all the task definitions.
Defaults to a list ofsimple representations.
GET api/workflow-definitions/{workflow definition Id}/task-definitions
<= Task Definitions[]
Returns representations of the task definitions contained in the specified workflow definition.
Defaults to a list ofsimple representations.
GET api/task-definitions/{task definition Id}
<= Task Definition
Returns a representation of the specified task definitions.
Defaults to a detailed representation.
?? Do we want to support hot-deploying of new task definitions? What about updating/deleting?
[edit] Task Instance
[edit] Representations
[edit] Simple Representation
Contains the task instance Id and some basic display data (name, description, etc).
{
"data":
{
"url": "api/task-instances/{task instance Id}",
"name": "task instance name",
"description": "task instance description"
}
}
or as a list:
{
"data":
[
... // task instance representations as above.
]
}
[edit] Detailed Representation
Contains a full description of the task instance, including all 'fields'. Fields are essentially name-value pairs as described by the field definitions. They will probably be very similar to the Forms API fields.
{
"data":
{
"url": "api/task-instances/{task instance Id}",
"name": "task instance name",
"title": "task instance title",
"description": "task instance description",
"state": "task instance state (In Progress or Complete)",
"path": "api/task-instances/{task instance Id}/paths/{path Id}",
"definition":
{
// Detailed Task Definition Representation shown above.
}
// Map of all the property values.
// The names used are the property QNames with ':' replaced by '_'.
"values":
{
// Example boolean property.
"example_booleanProperty": true/false,
// Example numeric property.
"example_numericProperty": 12345,
// Example string property.
"example_stringProperty": "some string value",
// Example association.
"example_assocName": "some NodeRef Id", // Should this be a node URL?
...
}
}
}
[edit] Methods
GET api/task-instances
<= Task Instances[]
Returns representations of all the task instances
Defaults to a list of simple representations.
GET api/task-instances?authority={authority Id}?status={status Id}
<= Task Instances[]
Returns a representation of the task instances assigned to the specified authority and of the specified status.
Defaults to a list of simple representations.
GET api/task-instances/{task instance Id}
<= Task Instance
Returns a representation of the specified task instance.
Defaults to a detailed representation.
?? How do we get task instances for pooled authorities?
POST api/task-instances/startTaskExecutorQueue
=> Task Instance Id
<= Task Instance
Posts the specified task instance to a queue, ready to start it (effectively starts the task). Returns a representation of that task instance.
Defaults to a detailed representation.
POST api/task-instances/suspendTaskExecutorQueue
=> Task Instance Id
<= Task Instance
Posts the specified task instance to a queue to be suspended (effectively suspsends the task). Returns a representation of that task instance.
Defaults to a detailed representation.
POST api/task-instances/queries
=> Task Query
<= Task Instance[]
Posts a task query to the query queue (effectively performs the query). Returns a list of task instances matching the query.
Defaults to simple representations.
PUT api/task-instances/{task instance Id}
=> Task Instance
<= Task Instance
Updates the task instance, changing fields. Returns a representation of that task instance.
Defaults to a detailed representation.
The posted task representation should be as follows:
{
"id": "task instance Id", // Required
"name": "task instance name", // Optional
"title": "task instance title", // Optional
"description": "task instance description", // Optional
"state": "task instance state (In Progress or Complete)", // Optional
"values": // List all the property values to update
{
// Example property.
"example_prpopertyName": "property value",
...
}
}
