Page Comparison

Table of Contents

outline	true
style	none

...

Note: See the How to get RECID values FAQ page for how to locate needed RECIDs.

Available Fields

Field	Required for INSERT	Required for UPDATE	Required for Action Type	Data Type	Options	Notes
type	Yes	Yes		String	ACTION	Required for ALL Service Desk Action Requests
RECID / sda_number	No	Yes*		Integer		Either “RECID” or “sda_number” are "Conditionally Required*" when attempting to UPDATE, but not both. RECID column from SERVICE_DESK_ACTIONS table.
sd_recid / sd_number	Yes*	No		Integer / String		Either “sd_recid” or “sd_number” are "Conditionally Required*" when attempting to INSERT, but not both. RECID column from SERVICE_DESK table.
sd_action	Yes	No		String	ADD, CHG_MOVE, CHG_UPDOWN, CHG_MISC, REMOVE, CHG_SERVICE_ID, CHG_MULTI_LOCATION, CHG_OWNER, TASK	The type of Service Desk Action to be created
location	No*	No*	CHG_MULTI_LOCATION	Integer		RECID of Location. Some Services can make the Location "Conditionally Required". For Multi Location Services, only Locations already associated to the Service can be used for actions that are not ADD For Multi Location Services with 2 or more Locations, Location is "Conditionally Required" for all CHANGE and REMOVE Actions. The status of the Location must be Active, and allowed by the Service Catalog.
moveto_location	No	No		Integer		RECID of Location *Not allowed, and will throw an Error if used on a TASK Action
catalog	Yes	No	ADD, CHG_UPDOWN, TASK	Integer		RECID of Service Catalog
service / service_id	Yes*	No	CHG_UPDOWN, CHG_MOVE, CHG_MISC, REMOVE, CHG_SERVICE_ID, CHG_MULTI_LOCATION, CHG_OWNER	Integer		Either RECID of Service or SERVICE_ID of Service needs to be provided For CHG_SERVICE_ID, CHG_MULTI_LOCATION and CHG_OWNER, the Service must be Active *Not allowed, and will throw an Error if used on a TASK Action

sla

No

Integer

SLAs

RECID of SLA

due_date

rating_group

No*

No

String

Format “YYYY

	The LIST CODE for the Rating Group for the Phone Service being used by the Service Desk Action. Conditionally Required creating Service Desk Actions when using a Serice Catalog of type "Phone".
sla	No	No	Integer	SLAs	RECID of SLA
due_date	No	No	String		Format “YYYY/MM/DD”
service_host / service_host_name	No*	No*	Integer / String	Service Hosts	RECID of Service Host / Name of Service Host / Either RECID or Name should be provided /

*Some Services CService Host

Conditionally Required when adding an Action to a Phone Service Catalog.
reference	No	No	String
owner_contact	No	No	Integer	Contacts	RECID of Contact. Only a Contact or Department can be Owner, not both.
owner_department	No	No	Integer	Department Hierarchy	RECID of Department. Only a Contact or Department can be Owner, not both.
urgency	No	No	Integer / String	Urgency	Can be RECID or VALUE
start_date	No	No	String		Format: “YYYY/MM/DD”
gla	No	No	Integer		Multiple are sent comma delimited. Example: gla1,gla2,gla3
gla_type	Only if gla is sent	Only if gla is sent	String	Options: Default, Usage, Equipment and Labor	Multiple are sent comma delimited. Example: type1,type2,type3.
gla_percent	Only if gla is sent	Only if gla is sent	Integer	The total of all percentages for a single type must be 100	Mutliple are sent comma delimited. Example: percent1,percent2,percent3.
sdc_recid	No	No	Integer		Passing an SDC will allow an Action to be created with default Workflows, Equipment and Charges.

