Document toolboxDocument toolbox

(2024.2) 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.

Request Type

Description

Request Type

Description

servicedesk.TYPE.OUTPUT

Retrieve a specific type of service desk items. Replace TYPE with any of the following: SO, IN

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.

Parameter

Default

Description

Parameter

Default

Description

LIMIT

20

Number of listings to show.

PAGE

1

Page number to show.

Response Data

Name

Datatype

Searchable

Notes

Name

Datatype

Searchable

Notes

SD_TYPE

string

Yes

The type of the SD item (e.g. Inquiry), use TYPE for search

SD_NUMBER

string

Yes

The unique identifier for a service desk item

DUE_DATE

string

Yes

The date established for the service desk item to be completed

DESCRIPTION

string

Yes

A brief description of the service desk item

OWNER

string

Yes

Name of the service owner – either a Contact or Dept. Hierarchy

CSR

string

Yes

The Customer Service Representative

REQUESTOR

string

Yes

The contact that initiated the service desk item

SD_SOURCE

string

Yes

The originating source of the service desk item (e.g., email or phone)

status

string

Yes

Current status of the service desk item

SERVICEDESK_REMARKS

list

No

All remarks or comments for the service desk item and its actions

SERVICEDESK_EMAIL

list

No

The email thread concerning the service desk item

SERVICEDESK_ATTACHMENTS

list

No

List of attachment documents and files

SERVICEDESK_ACTIONS

list

No

List of all actions for the service desk item

SERVICEDESK_EQUIPMENT

list

No

List of all equipment to be used/associated with the service desk item

SERVICEDESK_CONTACTS

list

No

List of contacts for the service desk item

SERVICEDESK_CHARGES

list

No

List of all charges to be billed on the service desk item

SERVICEDESK_LABOR

list

No

List of the labor performed by worker and when performed

SERVICEDESK_WORKFLOW

list

No

List of all workflow on the service desk item

SERVICEDESK_GLA

list

No

All G/L Accounts associated with this service desk item

SERVICEDESK_CABLE

list

No

List of cable paths for the service desk item

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



Parameter

Replace With

Parameter

Replace With

LISTTYPE

The type of List to be retrieved. Types can be found below.

List Types

Type

Description

Extra Parameters*

Searchable

Results

Type

Description

Extra Parameters*

Searchable

Results

CONTACTS

Retrieve available Contacts

CTYPE - Type of contact. Example: "worker"

yes

Contacts





DEPTHIER

Retrieve available Departments



Coming Soon

Department Hierarchy





EQP_CATALOG

Retrieve available Equipment Catalogs



yes

Equipment Catalog





CHARGE_CATALOG

Retrieve available Charge Catalogs



yes

Charge Catalog





PRCODE

Retrieve available Problem Codes



no

Problem Code





RESCODE

Retrieve available Resolution Codes



no

Resolution Code





CSRS

Retrieve available Customer Service Representatives (CSR)



no

CSR





status

Retrieve available Service Desk Statuses



no

SD Status





SDTYPES

Retrieve available Service Desk Types (Some may not be currently valid for creating or updating SD records via the API)



no

SD Types





UDFS

Retrieve available User Defined Fields (UDF)

SDTYPE - Retrieve UDFs for only a specific SD Type
SORT - Order the results ASC by a specific field

no

UDF





WORKGROUPS

Retrieve available Workgroups



no

Workgroups





LABOR_TYPE

Retrieve available Labor Types



no

Labor Types





SD_CHRG_ACTION

Retrieve available Service Desk Charge Actions



no

SD Charge Actions





URGENCY

Retrieve available Service Desk Urgency values



no

SD Urgency





AUTH_CODE_TYPE

Retrieve available Auth Code Types



no

SD Auth Code





BANDWIDTH

Retrieve available Bandwidth values



no

SD Bandwidth





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.

Available Fields

Field

Required

