Assign Work Item

This synchronous Integration Point (IP) allows an assignor to assign one or more work items to a single assignee.

Request

This API supports the following POST operation:

POST http://[hostName]:[portNumber]/[api-context-root]/workitems/assign/{assigneeuserid}

Payload

{
  "workitemList": [
    { "id": "" },
    { "id": "" }
  ]
}

assigneeuserid

User ID of the user to whom the work items will be assigned. Required.

workitemList

List of work items to be assigned in this request. A maximum of 500 entries is supported per request. Required.

id

Unique identifier of the work item to be assigned. Required.

Details

A work item cannot be assigned under any of the following conditions:

• The work item does not exist, or is in done status.

• The assignee is missing or not provided.

• The assignor does not hold the Queue Admin access role for the work item’s queue.

• The assignee does not hold the Queue User access or Queue Admin access role for the work item’s queue.

• After successful processing:

  • If the work item is unassigned, it is assigned to the specified assignee.

  • If the work item is currently assigned to a different user, it is reassigned to the specified assignee.

  • If the work item is already assigned to the same assignee, no change is made to the work item record and no work item history entry is written, though the request is still treated as a success.

  • For any successful assignment, the work item record is updated and a new work item history entry is written. For more information, see Work Item History.

"Self-assignment is allowed if the user holds the Queue Admin role on the queue"

Assignment Notification

When a work item is assigned to a user, a notification is generated and delivered to a configured endpoint.

The notification is skipped when:

• No work item notification is linked to the Queue Definition.

• No assigned dynamic logic is configured for the linked work item notification.

Endpoint

The notification definition code is derived from the work item notification resource linked to the Queue Configuration of the work item’s queue. The code attribute on that entity is used as the notification definition code for all property resolution described below.

The generic work item notification endpoint is configured through the following system property:

ohi.worklist.notification.endpoint

The endpoint can be overridden for a specific notification definition code by configuring:

ohi.worklist.notification.endpoint.{0}

• When the placeholder is replaced with the work item notification code, the system delivers the notification for that code to a specific endpoint.

• If a notification endpoint is configured for a specific notification definition code, all other supporting properties are resolved using that same code; otherwise, built-in defaults are used.

• If the endpoint is configured without a notification definition code, all other supporting properties are resolved using the generic code WorklistNotificationClient.

Supporting Properties

The following optional properties control how the notification call is made. Replace {0} with the work item notification code for code-specific configuration, or use WorklistNotificationClient when configuring for the generic endpoint.

Category	Property Name	Allowed Values / Example	Description
Media Type	ohi.worklist.service.{0}.media.type	Optional. Sample: ohi.worklist.service.WorklistNotificationClient.media.type=application/json ohi.worklist.service.<code>.media.type=application/xml	The media type used when sending the notification to the external endpoint. Default: application/json.
HTTP Method	ohi.worklist.service.{0}.notification.method	Optional. Possible values are POST or PUT. ohi.worklist.service.WorklistNotificationClient.notification.method=POST ohi.worklist.service.<code>.notification.method=PUT	The HTTP method used to send the notification. Default: POST.
Authentication Mechanism	ohi.worklist.service.{0}.client.authentication	Optional. Possible values are BasicAuthentication, OAuth, or None. ohi.worklist.service.WorklistNotificationClient.client.authentication=BasicAuthentication ohi.worklist.service.<code>.client.authentication=None	The authentication mechanism used when invoking the notification endpoint. Default: BasicAuthentication.

If the authentication mechanism is not None, credentials must be set up.

For BasicAuthentication, credentials are configured through the Credentials Integration Point. The credentialKey used to register the credentials must match the key used to configure the endpoint: either the generic WorklistNotificationClient or the specific notification code (for example, <WNOT_CODE>).

For OAuth, credentials are configured as described in Securing Outbound RESTful Service Invocations using OAuth 2.0, section Callout Rule.

Notification Response

• If notification is not configured for a work item, the notification process is skipped.

• If notification is configured but delivery does not succeed, it is treated as a failure.

  • On notification failure, an error task is created in the OHI Task Framework. A user can review the error task, address the underlying issue, and restart the task to resend the notification. This follows the standard OHI pattern for notification failures, consistent with the existing Task Notification Failed behavior.

Authorization

This IP requires a grant for access restriction workitems.assign IP.

Response Messages

Failure

Code	Description
OHI-IP-WTSK-001	Work item {workitemId} is unknown.
OHI-IP-WTSK-002	Work item {workitemId} is in Done status and cannot be updated.
OHI-IP-WTSK-003	Assignor {assignorUserId} is not authorized to assign work items for the work item’s queue.
OHI-IP-WTSK-004	Assignee {assigneeUserId} is not eligible to receive work items for the work item’s queue.
OHI-IP-WTSK-005	Assignee is unknown
OHI-IP-WTSK-006	No work item provided. At least one work item is required
OHI-IP-WTSK-007	A maximum of 500 work item IDs is supported per request

The response can also contain generic error messages not specific to this web service. For more information, see Response Messages.