Entity API

The Entity API exposes common entity types including tickets, service requests, teams, departments, locations, assets etc. Depending on your privileges, you can view items, update fields, add attachments, delete items, and perform other actions.

Responses are based on the fields and views available to the entity requested, including any custom fields or views created in the application. Responses also include links to additional resources associated with each entity. For example, Service Request items return REST API links to each item's associated entities, like impacted resources, history records, tasks, attachments, etc.

Tip: The Entity API supports basic authentication. For more information, please see Creating a Request > Headers.

Action	Method	API	Description
Retrieve a Single Item	GET	api/entity/{entitytype}/{id}?columns={columns[0]} &columns={columns[1]}	Returns the item with the specified entity type and unique ID.
Retrieve Multiple Items	GET	api/entity/{entitytype}?columns={columns[0]} &columns={columns[1]} &filter={filter} &sort={sort} &pagesize={pagesize} &page={page}	Returns a list of items of the specified type. You can specify additional parameters to further limit the results returned. Note: The items returned are based on the privileges of the ChangeGear user.
Retrieve Items Based on a View	GET	api/entity/{entitytype}/{viewname}?columns={columns[0]} &filter={filter} &sort={sort} &pagesize={pagesize} &page={page}	Returns items using the specified view. Note: The items returned are based on the privileges of the user.
Retrieve an Attachment	GET	api/entity/{entitytype}/{parentid}/attachments/{attachmentid}	Returns the attachment data for the specified item.
Create an Item	POST	api/{entitytype}	Creates a new item of the specified type.
Update an Item	PUT	api/{entitytype}/{id}	Updates the item with the specified type and ID.
Update a Child Entity	PUT	api/{entitytype}/{id}	Updates child entities belonging to a parent entity.
Update the Change Log	PUT	api/ichangemanagementticket/{id}	Appends an entry to the Change Log. Note: This feature is only available for change tickets and may not be enabled depending on your ChangeGear license.
Delete an Item	DELETE	api/entity/{entitytype}/{id}	Deletes an item with the specified type and ID.
Check Action Availability	PUT	api/{entitytype}/{id}/canperform/{action}	Verifies whether the specified action can be performed.

 

Retrieve a Single Item

This endpoint returns the item with the specified entity type and ID. You can also specify which fields to include in the response.

Request Information

At a minimum, the request should contain the type of entity being retrieved and the unique ID of the entity that you wish to retrieve. You can also specify the fields that are included in the response using the columns parameter. By default, the REST API returns all fields for that type.

URL

api/entity/{entitytype}/{id}?columns={columns[0]}&columns={columns[1]}

Name	Description	Type	Example	Additional Information
entitytype	The type of entity to return.	String	IncidentRequest	Required.
id	The unique identifier assigned to the item.	Integer	50	Required.
columns	The data field(s) to include in the results. If the column list is empty, then the REST API returns all visible columns.	Array of Strings	columns=EmailPIT &columns=DueDate	You can specify multiple columns by using multiple column parameters.

Method

GET

Header Parameters

Parameter	Description	Type	Example
sessionid	The encrypted session ID.	string	EhbNKWgPZNJnHRPWJ3PfvLrtavbL591==

Sample Request

URL: https://changegear-server/cgrestapi/api/entity/incidentrequest/100?columns=EmailPIT&columns=DueDate

Header: sessionid: EhbNKWgPZNJnHRPWJ3PfvLrtavbL591sfEVzR3Hn/Fs7RCBceNxpWIuhw0iIn8YM

Response Information

The REST API returns a list of fields for the item matching the item ID.

Sample Response Snippet

Retrieve Multiple Items

This endpoint retrieves a list of items of the specified entity type. You can specify the fields to include in the response, as well as the filter and sorting order of the items included in the response.

Request Information

At a minimum, the request should contain the type of entity being retrieved. You can also specify the fields that will be included in the response using the columns parameter. By default, the REST API returns all fields for that type.

URL

api/entity/{entitytype}?columns={columns[0]}&columns={columns[1]}&filter={filter}&sort={sort}&pagesize={pagesize}&page={page}&metadata={true/false}