Data Type

Options

Default

Notes

Field

Required

Data Type

Options

Default

Notes

recid

Only when updating

Integer





Identifier of the record to be updated

status

No

String

"complete", "finalize"



This field should only be used when attempting to Complete or Finalize a Service Order or Incident. When a new Service Desk Item is created, the status is set automatically to "Pending".

due_date

No

String





The date when the Service Desk item is due.

finalized_date

No*

String





Required when setting status to "finalize". The desired date is in the valid format of: mm/dd/yyyy. This field is for Service Orders only. Charges created will use the finalize Date as their Billing Date.

type

Yes

String

"SO" - Service Order
"IN" - Incident
"ES" - Estimate
"WO" - Work Order
"IQ" - Inquiries



Service Desk type

source

No

String

Value Lookups:





"API"

Code for the source of the Service Desk Item. List Type must be SD_SOURCE.

urgency

No

String

Value Lookups:







Set the urgency on the Service Desk Item.

csr

Yes

Integer

Value Lookups:







The customer service representative assigned to the Service Desk item. The Record ID of the Service Rep to be assigned is a required field.

owner

No*

Integer

Value Lookups:







Record ID of either the Contact or the Department owner.
*Required only when completing an order

owner_type

No*

String

"contact" or "department"



Type of owner.
*Required only when setting an owner

requestor

No

Integer

Value Lookups:







Record ID for the name of the person (contact) who is requesting the Service Desk item.

description

No

String





A description of the Service Desk item

assoc_proj

No

Integer





Record ID of the project or problem associated with the service desk item.

remarks

No

String





Service Desk remarks. These remarks show up on the "Activity/Remarks" tab of Service Desk.

udf_IDENTIFIER

No

Mixed





IDENTIFIER of UDF preceded by “udf_”. Example: udf_FIELD123
Provided value will be validated against UDF’s data type requirements and used if acceptable.

udf_UDF-RECID

Yes*

Integer





UDF-RECID is the RECID of the UDF to assign the value to. Example: udf_684=value

  • See Note Below

udf_UDF-IDENTIFIER

Yes*

Mixed

Value Lookups:







IDENTIFIER is the unique Identifier of the UDF to assign the value to. Example: udf_LEGACYNUM=value

  • See Note Below

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

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

Key

Value

recid

143658

type

SO

csr

1

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

Field

Required

Data Type

Options

Default

Notes

Field

Required

Data Type

Options

Default

Notes

status

No

String

"complete", "finalize"



If setting the status to "complete", res_code will be required

finalized_date

No*

String





Required when setting status to "finalize". Date the Incident is finalize on.  Today's date in valid format (mm/dd/yyyy)

prob_code

yes

Integer

Value Lookups:







Record ID of the trouble code.

owner

yes

Integer

Value Lookups:







Record ID of either the Contact or the Department owner.

owner_type

yes

String

"contact" or "department"



Type of owner.

problem

no

String





The details or description of the trouble

res_code

no*

Integer

Value Lookups:







Record ID of the Resolution Code. If setting the status to "complete", this field becomes required.

resolution

no

String





The details or description of the Resolution

service

no

Integer





Record ID for the Service with the trouble

equipment

no

Integer





Record ID for the Equipment with the trouble

sdc

no

Integer





Record ID of the Service Desk Classification

equipment_udf_IDENTIFIER

no

mixed





IDENTIFIER of UDF preceded by "equipment_udf_". Example: equipment_udf_FIELD123.
The provided value will be validated against UDF’s data type requirements and used if acceptable. Only valid if the parameter "equipment" is provided

equipment_udf_RECID

no

mixed





RECID of UDF preceded by "equipment_udf_". Example: equipment_udf_123.
The provided value will be validated against UDF’s data type requirements and used if acceptable. Only valid if the parameter "equipment" is provided

service_udf_IDENTIFIER

no

mixed





