Detailed Description

Create Task Activity

Overview

This API can be used to create a new task activity. Only one activity can be created at a time.

Since: 21.1.0.0

APIs

Method	URL	Description
POST	`/ws/v12/interaction/activity`	Create task activity.

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 'Create' action on 'Activity' resource type.
Activity must be created in the home department of the logged in user, or in the department in which the logged in user is a foreign user.
If the activity is being assigned to a target user, that is, a user other than the one who is logged in:
- The logged in user must have 'Transfer Activities' permission on the target user.

Licenses

The logged in user must have any of the User Licenses.
If the activity is being assigned to a target user, that is, a user other than the one who is logged in:
- The target user must have any of the User Licenses.

Request

Request headers

Name	Description	Allowed values	Default value
X-egain-session	Session ID obtained from Login API response header	N/A	N/A
Content-Type	Media type sent by the client.	`application/xml` or `application/json` or `multipart/form-data`	N/A
Accept	Content type accepted 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. The request body can be in one of the below two formats:

XML or JSON representing the activity
- The activity can contain non-inline attachments. Refer Attachments Element section for more details.

Multipart form data
- The following two parts must be present:
  1. "data": This part must have the data representing the activity. This can either be in XML format or JSON format.
  2. "data-type": This part identifies the data type of "data" part. It can have one of the two values - "application/json" or "application/xml".
- Optionally there can be more parts that represent non-inline attachments of activity. Each of these parts must contain following header:
  1. "Content-Disposition": This header must have a property by name "fileName", which indicates the file name of the attachment.
NOTE: Inline attachments are not supported by this API.

Elements required in request body

Name	Description
department.name	Name of the department in which the activity should be created.
type.value	Type of the activity. Must be "task".
type.subtype.value	Subtype of activity. Must be one of the subtypes of task configured in application. To find out the configured values in the application, refer Get Activity Attributes API.
subject or payload.task.contents	Must have at least one of subject or payload.task.contents.
customer	The attributes provided in the value of query parameters "searchContactOnAttribute" and "activityContact" must be provided in the customer representation. If a customer is found using the value of the query parameter "searchContactOnAttribute", the other values provided in this representation are ignored. If a customer is not found using the value of the query parameter "searchContactOnAttribute": If the query parameter "createCustomer" is provided, a new customer of type "individual" will be created using the provided values. Refer New customer creation section for more details. If the query parameter "createCustomer" is not provided, this API will error out.

Optional elements allowed in request body

Name	Description
case.id	Case to which activity should be associated with. If this attribute is not provided, the server will create a new case for this activity. If this attribute is provided, this case must exist in the system and the activity will be associated to the case.
priority	Priority of the activity. Must be a value between 1 and 7.
dueDate	Due date of the activity. Must be a future date. Refer supported date format here.
subject	Subject of the activity. Must not exceed 255 characters.
attachments	Attachments of the activity. If attachments are provided, file type of any attachment must not be blocked in the application. Refer Attachments Element section for more details. This attribute is not allowed for multipart/form-data requests. To send attachments for multipart/form-data requests refer Example 3 - Create task activity with all attributes, using Multipart/form-data as content-type .
customAttributes	Custom attribute of the activity. Name must match one of the custom attributes configured in application. If the custom attribute is configured as an enumeration, the value must be one of the predefined values. For string type of custom attribute that is not configured as an enumeration, refer list of Allowed Characters For Custom Attributes.
payload.task.contents	Content of the activity. Supported content type are "text" and "html". One or both can be provided.
status.assigned.user.id or status.assigned.user.loginId or status.assigned.user.externalId or status.assigned.user.customAttributes	User to whom the activity should be assigned. Refer Target User section for more details.

Attachments Element

Each attachment must be represented as a separate attachment element. It must have the following representation:

Elements required for attachment

Name	Description
contentType	Content type of the attachment content. Must not exceed 255 characters.
content	Content of the attachment in base64 encoding.
fileName	Name of the attachment file. Must not exceed 255 characters.

Optional elements allowed for attachment

None

Target User

Optionally, one of the below attributes can be provided to assign the activity to another user. If none of these are provided, the server will assign the activity to the logged in user.

Name	Description
status.assigned.user.id	Id of the target user.
status.assigned.user.loginId	Login id of the target user.
status.assigned.user.externalId	External id of the target user.
status.assigned.user.customAttributes	Any custom attribute that can uniquely identify the target user.

New customer creation

This API does not allow specifying "department.name" attribute in the customer element. Instead, when creating a new customer, customer's department is determined as follows:

If "Customer departmentalization" setting is enabled, the customer will be created in the department of the activity.
If "Customer departmentalization" setting is not enabled, the created customer will be shared across all departments.

Additionally, not more than one contact point of the below types can be provided:

Email address.
Home phone number.
Mobile phone number.
Office phone number.
Facebook ID.
Twitter ID.
Instagram ID.

Refer Create Individual Customer API for more details.

Request body XML schemas:

Activity Schema

API specific query parameters

Required API specific query parameters

Name	Description	Allowed Values	Default Value
searchContactOnAttribute	This parameter indicates the attribute of the contact person, on which customer records will be looked up. The attribute corresponding to the provided value must exist in the customer representation. Eg: If provided value is "email.emailAddress", the contact person in the customer representation must contain email address. If "Customer departmentalization" setting is enabled, this API will search the customer in the department of the activity, otherwise it will search the customer across the application. If a customer with the value of this attribute does not exist, a new customer will be created using the customer details provided in the customer element.	email.emailAddress: Email address of the customer. home.phone: Home phone number of the customer. mobile.phone: Mobile phone number of the customer. office.phone: Office phone number of the customer. social.facebookId: Facebook ID of the customer. social.twitterId: Twitter ID of the customer. social.instagramId: Instagram ID of the customer. custom.<attribute_name>: Custom attribute of the contact person.	N/A

Supported API specific query parameters

Name	Description	Allowed Values	Default Value
createCustomer	This indicates whether a new customer must be created if a customer is not found when looked up using the query parameter "searchContactOnAttribute".	yes: Create a new customer if lookup does not find a customer.	N/A
activityContact	The contact to be used for the activity. The attribute corresponding to the provided value must exist in the customer representation. Eg: If provided value is "email.emailAddress", the contact person in the customer representation must contain an email contact point. If not provided, the activity will be associated with the customer and the contact person. It will not be associated with the contact point.	email.emailAddress: Email address of the customer. home.phone: Home phone number of the customer. mobile.phone: Mobile phone number of the customer. office.phone: Office phone number of the customer. social.facebookId: Facebook ID of the customer. social.twitterId: Twitter ID of the customer. social.instagramId: Instagram ID of the customer.	N/A

Supported common query parameters

None

Response

Response headers

Name	Description	Possible values
X-egain-session	Session ID of the current user session	N/A
Content-Type	Media type of response body	`application/xml` or `application/json`
Location	Location of the new created activity	N/A

Response body XML schemas:

Error - used in case of error

HTTP status codes

Success Status codes

201 - Created

The request was successfully executed.

Failure Status codes

400 - Bad Request

Unsupported query parameters are provided.
Unsupported values are provided for the query parameters.
Elements provided do not adhere to the rules stated in the Request Body section.
Multiple users match the target user search criteria.
Multiple contacts are found against the search contact criteria.
Request body is empty.

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.

406 - Not Acceptable

If invalid language header is provided.

500 - Internal server error

Examples:

Example 1 - Create task activity with required attributes and search customer only
Example 2 - Create task activity with all attributes with customer creation
Example 3 - Create task activity with all attributes, using Multipart/form-data as content-type