Parameter	Description	Type	Example	Additional Information
entitytype	The type of entity to return.	String	IncidentRequest	Required.
columns	The data field(s) to include in the results. If the column list is empty, then the REST API returns all visible columns.	Array of strings	columns=ItemID &columns=Status	You can specify multiple columns by using multiple column parameters.
filter	Filters the items by the criteria specified.	String	filter=[Summary]+like+'%25fax%25'	Use percent-encoding when formatting filters with special characters. For more information, see Percent Encoding under Creating a Request.
sort	The data field(s) to sort on.	String	sort=DueDate	You can specify multiple columns by using multiple sort parameters. Items are sorted in ascending order.
pagesize	The number of items to return per page.	Integer	pagesize=15	Defaults to 10.
page	The page number if the number of items exceeds the page size.	Integer	page=1	Defaults to 1.
metadata	Gets the total item count based on the other parameters in the call and metadata for the columns in that entity type.	Boolean	metadata=True	Defaults to False.

Method

GET

Header Parameters

Parameter	Description	Type	Example
sessionid	The encrypted session ID.	string	ap9pYaaBK8K5iMNZNC5DtA==

Sample Request

URL: https://changegear-server/cgrestapi/api/entity/incidentrequest?columns=ItemID&columns=Status&filter=[Summary]+like+'%25fax%25'&sort=DueDate&pagesize=15&page=1&metadata=True

Header: sessionid: EhbNKWgPZNJnHRPWJ3PfvLrtavbL591sfEVzR3Hn/Fs7RCBceNxpWIuhw0iIn8YM

Response Information

The REST API returns a list of items matching the parameters. If there are no results, the REST API returns an empty JSON object.

Sample Response Snippet

Retrieve Items Based on a View

This endpoint returns a list of items using the specified view. You can provide additional parameters to filter and sort the result set.

Request Information

URL

GET api/entity/{entitytype}/{viewname}?columns={columns[0]}&filter={filter}&sort={sort}&pagesize={pagesize}&page={page}

Name	Description	Type	Example	Additional Information
entitytype	The type of entity to return.	String	IncidentRequest	Required.
viewname	The name of the view to use when creating the response.	String	All%20Incidents	Required. Use percent-encoding when the view name contains special characters. For more information, see Percent Encoding under Creating a Request.
columns	The data field(s) to include in the results. If the column list is empty, then the REST API returns all visible columns.	Array of strings	columns=EmailPIT &columns=DueDate	You can specify multiple columns by using multiple column parameters.
filter	Filter the items by the criteria specified.	String	filter=[Summary]+like+'%25fax%25'	Use percent-encoding when formatting filters with special characters. For more information, see Percent Encoding under Creating a Request.
sort	The sorting method to apply.	String	sort=DueDate	You can specify multiple columns by specifying multiple sort parameters. Items are sorted in ascending order.
pagesize	The number of items to return per page	Integer	pagesize=15	Defaults to 10.
page	The page number if the number of items exceeds the page size.	Integer	page=2	Defaults to 1.

Method

GET

Header Parameters

Parameter	Description	Type	Example
sessionid	The encrypted session ID.	String	ap9pYaaBK8K5iMNZNC5DtA==

Sample Request

URL: https://application-server/cgrestapi/api/entity/incidentrequest/All%20Incidents

Header: sessionid: EhbNKWgPZNJnHRPWJ3PfvLrtavbL591sfEVzR3Hn/Fs7RCBceNxpWIuhw0iIn8YM

Response Information

The REST API returns a list of items matching the entity type. The data returned is filtered based on the view. If there are no results, the REST API returns an empty JSON object.

Sample Response Snippet

Retrieve an Attachment

This endpoint retrieves attachment data for the specified item.

Tip: To use this call, you must know the unique identifier of the attachment you want to access. To get the unique identifier, you can retrieve a list of an item's attachments by replacing the attachments portion of the URL with the entity type of the parent item followed by AttachmentRecords and get the ID from that. For example:
Incident Request: api/entity/{entitytype}/{parentid}/IncidentRequestAttachmentRecords
Problem Report: api/entity/{entitytype}/{parentid}/ProblemReportAttachmentRecords

Note: Attachments submitted and retrieved via the REST API are encoded using Base64 encoding.

Request Information

The attachment endpoint requires information about both the parent entity and the attachment itself. For the parent entity, you must provide the entity type and unique ID. For the attachment, you must provide the unique attachment ID for the parent entity.

URL

