30.2 Accessing and Using the Workflow Process and Definition Service

The Workflow Process and Definition Service exposes resources for managing workflow processes. The service allows a way for you to retrieve all provisioning request definitions in the system, or access a particular definition by ID. In addition, the service provides a way to retrieve all existing workflow processes, or access a particular process by ID.

30.2.1 Available Resources

There are four basic types of resources available with the Workflow Process and Definition Service:

Entry Point

The entry point URI for the Workflow Process and Definition Service is:

/v1

The root entry point returns a list of all resources available.

Definitions Resource

The Definitions resource supports two basic URI patterns:

  • Resource for returning a collection of provisioning request definitions (PRDs)

  • Resource for returning a specific PRD

Processes Resource

The Processes resource supports two basic URI patterns:

  • Resource for returning a collection of existing workflow processes

  • Resource for returning a specific process

Resources for Filtering, Debugging, and Displaying Schema Information

The service supports the following parameters to allow you to perform operations on the primary work items data set:

  • A filter parameter to enable the filtering of result sets

  • A debug matrix parameter to enable you to return the JSON structures in a human readable format

  • A schema matrix parameter to enable you to return the schema for the data set

30.2.2 Complete URI Syntax

The following table shows the complete URI syntax for all resource end points associated with the Workflow Process and Definition Service, along with a description for each URI and a list of supported HTTP methods:

Table 30-1 Resource URIs

URI

Description

/v1

Entry point for the service.

/v1/wf/definitions

Returns a collection (JSON Array) of workflow definitions (provisioning request definitions) available in the Workflow system.

The following HTTP methods are supported with this URI:

GET - This will return a collection of workflow definitions in JSON Array.POST – Not supportedPUT – Not supportedDELETE – Not supported

/v1/wf/definitions/{definition ID}

Returns a specific workflow definition (JSON Object) available in the Workflow system.

The following HTTP methods are supported with this URI:

GET - Returns a specific workflow definition (JSON Object) with all the details. This will include the data items associated with that definition.PUT – Not supported.POST – Start a work flow process.DELETE – Not supported

Starting a workflow process To start a workflow process, you need to perform a GET operation to retrieve a provisioning request definition first. Once you have the JSON structure for the definition, you need to massage this JSON structure and perform a POST. For details on the JSON structure for GET operations, see INSERTXREF. For details on the minimal JSON structure required for POST operations, see INSERTXREF.

/v1/wf/processes

Returns a collection of workflow processes in a JSON Array.

The following HTTP methods are supported with this URI:

GET - Returns a collection of workflow processes currently in the Workflow system in a JSON Array.POST – Not supportedPUT – Not supportedDELETE – Not supported

/v1/wf/processes/{process id}

Returns a single JSON Object with all the workflow process details.

The following HTTP methods are supported with this URI:

GET - Returns a specific work flow process (JSON Object) with all the details. PUT – Not supported.POST – Same as DELETE because of limitations in browsers to set the DELETE method DELETE – Terminates a work flow process

/v1/wf/processes?filter={process parameter}={process value}

Returns a collection of work flow processes (JSON Array) for a specific process query parameter and value.

The possible process query parameters are listed below:

Definition Definition DN

ProcesstId Process request instance ID (GUID)

EngineId Engine ID

Recipient Recipient DN

Initiator Initiator DN

ApprovalStatus Approval status code (Integer)

ProcessStatus Process status code (Integer)

CreationTime Creation time (date-time format) followed by operator (EQ, LT, LE, GT, GE). Example: 20080723044715000-0400EQ

CompletionTime Completion time(date-time format) followed by operator (EQ, LT, LE, GT, GE). Example: 20080723044715000-0400EQ

CorrelationId Correlation ID

Here is an example that illustrates filtering by recipient:

/v1/wf/processes?filter=recipient%3dcn%3dadmin,ou%3didmsample,o%3dnovell

Table 30-2 Matrix Parameters for Debugging and Displaying the Schema

URI

Description

/v1/wf/definitions;debug

This debug matrix parameter displays the definitions JSON structure in human readable format, as opposed to compressed format. This matrix parameter can be put anywhere in the URI.

/v1/wf/definitions/{DefinitionID};debug

This debug matrix parameter displays the definition ID JSON structure in human readable format, as opposed to compressed format. This matrix parameter can be put anywhere in the URI.

