(2024.2) Service Desk Action API Endpoint
- 1 Read Call
- 2 Write Call
- 2.1 Available Fields
- 2.1.1 Using SDCs
- 2.1.2 Ordering from Service Pools
- 2.1.2.1 Headers:
- 2.1.3 ADD Action Example
- 2.1.4 CHG_MOVE Action Example
- 2.1.5 CHG_UPDOWN Action Example
- 2.1.6 CHG_MISC Action Example
- 2.1.7 REMOVE Action Example
- 2.1.8 CHG_SERVICE_ID Action Example
- 2.1.9 CHG_MULTI_LOCATION Action Example
- 2.1.10 CHG_OWNER Action Example
- 2.1.11 TASK Action Example
- 2.2 Results
- 2.1 Available Fields
- 3 Adding Attachments to Service Desk Actions
- 3.1 Available Fields
- 3.1.1 Request Example
- 3.1 Available Fields
- 4 Service Desk Action UDFs
- 4.1 Available Fields
- 4.2 Results
- 5 Service Desk Action GLAs
- 5.1 Available Fields
- 5.2 Results
- 6 Service Desk Action Charges
- 6.1 Available Fields
- 6.2 Request Example
- 6.3 Results
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.
An example query to retrieve basic Service Desk Action data is as follows:
SELECT * FROM SERVICE_DESK_ACTIONS WHERE SERVICE_DESK_RECID = {SERVICE_DESK_RECID}
If readable values are desired for data such as “SD Action”, “Service Catalog”, etc., then JOINS will need to be made to the appropriate tables. The below query will retrieve the same data as above, but with readable values for “SD Action” and “Service Catalog” (if the data exists).
SELECT
SDA . *,
L . VALUE as SD_ACTION_READABLE,
SC . SERVICE_NAME as SERVICE_CATALOG_NAME
FROM SERVICE_DESK_ACTIONS SDA
JOIN LISTS L ON SDA . SD_ACTION_LISTS_RECID = L . RECID
JOIN LEFT SERV_CATALOG SC ON SDA . SERV_CATALOG_RECID = SC . RECID
WHERE
SDA . SERVICE_DESK_RECID = {SERVICE_DESK_RECID}
Note: In both examples above, {SERVICE_DESK_RECID} needs to be replaced with the actual RECID of the Service Desk Item.
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.
Currently available Action types:
Add
Move
Upgrade/Downgrade
Remove
Miscellaneous
Service ID
Add Location
Change Owner
Task
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 | |
status | No | No |
| String | "complete" | This field should only be used when attempting to Complete a Service Desk 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* | No* | CHG_MULTI_LOCATION | Integer | RECID of Location. | |
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 | |
rating_group | No* | No | String | The LIST CODE for the Rating Group for the Phone Service being used by the Service Desk Action. | ||
sla | No | No | Integer | RECID of SLA | ||
due_date | No | No | String | Format “YYYY/MM/DD” | ||
service_host / service_host_name | No* | No* | Integer / String | RECID of Service Host / Name of Service Host / Either RECID or Name should be provided / Conditionally Required when adding an Action to a Phone Service Catalog. | ||
reference | No | No | String | |||
owner_contact | No | No | Integer | RECID of Contact. Only a Contact or Department can be Owner, not both. | ||
owner_department | No | No | Integer | RECID of Department. Only a Contact or Department can be Owner, not both. | ||
urgency | No | No | Integer / String | 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 | No | 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 | No | CHG_SERVICE_ID | Integer | The new Service ID for the Service being changed.
| |
auth_code_type | Yes* | No | ADD | Integer | Value Lookups: | RECID of Auth Code Type for an authcode service. |
classes_of_service | Yes* | No | ADD | Integer | RECID of Class of Service for an authcode service. | |
bandwidth | No | No | Integer | Value Lookups: | RECID of Bandwidth for a data/backbone service. | |
owner_type | No | No | CHG_OWNER | String | 'contact', 'department' | The type of the Owner, either a Contact or a Department. |
owner | No | No | CHG_OWNER | Integer | RECID of the Owner. Must be Active. | |
udf_IDENTIFIER | No | No | Mixed | IDENTIFIER is the unique identifier string given to each UDF | ||
action_udf_IDENTIFIER | No* | No* | Mixed | IDENTIFIER of UDF belonging to a Service preceded by “action_udf_”. Example: action_udf_FIELD123 *A single UDF parameter is Required, but not all of them, if using an Action UDF | ||
action_udf_RECID | No* | No* | Integer | RECID of UDF belonging to a Service preceded by “action_udf_”. Example: action_udf_FIELD123 *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
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
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 | Default | 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. |
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
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"
Request Example
Call:
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:
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.
Below is the proper format for making a UDF request. Note "type=UDFS" to indicate that this is to add UDFs to an Action.
Available Fields
Field | Required | Data Type | Options | 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.
| ||
udf_UDF-IDENTIFIER | Yes* | Mixed | IDENTIFIER is the unique Identifier of the UDF to assign the value to. Example: udf_LEGACYNUM=value
|
NOTES
"udf_UDF-RECID" and "udf_UDF-IDENTIFIER" are Conditionally Required. The use of one is Required, but not both.
"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
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"
Results
Service Desk Action GLAs
GLAs can be easily set for a Service Desk Action.
Below is the proper format for making a UDF request. Note "type=GLA" to indicate that this is to add GLAs to an Action.
Available Fields
Field | Required | Data Type | Options | 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" |
NOTES
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"
"sda_recid=345"
Incorrect Examples:
"sd_recid=123"
"sda_number=001"
Results
Service Desk Action Charges
Available Fields
Field | Required | Data Type | Options | Default | 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:
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:
Locating Service Desk Action Data
Please see the wiki entry for Service Desk Actions for detailed information about where this data can be found.