api/entity/{entitytype}/{parentid}/attachments/{attachmentid}

Name	Description	Type	Example	Additional Information
entitytype	The type of entity to return.	String	IncidentRequest	Required.
parentid	The unique identifier of the item containing the attachment.	Integer	50	Required.
attachmentid	The unique identifier of the attachment itself.	Integer	2	Required.

Method

GET

Header Parameters

Parameter	Description	Type	Example
sessionid	The encrypted session ID.	string	ap9pYaaBK8K5iMNZNC5DtA==

Sample Request

URL: https://changegear-server/cgrestapi/api/entity/incidentrequest/100/attachments/5

Header: sessionid: EhbNKWgPZNJnHRPWJ3PfvLrtavbL591sfEVzR3Hn/Fs7RCBceNxpWIuhw0iIn8YM

 

Response Information

The REST API returns the attachment contents encoded in Base64. If the attachment cannot be found, the REST API returns an empty JSON array.

 

Create an Item

This endpoint creates a new item of the specified type. As part of the request, you must specify initial values for at least one of the item's fields. To initialize the value of a field, pass the field name and value as a JSON object in the body of the message.

Request Information

The request specifies the type of entity to create as well as the initial values of the item's fields. These values will populate the entity when it is created.

URL

api/{entitytype}

Name	Description	Type	Example	Additional Information
entitytype	The type of entity to create.	String	IncidentRequest	Required.

Method

POST

Header Parameters

Parameter	Description	Type	Example
sessionid	The encrypted session ID.	String	ap9pYaaBK8K5iMNZNC5DtA==

Body Parameters

The body contains a JSON representation of the item's fields and the initial values of those fields. To set the value of a field, specify the field name in the body parameters. In the sample request below, we create a new incident request with the summary "Testing the REST API", an urgency of "1 - Emergency", a priority of "2 - High", and an impact of "1 - Major." We also attach an image and insert an entry into the description field using the AttachmentRecords and HistoryRecords fields respectively.

Sample Request

 

Response Information

If the item was created successfully, the REST API returns the ID of the new item as a JSON object. Otherwise, the REST API returns a plain text error message.

Sample Response

{ "ID": 100 }

 

Update an Item

This endpoint updates the item of the specified type and ID. To update the value of a field, create a JSON object and map the new value to the name of the field. You can update multiple fields simultaneously.

Version Control (ETags)

In order to prevent multiple users from editing the same item simultaneously, ChangeGear implements a form of version control known as ETags (or Entity Tags). ETags represent a specific version of a specific resource. When a user attempts to update an item, ChangeGear checks the ETag provided by the user against the ETag stored for that specific resource. If the ETags match, then the resource is updated. If you want to update an item using the REST API, you need to present the correct ETag to the server for validation.

To update an item using ETags:

1. Retrieve the item you want to update.

2. Extract the value of the ETag field from the resulting JSON object.

3. Create a new JSON object with the fields that you wish to update. Be sure to include the ETag field with the value retrieved from step 1.

4. Construct an update call using the instructions provided in this section.

5. Send the call to the REST API.

Request Information

The request consists of the type of entity, the unique ID of the entity, and the new values of the fields that will be updated.

URL

api/{entitytype}/{id}

Name	Description	Type	Example	Additional Information
entitytype	The type of entity to update.	String	IncidentRequest	Required.
id	The unique identifier assigned to the item.	Integer	50	Required.

Method

PUT

Header Parameters

Parameter	Description	Type	Example
sessionid	The encrypted session ID.	string	EhbNKWgPZNJnHRPWJ3PfvLrt==

Body Parameters

The body contains a JSON representation of the item's fields and the new values of those fields. In the following sample request, we are changing the summary field of incident ticket 50 to "New Summary."

Sample Request

URL: https://changegear-server/cgrestapi/api/incidentrequest/50
Header: sessionid: EhbNKWgPZNJnHRPWJ3PfvLrtavbL591sfEVzR3Hn/Fs7RCBceNxpWIuhw0iIn8YM

Body: {

eTag: 97,

Summary: 'New Summary'

}

 

Response Information

If the item was updated successfully, the REST API returns the ID of the updated item as a JSON object. Otherwise, the REST API returns a plain text error message.

Sample Response Snippet

{ "ID": 100 }

 

Update a Child Entity