/v1/wf/definitions;schema

The schema matrix parameter can be put anywhere in the URI and in combination with the “Accept” header type will return the appropriate schema document for the content type. In this case a JSON schema document is returned for the definitions.

/v1/wf/definitions/{Definition ID};schema

The schema matrix parameter can be put anywhere in the URI and in combination with the “Accept” header type will return the appropriate schema document for the content type. In this case a JSON schema document is returned for the specified definition ID.

/v1/wf/processes;debug

This debug matrix parameter displays the workflow processes JSON structure in human readable format, as opposed to compressed format. This matrix parameter can be put anywhere in the URI.

/v1/wf/processes/{Process ID};debug

This debug matrix parameter displays the process ID JSON structure in human readable format, as opposed to compressed format. This matrix parameter can be put anywhere in the URI.

/v1/wf/processes;schema

The schema matrix parameter can be put anywhere in the URI and in combination with the “Accept” header type will return the appropriate schema document for the content type. In this case a JSON schema document is returned for the workflow processes.

/v1/wf/processes/{Process ID};schema

The schema matrix parameter can be put anywhere in the URI and in combination with the “Accept” header type will return the appropriate schema document for the content type. In this case a JSON schema document is returned for the specified process ID.

30.2.3 JSON Representations Received by the Client

This section shows the JSON structures received by the client for each resource. In each case, the HTTP method is GET.

In all JSON structures, date-time values follow this format:

yyyyMMddhhmmssSSS-ZZZZ

Here is an example that illustrates the format:

20080723044715000-0400

Root entry point

The root entry point returns this structure:

[
   {
      "Link": "/RIS/v1/wf/workitems",
      "Type": "wf/workitems",
      "Value": "Workflow Workitems"
   }
]

Where:Link – relative link to the service availableType – Non localized internal code for the service. Value – Localized value of the service.

Definitions end point

The definitions end point (/v1/wf/definitions) returns a collection (JSON Array) of provisioning request definitions available in the Workflow System.

[
   {
      "Links": [
         {
            "Link": "/RIS/v1/wf/processes?filter=Definition%3Dcn%3DPageWizardForm%2Ccn%3DRequestDefs%2Ccn%3DAppConfig%2Ccn%3DPicassoDriver%2Ccn%3DTestDrivers%2Co%3Dnovell",
            "Type": "wf/processes",
            "Value": "Workflow Processes"
         },
         {
            "Link": "/RIS/v1/wf/workitems?filter=Definition%3Dcn%3DPageWizardForm%2Ccn%3DRequestDefs%2Ccn%3DAppConfig%2Ccn%3DPicassoDriver%2Ccn%3DTestDrivers%2Co%3Dnovell",
            "Type": "wf/workitems",
            "Value": "Workflow Workitems"
         }
      ],
      "DataItems": [{
         "Name": "recipient",
         "Type": "string",
         "Value": ""
      }],
      "Value": "PageWizardForm",
      "DN": "cn=PageWizardForm,cn=RequestDefs,cn=AppConfig,cn=PicassoDriver,cn=TestDrivers,o=novell",
      "GUID": "8d64ba822ada934512968d64ba822ada",
      "Link": "/RIS/v1/wf/definitions/8d64ba822ada934512968d64ba822ada",
      "Category": "entitlements",
      "DigitalSignatureType": "not-required",
      "Description": "PageWizardForm",
      "Operation": "0"
   },
......
]

Single definition end point

