Service Desk API Calls

Read Call

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 API End Point documentation for more information.

Example SELECT query for retrieving Service Desk items and related records:

SELECT * FROM V_SERVICE_SD_CHARGES;

Retrieve Service Desk items that match your search.

Remember, OUTPUT is replaced by the desired data type you want returned. 

Controlling Results Count

By default, 20 items will be returned at a time. 

These parameters are added in addition to any fields from the specific data types.

Response Data

Results

Lists

When inserting or updating Service Desk records, it is sometimes necessary to provide values that exist elsewhere in the system. The LIST method can help to retrieve available options for these values.

Below is how to make a LIST request:

   GET http://DOMAIN/api/API_KEY/servicedesk.OUTPUT?LIST=LISTTYPE

Searchable

If a LISTTYPE is designated as searchable in the table below, adding the "SEARCH" param will return values that contain the provided value.

GET http://DOMAIN/api/API_KEY/servicedesk.OUTPUT?LIST=LISTTYPE&SEARCH=test

List Types

Extra Parameters can be appended to the URL in standard Query String fashion.

Write Call

Note: The List Calls are used to locate the proper List Recid value that needs to be passed in the Endpoint Call. Details for the Call can be found in the Options section of the Available Fields for the various API Call Types.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.

UDF parameters are all lower case when processed by PCR-360. Since Organizations can create their own UDF fields, the generic use of IDENTIFIER is used as a placeholder for actual UDF Identifiers.

Available Fields

• udf_UDF-RECID and udf_UDF-IDENTIFIER are Conditionally Required. The use of one is Required, but not both.
• If a validation error occurs when a request is made to complete or finalize a Service Order, the API will send the same error message as the application. This usually is from a missing required field, or still open Workflows.

Request Example

Call:

POST DOMAIN/KEY/servicedesk.json

Headers:

Body:

Results

If the request is successful, the SD Number will returns as follows:

Service Desk Incidents

Typically, an Incident will include a Service or piece of Equipment that is having an issue. If this was not included when the Incident was created, it can be done with an update.

When including a Service or piece of Equipment on an Incident request, you MUST also supply a Contact Owner or Hierarchy owner for the Incident when creating a new Incident. If an Incident is being updated and it does not currently have an “Owner” specified, the update must also include a record ID for the Contact or Department Hierarchy “Owner”.

Available Fields

These fields are IN ADDITION TO the Service Desk fields listed above

Request Example

Call:

POST DOMAIN/KEY/servicedesk.json

Headers:

Body:

Results

If the request is successful, the SD Number will be returned as follows:

Service Desk Estimates

Typically, an Estimate will include Charges, Labor, and Equipment.

Available Fields

These fields are IN ADDITION TO the Service Desk fields listed above

Request Example

Call:

POST DOMAIN/KEY/servicedesk.json

Headers:

Body:

Results

If the request is successful, the SD Number will be returned as follows:

Service Desk UDFs

User Defined Fields can be easily set for a Service Desk item.

Below is the proper format for making a UDF request.

Note: "type=UDFS" to indicate that this is to add UDFs to a Service.

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

Available Fields

NOTES

• Either "sd_recid" or "sd_number" need to be provided as a Required field, but not both.
• If "sda_recid" is provided, "sd_recid" and "sd_number" are not required.
• "sda_number" can be provided instead of "sda_recid" IF "sd_recid" or "sd_number" are provided.

Request Example

Call:

POST DOMAIN/KEY/servicedesk.json

Headers:

Body:

Results

If the request is successful, the RECID(s) of the new Service Desk UDF records will be returned in the same order as provided:

Service Desk Remarks

If the supplied API key has write privileges to write Service Desk Remarks, it is easy to insert Remarks for the new or existing Service Desk Item.

Available Fields

Request Example

Call:

POST DOMAIN/KEY/servicedesk.json

Headers:

Body:

Results

If the request is successful, the SD Number will be returns as follows:

Service Desk Estimate Charges

It is easy to insert a single Charge for the new or existing Service Desk Estimate. On the write request just add the appropriate fields to the query. If multiple Charges need to be added to a single Estimate, then separate POST requests will need to be made.

Below is the proper format for making a separate request.

Note: "type=EST_CHARGES" to indicate that this is to create an Estimate Charge record.

Available Fields

Request Example

Call:

POST DOMAIN/KEY/servicedesk.json

Headers:

Body:

56487

Results

If the request is successful, the RECID of the new service desk estimate charge is returned as follows:

Service Desk Estimate Labor

It is easy to insert a single Labor record for the new or existing Service Desk Estimate. On the write request, just add the appropriate fields to the query. If multiple Labor records need to be added to a single Estimate, then separate POST requests will need to be made.

Below is the proper format for making a separate request.

Note: "type=EST_LABOR" to indicate that this is to create an Estimate Labor record.

Available Fields

Request Example

Call:

POST DOMAIN/KEY/servicedesk.json

Headers:

Body:

55073

Results

If the request is successful, the RECID of the new service desk estimate labor record is returned as follows:

Service Desk Estimate Equipment

