Page Comparison

Table of Contents

outline	true
style	none

Read Call

All GET requests for retrieving data will be done via the SQL endpoint. Please see the SQL for more information on how to create a request. Please see the Data Dictionary for comprehensive detail of available Tables and Data.

In an effort to make the PCR-360 API more flexible, PCR has made the decision to no longer create individual endpoints for all the different data types. Instead, PCR is encouraging Users to use the SQL endpoint with a structured SELECT statement to retrieve exactly the data you want. Please see the SQL endpoint documentation for more information.

...

HINT : The PCR-360 database makes use of the “LISTS” table for many types of data from many different Tables. The convention that we use is that any column that ends with “_LISTS_RECID” can be joined to the “LISTS” table to retrieve the readable value.

Write Call

Service Desk Actions can be created via the API. Currently, the API can only create Pending Actions and cannot modify the status.

...

Insert excerpt

	Custom API
	Custom API
nopanel	true

Available Fields

Field

Required for INSERT

Required for UPDATE

Required for Action Type

Data Type

Options

Notes

type

Yes

String

ACTION

Requiredfor ALL Service Desk Action Requests

status

No

String

"complete"

This field should only be used when attempting to Complete or Finalize a Service Order or IncidentDesk Action. When a new Service Desk Item is created, the status is set automatically to "Pending".

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*

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

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

rating_group

No*

No

String

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

Integer

SLAs

RECID of SLA

due_date

No

String

Format “YYYY/MM/DD”

service_host / service_host_name

No*

Integer / String

Service Hosts

RECID of Service Host / Name of Service Host / Either RECID or Name should be provided / Conditionally Requiredwhen adding an Action to a Phone Service Catalog.

reference

No

String

owner_contact

No

Integer

Contacts

RECID of Contact. Only a Contact or Department can be Owner, not both.

owner_department

No

Integer

Department Hierarchy

RECID of Department. Only a Contact or Department can be Owner, not both.

urgency

No

Integer / String

Urgency

Can be RECID or VALUE

start_date

No

String

Format: “YYYY/MM/DD”

gla

No

Integer

Multiple are sent comma delimited. Example: gla1,gla2,gla3

gla_type

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

Integer

The total of all percentages for a single type must be 100

Mutliple are sent comma delimited. Example: percent1,percent2,percent3.

sdc

No

Integer

Passing an SDC will allow an Action to be created with default Workflows, Equipment and Charges. RECID column from SDC table.

new_service_id

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

Value Lookups:

Toggle cloak

Cloak

Insert excerpt

	API
	API
nopanel	true

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

classes_of_service

Yes*

No

ADD

Integer

Example

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

bandwidth

No

Integer

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

action_udf_IDENTIFIER

No*

Mixed

IDENTIFIER of UDF belonging to a Service preceded by “action_udf_”. Example: action_udf_FIELD123
Provided value will be validated against UDF’s data type requirements and used if acceptable.

*A single UDF parameter is Required, but not all of them, if using an Action UDF

action_udf_RECID

No*

Integer

RECID of UDF belonging to a Service preceded by “action_udf_”. Example: action_udf_FIELD123
Provided value will be validated against UDF’s data type requirements and used if acceptable.

*A single UDF parameter is Required, but not all of them, if using an Action 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:

...

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	ADD
catalog	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_id	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

Attachments can be added to Service Desk Actions either on there own, or as a part of any normal creation or update of an existing Action.

Available Fields

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 column from SERVICE_DESK table.
sda_recid	yes	Integer		RECID column from SERVICE_DESK_ACTIONS table.

...

"sd_recid=123"
"sda_number=001"

Request Example

Call:

Code Block

language	php

POST DOMAIN/KEY/servicedesk.json

Headers:

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

Body:

Key	Value
sd_recid	66116
sda_recid	5309

JSON:

Code Block

language	xml

{
    ...
    "files": [
        {
            "filename":"file1.pdf",
            "data":"/9j/SOMEMORE/BASE64ENCODED/FUN"
        },
        {
            "filename":"file2.pdf",
            "data":"/9j/SOMEMORE/BASE64ENCODED/FUN"
        }
    ]
}

Service Desk Action UDFs

User Defined Fields can be easily set for a Service Desk Action. When Service Desk Upgrade/Downgrade Actions are created by the API, the "old" UDF values from the selected Service are stored on the Action record.

...

Code Block

language	xml

POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT?type=UDFS&field1=value1 ...

Available Fields

Field	Required	Data Type	Default	Notes
type	Yes	String	UDFS	type=UDFS is required
sd_recid	Yes*	Integer		*Conditionally Required, see NOTE below. RECID column from SERVICE_DESK table.
sda_recid	Yes*	Integer		*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

...

"sd_recid=123"
"sda_number=001"

Results

Toggle cloak

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

{
    "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.

...

Code Block

language	xml

POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT?TYPE=GLA&field1=value1 ...

Available Fields

Field	Required	Data Type	Default	Notes
type	yes	String	GLA	type=GLA is required
sd_recid	no	Integer		*Conditionally Required, see NOTE below. RECID column from SERVICE_DESK table.
sda_recid	np	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"

...

"sd_recid=123"
"sda_number=001"

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
        }
    ]
}

Service Desk Action Charges

Available Fields

Field	Required	Data Type	Options	Notes
type	yes	String	"CHARGES"	Service Desk type, must be in the status of Pending, Hold or Complete
recid	no*	Integer		Required to Update an existing Charge
sd_recid	no*	Integer		Required to Add a new Charge. Either sd_recid or sd_number must be used
sd_number	no*	Integer		Required to Add a new Charge. Either sd_recid or sd_number must be used
sda_recid	no*	Integer		Conditionally Required. Used to Add or Update a specific Service Desk Action.
sda_number	no*	Integer		Conditionally Required. sd_recid or sd_number must also be used. Used to Add or Update a specific Service Desk Action.
charge_catalog_recid	yes	Integer		RECID of the Charge Catalog
override_amount	no	Number		Amount to Override the Catalog Charge Amount, if the Catalog allows it
quantity	no	Number		Quantity of Charges of the chosen Catalog to apply, if the Catalog is set to use Quantity
override_gla	no	Integer		RECID of the Override GLA, if the Catalog allows it
prorate	no	Boolean	1 (True) or 0 (False)	Only allowed if BILL_MRC_CHANGE_FORCE_PRORATE config option is false
description	no	String		Description of the Charge
arc_date	no	String		Alternate Recurring Cycle Date, format: “YYYY/MM/DD”

Request Example

Call:

Code Block

language	php

POST DOMAIN/KEY/servicedesk.json

Headers:

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

Body:

Key	Value
type	CHARGES
sd_recid	35812
charge_catalog_recid	7
description	This is a sample Charge

Results

If the request is successful, the RECID of the new Service Desk Action Charge record is returned as follows:

...

Versions Compared

Old Version 5

New Version Current

Key

Read Call

Write Call

Available Fields

Using SDCs

Ordering from Service Pools

Headers:

ADD Action Example

CHG_MOVE Action Example

CHG_UPDOWN Action Example

CHG_MISC Action Example

REMOVE Action Example

CHG_SERVICE_ID Action Example

CHG_MULTI_LOCATION Action Example

CHG_OWNER Action Example

TASK Action Example

Results

Adding Attachments to Service Desk Actions

Available Fields

Request Example

Call:

Headers:

Body:

JSON:

Service Desk Action UDFs

Available Fields

Results

Service Desk Action GLAs

Available Fields

Results

Service Desk Action Charges

Available Fields

Request Example

Call:

Headers:

Body:

Results