The end point for accessing a single definition (/v1/wf/workitems/{work id} returns a single JSON Object with all the details for the definition. The return payload also includes the data items required to start a work flow process.

{
      "Links": [
         {
            "Link": "/RIS/v1/wf/processes?filter=Definition%3Dcn%3DPageWizardForm%2Ccn%3DRequestDefs%2Ccn%3DAppConfig%2Ccn%3DPicassoDriver%2Ccn%3DTestDrivers%2Co%3Dnovell",
            "Type": "wf/processes",
            "Value": "Workflow Processes"
         },
         {
            "Link": "/RIS/v1/wf/workitems?filter=Definition%3Dcn%3DPageWizardForm%2Ccn%3DRequestDefs%2Ccn%3DAppConfig%2Ccn%3DPicassoDriver%2Ccn%3DTestDrivers%2Co%3Dnovell",
            "Type": "wf/workitems",
            "Value": "Workflow Workitems"
         }
      ],
      "DataItems": [{
         "Name": "recipient",
         "Type": "string",
         "Value": ""
      }],
      "Value": "PageWizardForm",
      "DN": "cn=PageWizardForm,cn=RequestDefs,cn=AppConfig,cn=PicassoDriver,cn=TestDrivers,o=novell",
      "GUID": "8d64ba822ada934512968d64ba822ada",
      "Link": "/RIS/v1/wf/definitions/8d64ba822ada934512968d64ba822ada",
      "Category": "entitlements",
      "DigitalSignatureType": "not-required",
      "Description": "PageWizardForm",
      "Operation": "0"
   }

Workflow processes end point

The workflow processes end point (/v1/wf/processes) returns a collection (JSON Array) of running workflow processes available in the Workflow System.

[
   {
      "Links": [{
                   "Type": "wf/workitems",
         "Value": "Workflow Workitems"
         "Link": "/POC/roa/v1/wf/workitems?filter=ProcessId%3De11a2f10c90f489895f968d565b15091"
      }],
      "GUID": "e11a2f10c90f489895f968d565b15091",
      "Link": "/RIS/v1/wf/processes/e11a2f10c90f489895f968d565b15091",
      "Initiator": {
         "DN": "CN=admin,OU=medical-idmsample,O=novell",
         "Value": "Application Administrator Of Sample Data",
         "GUID": "",
         "Link": ""
      },
      "Recipient": {
         "DN": "cn=ablake,ou=users,ou=medical-idmsample,o=novell",
         "Value": "Allison Blake",
         "GUID": "",
         "Link": “"
      },
      "Definition": {
         "Value": "Role Approval",
         "DN": "cn=Role Approval,cn=RequestDefs,cn=AppConfig,cn=CaribouDriver,cn=TestDrivers,o=novell",
         "GUID": "d8c8e1a6d6432341fa84d8c8e1a6d643",
         "Link": "/RIS/v1/wf/definitions/e11a2f10c90f489895f968d565b15091",
         “Version”:”8”
      },
      "Created": "20080723044715000-0400",
      "Completed": "",
      "ApprovalStatus": "Processing",
      "ProcessStatus": "Running",
      "Version": "8",
      "EngineId": "ENGINE"
   }
]

Single workflow process end point

The end point for accessing a single process (/v1/wf/processes/{process id} returns a single JSON Object with all the details for the process.

{
      "Links": [{
                   "Type": "wf/workitems",
         "Value": "Workflow Workitems"
         "Link": "/POC/roa/v1/wf/workitems?filter=ProcessId%3De11a2f10c90f489895f968d565b15091"
      }],
      "GUID": "e11a2f10c90f489895f968d565b15091",
      "Link": "/RIS/v1/wf/processes/e11a2f10c90f489895f968d565b15091",
      "Initiator": {
         "DN": "CN=admin,OU=medical-idmsample,O=novell",
         "Value": "Application Administrator Of Sample Data",
         "GUID": "",
         "Link": ""
      },
      "Recipient": {
         "DN": "cn=ablake,ou=users,ou=medical-idmsample,o=novell",
         "Value": "Allison Blake",
         "GUID": "",
         "Link": “"
      },
      "Definition": {
         "Value": "Role Approval",
         "DN": "cn=Role Approval,cn=RequestDefs,cn=AppConfig,cn=CaribouDriver,cn=TestDrivers,o=novell",
         "GUID": "d8c8e1a6d6432341fa84d8c8e1a6d643",
         "Link": "/RIS/v1/wf/definitions/e11a2f10c90f489895f968d565b15091",
         “Version”:”8”
      },
      "Created": "20080723044715000-0400",
      "Completed": "",
      "ApprovalStatus": "Processing",
      "ProcessStatus": "Running",
      "Version": "8",
      "EngineId": "ENGINE"
   }

30.2.4 JSON Representations Sent by the Client

This section shows the JSON structure sent by the client for the single workitem end point when the HTTP PUT or HTTP POST method is used.

Single definition end point

When the client uses the HTTP POST method with the /v1/wf/definitions/{definition id} URI, the following minimum information from a definition JSON structure is required to start a workflow process.

{
      "DataItems": [{
         "Name": "title",
         "Type": "string",
         "Value": ""
      }],
      "Recipient": "cn=ablake,ou=users,ou=medical-idmsample,o=novell"
}

All elements of the JSON object received from a GET call can be returned to the server. However, only the two items shown above are necessary. All other elements will be ignored by the server.

Single workflow process end point

When the client uses the HTTP DELETE method with the /v1/wf/processes{process id} URI, there is no need to send a JSON object to the server. This action terminates the specified workflow process. The key to the process instance is specified as part of the URI.

30.2.5 Event Status Codes

This section shows the event status codes for the available resources:

Table 30-3 Event Status Codes

URI

Status Codes

/v1

HTTP GET - Status 200 - OK

/v1/wf/definitions

HTTP GET - Status 200 - OK

/v1/wf/definitions/{Definition ID}

HTTP GET – Status 200 – OKHTTP POST – Status 204 – OK with no content

/v1/wf/processes

HTTP GET - Status 200 - OK

/v1/wf/processes/{Process ID}

HTTP GET – Status 200 – OKHTTP DELETE – Status 204 – OK with no contentHTTP POST – Status 204 – OK with no content

30.2.6 JSON Schema

The service supports the use of a schema matrix parameter to return the JSON schema for any returned data set. The JSON schema is based on the proposed schema for JSON as described at:

http://www.json.com/json-schema-proposal/

Root entry point schema

The schema for the root ROA entry point (/v1;schema) is as follows:

{"Link": {
   "description": "schema for: /v1",
   "type": "array",
   "properties": {
      "Link": {"type": "string"},
      "Type": {
         "type": "string",
         "enum": [
            "root",
            "wf/definitions",
            "wf/processes",
            "wf/workitems"
         ]
      },
      "Value": {"type": "string"}
   }
}}

Definitions end point schema

The schema for the definitions end point (/v1/wf/definitions;schema) is as follows:

{"DefinitionInfo": {
   "description": "schema for: /v1/wf/definitions",
   "type": "array",
   "properties": {
      "Links": {
         "type": "array",
         "properties": {
            "Link": {"type": "string"},
            "Type": {
               "type": "string",
               "enum": [
                  "root",
                  "wf/definitions",
                  "wf/processes",
                  "wf/workitems"
               ]
            },
            "Value": {"type": "string"}
         }
      },
      "DataItems": {
         "type": "array",
         "properties": {
            "Name": {"type": "string"},
            "Type": {"type": "string"},
            "Value": {"type": "string"}
         }
      },
      "Value": {"type": "string"},
      "DN": {"type": "string"},
      "GUID": {"type": "string"},
      "Link": {"type": "string"},
      "Category": {"type": "string"},
      "LegalDisclaimer": {"type": "string"},
      "DigitalSignatureType": {"type": "string"},
      "Description": {"type": "string"},
      "Operation": {"type": "string"},
      “Recipient”: {“type”: “string”}
   }
}}

Single definition end point schema

The schema for the single definition end point (/v1/wf/definitions/{Definition id};schema) is as follows:

{
   "description": "schema for: /v1/wf/definitions/{Definition ID}",
   "type": "object",
   "properties": {
      "Links": {
         "type": "array",
         "properties": {
            "Link": {"type": "string"},
            "Type": {
               "type": "string",
               "enum": [
                  "root",
                  "wf/definitions",
                  "wf/processes",
                  "wf/workitems"
               ]
            },
            "Value": {"type": "string"}
         }
      },
      "DataItems": {
         "type": "array",
         "properties": {
            "Name": {"type": "string"},
            "Type": {"type": "string"},
            "Value": {"type": "string"}
         }
      },
      "Value": {"type": "string"},
      "DN": {"type": "string"},
      "GUID": {"type": "string"},
      "Link": {"type": "string"},
      "Category": {"type": "string"},
      "LegalDisclaimer": {"type": "string"},
      "DigitalSignatureType": {"type": "string"},
      "Description": {"type": "string"},
      "Operation": {"type": "string"},
      “Recipient”: {“type”: “string”}
   }

Workflow processes end point schema

The schema for the processes end point (/v1/wf/processes;schema) is as follows:

{"ProcessInfo": {
   "description": "schema for: /v1/wf/processes",
   "type": "array",
   "properties": {
      "Links": {
         "type": "array",
         "properties": {
            "Link": {"type": "string"},
            "Type": {
               "type": "string",
               "enum": [
                  "root",
                  "wf/definitions",
                  "wf/processes",
                  "wf/workitems"
               ]
            },
            "Value": {"type": "string"}
         }
      },
      "GUID": {"type": "string"},
      "Link": {"type": "string"},
      "Initiator": {
         "type": "object",
         "properties": {
            "DN": {"type": "string"},
            "Value": {"type": "string"},
            "GUID": {"type": "string"},
            "Link": {"type": "string"}
         }
      },
      "Recipient": {
         "type": "object",
         "properties": {
            "DN": {"type": "string"},
            "Value": {"type": "string"},
            "GUID": {"type": "string"},
            "Link": {"type": "string"}
         }
      },
      "Definition": {
         "type": "object",
         "properties": {
            "Value": {"type": "string"},
            "DN": {"type": "string"},
            "GUID": {"type": "string"},
            "Link": {"type": "string"}
         }
      },
      "Created": {
         "type": "string",
         "format:": "date-time"
      },
      "Completed": {
         "type": "string",
         "format:": "date-time",
         "optional": true
      },
      "Proxy": {
         "type": "string",
         "optional": true
      },
      "CorrelationId": {
         "type": "string",
         "optional": true
      },
      "ApprovalStatus": {"type": "string"},
      "ProcessStatus": {"type": "string"},
      "Version": {"type": "string"},
      "EngineId": {"type": "string"}
   }
}}

Single process end point schema

The schema for the single process end point (/v1/wf/processes/{Process ID};schema) is as follows:

{
   "description": "schema for: /v1/wf/processes/{Process ID}",
   "type": "object",
   "properties": {
      "Links": {
         "type": "array",
         "properties": {
            "Link": {"type": "string"},
            "Type": {
               "type": "string",
               "enum": [
                  "root",
                  "wf/definitions",
                  "wf/processes",
                  "wf/workitems"
               ]
            },
            "Value": {"type": "string"}
         }
      },
      "GUID": {"type": "string"},
      "Link": {"type": "string"},
      "Initiator": {
         "type": "object",
         "properties": {
            "DN": {"type": "string"},
            "Value": {"type": "string"},
            "GUID": {"type": "string"},
            "Link": {"type": "string"}
         }
      },
      "Recipient": {
         "type": "object",
         "properties": {
            "DN": {"type": "string"},
            "Value": {"type": "string"},
            "GUID": {"type": "string"},
            "Link": {"type": "string"}
         }
      },
      "Definition": {
         "type": "object",
         "properties": {
            "Value": {"type": "string"},
            "DN": {"type": "string"},
            "GUID": {"type": "string"},
            "Link": {"type": "string"},
            "Version": {"type": "string"}
         }
      },
      "Created": {
         "type": "string",
         "format:": "date-time"
      },
      "Completed": {
         "type": "string",
         "format:": "date-time",
         "optional": true
      },
      "Proxy": {
         "type": "string",
         "optional": true
      },
      "CorrelationId": {
         "type": "string",
         "optional": true
      },
      "ApprovalStatus": {"type": "string"},
      "ProcessStatus": {"type": "string"},
      "Version": {"type": "string"},
      "EngineId": {"type": "string"}
   }
}

30.2.7 Testing the Client with the CURL Command

You can use the CURL command to test the REST client.

Table 30-4 CURL Commands for Testing the Client

URI

Command

http://domain:port/RIS/v1

curl -v -H "Accept: application/json" http://domain:port/RIS/v1

wf/definitions

curl -v -H "Accept: application/json" http://domain:port/RIS/v1/wf/definitions

wf/definitions/{defintion id}

curl -v -H "Accept: application/json" http://domain:port/RIS/v1/wf/definitions/{definition id}

wf/definitions/{definition id}

To start a process, store the JSON structure in a file and pass it to the curl command.

curl -v -H "Content-Type: application/json" -X POST --data-binary @<filename of JSON structure> http://domain:port/RIS/v1/wf/definitions/{definition id}

wf/processes

curl -v -H "Accept: application/json" http://domain:port/RIS/v1/wf/processes

wf/processes/{request id}

curl -v -H "Accept: application/json" http://domain:port/RIS/v1/wf/processes/{request id}

wf/processes/{request id}

To terminate a process, store the JSON structure in a file and pass it to the curl command.

curl -v -H "Accept: application/json" -X DELETE http://domain:port/RIS/v1/wf/processes/{request id}