RECID column from SERVICE_DESK_ACTIONS table.
new_service	No	No	CHG_SERVICE_ID	Integer	The new Service ID for the Service being changed. One of the following must be true for the new Service ID: existing & available & New Service ID must be in the same Catalog or an ancestor of the Catalog as the original Service ID (NOT normalized type) & not in a pool existing & available & New Service ID must be in the same Catalog or an ancestor of the Catalog as the original Service ID (NOT normalized type) & in a pool if the new Service ID specified is an existing Service and the Catalog for the original Service specified on a pool then the new Service ID must be in the same pool doesn't exist
auth_code_type	Yes*	No	ADD	Integer

Lists

Value Lookups:

Toggle cloak

Cloak

Insert excerpt

	API
	API
nopanel	true

RECID of Auth Code Type for an authcode service.
*Required when attempting to INSERT an authcode Service.

classes_of_service

Yes*

No

ADD

Integer

Example

RECID of Class of Service for an authcode service.
*Required when attempting to INSERT a new auth_code_type record.

bandwidth

No

Integer

Lists

Value Lookups:

Toggle cloak

Cloak

Insert excerpt

	API
	API
nopanel	true

RECID of Bandwidth for a data/backbone service.

owner_type

No

CHG_OWNER

String

'contact', 'department'

The type of the Owner, either a Contact or a Department.

owner

No

CHG_OWNER

Integer

RECID of the Owner. Must be Active.

udf_IDENTIFIER

No

Mixed

IDENTIFIER is the unique identifier string given to each UDF

Using SDCs

For full documentation on SDCs, see the Service Desk Classification wiki page.

...

Ordering from Service Pools

To request a Service from a pool:

...

Excerpt

...

Code Block

language	xml

POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT

...

Field

...

Value

...

type

...

ACTION

...

sd_number

...

SO201804031

...

sd_action

...

ADD

...

catalog

...

879

...

due_date

...

2019/12/31

...

hidden

...

Content-Type

...

application/json

...

Pcr-Html-Encoded

...

TRUE

...

true

Services can be used from Service Pools from the Order screen at Main > Service Desk > Orders. When requesting a new Service a User will specify a Service Catalog Type on the Service Order Action and then must select from a list of Available services. The list is drawn from all these criteria:

Services listed must have Status “Available“
Services listed must be in the specified catalog or an ancestor
Services listed must be in a pool only if the selected catalog is specified on that pool
If the specified catalog is not listed on any pools then any Available Service not specified on a pool that also matches the catalog can be selected.

The requested Service must have Status “Available“
The requested Service must be in the requested catalog or an ancestor
The requested Service must be in a pool only if the requested catalog is specified on that pool
If the requested catalog is not listed on any pools then any Available Service not specified on a pool that also matches the catalog can be requested

Headers:

Key	Value
Content-Type	application/json
Pcr-Html-Encoded	TRUE

ADD Action Example

Toggle cloak

Cloak

Code Block

language	xml

POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT

Field	Value
type	ACTION
sd_number	SO201804031
sd_action CHG_MOVE	ADD
service catalog	1324 879
due_date	2019/12/31

CHG_MOVE Action Example

Toggle cloak

Cloak

Code Block

language	xml

POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT

Field	Value
type	ACTION
sd_number	SO201804031
sd_action	CHG_MOVE
service	1324
due_date	2019/12/31

CHG_UPDOWN Action Example

Toggle cloak

Cloak

Code Block

language	xml

POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT

Field	Value
type	ACTION
sd_number	SO201804031
sd_action	CHG_UPDOWN
catalog	879
service	1324
due_date	2019/12/31

CHG_MISC Action Example

Toggle cloak

Cloak

Code Block

language	xml

POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT

Field	Value
type	ACTION
sd_number	SO201804031
sd_action	CHG_MISC
service	1324
due_date	2019/12/31

REMOVE Action Example

Toggle cloak

Cloak

Code Block

language	xml

POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT

Field	Value
type	ACTION
sd_number	SO201804031
sd_action	REMOVE
service	1324
due_date	2019/12/31

CHG_SERVICE_ID Action Example

Toggle cloak

Cloak

Code Block

language	xml

POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT

Field	Value
type	ACTION
sd_number	SO201804031
sd_action	CHG_SERVICE_ID
service	1324
new_service	5555555555
due_date	2019/12/31

CHG_MULTI_LOCATION Action Example

