Table of Contents | ||||
---|---|---|---|---|
|
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:
Code Block | ||
---|---|---|
| ||
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).
Code Block | ||||
---|---|---|---|---|
| ||||
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
...
RECID / sda_number
...
No
...
Yes*
...
Integer
...
*Either “RECID” or “sda_number” are "Conditionally Required" when attempting to UPDATE, but not both
...
sd_recid / sd_number
...
Yes*
...
No
...
Integer / String
...
*Either “sd_recid” or “sd_number” are "Conditionally Required" when attempting to INSERT, but not both
...
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
...
No
...
Integer
...
...
RECID of SLA
...
due_date
...
No
...
No
...
String
...
Format “YYYY/MM/DD”
...
service_host / service_host_name
...
No*
...
No*
...
Integer / String
...
...
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.
...
- 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
- 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
...
udf_IDENTIFIER
...
No
...
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.
Headers:
...
Key
...
Value
...
Content-Type
...
application/json
...
Pcr-Html-Encoded
...
TRUE
...
Code Block | ||
---|---|---|
| ||
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
...
Code Block | ||
---|---|---|
| ||
POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT |
...
Code Block | ||
---|---|---|
| ||
POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT |
...
Code Block | ||
---|---|---|
| ||
POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT |
...
Code Block | ||
---|---|---|
| ||
POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT |
...
ACTION
...
Code Block | ||
---|---|---|
| ||
POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT |
...
Field
...
Value
...
type
...
ACTION
...
Code Block | ||
---|---|---|
| ||
POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT |
...
Field
...
Value
...
type
...
ACTION
...
CHG_MULTI_LOCATION
...
Code Block | ||
---|---|---|
| ||
POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT |
...
Field
...
Value
...
type
...
ACTION
...
CHG_OWNER
...
Code Block | ||
---|---|---|
| ||
POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT |
...
Field
...
Value
...
type
...
ACTION
...
TASK
...
Cloak | |||||
---|---|---|---|---|---|
If the request is successful, the RECID of the Action will be returned as follows:
|
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
...
'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).
...
RECID for the Service Desk Action
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:
Code Block | ||
---|---|---|
| ||
POST DOMAIN/KEY/servicedesk.json |
Headers:
...
Key
...
Value
...
Content-Type
...
application/json
...
Pcr-Html-Encoded
...
TRUE
Body:
...
Key
...
Value
...
JSON:
...
language | xml |
---|
...
Table of Contents | ||||
---|---|---|---|---|
|
Read Call
As of version 2.1.4.5, 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:
Code Block | ||
---|---|---|
| ||
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).
Code Block | ||
---|---|---|
| ||
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
As of PCR-360 version 2.1.4, 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
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 required when attempting to UPDATE, but not both | ||
sd_recid / sd_number | Yes* | No | Integer / String | *Either “sd_recid” or “sd_number” are required when attempting to INSERT, but not both | ||
sd_action | Yes | No | String | ADD, CHG_MOVE, CHG_UPDOWN, CHG_MISC, REMOVE | The type of Service Desk Action to be created | |
location | No* | No* | Integer | RECID of Location / *Some Services can make the Location required | ||
moveto_location | No | No | Integer | RECID of Location | ||
catalog | Yes | No | ADD, CHG_UPDOWN | Integer | RECID of Service Catalog | |
service / service_id | Yes | No | CHG_UPDOWN, CHG_MOVE, CHG_MISC, REMOVE | Integer | *Either RECID of Service or SERVICE_ID of Service needs to be provided | |
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 / *Some Services require Service Host | ||
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. | |
udf_IDENTIFIER | No | No | Mixed | IDENTIFIER is the unique identifier string given to each UDF |
Results
If the request is successful, the RECID of the Action will be returned as follows:
Code Block | ||
---|---|---|
| ||
{
"status": "success",
"page": "1",
"count": 1,
"total_count": 0,
"servicedesk": 22184
} |
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 recordset for a Service Desk Action.
Below is the proper format for making a UDF request. Note "type=UDFS" to indicate that this is to add UDFs to an Action.
Code Block | ||
---|---|---|
| ||
POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT?type=UDFS&field1=value1 ... |
Available Fields
Field | Required | Data Type | Options | Default | Notes | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
type | Yesyes | String | UDFS | type=UDFS is required | ||||||||||
sd_recid | Yesyes* | Integer | The RECID of the Service Desk item that the UDF is for. _*Conditionally Required, see See NOTE below_ | |||||||||||
sda_recid | Yesyes* | Integer | The RECID of the Action. _*Conditionally Required, see See NOTE below_ | |||||||||||
sd_number | Yes* | String | The Number of the Service Desk item that the UDF is for. *Conditionally Required, see NOTE below | sda_number | Yesyes* | IntegerString | The Number of the Action Service Desk item that the UDF is for. _*Conditionally Required, see See NOTE belowudf_IDENTIFIER | Yes | Mixed | IDENTIFIER is the unique Identifier of the UDF to assign the value to. Example: udf_LEGACYNUM=value | udf_UDF-RECID | Yes|||
sda_number | yes* | Integer | UDF-RECID is the RECID The Number of the | UDF to assign the value to. Example: udf_684=valueSee Note BelowAction that the UDF is for. _*See NOTE below_ | ||||||||||
udf_ | UDF-IDENTIFIER | Yes*yes | Mixed | IDENTIFIER is the unique Identifier of the UDF to assign the value to. Example: udf_LEGACYNUM=value | See Note Below
NOTES
- "udf_UDF-RECID" and "udf_UDF-IDENTIFIER" are Conditionally Required. The use of one is Required, but not both.
- "Either "sd_recid" or "sd_number" are Conditionally Required. The use of one is Requiredneed to be provided, but not both.
- Either "sda_number" or "sda_recid" are Conditionally Required. The use of one is Requiredis 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
...
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 | ||
---|---|---|
| ||
<servicedesk> <status>success</status> <page>1</page> <count>1</count> <total_count>1</total_count> <servicedesk> <item>5434</item> <item>5435</item> </servicedesk> </servicedesk> |
Service Desk Action GLAs
GLAs can be easily set for a Service Desk Action.
...
Code Block | ||
---|---|---|
| ||
POST http://DOMAIN/api/API_KEY/servicedesk.OUTPUT?TYPE=GLA&field1=value1 ... |
Available Fields
Field | Required | Data Type | Options | Default | Notes |
---|---|---|---|---|---|
type | yes | String | GLA | type=GLA is required | |
sd_recid | noyes* | Integer | The RECID of the Service Desk item that the UDF is for. _*Conditionally Required, see See NOTE below_ | ||
sda_recid | npyes* | Integer | The RECID of the Action. *Conditionally Required, see _*See NOTE below_ | ||
sd_number | npyes* | String | The Number of the Service Desk item that the UDF is for. _*Conditionally Required, see See NOTE below_ | ||
sda_number | noyes* | Integer | The Number of the Action that the UDF is for. _*Conditionally Required, see 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
...
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 | ||
---|---|---|
| ||
<servicedesk><status>success</status> <page>1</page> <status>success</status> <page>1</page> <count>1</count> <total_count>1</total_count> <servicedesk> <item>5434</item> <item>5435</item> </servicedesk> </servicedesk> |
Service Desk Action GLA App Record
Locating Service Desk Action Data
Please see the wiki entry for Service Desk Actions for detailed information about where this data can be found.
...