Updating a child entity follows the same structure as updating a parent item, except you specify an action for the child in the body of the API call.

The following example shows how to delete an attachment using this method. Other child entities–such as history records–may not have the same options or functionality available.

Request Information

The URL, method, and header parameters are identical to updating an entity. The body, however, specifies the child entity to update and the operation to perform.

Body Parameters

Parameter	Description	Type	Example	Additional Information
ID (Parent)	The unique ID of the parent.	Integer	5
eTag	The current revision number of the ticket.	Integer	1	If the eTag does not match, then the update will fail.
Child Type	The entity type of the child.	String	AttachmentRecords
ID (Child)	The unique ID of the child.	Integer	10
ChildOperation	The operation to perform on the child entity.	String	Delete

Sample Request

URL: https://changegear-server/cgrestapi/api/ichangemanagementticket/100

Header: sessionid: EhbNKWgPZNJnHRPWJ3PfvLrtavbL591sfEVzR3Hn/Fs7RCBceNxpWIuhw0iIn8YM

Body: {

"eTag": 3,

"AttachmentRecords" : [

{

"ID": 12,

"ChildOperation": "Delete"

}

]

}

 

Update the Change Log

The Change Log stores a history of changes to source code, artifacts, and operational files that are modified as part of the change request life cycle. It allows you to track revisions to files, archive copies of files, and even integrate with external version control systems. This endpoint appends a new change log event to a ticket.

The Change Log can be viewed in the ChangeGear Web client by members in the Change Staff persona. However, log entries can only be added to the Change Log using the REST API. Additionally, the Change Log can only be appended to. You cannot update or delete existing Change Log records without first deleting the parent ticket.

Note: You may not have access to this feature depending on your ChangeGear license.

By default, the Change Log is only visible on DevOps change request forms. You can add the Change Log to another form by adding a Custom Control to the form and specifying ~/MainUI/Changemanagement/ChangeLogControl.ascx in the WebControlVirtualPath property.

Request Information

The request consists of the unique ID of the change request to update, as well as the new change log entry to append to the request.

URL

api/changemanagementticket/{id}

Name	Description	Type	Example	Additional Information
id	The unique identifier assigned to the ticket.	Integer	50	Required.

Method

PUT

Header Parameters

Parameter	Description	Type	Example
sessionid	The encrypted session ID.	String	EhbNKWgPZNJnHRPWJ3PfvLrt==

Body Parameters

The body contains a JSON representation of the new fields to submit to the ticket. In the following sample request, we are submitting a code file to be reviewed and approved. We submit the file as a Base64-encoded attachment, which ChangeGear converts into a downloadable link in the ChangeGear Web client.

