Document toolboxDocument toolbox

(v1) .Service Desk Action API Calls v2021.1

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 (v1) How to get RECID values FAQ page for how to locate needed RECIDs.

Using POST Calls

  • POST requests will ignore parameters supplied as a query string and need any additional parameters in the request Body.
  • To configure the number of Pages/Results returned by the API (this is most useful for the SQL Endpoint), you can send these as additional Parameter's in the Body.

    Parameter

    Data Type

    Default

    Description

    limit

    Interger

    20

    Number of listings to show.

    page

    Interger

    1

    Page number to show.

  • API fields are not case sensitive, and will always be returned in the lower case format.

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

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 C Service Host

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.

sdcNoNo
Integer
Passing an SDC will allow an Action to be created with default Workflows, Equipment and Charges. RECID column from SDC table.
new_serviceNoNoCHG_SERVICE_IDInteger
The new Service ID for the Service being changed.
One of the following must be true for the new Service ID:
  1. 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
  2. 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
  3. doesn't exist
auth_code_typeYes*NoADDInteger

Lists 

RECID of Auth Code Type for an authcode service.
*Required when attempting to INSERT an authcode Service.
classes_of_serviceYes*NoADDIntegerExampleRECID of Class of Service for an authcode service.
*Required when attempting to INSERT a new auth_code_type record.
bandwidthNoNo
Integer

Lists 

RECID of Bandwidth for a data/backbone service.
owner_typeNoNoCHG_OWNERString'contact', 'department'The type of the Owner, either a Contact or a Department.
ownerNoNoCHG_OWNERInteger
RECID of the Owner. Must be Active.

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


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

FieldRequiredData TypeOptionsDefaultNotes
typenoStringATTACHMENT
Can be used to add an attachment when creating, or updating any Service Desk Action
filesyesarray

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_recidyesInteger

RECID column from SERVICE_DESK table.
sda_recidyesInteger

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_recid66116
sda_recid5309
JSON:
{
    ...
    "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.

Below is the proper format for making a UDF request. Note "type=UDFS" to indicate that this is to add UDFs to an Action.

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

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-RECIDYes*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-IDENTIFIERYes*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.
  • "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.

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

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


Locating Service Desk Action Data

Please see the wiki entry for Service Desk Actions for detailed information about where this data can be found.

Help Desk Portal - Email: help@pcr.com - Phone: 616.259.9242