The Provisioning Work Items Service exposes resources to retrieve provisioning work item information. The service allows a user is able to retrieve all work items related to himself or herself and then act upon a specific work item if so desired (Approve, Deny, Refuse).
There are three types of resources available for the service. These resources are described in the sections that follow:
The entry point URI for the Provisioning Work Items Service is:
/v1
The root entry point returns a list of all resources available.
The service provides a resource URI for every object exposed. The Work Items resource supports two basic URI patterns:
Resource for returning a collection of work items
Resource for returning a specific work item instance
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
The following table shows the complete URI syntax for all resource end points associated with the Work Items Service, along with a description for each URI and a list of supported HTTP methods:
Table 29-1 Resource URIs
|
URI |
Description |
|---|---|
|
/v1 |
Entry point for the service. |
|
/v1/wf/workitems |
Will return a collection (JSON Array) of work items available in the work flow sub system. Note: the URI is preceded with “wf/” this is to allow us to introduce other work flow related ROA services in the future such as “wf/processes” which will list all processes available in the work flow sub system. The following HTTP methods are supported with this URI: GET - This will return a collection of work items (JSON Array).POST – Not supportedPUT – Not supportedDELETE – Not supported |
|
/v1/wf/workitems?filter={parameter}={value} |
Return a collection of work items (JSON Array) for a specific addressee DN. The possible query parameters are listed below: Addressee Addressee DN DefinitionId Process DN ProcesstId Process request instance ID (GUID) ActivityId Activity ID Status Status code (Integer) Owner Owner DN Priority Priority (Integer) CreationTime Creation time (date-time format) followed by operator (EQ, LT, LE, GT, GE). Example: 20080723044715000-0400EQ ExpTime Expiry 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 Recipient Recipient DN Initiator Initiator DN Here is an example that illustrates filtering by addressee: /v1/wf/workitems?filter=addressee%3dcn%3dadmin,ou%3didmsample,o%3dnovell |
|
/v1/wf/workitems?filter=workid={work id} |
Return a specific work item (JSON Array) instance based on the work item GUID. Example: /v1/wf/workitems?filter=workid%3d456789afbc78 Note: the URI must be fully URL encoded. |
|
/v1/wf/workitems/{WorkId} |
This will return a single JSON Object with all the work item details. This will include the data items and actions allowed on the work item. The following HTTP methods are supported with this URI: GET - Return a specific work item instance (JSON Object) with all details. This will include the actions supported and data items available for that work itemPUT – Forward the appropriate action on the work item.POST – Same as PUT because of limitations in browsers to set the PUT method DELETE – Not supported |
Table 29-2 Matrix Parameters for Debugging and Displaying the Schema
|
URI |
Description |
|---|---|
|
/v1/wf/workitems;debug |
This debug matrix parameter displays the workitems JSON structure in human readable format, as opposed to compressed format. This matrix parameter can be put anywhere in the URI. |
|
/v1/wf/workitems/{WorkId};debug |
This debug matrix parameter displays the work ID JSON structure in human readable format, as opposed to compressed format. This matrix parameter can be put anywhere in the URI. |
|
/v1/wf/workitems;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 workitems. |
|
/v1/wf/workitems/{WorkId};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 work ID. |
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
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.
The workitems end point (/v1/wf/workitems) returns a collection (JSON Array) of work items available in the Workflow subsystem.
[
{
"AvailableActions": [
{
"Value": "Deny",
"Code": "1"
},
{
"Value": "Approve",
"Code": "0"
}
],
"GUID": "6d8650ac062548fb84cb0e21bfc3cea6",
"Link": "/RIS/v1/wf/workitems/6d8650ac062548fb84cb0e21bfc3cea6?filter=ProcessId%3Dc24dc77790ea497eb07617341c01e718",
"ActivityId": "Activity",
"ActivityName": "Approve Role Request (Serial)",
"Addressee": {
"DN": "cn=admin,ou=medical-idmsample,o=novell",
"Value": "Application Administrator Of Sample Data",
"GUID": "",
"Link": “"
},
"AssignmentType": "0",
"Created": "20080723044715000-0400",
"Owner": "Unclaimed",
"Priority": "2",
"Definition": {
"Value": "Role Approval",
"DN": "cn=Role Approval,cn=RequestDefs,cn=AppConfig,cn=CaribouDriver,cn=TestDrivers,o=novell",
"GUID": "",
"Link": "",
"Version": "8"
},
"Process": {
"GUID": "c24dc77790ea497eb07617341c01e718",
"Link":”"
},
"Status": "0",
"DigitalSignatureType": "not-required",
"Initiator": {
"DN": "CN=admin,OU=medical-idmsample,O=novell",
"Value": "Application Administrator Of Sample Data",
"GUID": "",
"Link":”"
},
"Recipient": {
"DN": "cn=admin,ou=medical-idmsample,o=novell",
"Value": "Application Administrator Of Sample Data",
"GUID": "",
"Link":”"
}
},
.....
]
The end point for accessing a single workitem (/v1/wf/workitems/{work id} returns a single JSON Object with all the workitem details. This object includes the data items and actions allowed on the workitem.
{
"AvailableActions": [
{
"Value": "Deny",
"Code": "1"
},
{
"Value": "Approve",
"Code": "0"
}
],
"DataItems": [
{
"Name": "RequestNumber",
"Type": "string",
"Value": "20080723104715-53f04600fba5496c97ac76f7ff289b6f-0"
},
{
"Name": "RequesterName",
"Type": "string",
"Value": "cn=admin,ou=medical-idmsample,o=novell"
},
{
"Name": "Operation",
"Type": "string",
"Value": "Add Role To User"
},
{
"Name": "SourceDN",
"Type": "string",
"Value": "rudy test"
},
{
"Name": "TargetDN",
"Type": "string",
"Value": "Allison Blake"
},
{
"Name": "RequestDate",
"Type": "string",
"Value": "20080723044715000-0400"
},
{
"Name": "StartDate",
"Type": "string",
"Value": "20080723044715000-0400"
},
{
"Name": "Description",
"Type": "string",
"Value": "rudy"
},
{
"Name": "CurrentStatus",
"Type": "string",
"Value": "Approval Pending"
}
],
"GUID": "f06881a871834653991f2c000f21c782",
"Link": "/RIS/v1/wf/workitems/f06881a871834653991f2c000f21c782?filter=ProcessId%3De11a2f10c90f489895f968d565b15091",
"ActivityId": "Activity",
"ActivityName": "Approve Role Request (Serial)",
"Addressee": {
"DN": "cn=admin,ou=medical-idmsample,o=novell",
"Value": "Application Administrator Of Sample Data",
"GUID": "",
"Link": “"
},
"AssignmentType": "0",
"Created": "20080723044715000-0400",
"Owner": "Unclaimed",
"Priority": "2",
"Definition": {
"Value": "Role Approval",
"DN": "cn=Role Approval,cn=RequestDefs,cn=AppConfig,cn=CaribouDriver,cn=TestDrivers,o=novell",
"GUID": "",
"Link": "",
"Version": "8"
},
"Process": {
"GUID": "e11a2f10c90f489895f968d565b15091",
"Link":”"
},
"Status": "0",
"DigitalSignatureType": "not-required",
"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": “"
}
}
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.
When the client uses the HTTP PUT or HTTP POST method with the /v1/wf/workitems/{work id} URI, the JSON Object structure is the same as the GET operation. However, the only information used by the server is the AvailableActions and the DataItems sections. The first available action found is taken as the forwarding action to perform on the work item.
{
"AvailableActions": [
{
"Value": "Approve",
"Code": "0"
}
],
"DataItems": [
{
"Name": "RequestNumber",
"Type": "string",
"Value": "20080723104715-53f04600fba5496c97ac76f7ff289b6f-0"
},
{
"Name": "RequesterName",
"Type": "string",
"Value": "cn=admin,ou=medical-idmsample,o=novell"
},
{
"Name": "Operation",
"Type": "string",
"Value": "Add Role To User"
},
{
"Name": "SourceDN",
"Type": "string",
"Value": "rudy test"
},
{
"Name": "TargetDN",
"Type": "string",
"Value": "Allison Blake"
},
{
"Name": "RequestDate",
"Type": "string",
"Value": "20080723044715000-0400"
},
{
"Name": "StartDate",
"Type": "string",
"Value": "20080723044715000-0400"
},
{
"Name": "Description",
"Type": "string",
"Value": "rudy"
},
{
"Name": "CurrentStatus",
"Type": "string",
"Value": "Approval Pending"
}
]
}
This section shows the event status codes for the available resources:
Table 29-3 Event Status Codes
|
URI |
Status codes |
|---|---|
|
/v1 |
HTTP GET - Status 200 - OK |
|
/v1/wf/workitems |
HTTP GET - Status 200 - OK |
|
v1/wr/workitems/{work id} |
HTTP GET – Status 200 – OKHTTP PUT – Status 204 – OK with no contentHTTP POST – Status 204 – OK with no content |
The Jersey implemented error conditions are used. When server errors are found, Jersey returns the appropriate 400 and 500 level codes.
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/
The schema for the root ROA entry point (/v1;schema) is as follows:
{
“description” : “schema for: /v1”,
“type” : “array”,
“properties” :
{
"Link": {"type" : “string”,
“enum“: [“/RIS/v1/wf/workitems“]
},
"Type": {“type” : "string",
“enum“: [“wf/workitems“]
},
"Value":{“type” : “string”,
“enum“: [“Workflow Workitems“]
}
}
}
The schema for the workitems end point (/v1/wf/workitems;schema) is as follows:
{
“description” : “schema for: /v1/wf/workitems”,
“type” : “array”,
“properties” :
{
"AvailableActions" :
{ “type” : “array”,
“properties” :
{
"Value" :
{ "type" : “string”,
“enum“: [“Approve”, “Deny“, “Refuse”]
}
"Code" :
{ "type" : “integer”,
“enum“: [0, 1, 2]
}
},
"DataItems":
{ “type” : “array”,
“properties” :
{
"Name": { “type” : “string”},
"Type": { “type” : “string”},
"Value": { “type” : “string”}
}
},
"GUID" : { “type” : “string”},
"Link" : { “type” : “string”},
"ActivityId" : { “type” : “string”},
"ActivityName" : { “type” : “string”},
"Addressee":
{ “type” : “object”,
“properties” :
{
"DN": { “type” : “string”},
"Value": { “type” : “string”},
"GUID": { “type” : “string”},
"Link": { “type” : “string”}
},
"AssignmentType": { “type” : “integer”},
"Created":
{ “type” : “string”,
“format” : “date-time”
},
"ExpiryDate":
{ “type” : “string”,
“format” : “date-time”,
“optional” : “true”
},
"Owner": { “type” : “string”},
"Priority": { “type” : “integer”},
"Definition":
{ “type” : “object”,
“properties” :
{
"Value": { “type” : “string”},
"DN": { “type” : “string”},
"GUID": { “type” : “string”},
"Link": { “type” : “string”},
"Version": { “type” : “string”}
}
},
"Process":
{ “type” : “object”,
“properties” :
{
"GUID": { “type” : “string”},
"Link": { “type” : “string”}
}
},
"Status": { “type” : “integer”,
“minimum” : 0,
“maximum” : 5
},
"LegalDisclaimer": { "type": "string",
"optional": true
}
"DigitalSignatureType":
{ “type” : “string”,
“enum“: [“data“. “form”, “not-required”]
},
"Completed":
{ “type” : “string”,
“format” : “date-time”,
“optional” : “true”
},
"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”}
}
},
"ProxyFor": { "type": "object",
"properties":
{
"DN": {"type": "string"},
"Value": {"type": "string"},
"GUID": {"type": "string"},
"Link": {"type": "string"
},
"optional": true
}
}
}
The schema for the single workitem end point (/v1/wf/workitems/{work id};schema) is as follows:
{
“description” : “schema for: /v1/wf/workitems{work id}”,
“type” : “object”,
“properties” :
{
"AvailableActions" :
{ “type” : “array”,
“properties” :
{
"Value" :
{ "type" : “string”,
“enum“: [“Approve”, “Deny“, “Refuse”]
}
"Code" :
{ "type" : “integer”,
“enum“: [0, 1, 2]
}
},
"DataItems":
{ “type” : “array”,
“properties” :
{
"Name": { “type” : “string”},
"Type": { “type” : “string”},
"Value": { “type” : “string”}
}
},
"GUID" : { “type” : “string”},
"Link" : { “type” : “string”},
"ActivityId" : { “type” : “string”},
"ActivityName" : { “type” : “string”},
"Addressee":
{ “type” : “object”,
“properties” :
{
"DN": { “type” : “string”},
"Value": { “type” : “string”},
"GUID": { “type” : “string”},
"Link": { “type” : “string”}
},
"AssignmentType": { “type” : “integer”,
“minimum” : 0,
“maximum” : 17
},
"Created":
{ “type” : “string”,
“format” : “date-time”
},
"ExpiryDate":
{ “type” : “string”,
“format” : “date-time”,
“optional” : “true”
},
"Owner": { “type” : “string”},
"Priority": { “type” : “integer”},
"Definition":
{ “type” : “object”,
“properties” :
{
"Value": { “type” : “string”},
"DN": { “type” : “string”},
"GUID": { “type” : “string”},
"Link": { “type” : “string”},
"Version": { “type” : “string”}
}
},
"Process":
{ “type” : “object”,
“properties” :
{
"GUID": { “type” : “string”},
"Link": { “type” : “string”}
}
},
"Status": { “type” : “integer”,
“minimum” : 0,
“maximum” : 5
},
"LegalDisclaimer": { "type": "string",
"optional": true
}
"DigitalSignatureType":
{ “type” : “string”,
“enum“: [“data“. “form”, “not-required”]
},
"Completed":
{ “type” : “string”,
“format” : “date-time”,
“optional” : “true”
},
"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”}
}
},
"ProxyFor": { "type": "object",
"properties":
{
"DN": {"type": "string"},
"Value": {"type": "string"},
"GUID": {"type": "string"},
"Link": {"type": "string"
},
"optional": true
}
}