IDENTIFIER of UDF preceded by "service_udf_". Example: service_udf_FIELD123.
The provided value will be validated against UDF’s data type requirements and used if acceptable. Only valid if the parameter "service" is provided

service_udf_RECID

no

mixed





RECID of UDF preceded by "service_udf_". Example: service_udf_123
The provided value will be validated against UDF’s data type requirements and used if acceptable. Only valid if the parameter "service" is provided.

Request Example

Call:
Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

Key

Value

recid

267870

prob_code

4

owner

1

owner_type

"contact"

type

IN

csr

1

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

Field

Required

Data Type

Options

Default

Notes

Field

Required

Data Type

Options

Default

Notes

charge_catalog

no

Integer

Value Lookups:







Record ID of the applicable Charge.

charge_description

no

String





The details or description of the Charge on the Estimate

chrg_quantity

no

Integer



1

Quantity of Charge to be used.

prorate

no

Integer

1 or 0

0

Should the Charge be prorated when activated

override_amount

no

Decimal





If allowed by the selected Charge, overrides the default amount from the Charge.

eqp_catalog

no

Integer

Value Lookups:







Record ID of the Equipment Catalog item to added to the Estimate.

eqp_quantity

no

Integer



1

Quantity of the Equipment to be added to the Estimate.

eqp_billable

no

Integer

1 or 0



Mark whether the Equipment item is billable.

labor_type

yes*

Integer

Value Lookups:







Type of Labor to be added.
*Only Required when adding Labor to the Estimate (when "workgroup" field is provided).

workgroup

no

Integer

Value Lookups:







Record ID of the Workgroup to be associated with the Labor record on the Estimate.

labor_description

no

String





Description to give the Labor record.

hours

yes*

String





Hours to be assigned to the labor. Use "h" for hours and "m" for minutes. Example: "1h 30m"
*Only Required when adding labor to the estimate (when "workgroup" field is provided).

rate

no

Decimal





Rate to be billed for Labor. If not provided, default rate from Workgroup will be used.

labor_billable

no

Integer

1 or 0



Mark whether the Labor item is billable.

Request Example

Call:
Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

Key

Value

recid

355989

type

ES

csr

1

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.



Available Fields

Field

Required

Data Type

Options

Default

Notes

Field

Required

Data Type

Options

Default

Notes

sd_recid

yes*

Integer





*Either sd_recid or sd_number are conditionally Required, but not both. RECID column from SERVICE_DESK table.

sd_number

yes*

String





*Either sd_recid or sd_number are conditionally Required, but not both. The Number of the Service Desk item that the UDF is for.

sda_recid

no*

Integer





RECID of the Service Desk Action. If "sda_recid" is provided, "sd_recid" and "sd_number" are not Required.

sda_number

no*

String





Service Desk Action Number for the Action. "sda_number" can be provided instead of "sda_recid" IF "sd_recid" or "sd_number" are provided.

udf_IDENTIFIER

yes*

Mixed





IDENTIFIER is the unique Identifier of the UDF to assign the value to. Example: udf_LEGACYNUM=value
*A single UDF parameter is Required, but not all of them

action_udf_IDENTIFIER

yes*

Mixed





IDENTIFIER of UDF belonging to a Service preceded by “action_udf_”. Example: action_udf_FIELD123
Provided value will be validated against UDF’s data type requirements and used if acceptable.

*A single UDF parameter is Required, but not all of them

action_udf_RECID

yes*

Integer





RECID of UDF belonging to a Service preceded by “action_udf_”. Example: action_udf_FIELD123
Provided value will be validated against UDF’s data type requirements and used if acceptable.

*A single UDF parameter is Required, but not all of them

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:
Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

Key

Value

sd_recid

5434

type

SO

udf_IDENTIFIER

1

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

Field

Required

Data Type

Options

Default

Notes

Field

Required

Data Type

Options

Default

Notes

type

yes