Parameter	Description	Type	Example	Additional Information
eTag	The current revision number of the ticket.	Integer	5	If the eTag does not match, then the update will fail.
AttachmentRecords	An array of file attachments. The file itself is passed as a Base64-encoded string.	Array of JSON Objects	"AttachmentRecords" : [   {     "RFCProperty": "ChangeLog",     "File": patch_1.patch",     "FileContent": "<Base64-encoded string>"   } ]	You can add multiple attachments by separating each JSON object with a comma.
RFCProperty	An AttachmentRecord property that determines what ChangeGear component the attachment is associated with. In this case, the RFCProperty is set to ChangeLog.	String	"RFCProperty": "ChangeLog"
File	An AttachmentRecord property that defines the name of the file.	String	"File": "patch_1.patch"
FileContent	An AttachmentRecord property containing the Base64-encoded contents of the file.	String	"FileContent": "<Base64-encoded string>"
ChangeLogs	An array of Change Log entries.	Array of JSON Objects	"ChangeLogs": [   {     "Description": "Patch 1",     "ChangeLogFiles": [     {       "FileName": "patch_1.patch",       "FileDate": "2016-05-31T13:15:30Z",       "FileSize": 38610     }     ]   } ]	You can add multiple Change Log entries (and multiple files per Change Log) by separating each JSON object with a comma.
Description	A ChangeLog property providing a summary of the log event.	String	"Description": "Patch 1 revision 4"
ChangeLogFiles	A ChangeLog property that lists the AttachmentRecords belonging to the ChangeLog.	Array of JSON Objects	"ChangeLogFiles": [   {     "FileName": "patch_1.patch",     "FileDate": "2016-05-31T13:15:30Z",     "FileSize": 38610   } ]	You can add multiple files per Change Log by separating each JSON object with a comma.
FileName	A ChangeLogFile property that displays the name of the file. Note: This should match the File property of the associated attachment record.	String	"FileName": "patch_1.patch"	To allow users to download files from the Change Log in the ChangeGear Web client, this should correspond to the File field of an attachment.
FileDate	A ChangeLogFile property defining the date that the file was created or modified.	String	"FileDate": "2016-05-31T13:15:30Z"	Dates are in UTC time.
FileSize	A ChangeLogFile property defining the size of the file.	Integer	"FileSize": 38610

Sample Request

URL: https://changegear-server/cgrestapi/api/ichangemanagementticket/100

Header: sessionid: EhbNKWgPZNJnHRPWJ3PfvLrtavbL591sfEVzR3Hn/Fs7RCBceNxpWIuhw0iIn8YM

Body: {

"eTag": 3,

"AttachmentRecords" : [

{

"RFCProperty": "ChangeLog",

"File": "patch843535_4.patch",

"FileContent": <Base64-encoded file contents>

}

],

"ChangeLogs": [

{

"Description": "Patch 843545 rev. 4",

"ChangeLogFiles": [

{

"FileName": "patch843535_4.patch",

"FileDate": "2016-05-31T13:15:30Z",

"FileSize": 38610

}

]

}

]

}

 

Response Information

The REST API returns a list of fields for the item matching the item ID. If the update process fails, the REST API returns an error message describing the cause of the failure.

Sample Response Snippet

 

Delete an Item

This endpoint deletes the item of the specified type and ID.

Note: Deleting an item performs a logical delete (deletes from the front end but not from the database), which does not fully remove the item from the system. Deleted items can still be retrieved using the GET method, although the IsDeleted field will be set to false.

Request Information

URL

api/entity/{entitytype}/{id}

Name	Description	Type	Example	Additional Information
entitytype	The type of entity to return.	String	Incident Request	Required.
id	The unique identifier assigned to the item.	Integer	50	Required.

Method

DELETE

Header Parameters

Parameter	Description	Type	Example	Additional Information
sessionid	The encrypted session ID.	string	ap9pYaaBK8K5iMNZNC5DtA==	Required.

Response Information

If the item was deleted successfully, the REST API returns the ID of the deleted item. Otherwise, the REST API returns an error message.

Sample Response Snippet

{ "ID": 100 }/

 

Check Action Availability

This endpoint validates that the specified action can be performed on the ticket. It also returns the layout of the post-action ticket and whether performing the action causes a comment popup to appear.

Request Information

The request consists of the type of entity, the entity ID, and the action to perform. Since an action is performed on ticket update, you will also need to pass the fields that you wish to update, along with their desired new values.

URL

api/{entitytype}/{id}/canperform/{action}

Name	Description	Type	Example	Additional Information
entitytype	The type of entity to return.	String	IncidentRequest	Required.
id	The unique identifier assigned to the item.	Integer	50	Required.
action	The action to perform on the entity	String	Submit	Required. You can retrieve a list of actions using the Retrieve a Single Item endpoint.

Method

PUT

Header Parameters

Parameter	Description	Type	Example	Additional Information
sessionid	The encrypted session ID.	string	ap9pYaaBK8K5iMNZNC5DtA==	Required.

Body Parameters

The body contains a JSON representation of the new fields to submit to the ticket. Please see the Update an Item endpoint for an example.

Sample Request

URL: https://changegear-server/cgrestapi/api/incidentrequest/100/canperform/Submit

Header: sessionid: EhbNKWgPZNJnHRPWJ3PfvLrtavbL591sfEVzR3Hn/Fs7RCBceNxpWIuhw0iIn8YM

Response Information

The REST API returns whether the action can be performed, as well as the state of the form after the action is performed.

Response Parameters

Parameter	Description	Type	Example
ShowCommentsPopup	Whether a comment popup will be displayed when the action is performed (for example, when closing an Incident ticket).	Boolean	"ShowCommentsPopup": true
Layout	The layout used by the form (or comment popup) after the action is performed.	String	"Layout": "CloseTypeComment"
CanPerform	Whether the action can be performed given the fields provided and the user's privileges.	Boolean	"CanPerform": true

Sample Response Snippet

 

Back