Detailed Description

Change Case of Activities

Overview

This API can be used to change the case of one or more open activities of the same case. The target case can be a new case or an existing case.

For this API to execute successfully:

All activities must exist in the application.
All activities must belong to the same case and the case must exist in the application.
The status of all activities in the request must be "in queue waiting to be assigned" or "assigned to a user".
The customer associated with both the original and the target case must be the same.
If the target case is an existing case, the case ID must be an existing case ID.
If a response exists for any of the activities in the request body, they must be in "Completed" status.
No more than 75 activities must be sent in one request

As part of completing this API request:

If the target case is closed, it will be reopened.
If the source case is left with no open activities, it will be closed.
If any of the activities have responses which are in "Completed" status, the case of these activities will also be changed.
If the target case is a new case:
- The new case will be created in the same department as the original case.
- The created case will be in open status.
- The owner of the new case will be the same as the original case.
- The customer of the new case will be the same as the original case. If the original case does not have a customer, the new case will not have a customer either.
- The originatingChannel for the new case will be the same as original case.

Since: 11.6

APIs

Method	URL	Description
PUT	`/ws/v12/interaction/activity/{IDs}/changecase`	Change case of one or more activities. {IDs}: a comma separated string of activity IDs that belong to the same case.

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 "Change Case" action on "Activity" resource.
All the activities must belong to either the 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 MailPlus: To change the case of email activities.
ECE CallTrackPlus: To change the customer of calltrack activities.
Any User License: To change the customer of other activity types.

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. The request body varies depending on whether the target case for activities is a new case or an existing case.

Elements required in the request body for existing case

If the target case for activities is an existing case, the 'case' element in the request body must contain:

Name	Description
id	Must be an existing case ID in the application

Optional elements allowed in the request body for existing case

None

Elements required in the request body for new case

None, although the request body must be present with the case element.

Optional elements allowed in the request body for new case

Name	Description
case.dueDate	Must be a valid date, in the future.
case.severity.value	Must be 'urgent', 'high', 'medium' or 'low'.
case.subject	If not provided, the subject of the original case would be used as the subject of the case as well. Must not exceed 1024 characters.
case.description	Must not exceed 1024 characters.
case.solution	Must not exceed 1024 characters.
case.customAttributes	Names of the custom attributes must exist in ECE application. If the attribute is an enumeration, the values sent must be one from the list of allowed values. For string type of custom attribute that is not configured as an enumeration, refer list of Allowed Characters For Custom Attributes.

Request body XML schemas:

schema-interaction-Case

Supported API specific query parameters

relateCase: The only value allowed for this query parameter is "yes". This is required to relate the current case with the new case of the activities.

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`

If a new case is created, URI of the newly created case is returned in the Location response header:

Name	Description	Possible values
Location	URI of new resource, in the format /{context-root}/ws/v12/interaction/case/{ID}	N/A

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:

schema-kb-WSError - used in case of error

HTTP status codes

Success Status codes

201 - Created

Successfully created a new case and changed the case of the activities the newly created case. The response will contain a "Location" header indicating the URI of the newly created case.

204 - No Content

Successfully changed the case of the activities to the target case.

Failure Status codes

400 - Bad Request

Any query parameter is sent in the request.
Any criteria for successful execution mentioned in the Overview and Request Body sections are violated.

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 in the request URI are locked by another user.

404 - Not Found

One or more activities in the request URI do not exist.

406 - Not Acceptable

Invalid 'Accept-Language' header value.

500 - Internal server error

Examples:

Example 1 - Change case of an activity to a new case without optional attributes
Example 2 - Change case of an activity to an existing case
Example 3 - Change case of multiple activities to an existing case and relate the two cases
Example 4 - Change case of multiple activities to a new case by providing all case attributes