It is easy to insert a single Equipment record for the new or existing Service Desk Estimate. On the write request, add the appropriate fields to the query. If multiple Equipment records need to be added to a single Estimate, then separate POST requests will need to be made.

Below is the proper format for making a separate request.

Note: "type=EST_EQP" to indicate that this is to create an Estimate Equipment record.

Available Fields

Request Example

Call:

POST DOMAIN/KEY/servicedesk.json

Headers:

Body:

78451

Results

If the request is successful, the RECID of the new service desk estimate equipment record is returned as follows:

Service Desk Adding GLAs

It is easy to insert one or more GLA records for the new or existing Service Desk Order. On the write request, add the appropriate fields to the query.

Below is the proper format for making a separate request.

Note: "type=GLA" to indicate that this is to create a Service Order record.

Available Fields

NOTES

• Either "sd_recid" or "sd_number" need to be provided as a Required field, but not both.
• If "sda_recid" is provided, "sd_recid" and "sd_number" are not required.
• "sda_number" can be provided instead of "sda_recid" IF "sd_recid" or "sd_number" are provided.
• "action_default_gla" is required if the configuration sda_allow_multiple_default_glas is TRUE.

Request Example

Call:

POST DOMAIN/KEY/servicedesk.json

Headers:

Body:

Results

If the request is successful, the RECID of the new service desk GLA record is returned as follows:

Service Desk Equipment

It is easy to insert one or more Equipment records for the new or existing Service Desk Order. On the write request, add the appropriate fields to the query.

Below is the proper format for making a separate request.

Note: "type=EQUIPMENT" to indicate that this is to create an Equipment record.

Available Fields

NOTES

• Either "sd_recid" or "sd_number" need to be provided as a Required field, but not both.
• If "sda_recid" is provided, "sd_recid" and "sd_number" are not required.
• "sda_number" can be provided instead of "sda_recid" IF "sd_recid" or "sd_number" are provided.

Request Example

Call:

POST DOMAIN/KEY/servicedesk.json

Headers:

Body:

Results

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

Service Desk Labor

It is easy to insert one or more Labor records for the new or existing Service Desk Item. On the write request, add the appropriate fields to the query.

Below is the proper format for making a separate request.

Note: "type=LABOR" to indicate that this is to create an Equipment record.

Available Fields

NOTES:

• "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:

Body:

Results

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

Service Desk Work Orders

Work Orders are a special type of one-time Order, that does not create or manage Services.

Note: "type = WO".

Available Fields

Request Example

Call:

POST DOMAIN/KEY/servicedesk.json

Headers:

Body:

Results

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

Service Desk Workflow

Note: "type=WORKFLOW' to indicate that this is to create a Workflow record. 

NOTES:

• "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"
• "sd_recid=345"

Incorrect Examples

• "sd_recid=123"
• "sda_number=001"

Request Example

Call:

POST DOMAIN/KEY/servicedesk.json

Service Desk Inquiries

Inquiries are a special type of request for generic Information.

Note: "type = IQ".

Available Fields

Request Example

Call:

POST DOMAIN/KEY/servicedesk.json

Headers:

Body:

Results

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

Service Desk Charges

Available Fields

Request Example

Call:

POST DOMAIN/KEY/servicedesk.json

Headers:

Body:

Results

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

Adding Attachments to Service Desk Items

Attachments can be added to Service Desk Items either on their own, or as a part of any normal creation or update of an existing Service Desk Item.

Available Fields

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:

Body:

JSON:

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

How to Create a Service Order

The method of making calls to the API will vary depending on what application or language used. Running requests using cURL on the command line. The most basic of examples is as follows:

The request below makes a service order with the Service Rep whose contact RECID is 209.

curl -X POST --data "CSR=1" http://URL_TO_YOUR_PCR360_INSTALLATION/api/YOURAPIKEY/servicedesk.SO.json

• "curl" indicates the program you're trying to use.
• -X POST tells curl you want to make a POST request (change POST to GET to make a GET request, etc)
• --data "…" is a query string of parameters to send as the POST data. i.e. "foo=bar&bat=baz&etc=123" and so on.
• the URL to request. Notice at the end is "json". This is the format you want the response returned in. "json", "php" and "xml" are your available options.

This request returns the following:

{
	"status": "success",
	"page": 1,
	"count": 1,
	"total_count": 0,
	"servicedesk": "SO20160600145"
}

It is a JSON encoded string (because json was specified in the URL) with 2 important points of information: "status" and "servicedesk". If "status" is "success" as it is above, then "servicedesk" will be the ID for the Service Order (or Estimate (ES) or Incident (IN) if specified). If "status" is "failure", then a parameter named "message" will be in-place of "servicedesk" with a reason as to why it failed. Example:

{
	"status": "failure",
	"message": "The following information is required: car"
}

Locating Service Desk Data

Within PCR-360, these menu options list a variety of Grids that can be used to help locate any of the required fields.

• Main > Service Desk
• Main > Services
• Main > Inventory
• Main > Catalog
  • Specifically G/L Accounts (GLA) and Charges

All grids have the option to show the ROW ID column, which is also the RECID for that particular record.