Toggle cloak

Cloak

Code Block

language	xml

POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT

Field	Value
type	ACTION
sd_number	SO201804031
sd_action	CHG_MULTI_LOCATION
service	1324
location	8675309
due_date	2019/12/31

CHG_OWNER Action Example

Toggle cloak

Cloak

Code Block

language	xml

POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT

Field	Value
type	ACTION
sd_number	SO201804031
sd_action	CHG_OWNER
service	1324
owner_type	contact
owner	357
due_date	2019/12/31

TASK Action Example

Toggle cloak

Cloak

Code Block

language	xml

POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT

Field	Value
type	ACTION
sd_number	SO201804031
sd_action	TASK
due_date	2019/12/31
catalog	52

Results

Toggle cloak

Cloak

If the request is successful, the RECID of the Action will be returned as follows:

Code Block

language	java

{ 
	"status": "success",
	"page": "1", 
	"count": 1, 
	"total_count": 0, 
	"servicedesk": 22184 
}

Adding Attachments to Service Desk Actions

...

Field	Required	Data Type	Options	Notes
type	no	String	ATTACHMENT	Can be used to add an attachment when creating, or updating any Service Desk Action
files	yes	array		The file(s) to be attached. 'files' is an array with infinite number of sub-arrays. Each sub-array has keys of 'filename' (the file's name) and 'data' (the base64 encoded data for the file).
sd_recid	yes	Integer		RECID for the Service Desk Recordcolumn from SERVICE_DESK table.
sda_recid	yes	Integer		RECID for the Service Desk Actioncolumn from SERVICE_DESK_ACTIONS table.

NOTES:

a User can provide just the 'sd_recid' to attach the file to the Service Desk item and if the 'sda_recid' is provided, it will attach it to the Action.
"sd_recid" or "sd_number" are Conditionally Required. The use of one is Required, but not both.
"sda_number" or "sda_recid" are Conditionally Required. The use of one is Required, but not both.
"sd_recid", "sd_number" and "sda_number" can be omitted if "sda_recid" is provided

...

Field	Required	Data Type	Default	Notes
type	Yes	String	UDFS	type=UDFS is required
sd_recid	Yes*	Integer		The RECID of the Service Desk item that the UDF is for. *Conditionally Required, see NOTE below. RECID column from SERVICE_DESK table.
sda_recid	Yes*	Integer		The RECID of the Action. *Conditionally Required, see NOTE below. RECID column from SERVICE_DESK_ACTIONS table.
sd_number	Yes*	String		The Number of the Service Desk item that the UDF is for. *Conditionally Required, see NOTE below
sda_number	Yes*	Integer		The Number of the Action that the UDF is for. *Conditionally Required, see NOTE below
udf_IDENTIFIER	Yes	Mixed		IDENTIFIER is the unique Identifier of the UDF to assign the value to. Example: udf_LEGACYNUM=value
udf_UDF-RECID	Yes*	Integer		UDF-RECID is the RECID of the UDF to assign the value to. Example: udf_684=value. RECID column from USER_DEFINED_FIELDS_VALS table. See Note Below
udf_UDF-IDENTIFIER	Yes*	Mixed		IDENTIFIER is the unique Identifier of the UDF to assign the value to. Example: udf_LEGACYNUM=value See Note Below

...

<servicedesk> <status>success</status> <page>1</page> <count>1</count> <total_count>1</total_count> <servicedesk> <item>5434</item> <item>5435</item> </servicedesk> </servicedesk>

order as provided:

Cloak

If the request is successful, the RECID(s) of the new Service Desk Action UDF records will be returned in the same order as provided:

Code Block

language	xml

Code Block

language	xml

{
    "status": "success",
    "page": 1,
    "count": 1,
    "total_count": "1",
    "servicedesk": [
        {
            "item": 5434,
            "item": 5435
        }
    ]
}

Service Desk Action GLAs

GLAs can be easily set for a Service Desk Action.

...

Field	Required	Data Type	Options	Default	Notes
type	yes	String		GLA	type=GLA is required
sd_recid	no	Integer			The RECID of the Service Desk item that the UDF is for. *Conditionally Required, see NOTE below. RECID column from SERVICE_DESK table.
sda_recid	np	Integer	The RECID of the Action.	Integer		*Conditionally Required, see NOTE below. RECID column from SERVICE_DESK_ACTIONS table.
sd_number	np	String			The Number of the Service Desk item that the UDF is for. *Conditionally Required, see NOTE below
sda_number	no	Integer			The Number of the Action that the UDF is for. *Conditionally Required, see NOTE below
gla	yes	Mixed			A single GLA RECID or comma-separated GLA RECIDs
gla_type	yes	String			A single GLA type or comma-separated GLA types. Example: "Default" or "Usage"
gla_percent	yes	Mixed			A single number of "100" or comma-separated numbers that equal 100. Example: "50,50"

...

Either "sd_recid" or "sd_number" need to be provided, but not both
Either "sda_number" or "sda_recid" is required, but not both
"sd_recid", "sd_number" and "sda_number" can be omitted if "sda_recid" is provided

Correct Examples

"sd_recid=123&sda_number=001"
"sd_number=SO12345&sda_number=002" or
"sda_recid" is required, but not both=345"

Incorrect Examples:

"sd_recid=123"
"sda_number=001", "sd_number" and "sda_number" can be omitted if "sda_recid" is provided

Correct Examples

"sd_recid=123&sda_number=001"
"sd_number=SO12345&sda_number=002"
"sda_recid=345"

Incorrect Examples:

"sd_recid=123"
"sda_number=001"

...

If the request is successful, the RECID(s) of the new Service Desk Action GLA records will be returned in the same order as provided:

...

language	xml

...

Results

Toggle cloak

Cloak

If the request is successful, the RECID(s) of the new Service Desk Action GLA records will be returned in the same order as provided:

Code Block

language	xml

{
    "status": "success",
    "page": 1,
    "count": 1,
    "total_count": "1",
    "servicedesk": [
        {
            "item": 5434,
            "item": 5435
        }
    ]
}

Locating Service Desk Action Data

...

Versions Compared

Old Version 64

New Version 65

Key

Available Fields

Using SDCs

Ordering from Service Pools

Headers:

ADD Action Example
Toggle cloak

CHG_MOVE Action Example
Toggle cloak

CHG_UPDOWN Action Example
Toggle cloak

CHG_MISC Action Example
Toggle cloak

REMOVE Action Example
Toggle cloak

CHG_SERVICE_ID Action Example
Toggle cloak

CHG_MULTI_LOCATION Action Example
Toggle cloak

CHG_OWNER Action Example
Toggle cloak

TASK Action Example
Toggle cloak

Results
Toggle cloak

Adding Attachments to Service Desk Actions

Service Desk Action GLAs

Results
Toggle cloak

Page Comparison

Versions Compared

Old Version 64

New Version 65

Key

Available Fields

Using SDCs

Ordering from Service Pools

Headers:

ADD Action Example Toggle cloak

CHG_MOVE Action Example Toggle cloak

CHG_UPDOWN Action Example Toggle cloak

CHG_MISC Action Example Toggle cloak

REMOVE Action Example Toggle cloak

CHG_SERVICE_ID Action Example Toggle cloak

CHG_MULTI_LOCATION Action Example Toggle cloak

CHG_OWNER Action Example Toggle cloak

TASK Action Example Toggle cloak

Results Toggle cloak

Adding Attachments to Service Desk Actions

Service Desk Action GLAs

Results Toggle cloak

ADD Action Example
Toggle cloak

CHG_MOVE Action Example
Toggle cloak

CHG_UPDOWN Action Example
Toggle cloak

CHG_MISC Action Example
Toggle cloak

REMOVE Action Example
Toggle cloak

CHG_SERVICE_ID Action Example
Toggle cloak

CHG_MULTI_LOCATION Action Example
Toggle cloak

CHG_OWNER Action Example
Toggle cloak

TASK Action Example
Toggle cloak

Results
Toggle cloak

Results
Toggle cloak