String





type must be REMARKS

sd_recid

yes

Integer





RECID column from SERVICE_DESK table.

remarks

yes

String





The remark to add to the service

sda_recid

no

Integer





*Conditionally Required for use on a Service Desk Action. RECID column from SERVICE_DESK_ACTIONS table.

Request Example

Call:
Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

Key

Value

sd_recid

999

type

REMARKS

remarks

This is a Remark from the API

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

Field

Required

Data Type

Options

Default

Notes

Field

Required

Data Type

Options

Default

Notes

estimate_recid

yes

Integer





RECID column from SERVICE_DESK_EST table.

charge_catalog

yes

Integer

Value Lookups:







Record ID of the applicable charge.

charge_description

no

String





The details or description of the charge on the estimate

chrg_quantity

no

Integer



1

Quantity of charge to be used.

prorate

no

Integer

1 or 0

0

Should the charge be prorated when activated

override_amount

no

Decimal





If allowed by the selected charge, overrides the default amount from the charge.

Request Example

Call:
Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

Key

Value

estimate_recid

56487

charge_catalog

1

type

EST_CHARGES

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

Field

Required

Data Type

Options

Default

Notes

Field

Required

Data Type

Options

Default

Notes

estimate_recid

yes

Integer





RECID column from SERVICE_DESK_EST table.

labor_type

yes

Integer

Value Lookups:







Type of Labor to be added.

workgroup

yes

Integer

Value Lookups:







Record ID of the Workgroup to be associated with the Labor record on the Estimate.

labor_description

no

String





Description to give the Labor record.

hours

yes

String





Hours to be assigned to the Labor. Use "h" for hours and "m" for minutes. Example: "1h 30m".

rate

no

Decimal





Rate to be billed for Labor. If not provided, default rate from Workgroup will be used.

labor_billable

no

Integer

1 or 0



Mark whether the Labor Item is billable.

Request Example

Call:
Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

Key

Value

estimate_recid

55073

labor_type

Regular

workgroup

1

hours

1h 45m

type

EST_CHARGES

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

Field

Required

Data Type

Options

Default

Notes

Field

Required

Data Type

Options

Default

Notes

estimate_recid

yes

Integer





RECID column from SERVICE_DESK_EST table.

eqp_catalog

yes

Integer

Value Lookups:







Record ID of the Equipment Catalog item to added to the Estimate.

eqp_quantity

yes

Integer



1

Quantity of the Equipment to be added to the Estimate.

eqp_billable

yes

Integer

1 or 0



Mark whether the Equipment item is billable.

Request Example

Call:
Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

Key

Value

estimate_recid

78451

eqp_catalog

1

eqp_quantity

1

eqp_billable

1

type

EST_CHARGES

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

Field

Required

Data Type

Options

Default

Notes

Field

Required

Data Type

Options

Default

Notes

type

yes

String



GLA

type=GLA is Required

sd_recid

yes*

Integer





RECID column from SERVICE_DESK table.
*See NOTE below

sd_number

yes*

String





The Number of the Service Desk item that the UDF is for.
*See NOTE below

sda_recid

no*

Integer





RECID of the Service Desk Action. If "sda_recid" is provided, "sd_recid" and "sd_number" are not Required.

sda_number

no

String





Service Desk Action Number for the Action. "sda_number" can be provided instead of "sda_recid" IF "sd_recid" or "sd_number" are provided.

action_default_gla

no*

String or Integer





If a single GLA is sent with a Service Desk request, the value of this is RECID of the GLA. If multiple GLAs are sent with a Service Desk request OR request made directly to the Service Desk GLA POST, this param is "1" or "0" (true/false). If multiple GLAs sent, then these are comma-separated corresponding to the GLAs.

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 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:
Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

Key

Value

sd_recid

78451

gla

1

gla_type

Default

gla_percent

100

type

GLA

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

Field

Required

Data Type

Options

