Ticketing

A ticket, often referred to as "Case", in ITX serves as a centralized solution for consolidating related activities into one organized space. It functions as a dynamic record that captures various elements of a task or issue, facilitating efficient management and resolution. Within a ticket, users can document both internal and external communications, creating a comprehensive repository for collaboration. This approach streamlines communication channels, enhances transparency, and ensures that all relevant information pertaining to a particular task or problem is easily accessible and traceable.

Attributes

Each case consists of multiple attributes which describes the case itself. Below is a short summary of the attributes you most likely will come across when using the API. See OpenAPI specification for complete models.

Name	Description
eactId	Primary key
corporation	Which corporation this case belongs to
activityType	Always 15 for cases.
seqNo	Case number. Will increase sequentially for each case
status	Internal status of the case. Will match $.emsStatus.internalStatus
description	Case title
creationTs	Creation timestamp
updateTs	Last update timestamp. Only tracks changes on the case itself, not linked activities
creator	User which created this case.
entityExtension	The contact this case belongs to
category	Category of the case.
priority	Priority of the case
emsStatus	Customizable status. Actual logic is defined by this status' internal status.
emsStatusChangeTs	Timestamp of last status change
internalUpdateTs	Timestamp of last internal communication update. For example sending new email
externalUpdateTs	Timestamp of last internal communication update. For example receiving a new email
deadlineTs	Deadline of the case
emsStatusLastOpen	Timestamp of when the case most recent "open" ems status
queue	Defined which queue this case belongs to
onHoldToTs	On hold timestamp for this case. Will automatically go back to emsStatusLastOpen when this timestamp has been exceeded.
onHoldComment	User defined comment that describes why the case is on hold
members	List of involved activity members. For example assigned users, followers or contact person. See Activity members
links	List of activity links. For example sub-cases or emails
texts	List of case comments.
logs	List of log records for a given case. For example status changes, assigned user changes
emsTags	List of involved tags.
coreFileReferences	List of related files. Usually manually uploaded files or attachments
propValues	List of user defined properties.

Statues

This is the available case statuses you may come across when using the API. There may be one or more EMS Statuses of the following types. $.status will be updated to $.emsStatus.internalStatus automatically on ems status change. No need to manually maintain this status field.

Name	ID	Features
Open	1	Will remain on this status until manually changed
Closed	2	Will change to $.emsStatusLastOpen on incoming updates.
Awaiting external action	3	Will change to $.emsStatusLastOpen on incoming updates.
Deleted	4	Will remain in this status until manually changed
Merged	5	No updates should be done on cases which have been merged. Use the case this case was merged into for updates.
Spam	6	Will remain in this status until manually changed
Awaiting internal action	7	Will remain in this status until manually changed
On hold	8	Will change to $.emsStatusLastOpen when surpassing $.onHoldToTs

Activity members

info

Please read generic activity member introduction from "Activity API" before continuing.

The members list in the context comprises all individuals, including both internal users and external contact persons, who are or have been actively involved with the case. Each member's role is specified in the role field, providing insights into their respective functions. For instance, a role value of 20 indicate a contact person.

You may come across the following roles when working with cases:

Role name	Role ID	Multiple active members
Assigned user	1	no
Case follower	2	yes
Contact	20	no

Here is some javascript functions describing how to retrieve a list of follower, and the currently assigned user. The same logic can be applied to contact person.

const ROLE_ASSIGNED_USER = 1;
const ROLE_CASE_FOLLOWER = 2;

function getActiveFollowerMembers(caze) {
	return getActiveMembersOfRole(caze, ROLE_CASE_FOLLOWER);
}

function getAssignedUser(caze) {
	const foundUserMembers = getActiveMembersOfRole(caze, ROLE_ASSIGNED_USER);
	if (foundUserMembers.length == 1) {
		// Should only ever exist 1 active member.
		return foundUserMembers[0]; 
	}
}

function getActiveMembersOfRole(caze, searchForRole){
	if (!caze.members) {
		// No members provided. Return empty list
		return [];
	}
	return caze.members.filter(iMember => memberIsActive(iMember) 
		&& iMember.role == searchForRole);
}

function memberIsActive(activityMember) {
	return activityMember.startTs != null && activityMember.endTs == null;
}

Creating and retrieving cases

info

Check the OpenAPI specification for complete examples

Find existing cases

POST /itxems/cases/search

Create or update case

POST /itxems/case

---

Category

Ticket categories are used to organize, route, prioritize, and analyze tickets. Each category is identified by its primary key, ctnoId.

You can retrieve the list of available categories using:

GET /rest/itxems/categories

---

Status

The status of a case is determined by two fields: status and emsStatus.

• status takes precedence and is the only field with functional meaning beyond display purposes.
• emsStatus.internalStatus always corresponds to the same value as status.

If you submit a POST request with mismatched values where emsStatus points to a different status than the one defined in status the system will automatically override emsStatus with a value that matches the provided status.

Static status values

The following status values are system-defined and static:

Status name	Value
Open	1
Closed	2
Awaiting external action	3
Deleted	4
Merged	5
Spam	6
Awaiting internal action	7
On hold	8

User-defined emsStatus

User-defined emsStatus values can be retrieved here:

GET /rest/itxems/statuses?type=35013

Each emsStatus is identified by its primary key, emstId.
If the emsStatus field is omitted when creating a ticket, the system will automatically apply the default emsStatus for the given status.

---

Priority

A priority is identified by its primary key, emprId.
You can retrieve the available priorities using:

GET /rest/itxems/priorities

If the priority field is omitted when creating a ticket, the system will automatically apply the default priority.

---

Queue

A queue is identified by its primary key, ucquId.
You can retrieve the available queues using:

GET /rest/itxpbx/queue

---

Examples

info

The case creation response includes a JSON field named eactId. This value is the primary identifier for the case and must be used to reference the case in all subsequent operations.

---

New open case on contact with queue, category and priority set

POST /rest/itxems/case

{
  "description": "Example case title",
  "entityExtension": {
    "eeexId": 3257440
  },
  "status": 1,
  "emsStatus": {
    "emstId": 3
  },
  "corporation": {
    "corpId": 1
  },
  "queue": {
    "ucquId": 541
  },
  "category": {
    "ctnoId": 768957
  },
  "priority": {
    "empriId": 46
  }
}

---

Minimal example, closed case

POST /rest/itxems/case

{
  "description": "This case is closed",
  "status": 2,
  "corporation": {
    "corpId": 1
  }
}

---

Upload attachment on case

info

tblId=35007 and type=3 is static values. id must be set to eactId of case

This endpoint expects content type multipart/form-data and param files containing file data

POST /rest/core/corefile?tblId=35007&type=3&id=<case_eact_id>

Example request with curl

curl --request POST \
  --url 'https://<endpoint>/rest/core/corefile?tblId=35007&type=3&id=<case_eact_id>' \
  --header 'content-type: multipart/form-data' \
  --form files=@./sample.pdf

---