Table of Contents | ||||
---|---|---|---|---|
|
...
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
| ||||||||||||
SD_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 | 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
|
...
Field | Required | Data Type | Options | Default | Notes | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
recid | Only when updating | Integer | Identifier of the record to be updated | ||||||||||||||
due_date | No | String | The date when the Service Desk item is due. | ||||||||||||||
type | Yes | String | "SO" - Service Order | Service desk type | "WO" - Work Order | Service Desk type | |||||||||||
source | No | String | Lists
| "API" | Code for the source of the Service Desk Item. List Type must be SD_SOURCE. | ||||||||||||
urgency | No | String | Lists
| Set the urgency on the Service Desk Item. | |||||||||||||
csr | Yes | Integer | Lists
| 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 | Lists
| Record ID of either the Contact or the Department owner. | |||||||||||||
owner_type | No* | String | "contact" or "department" | Type of owner. | |||||||||||||
requestor | No | Integer | Lists
| 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 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 | ||||||||||||||
udf_UDF-RECID | Yes* | Integer | UDF-RECID is the RECID of the UDF to assign the value to. Example: udf_684=value
| ||||||||||||||
udf_UDF-IDENTIFIER | Yes* | Mixed | Lists
| IDENTIFIER is the unique Identifier of the UDF to assign the value to. Example: udf_LEGACYNUM=value
|
...
Key | Value |
---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
Key | Value |
---|---|
recid | 143658 |
type | SO |
csr | 1 |
Results
If the request is successful, the SD Number will be returns as follows:
Toggle cloak |
---|
...
These fields are IN ADDITION TO the Service Desk fields listed above
Field | Required | Data Type | Options | Default | Notes | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
problem_code | yes | Integer | Lists
| Record ID of the trouble code. | |||||||||||||
owner | yes | Integer | Lists
| 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 | Lists
| Record ID of the Resolution Code. | |||||||||||||
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 |
Request Example
Call:
Code Block | ||
---|---|---|
| ||
POST DOMAIN/KEY/servicedesk.json |
Headers:
Key | Value |
---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
Key | Value |
---|---|
recid | 267870 |
problem_code | 4 |
owner | 1 |
owner_type | "contact" |
type | IN |
csr | 1 |
Results
If the request is successful, the SD Number will be returns as follows:
Toggle cloak |
---|
...
Key | Value |
---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
Key | Value |
---|---|
recid | 355989 |
type | ES |
csr | 1 |
Results
If the request is successful, the SD Number will be returns as follows:
Toggle cloak |
---|
...
Key | Value |
---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
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:
Toggle cloak |
---|
...
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. On the write request just add remarks=value
to the query, where value is a text string.
Available Fields
Field | Required | Data Type | Options | Default | Notes |
---|---|---|---|---|---|
type | yes | String | type must be REMARKS | ||
sd_recid | yes | Integer | Recid of Service Desk Item | ||
remarks | yes | String | The remark to add to the service | ||
sda_recid | no | Integer | Recid of the Service Desk Action. *Conditionally Required for use on a Service Desk Action. |
Request Example
Call:
Code Block | ||
---|---|---|
| ||
POST DOMAIN/KEY/servicedesk.json |
...
Key | Value |
---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
Key | Value |
---|---|
sd_recid | 999 |
type | REMARKREMARKS |
remarks | This is a Remark from the API |
Results
If the request is successful, the SD Number will be returns as follows:
Toggle cloak |
---|
...
Field | Required | Data Type | Options | Default | Notes | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
estimate_recid | yes | Integer | The RECID of the Service Desk Estimate that the charge is for | ||||||||||||||
charge_catalog | yes | Integer | Lists
| 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:
Code Block | ||
---|---|---|
| ||
POST DOMAIN/KEY/servicedesk.json |
...
Key | Value |
---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
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:
Toggle cloak |
---|
...
Field | Required | Data Type | Options | Default | Notes | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
estimate_recid | yes | Integer | The RECID of the Service Desk Estimate that the Charge is for | ||||||||||||||
labor_type | yes | Integer | Lists
| Type of Labor to be added. | |||||||||||||
workgroup | yes | Integer | Lists
| 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:
Code Block | ||
---|---|---|
| ||
POST DOMAIN/KEY/servicedesk.json |
...
Key | Value |
---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
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:
Toggle cloak |
---|
...
Field | Required | Data Type | Options | Default | Notes | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
estimate_recid | yes | Integer | The RECID of the Service Desk Estimate that the charge is for | ||||||||||||||
eqp_catalog | yes | Integer | Lists
| 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:
Code Block | ||
---|---|---|
| ||
POST DOMAIN/KEY/servicedesk.json |
...
Key | Value |
---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
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:
Toggle cloak |
---|
...
- 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:
Code Block | ||
---|---|---|
| ||
POST DOMAIN/KEY/servicedesk.json |
...
Key | Value |
---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
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:
Toggle cloak |
---|
...
Below is the proper format for making a separate request.
Note: "type=EQUIPMENT" to indicate that this is to create an Equipment record.
...
Field | Required | Data Type | Options | Default | Notes |
---|---|---|---|---|---|
type | yes | String | type=EQUIPMENT is Required | ||
sd_recid | yes* | Integer | The RECID of the Service Desk item that the Equipment is for. | ||
sd_number | yes* | String | The Number of the Service Desk item that the Equipment is for. | ||
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. |
sda_recid | no* | Integer | The RECID of the Action on the Service Desk item the Equipment is for. | ||
sda_number | no* | String | The Service Desk Action Number. | ||
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 |
...
- 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:
Code Block | ||
---|---|---|
| ||
POST DOMAIN/KEY/servicedesk.json |
...
Key | Value |
---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
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:
Toggle cloak |
---|
...
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 |
---|---|---|---|---|---|
type | yes | String | type=LABOR is Required | ||
sd_recid | yes* | Integer | Recid of the Service Desk Item to apply the Labor to. See Note Below. | ||
sda_recid | no* | Integer | Recid of the Service Desk Action to apply the Labor to. See Note Below. | ||
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 |
...
"sd_recid=123"
"sda_number=001"
Request Example
Call:
Code Block | ||
---|---|---|
| ||
POST DOMAIN/KEY/servicedesk.json |
...
Key | Value |
---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
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:
Toggle cloak |
---|
Cloak | |||||||
---|---|---|---|---|---|---|---|
|
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 above makes a service order with the Service Rep whose contact RECID is 209.
...
language | php |
---|
...
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 | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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 | Lists
| RECID for the Impact value |
Request Example
Call:
Code Block | ||
---|---|---|
| ||
POST DOMAIN/KEY/servicedesk.json |
Headers:
Key | Value |
---|---|
Content-Type | application/json |
Pcr-Html-Encoded | TRUE |
Body:
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:
Toggle cloak |
---|
Cloak | |||||||
---|---|---|---|---|---|---|---|
|
Adding Attachments to Service Desk Items
Attachments can be added to Service Desk Items either on there 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 |
---|---|---|---|---|---|
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 | RECID for the Service Desk Record |
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 |
---|---|
sd_recid | 66116 |
JSON:
Code Block | ||
---|---|---|
| ||
{
...
"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.
Code Block | ||
---|---|---|
| ||
curl -X POST --data "CSR=1" http://URL_TO_YOUR_PCR360_INSTALLATION/api/YOURAPIKEY/servicedesk.SO.json |
...
Within PCR-360, these menu options lists list a variety of Grids that can be used to help locate any of the required fields.
...