Default

Notes

Field

Required

Data Type

Options

Default

Notes

type

yes

String





type=EQUIPMENT is Required

sd_recid

yes*

Integer





RECID column from SERVICE_DESK table.
*See NOTE below

sd_number

yes*

String





The Number of the Service Desk item that the Equipment is for.
*See NOTE below

sda_recid

no*

Integer





RECID for the Service Desk Action. If "sda_recid" is provided, "sd_recid" and "sd_number" are not Required.

sda_number

no

String





Service Desk Action Number for the Action. "sda_number" can be provided instead of "sda_recid" IF "sd_recid" or "sd_number" are provided.

equipment 

no

Integer





RECID for the Equipment to be added. Used only for Cabling and Asset type Equipment.

equipment _id

no*

Integer





Equipment ID for the Equipment. Conditionally Required for Cabling type Equipment.

to_location 

no

Integer





RECID of the Location the Equipment will be moved to.

from_location 

no

Integer





RECID of the Location the Equipment will be moved from.

qty 

yes

Integer





Quantity of the Equipment to be added

billable 

no

Integer

1 or 0

defaulted to Catalog setting

Mark whether the Equipment item is Billable.

asset_tag

no*

String





The Asset Tag for the Equipment. Conditionally Required for Asset type Equipment.

override_gla

no

Integer





RECID of the GLA to override billing for this Equipment.

eqp_catalog

no*

Integer





Equipment Catalog RECID
*Required if not Cabling or Asset equipment

expense_type

no

Integer

Value Lookups:







The List ID value for the EXPENSE_TYPE List entry that is desired.

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:
Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

Key

Value

sd_recid

78451

qty

1

type

EQUIPMENT

eqp_catalog

1

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

Field

Required

Data Type

Options

Default

Notes

Field

Required

Data Type

Options

Default

Notes

type

yes

String





type=LABOR is Required

sd_recid

yes*

Integer





RECID column from SERVICE_DESK table.

*See Note Below.

sd_number 

yes*

String





Service Desk Number for the Service Desk Item.

*See Note Below

sda_recid

no*

Integer





RECID for the Service Desk Action. If "sda_recid" is provided, "sd_recid" and "sd_number" are not Required.

sda_number

no

String





Service Desk Action Number for the Action. "sda_number" can be provided instead of "sda_recid" IF "sd_recid" or "sd_number" are provided.

labor_type

yes

String

"Regular", "OT", "2xOT"



Type of Labor activity. This is a case-sensitive field.

date

yes

String





Date the Labor action was performed on. YYYY/MM/DD format.

hours

yes

Decimal





Hours to be assigned to the Labor. must be sent in decimal hours (0.5 is 30 min)

workflow

no

Integer





Recid for the Workflow

workgroup

yes

Integer





Recid for the Workgroup. Workgroup must be Active.

worker

yes

Integer





Recid for the Worker. Worker must be an Active Contact with Contact Type = Worker. Worker must be part of provided Workgroup.

flate_rate

no

Decimal



NULL

Rate to be billed for Labor. Only zero or positive dollar amounts are allowed.

description

no

String





Description to give the Labor record

billable

yes

Boolean

1 (True), 0 (False)



Mark whether the Labor action is billable

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:
Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

Key

Value

type

LABOR

sd_recid

66116

labor_type

Regular

date

2019/04/25

hours

1.25

workgroup

1

worker

1

billable

0

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

Field

Required

Data Type

Options

Default

Notes

Field

Required

Data Type

Options

Default

Notes

location

no

Integer





Location restrictions will be checked against the Service Catalog

catalog

no

Integer





RECID of the Service Catalog
Service Catalog must be a "Task" Type

sla

no

Integer





RECID of the SLA

sdc

no

Integer





RECID of the Service Desk Classification

details

no

CLOB





The details for the Work Order

impact

no

Integer

Value Lookups:







RECID for the Impact value

Request Example

Call:
Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

Key

Value

type

WO

catalog

7394

source

Web

csr

1

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. 

Field

Required

Data Type

Options

Default

Notes

Field

Required

Data Type

Options

Default

Notes

type

yes

String





type=WORKFLOW

recid

no

Integer





required if updating

sd_recid

yes*

Integer





*Either sd_recid or sd_number are conditionally Required, but not both. RECID column from SERVICE_DESK table.

sd_number

yes*

String





*Either sd_recid or sd_number are conditionally Required, but not both. The Number of the Service Desk item.

sda_recid

no*

Integer





RECID for the Service Desk Action Number. If "sda_recid" is provided, "sd_recid" and "sd_number" are not Required.

sda_number

no

String





Service Desk Action Number for the Action. "sda_number" can be provided instead of "sda_recid" IF "sd_recid" or "sd_number" are provided.

sequence

yes

Integer





needs to be higher than highest completed sequence

if status is complete, needs to be higher than lowest pending

workgroup

yes

Integer





Record ID of the Workgroup 

worker

no

Integer





Record ID of the Worker. Worker must be an Active Contact with Contact type = Worker. Worker must be part of provided Workgroup.

scheduled_date

no

String





The date Workflow is scheduled to begin.

scheduled_end_date

no

String





The date Workflow is scheduled to end.

billable

yes

Integer

1 or 0



Mark wether Workflow is billable

status

yes

String

PENDING, COMPLETE, HOLD, VOID



Current status of Workflow

notes

no

String





Editable notes for the Workflow

estimated_time

no

String





Example 1.5 is equivalent to 1 hour 30 minutes

start_date

no

String





The date the Workflow was started

completed_date

no

String





The date the Workflow was completed.

activity_remarks

no

String





Required if status is hold. 

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:

Service Desk Inquiries

Inquiries are a special type of request for generic Information.

Note: "type = IQ".

Available Fields

Field

Required

Data Type

Options

Default

Notes

Field

Required

Data Type

Options

Default

Notes

type

yes

String





type = IQ

recid

yes*

Integer





Required in order to Update the Inquiry

subject

yes*

String





Required in order to Create the Inquiry, and cannot be Updated

message

yes*

String





Required in order to Create the Inquiry

topic

yes*

Integer

Value Lookups:







Required in order to Create the Inquiry, and must be a valid LIST RECID of the type SD_INQTOPICS_LISTS_RECID

email

yes*

String





Required in order to Create the Inquiry, UNLESS using Token Authentication. This can not be Updated.

sdc

no

Integer





Cannot be Updated. RECID of the Service Desk Classification

Request Example

Call:
Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

Key

Value

type

IQ

email

demo@pcr.com

subject

Sample Inquiry

message

This is the Inquiry Text

topic

4

Results

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



Service Desk Charges

Available Fields

Field

Required

Data Type

Options

Default

Notes

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 Non-Recurring 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

charge_catalog_recid

yes

Integer





RECID of the Non-Recuring 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

Request Example

Call:
Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

Key

Value

type

CHARGES

sd_recid

35612

charge_catalog_recid

7

description





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

Field

Required

Data Type

Options

Default

Notes

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





*Either sd_recid or sd_number are conditionally Required, but not both. RECID column from SERVICE_DESK table.

sd_number

yes*

String





*Either sd_recid or sd_number are conditionally Required, but not both. The Number of the Service Desk item.

sda_recid

no*

Integer





If "sda_recid" is provided, "sd_recid" and "sd_number" are not Required.

sda_number

no

String





"sda_number" can be provided instead of "sda_recid" IF "sd_recid" or "sd_number" are provided.

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:
Headers:

Key

Value

Key

Value

Content-Type

application/json

Pcr-Html-Encoded

TRUE

Body:

Key

Value

Key

Value

sd_recid

66116

JSON:



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

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:

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.

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