Work Item Service API Specification

What Is the Work Item Service?

The work item service provides a standard way for services to present work items to users. The work item service:

• Provides a central repository of work items in the suite of services, which presents users with a single view of all of their work items.
• Manages assignment of work items to users and groups.
• Provides a user interface for viewing and completing work items.
• Sends notifications of work item events via the notification service.
• Manages the life-cycle of a work item and passes events back to the system that created it.
• Allows you to reassign certain work items to other users or assign delegates for all different types of work items once.

The work item service does not:

• Decide when a work item must be created.
• Perform actions when work items are completed, i.e., does not advance workflows, if, for example an approval request has been approved.
• Contain policies that overlap with externally defined policies, such as approval policies.

Typical Use Cases

Using the work item service:

• Provider applications create work item types and specify the actions that the work item type can enable. Provider applications can also modify and update or cancel work items.
• Integrators use an extension point that is hosted on the work item page to render context-specific data for the work item. For example, a travel application might embed a seating chart into the manual seat assignment task for a travel request.
• End users view a list of the work items assigned or delegated to them. They can also reassign work items to users or groups that belong to their organization.
• Assignees, delegates of an assignee, or privileged administrator users complete work items.

Key Concepts

Work Item

A work item represents a piece of work that must be carried out by an end user. Examples of work items are:

• An approval request - A request for a user to approve an action such as a request for a catalog item.
• A manual task - A request for a user to perform some action as part of a workflow. For example, VCO user interactions can generate manual tasks.

• A remediation task - Tasks that are generated because a request has failed. Remediation tasks would request that a user intervene and attempt to resolve the problem that caused a request to fail.

    Note: The above tasks are examples of work item types. They are not concrete types that will be
    provided by the work item queue.
  

Many services can have requirements to generate work items. These work items may mean different things, but at their core, they:

• Are a call to action for a user.
• Generate notifications when certain events occur.
• Are completed by a user performing some action.
• May require a form to be filled in.

While each application in the suite could implement its own work item functionality, this would:

• Lead to duplication throughout the suite.
• Potentially lead to inconsistent implementations.
• Make it difficult to present a user with a single view of all of their work items.

Services and Service Types

This specification refers to services and service types in the context of work item types and refers to another software component. These should NOT be interpreted to be services in the Service Catalog sense of the word.

UI Elements and Use Cases

The UI enables the following functionality.

View a List of Work Items

The UI displays a list of work items that are:

• Assigned to the current user
• Delegated to the current user

It displays all types of work item in a single list, and supports filtering work items by:

• Assigned versus delegated
• Work item type
• Active versus completed

Cancelled work items do not appear in this list.

View/Edit a Specific Work Item

The UI for viewing/editing a work item:

• Displays the selected work item.
• When using its linked form to generate the screen, populates the screen with the data from the work item's form data.
• Displays work item metadata separately.
• Displays the actions available to complete the current work item, as buttons, for example.
• Allows a work item to be updated without performing an action.
• Processes rules embedded in the layout.

Extension Point

The work item detail page can host an extension point into which integrators may render context specific data in support of the work item. Qualifying extensions must be of type csp.placesand declare their hostExtensionId as being cafe.inbox.detail.

For example, the following snippet shows what the vTravel application might declare to embed a seating chart in the manual seat assignment task of a travel request.

"extensions": [
{
"pointId": "csp.places",
"extensionId": "travel.inbox.seatingTask",
"hostExtensionId": "cafe.inbox.detail",
"description": "Seating chart for a travel destination",
...
}
]

Work Item Portlet

The work item portlet shows a list of work items assigned or delegated to the current use. The number of work items shown is configurable (the default is 10 work items). Functionally, it is the same as the work item list.

Model

This section describes the model for the work item service.

Work Item Type

Note the following points about a work item type:

