.Service Desk Action API Calls v2.1.4.7

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:

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,_ *

Unknown macro: {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	[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 require 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.
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:

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

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?field1=value1 ...

Available Fields

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. _*See NOTE below_
sda_recid	yes*	Integer		The RECID of the Action. _*See NOTE below_
sd_number	yes*	String		The Number of the Service Desk item that the UDF is for. _*See NOTE below_
sda_number	yes*	Integer		The Number of the Action that the UDF is for. _*See NOTE below_
udf_IDENTIFIER	yes	Mixed		IDENTIFIER is the unique Identifier of the UDF to assign the value to. Example: udf_LEGACYNUM=value

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 UDF records will be returned in the same order as provided:

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

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?field1=value1 ...

Available Fields

Field	Required	Data Type	Default	Notes
type	yes	String	GLA	type=GLA is required
sd_recid	yes*	Integer		The RECID of the Service Desk item that the UDF is for. _*See NOTE below_
sda_recid	yes*	Integer		The RECID of the Action. _*See NOTE below_
sd_number	yes*	String		The Number of the Service Desk item that the UDF is for. _*See NOTE below_
sda_number	yes*	Integer		The Number of the Action that the UDF is for. _*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:

    <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 GLA App Record

Unable to render embedded object: File (Service_Desk_Action-GLA.png) not found.

Locating Service Desk Action Data

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