Pick Activities
Overview
This API can be used by the logged in user to pick specific activities from other users and queues.
This API cannot be used to pick draft responses created for incoming email activities.
For this API to execute successfully:
- All activities must exist in the application.
- The activities must be of type Email. Calltrack and Chat type of activities cannot be picked using this API.
- The activities must not be assigned to the user performing this operation.
- The status of all activities in the request must be either "in queue waiting to be assigned" or "assigned to a user".
- If an activity is assigned to a different user then:
-
The activity must not be locked by that user.
-
If the activity is pinned by the user, the query parameter "unpin" must be sent with a value of "yes".
- No more than 75 activities must be sent in one request.
As part of completing this API request:
- User load is not considered, i.e., activities will be assigned to the logged in user regardless of the user's existing work load.
- Since
- 11.6
APIs
| Method | URL | Description |
| PUT | /ws/v12/interaction/activity/pick | Pick one or more activities from other users and queues. |
Authentication
Authentication is required. The client must be logged in to call this API. Each API request must contain X-egain-session request header returned by Login API.
Permissions
All of the following are required:
- User must have 'Pick Activities' action on 'Activity' resource.
- If status of any activity is "assigned to a user" then:
-
The logged in user must have "Pull activities" permission on the user to whom the activity is currently assigned.
-
If the activity is pinned by a user, and the query parameter "unpin" is sent with a value of "yes":
-
The logged in user must have 'Unpin' action on 'Activity' resource.
- If status of any activity is "in queue waiting to be assigned" then:
-
The logged in user must have "Pull activities" permission on the activities' queue.
- All the activities must either belong to the logged in user's home department, or to a department in which the user is a foreign user.
Licenses
The logged in user must have the following licenses:
- ECE Advisor Desktop or ECE MailPlus: If any email activity is picked.
- Any User License: If a task or generic activity is picked.
Request
Request headers
| Name | Description | Allowed values | Default value |
| X-egain-session | Session ID obtained from Login API response header | N/A | N/A |
| Accept | Content type accepted by client. | application/xml or application/json | N/A |
| Content-Type | Media type sent by the client | application/xml or application/json | N/A |
| Accept-Language | Language locale accepted by client (used for locale specific fields in resource representation and in error responses) | Supported 'Accept-Language' header codes | default system language |
Request Body
The request body is mandatory and can be in either XML or JSON format.
Elements required in the request body
'activities' element must be present in the request body. At least one 'activity' element must be present in the 'activities' element. Each 'activity' element must contain the following elements:
| Name | Description |
| id | ID of the activity to be picked |
| lastModified.date | Value of last modified date of the activity |
Optional elements allowed in the request body
None
Request body XML schemas:
Supported API specific query parameters
Query parameters allowed in the request
- unpin: The only value allowed for this query parameter is "yes". This is required to pick activities even if they are pinned by a user. If any of the activities is pinned by a user and the "unpin" query parameter is not provided in the request, the request will fail.
Supported common query parameters
None
Response
Response headers
| Name | Description | Possible values |
| X-egain-session | ID of the current user session | N/A |
| Content-Type | Media type of response body | application/xml or application/json |
Response body
The response body will be sent only in case of error. It can be in either XML or JSON format.
Response body XML schemas:
- Error - used in case of error
HTTP status codes
Success Status codes
204 - No Content
- Successfully picked the requested activities.
Failure Status codes
400 - Bad Request
- Unsupported query parameter is sent in the request.
- Unsupported query parameter value is sent in the request.
- Request body does not contain the required elements.
- Unsupported element is present in the request body.
- Any criteria for successful execution mentioned in the Overview and Request Body sections are violated (except when activity is locked, which will result in 403-Forbidden).
401 - Unauthorized
- X-egain-session request header is missing.
- Session is invalid or expired.
403 - Forbidden
- The user does not have sufficient permissions. Refer the Permissions section for details.
- One or more activities sent in the request are locked by another user.
406 - Not Acceptable
- Invalid 'Accept-Language' header value.
409 - Conflict
- The lastModified date of any activity in the request does not match its lastModified date on the server.
500 - Internal server error
Examples:
Example 1 - Pick an activity
Example 2 - Pick multiple activities