• It represents a specific type of work item.
• It may define an icon. If specified, this can be used to differentiate between work items of different types.
• It is owned by a specific application.
• It is registered by the owning application once (for example, at install time or the first time that the application is run, like the approval service, which registers the "Approval" work item type.

• Defines a number of actions that may be used to complete work items of this type:

  • Actions are ordered. The ordering of actions affects how they are displayed in a UI.
  • A default action may be specified.
  • A work item type may specify no action. In this case a generic "complete" action will be available.

• The behavior of the generic action is the same as any other action:

  • It causes the work item to be completed
  • It notifies the provider that the work item has been completed.

Work Item

A work item:

• Represents a single work item that is assigned to a recipient.
• Is assigned to a single recipient.

A recipient may be a user or a group.

When assigned to a group:

• The work item is not duplicated.
• Any member of the group may update or complete the work item.

Once a single member of the group updates the work item, no other members may do so.

Work Item States

A work item can exist in the following states:

• Active - The work item has been created and assigned but not yet completed. It may be updated, or reassigned.
• Completed - The work item has been completed as a result of some action.
• Canceled - The work item has been canceled.

Work Item Data

A work item presents two sets of data:

• The work item's own properties. These include things such as:
• Who it is assigned to
• What type it is
• What state it is in

• The form data defined by the work item's form. This may be anything, for example:

  • Approval related properties, for example, justification
  • Request related properties, for example, what was requested, how much, number of CPUs, and so on.

While the work item presents both of these sets of data, it does not own the form data. The form is a resource provided by some client application and provides a view of the data in that client application. The client application remains the owner of that data. For example, the approval service owns approval requests and does not relinquish this ownership to the work item service. Therefore:

• The work item does not persist a copy of the form data.
• The work item service is not considered a source of truth for form data.
• Persisting a copy in the work item service would introduce complicated synchronization concerns.

To implement form data:

• All form data is served live from the application that created the work item.
• Client applications must provide a REST endpoint that can serve this data.
• Client applications may delegate a portion of this to another application, but this must be transparent to the work item queue; for examplle, the approval service would need to pass the request along to the catalog to retrieve Request data.

As a result:

• It is prohibitive to retrieve live data when displaying many work items in a list. Therefore, work items also provide descriptive properties that:

  • Give a short description of the work item's purpose.
  • Are provided by the client application when the work item is created.
  • Are an intrinsic property of a work item and are hence easily retrieved for display in a list/grid view.

It is not possible to show form data in work item lists.

Assignment

A work item must be assigned to one or more assignees. This is enforced when the work item is created. An assignee may be:

• A group
• An individual

All assignees have access to the same work item:

• A unique work item is not created for each assignee.
• Any assignee may update the work item.
• Any assignee may complete the work item.
• Once complete, no other assignee may act on the work item.

If a use case demands that a work item is assigned to a group AND that each member of the group receive a unique work item, then it is the responsibility of the caller to expand the group and to create and assign one work item per group member.

For example, if an approval policy specified that all members of a group must approve an approval, the approval service would expand the group's membership and create one work item per member of the group.

It is also the responsibility of the client application to close/reject/abort any work items that may no longer be applicable. For example, if one user rejects an approval, the approval service is responsible for aborting the outstanding work items (if required).

Forms

A work item must specify a form. The form is used to:

• Display the work item in the web UI
• Generate notifications

A work item's form is:

• Not persisted within the work item. Instead it is provided by the client application, which is then the form provider.
• Is not persisted by the work item service. The form is retrieved from an external location specified by the form provider.
• The form must follow the vRA Shared Data Driven Format standard.

Work Item History

Each work item has a history of events related to that work item. Events include:

• Creation
• Assignment
• Reassignment
• Notifications
  • Sent
  • Received
• Work Item Updates
• Work Item Completion
• Work Item Cancellation

The work item history must capture the following:

• The user who performed the action.
• The action that was performed, for example, Completed, Updated, Reassigned. If the action is Completed, the completion action used to complete the work item, for example, Approved/Rejected.
• The date and time that the action was performed.

• A description of the action that was performed. This might be:

  • User generated; for example, a user types in some reason why they performed an action.
  • Machine generated;for example, another application generates a message. An example message might be something like "Approval request cancelled because it was no longer required."

Action

• Represents an action that a user may take to complete a work item.
• Is defined by the work item type of the work item.
• Has a unique ID that is provided by the publishing application.
• The unique ID is passed back to the publishing application when the action occur.
• It is expected that the publisher will recognise this id and may do something as a result of this action.

For example, when an approval work item is approved, the action id "approved" would be sent back to the approval service. The approval service can then update the approval as required.

Summary of Operations

Create Work Item Type

Create Work Item Type:

• Is performed by provider applications with solution-level privileges; for example, the approval service creates the "Approval" work item type.
• The provider specifies the actions that this work item type will have.
• Providers should be trusted not to maliciously interfere with other applications' work item types.
• The work item service is designed to prevent accidental interference, for example, it raises an error if an application attempts to register a work item type with a duplicate id. Do not accept it as an update.

Create Work Item

Create Work Item is initiated by a provider application, for example, by the approval service creating an approval.

Update Work Item

A work item may be updated by:

• One of its assignees.
• A delegate of one of its assignees.

In addition:

• The application that created the work item is notified of all updates.
• Client applications must provide a REST service to receive these updates. This service will be passed:
  • The updated form data for the work item as a property map.
  • Useful metadata (for example, who updated the work item and when) in a fixed schema.

Reassign Work Item

• A work item can be reassigned by any of its assignees, including delegates.
• Work items may be reassigned only to users or groups belonging to the same organization as the user performing the reassignment.
• The reassignment API should support reassigning to multiple principals, even if the UI does not.
• Reassignment replaces all of the current assignees with a new set of assignees.

Taking Ownership of a Work Item

Taking ownership of a work item:

• Makes the current user the sole assignee of a work item.
• Is not required in order to complete or update a work item.
• Is a specific action that a user must take.
• Should be surfaced in the UI as a separate action/button.
• Should not happen automatically because a user has viewed or updated a work item.
• Should re-use the reassignment API, i.e,. take ownership is effectively a shortcut for "reassign to me."

Complete Work Item

A work item may only be completed by:

• One of its assignees.
• A delegate of one of its assignees.

• A privileged, administrator user.

Note also that:

• A work item may be completed by any of the actions associated with its work item type.
• Work items may be completed via an incoming notification (for example, email). This may be done by replying to an email sent by the work item queue.
• The client application will be notified when a work item is completed.

• The client application must provide a REST service to be notified of completion. The service will be passed:

  • The form data of the work item that has been completed.
  • The action that completed the work item.
  • Useful work item metadata.

Cancel Work Item

Canceling a work item prevents a work item from being updated or completed The work item enters the cancelled state.

A work item:

• May only be cancelled by a solution user, i.e., the application that created the work item.
• Should be cancelled when it is no longer required.

This would be determined by the client application based on its rules. For example, the approval service may cancel any outstanding "Approval" work items once one of the approvers has rejected the approval.

Work items may not be cancelled by non-solution users.

Once aborted a work item may not be:

• Reactivated
• Updated

Note also that:

• A cancelled work item is not deleted.
• A work item's data may not be updated when aborting a work item.
• The client application will not be notified when a work item is cancelled.
• An audit trail message is written when a work item is cancelled. The cancellation API should support passing a reason why a work item has been cancelled which is also part of the audit trail.

If an application wished to offer a "Cancel" action for a work item, it would need to:

• Define such an action on the work item type.
• Respond to this action when the item is completed.

User Roles

Normal users can:

• Only view work items assigned to them.
• Update or complete work items assigned to them.
• Configure delegation for their work items.

Tenant administrators can:

• Reassign work items to other users in their organization.
• Cancel work items assigned to users in their organization.

Notifications

• Notifications will be sent via the notification service.
• Notifications are generated automatically by the work item queue for lifecycle events.

Outbound Notifications

• Outbound notifications are generated by lifecycle events of a work item.
• When sending outbound notifications, the work item service will pass a set of recipients to the notification service.
• Recipients may users and groups.
• The work item service delegates responsibility for handling group recipients to the notification service.

• Determine whether a group recipient has an address associated with it.
• Expand the group to its members if it does not.

Inbound Notifications

The work item service supports completing work items via inbound notifications, for example, email:

• The sender of an inbound notification must be the assignee of the work item or a member of the group when a work item is assigned to a group.

• Inbound notifications cannot be used to:

  • Reassign a work item
  • Cancel a work item

Delegation

Delegation allows specific people to complete a task on behalf of the assignee:

• Delegating a work item grants the delegate access to the work item.
• Delegation does not assign the work item to the delegate.
• Delegation does not prevent the assignee from performing actions on the work item.
• A work item may have zero or more delegates.
• A delegate may not re-delegate the work item.
• Delegates receive all notifications that are sent to the work item's assignee.
• Delegation is configured within the work item queue. It is not configured by applications that create work items.

Configuration

There may be multiple delegation configurations per user. Each configuration specifies:

• The delegates defined as a set of principals.
• The work item type that this delegation configuration applies to.
• A start date on which the delegation will become active.
• To support an out of office scenario.
• An end date on which the delegation will cease.