Create a Work Order. IssueList Approach

26 minute read

You can follow two approaches to create a work order: the classic approach and the IssueList approach. For the classic approach, see Create a WO. Classic Approach. The IssueList approach is described in this guide.

IssueList and IssueChoice

IssueList and IssueChoice are used by the Location Dashboard for work order (WO) creation.

IssueList

IssueList is a list of parameters and combinations of these parameters that customize the WO creation workflow for the Service Request Dashboard. It specifies which set of choices is displayed for the selected option, thus making the WO creation process an easier experience.

IssueList is represented by a Microsoft Excel workbook that consists of several sheets. The initial configuration of IssueList involves associating each problem type with a list of assets, associating each asset with a list of problem codes, and finally applying each Problem Type / Asset / Problem Code matrix to one or several areas.

Note: In the Excel workbook, the Problem Group column corresponds to the ProblemType parameter, the Equipment column is AssetType, and Problem Code stands for ProblemCode.

For example, when the caller selects Area A3, the DOOR and PLUMBING problem types are displayed. When the caller selects PLUMBING, the BACKFLOW, MAJOR LEAK, and NATURAL GAS assets are displayed. Finally, when the caller selects BACKFLOW, the BACKFLOW ISSUE and OTHER PLUMBING ISSUE problem codes are displayed.

Issue List

Note: You can download the Issue List workbook from the Convert Issue List section of the Dashboard.

IssueChoice

Using IssueList, ServiceChannel generates IssueChoice, which is a wizard that allows callers to choose only the right combination of parameters when creating WOs. For example, when the caller selects the required location and area, a list of problem types for these location and area is provided. After the caller selects a problem type, the remaining choices for the selected location, area, and problem type appear.

The screenshot below shows the process of the WO creation through the Service Request Dashboard. The IssueChoice feature helps callers select the right Problem Type, Asset, and Problem, which correspond to ProblemType, AssetType, and ProblemCode parameters.

IssueChoice

Get Initial Information

Before you can create a work order using IssueList, you need to collect some initial information as well as to get an attachment path when the attachment is required to submit a WO.

You should collect the values of the following parameters:

  • LocationId
  • AreaId and ExtendedAreaName
  • ProblemType
  • AssetType
  • ProblemCode
  • TradeName, Category, Priority, and Nte

You can also get some additional information, for example, Providers or Currency.

LocationId

LocationId represents a subscriber’s property, for example, a store, restaurant, or gym. This parameter is usually required to create a WO and is used in some intermediate requests to get other parameters.

Obtain the complete list of locations for a specific subscriber through the following request:

GET /locations

Example request:

GET https://sb2api.servicechannel.com/v3/locations HTTP/1.1
Authorization: Bearer {access_token}

Example response:

{
  "Locations": [
    {
      "Id": 2006071467,
      "SubscriberId": 2014917243,
      "StoreId": "100",
      "Name": "ServiceChannel - API",
      "ShortName": "ServiceChannel - API",
      "Latitude": 40.736618,
      "Longitude": -73.991806,
      "Distance": null,
      "LocationTypeId": null,
      "Address1": null,
      "Address2": "18 East 16th St - 2nd Floor",
      "City": "New York",
      "State": "NY",
      "Region": "NY",
      "District": "Union Square",
      "Zip": "10003",
      "Country": "US",
      "ClosedDate": null,
      "OpenDate": null,
      "Status": "Open",
      "Email": null,
      "FaxNumber": null,
      "Phone": null,
      "Contact": null,
      "Workorders": null,
      "Notes": [
        {
          "Id": 0,
          "HeaderId": 0,
          "Value": null,
          "Header": null
        }
      ]
    }, ...
  ]
}

Response code: HTTP/1.1 200 OK

Use the response to get the following field:

Required field Response body field
LocationId Locations.Id

AreaId and ExtendedAreaName

AredId is the unique identification code of the exact place within one location where the problem has occurred, while ExtendedAreaName is the descriptive name of the area.

GET /subscribers/current/storedashboards/current/issuelist/areas

Example request:

GET https://sb2api.servicechannel.com/v3/subscribers/current/storedashboards/current/issuelist/areas HTTP/1.1
Authorization: Bearer {access_token}

Example response:

{
  "IssueAreas": [
    {
      "ID": 4935,
      "Name": "ELEVATOR/ESCALATOR"
    },
    {
      "ID": 253,
      "Name": "EMPLOYEE LOUNGE"
    },
    {
      "ID": 4934,
      "Name": "EXECUTIVE/MANAGERS OFFICE"
    }, ...
  ]
}

Response code: HTTP/1.1 200 OK

Use the response to get the following fields:

Required field Response body field
AreaId IssueAreas.ID
ExtendedAreaName IssueAreas.Name

ProblemType

ProblemType is an overall description of the problem.

GET /subscribers/current/storedashboards/current/issuelist/areas/{areaId}/problemtypes

Parameter Parameter type Example value
areaId Path 4935

Example request:

GET https://sb2api.servicechannel.com/v3/subscribers/current/storedashboards/current/issuelist/areas/4935/problemtypes HTTP/1.1
Authorization: Bearer {access_token}

Example response:

{
  "ProblemGroupNames": [
    "Elevator",
    "EMERGENCY",
    "Flooring",
    "Lighting-Inside"
  ]
}

Response code: HTTP/1.1 200 OK

Use the response to get the following field:

Required field Response body field
ProblemType ProblemGroupNames (choose any name)

AssetType

AssetType describes an asset or equipment on which the problem has occurred.

Note: To create a work order using the IssueRequest object, you usually need to submit the AssetType parameter, but in this guide we use the EquipmentType parameter because AssetType and EquipmentType are the same thing in the context of WO creation.

GET /subscribers/current/storedashboards/current/issuelist/areas/{areaId}/equipmenttypes?locationId={locationId}&problemType={problemType}

Parameter Parameter type Example value
areaId Path 4935
locationId Query 2006071467
problemType Query Elevator

Example request:

GET https://sb2api.servicechannel.com/v3/subscribers/current/storedashboards/current/issuelist/areas/4935/equipmenttypes?locationId=2006071467&problemType=Elevator HTTP/1.1
Authorization: Bearer {access_token}

Example response:

{
  "IssueEquipmentTypes": [
    "Freight Elevator",
    "Passenger Elevator"
  ]
}

Response code: HTTP/1.1 200 OK

Use the response to get the following field:

Required field Response body field
AssetType IssueEquipmentTypes (choose any name)

ProblemCode

ProblemCode usually describes the exact problem with an asset or equipment.

GET /subscribers/current/storedashboards/current/issuelist/areas/{areaId}/problemcodes?problemType={problemType}&equipmentType={equipmentType}

Parameter Parameter type Example value
areaId Path 4935
problemType Query Elevator
equipmentType Query Freight Elevator

Example request:

GET https://sb2api.servicechannel.com/v3/subscribers/current/storedashboards/current/issuelist/areas/4935/problemcodes?problemType=Elevator&equipmentType=Freight%20Elevator HTTP/1.1
Authorization: Bearer {access_token}

Example response:

{
  "Problems": [
    "Freight Elevator Inspection",
    "Freight Elevator not working",
    "Freight Elevator not working - someone is trapped inside",
    "Freight Elevator Violation"
  ]
}

Response code: HTTP/1.1 200 OK

Use the response to get the following field:

Required field Response body field
ProblemCode Problems (choose any name)

TradeName, Category, Priority, Nte

TradeName describes a type of work a service provider performs. Category is the overall classification of a WO, for example, Maintenance, Repair, or CAPEX. Priority refers to the period during which a service provider should complete the work. Nte is the maximum monetary amount that a service provider may charge for the service.

GET /subscribers/current/storedashboards/current/issuelist/issuechoice?problemType={problemType}&equipmentType={equipmentType}&problemCode={problemCode}&locationId={locationId}

Parameter Parameter type Example value
problemType Query Elevator
equipmentType Query Freight Elevator
problemCode Query Freight Elevator Inspection
locationId Query 2006071467

Example request:

GET https://sb2api.servicechannel.com/v3/subscribers/current/storedashboards/current/issuelist/issuechoice?problemType=Elevator&equipmentType=Freight%20Elevator&problemCode=Freight%20Elevator%20Inspection&locationId=2006071467 HTTP/1.1
Authorization: Bearer {access_token}

Example response:

{
  "Type": "Elevator",
  "EquipmentType": "Freight Elevator",
  "Problem": "Freight Elevator Inspection",
  "Trade": "ELEVATORS",
  "Priority": "P4 - 72 HOURS",
  "RequireAttachment": true,
  "EquipmentEntry": null,
  "Category": "REPAIR",
  "Comments": "",
  "TroubleshootingMessage": "Scan your state's inspection form and attach it to this service request. Please keep a copy in your Store. Type \"Elevator Inspection\" in the \"enter brief description here\" field.",
  "ProviderRank": 0,
  "ApprovalCode": "",
  "AdditionalFields": [],
  "Nte": "1000",
  "RequireEquipment": false
}

Response code: HTTP/1.1 200 OK

Use the response to get the following fields:

Required field Response body field
TradeName Trade
Category Category
Priority Priority
Nte Nte

Attachments.Path

The previous issuelist/issuechoice request returned "RequireAttachment": true. That means an attachment is required to create a new work order.

To create an attachment without a WO and get the attachment path, set the workorderId parameter to -1.

POST /workorders/{workorderId}/attachments

Header Value
Content-Type multipart/form-data; boundary=—-WebKitFormBoundarynvLcpyj4OKRbWL1p
Parameter Parameter type Example value
workorderId Path -1

Example request:

POST https://sb2api.servicechannel.com/v3/workorders/-1/attachments HTTP/1.1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundarynvLcpyj4OKRbWL1p
Authorization: Bearer {access_token}

------WebKitFormBoundarynvLcpyj4OKRbWL1p
Content-Disposition: form-data; name="file"; filename="test.txt"
Content-Type: text/plain

Test text for WO creation request.
------WebKitFormBoundarynvLcpyj4OKRbWL1p--

Example response:

{
  "Attachments": [
    {
      "Id": null,
      "Name": "test.txt",
      "Path": "201706/d8f0792e-81ef-4fcb-95df-1ae0c1be9cd9-test.txt",
      "Description": "test.txt"
    }
  ],
  "Warning": ""
}

Response code: HTTP/1.1 201 Created

Use the response to get the following field:

Required field Response body field
Attachments.Path Attachments.Path

Create a WO Using Basic Parameters

When you get all the required information, send a request to create a WO.

POST /workorders

Header Value
Content-Type application/json
Parameter Parameter type Example value
request Body See below

Example request:

POST https://sb2api.servicechannel.com/v3/workorders HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "ContractInfo": {
    "LocationId": 2006071467,
    "TradeName": "ELEVATORS"
  },
  "Category": "REPAIR",
  "Priority": "P4 - 72 HOURS",
  "Nte": 1000,
  "CallDate": "2017-08-23T19:35:00Z",
  "Description": "ELEVATOR/ESCALATOR / Elevator / Freight Elevator / Freight Elevator Inspection",
  "ProblemCode": "Freight Elevator Inspection",
  "IssueRequestInfo": {
    "AreaId": 4935,
    "ExtendedAreaName": "ELEVATOR/ESCALATOR",
    "ProblemType": "Elevator",
    "AssetType": "Freight Elevator"
  },
  "Attachments": [
    {
      "Name": "test attachment",
      "Description": "for test only",
      "Path": "201706/d8f0792e-81ef-4fcb-95df-1ae0c1be9cd9-test.txt"
    }
  ]
}

Important: Indicate CallDate time in UTC.

Example response:

{
  "id": 87194147
}

Response code: HTTP/1.1 201 Created

Get Additional Information

You can include additional information into an API request to create a WO.

Subscribers that have the assigned Dashboard can retrieve supporting info through the following API request:

GET /subscribers/current/servicerequest/info?areaName={ExtendedAreaName}&problemType={ProblemType}&equipmentType={AssetType}&problemCode={ProblemCode}&locationId={LocationId}

Parameter Parameter type Example value
areaName Query ELEVATOR/ESCALATOR
problemType Query Elevator
equipmentType Query Freight Elevator
problemCode Query Freight Elevator Inspection
locationId Query 2006071467

Example request:

GET https://sb2api.servicechannel.com/v3/subscribers/current/servicerequest/info?areaName=ELEVATOR/ESCALATOR&problemType=Elevator&equipmentType=Freight%20Elevator&problemCode=Freight%20Elevator%20Inspection&locationId=2006071467 HTTP/1.1
Authorization: Bearer {access_token}

Example response:

{
  "IssueChoice": {
    "Type": "Elevator",
    "EquipmentType": "Freight Elevator",
    "Problem": "Freight Elevator Inspection",
    "Trade": "ELEVATORS",
    "Priority": "P4 - 72 HOURS",
    "RequireAttachment": true,
    "EquipmentEntry": "",
    "Category": "REPAIR",
    "Comments": "",
    "TroubleshootingMessage": "Scan your state's inspection form and attach it to this service request. Please keep a copy in your Store. Type \"Elevator Inspection\" in the \"enter brief description here\" field.",
    "ProviderRank": 0,
    "ApprovalCode": "",
    "AdditionalFields": [],
    "Nte": "1000",
    "RequireEquipment": false
  },
  "Providers": [
    {
      "Rank": 1,
      "Category": null,
      "Priority": null,
      "Nte": 400,
      "GeneralEmail": "",
      "IsDefault": true,
      "Phone": "7188675309",
      "FullName": "LF INCORPORATED LLC",
      "Address1": "18East 16th Street",
      "Address2": "Second Floor",
      "City": "New York",
      "State": "NY",
      "Zip": "10003",
      "Country": "US",
      "MainContact": null,
      "DateCreated": null,
      "LastUserDate": null,
      "SuperUser": null,
      "WebSite": "",
      "Email": "LFAlways1776@gmail.com",
      "TaxId": null,
      "Trade": null,
      "ProcessingEmail": "LFAlways1776@gmail.com",
      "FaxNumber": "",
      "SuiteFloor": null,
      "MailInfo": null,
      "ImageFile": null,
      "ReturnMail": null,
      "MailFrequency": null,
      "FormId": null,
      "Pager": "",
      "NightRequest": null,
      "ShortFormatEmail": null,
      "LastTrainingDate": null,
      "LastTrainingDateStr": null,
      "Id": 2000090505,
      "Name": "LF INCORPORATED LLC"
    }
  ],
  "ProvidersNotFoundMessage": null,
  "CallerName": "SC-Dev1",
  "ScheduledDateOffsetFromCallDate": 446417,
  "EquipmentsInfo": {
    "Equipments": [],
    "EquipmentRequired": false
  },
  "AssetsInfo": {
    "Assets": [],
    "AssetRequired": false
  },
  "SetupRequestConfirm": {
    "ChangeableCategory": false,
    "ChangeablePriority": false,
    "ChangeableNte": false,
    "ChangeableScheduledDate": false,
    "ChangeableProvider": false
  },
  "SetupRequest": {
    "NteToZeroForRecalls": false,
    "SetOriginalVendorForRecalls": true,
    "EnableEquipment": false,
    "EnableEquipmentReplacement": false,
    "AllowAttachments": false
  },
  "Categories": [
    {
      "Id": 10769,
      "SubscriberId": 2014917243,
      "Name": "CAPEX",
      "HasDependency": false,
      "PrimaryCategoryID": 1,
      "PrimaryCategoryName": "CAPEX"
    }, ...
  ],
  "Priorities": [
    {
      "Id": 5778,
      "Name": "P1 - 4 Hours",
      "PriorityName": "P1 - 4 Hours",
      "SubscriberId": null,
      "Eta": "4 Hrs",
      "SkipNights": false,
      "SkipWeekends": false,
      "LocationId": -1,
      "Trade": null,
      "ScheduledDate": "2017-08-24T15:01:42.343Z"
    }, ...
  ],
  "SetupGeneral": {
    "AllowAddingAttachments": false,
    "RequireAttachments": false
  },
  "UserSettings": {
    "MaximumNteAmount": 12345678
  },
  "Currency": {
    "Id": 1,
    "AlphabeticalCode": "USD"
  }
}

Response code: HTTP/1.1 200 OK

The response contains the following information:

IssueChoice
The same information that the issuelist/issuechoice request returns.
Providers
The information about providers for the specified issuechoice.
CallerName
The caller’s username.
ScheduledDateOffsetFromCallDate
The offset in seconds that is used to calculate ScheduledDate. ScheduledDateOffsetFromCallDate is added to CallDate in local time, not to CallDate in UTC.
AssetsInfo, EquipmentsInfo
Equipments/Assets contains detailed information about assets. EquipmentRequired/AssetRequired specifies if an asset should be selected to create a WO.
Categories
The detailed information about categories.
Priorities
The detailed information about priorities.
Currency
The currency ID and three-letter alphabetic code.
SetupRequestConfirm
Determines which fields can be changed before submitting a WO. Corresponds to some settings in the Request Confirm tab of the Edit Dashboard Settings section.

Request Confirm tab

SetupGeneral
Specifies if an attachment can be added to a WO and if it is required. Corresponds to some settings in the General tab of the Edit Dashboard Settings section.

General tab

UserSettings.MaximumNteAmount
The maximum NTE amount set for the current user. The user cannot change a WO NTE to the number greater than MaximumNteAmount. Corresponds to NTE limit setting in Admin > Permissions > Users.

ServiceChannel users settings

SetupRequest
Specifies several WO creation options, including important recall parameters NteToZeroForRecalls and SetOriginalVendorForRecalls. Corresponds to some settings in the Request tab of the Edit Dashboard Settings section. EnableEquipment determines if an asset list is shown for a request. Corresponds to the Enable asset checkbox (Edit Dashboard Settings > Request tab).

Request tab

ProvidersNotFoundMessage
The error message displayed when a provider is not found for the specified issuechoice. Corresponds to the Provider Not Found Message field in the Dashboard settings (Edit Dashboard Settings > Request tab).

Request tab

Create a WO Using Additional Parameters

Sometimes you may need to include additional information into an API request to create a WO. Send an issuelist/issuechoice request to check if that is required for a particular issuechoice. You may need to add a comment on the troubleshooting tip, answer the Interactive Troubleshooting questions, or provide a reference to a particular equipment or asset.

Add an Answer to the Troubleshooting Tip

The troubleshooting tip appears when the caller creates a WO though the Service Request Dashboard. It usually contains a request for more information or a step-by-step instruction for the on-site correction.

Troubleshooting tip

The troubleshooting tip is contained in TroubleshootingMessage.

Below is an example of the issuelist/issuechoice request that returned the response that contains TroubleshootingMessage:

GET /subscribers/current/storedashboards/current/issuelist/issuechoice?problemType={problemType}&equipmentType={equipmentType}&problemCode={problemCode}&locationId={locationId}

Parameter Parameter type Example value
problemType Query Door - Automatic
equipmentType Query Handicap Door
problemCode Query Handicap button is missing, post broken
locationId Query 2006071467

Example request:

GET https://sb2api.servicechannel.com/v3/subscribers/current/storedashboards/current/issuelist/issuechoice?problemType=Door%20-%20Automatic&equipmentType=Handicap%20Door&problemCode=Handicap%20button%20is%20missing,%20post%20broken&locationId=2006071467 HTTP/1.1
Authorization: Bearer {access_token}

Example response:

{
  "Type": "Door - Automatic",
  "EquipmentType": "Handicap Door",
  "Problem": "Handicap button is missing, post broken",
  "Trade": "DOORS",
  "Priority": "P3 - 24 HOURS",
  "RequireAttachment": false,
  "EquipmentEntry": "required",
  "Category": "REPAIR",
  "Comments": "",
  "TroubleshootingMessage": "Type the location of the handicap button/pole that needs repair, in the \"enter complete problem description, referencing troubleshooting scripts above\" field.",
  "ProviderRank": 0,
  "ApprovalCode": "",
  "AdditionalFields": [],
  "Nte": "500",
  "RequireEquipment": true
}

Response code: HTTP/1.1 200 OK

To add an answer to TroubleshootingMessage, specify it as the Description parameter value in the API request to create a WO.

Add Answers to the Interactive Troubleshooting Questions

About the Interactive Troubleshooting

Certain problems may require self-troubleshooting first before submitting a WO. The Interactive Troubleshooting feature allows callers to resolve specific issues on site, sometimes without the need of a service provider. This feature is also used to get additional information about the problem occurred.

Below is an example of the Interactive Troubleshooting that the caller should complete to submit a WO though the Service Request Dashboard. The questions could come in different forms, for example, a text field, a drop-down list, or just a label.

Interactive Troubleshooting

The information provided by the caller is then displayed in the WO Description field.

WO description

The text in blue is generated based on the Interactive Troubleshooting field titles and the information provided by the caller.

Exterior / Onsite / Onsite / Onsite / Client Name: Client Name Test / Client Street Address: Client Street Address Test / Client City: Client City Test / Client State: Client State Test / Client State: NM / Client Zip Code: 222 / Client Phone Number: +37525123567 / Test description

In the Dashboard, this information is displayed only in the WO Description field, but we save it in the database as name-value pairs.

Important: Using the Dashboard GUI or SC Mobile app, you cannot create a WO until you complete all the required fields, but an API call does not check that required fields are filled out. You need to check the required fields in your application if you want to implement the Interactive Troubleshooting.

Get AdditionalFields

The AdditionalFields parameter represents the Interactive Troubleshooting.

Below is an example of the issuelist/issuechoice request that returned the response that contains AdditionalFields. If it is not empty, you should add answers to the Interactive Troubleshooting questions to the WO creation request.

GET /subscribers/current/storedashboards/current/issuelist/issuechoice?problemType={problemType}&equipmentType={equipmentType}&problemCode={problemCode}&locationId={locationId}

Parameter Parameter type Example value
problemType Query Elevator
equipmentType Query Freight Elevator
problemCode Query Freight Elevator Inspection
locationId Query 2006071467

Example request:

GET https://sb2api.servicechannel.com/v3/subscribers/current/storedashboards/current/issuelist/issuechoice?problemType=Elevator&equipmentType=Freight%20Elevator&problemCode=Freight%20Elevator%20Inspection&locationId=2006071467 HTTP/1.1
Authorization: Bearer {access_token}

Example response:

{
  "Type": "Elevator",
  "EquipmentType": "Freight Elevator",
  "Problem": "Freight Elevator Inspection",
  "Trade": "ELEVATORS",
  "Priority": "P4 - 72 HOURS",
  "RequireAttachment": true,
  "EquipmentEntry": "",
  "Category": "REPAIR",
  "Comments": "",
  "TroubleshootingMessage": "Scan your state's inspection form and attach it to this service request. Please keep a copy in your Store. Type \"Elevator Inspection\" in the \"enter brief description here\" field.",
  "ProviderRank": 0,
  "ApprovalCode": "",
  "AdditionalFields": [
    {
      "ProblemType": "Onsite",
      "Item": "Onsite",
      "Problem": "Onsite",
      "For": null,
      "Id": "label2",
      "Header": "Client Name",
      "ErrorText": "Required field.",
      "AreaName": "",
      "Exclude": "",
      "Min": "",
      "Max": "",
      "Step": "",
      "Helptip": "Please enter associated client info.",
      "Type": 0,
      "Allow": 2,
      "Size": null,
      "ExpectedValue": "",
      "Options": null,
      "Required": true,
      "DisableFilter": false
    },
    {
      "ProblemType": "Onsite",
      "Item": "Onsite",
      "Problem": "Onsite",
      "For": null,
      "Id": "label3",
      "Header": "Client Street Address",
      "ErrorText": "Required field.",
      "AreaName": "",
      "Exclude": "",
      "Min": "",
      "Max": "",
      "Step": "",
      "Helptip": "Please enter associated client info.",
      "Type": 0,
      "Allow": 2,
      "Size": null,
      "ExpectedValue": "",
      "Options": null,
      "Required": true,
      "DisableFilter": false
    }, ...
  ],
  "Nte": "1000",
  "RequireEquipment": false
}

Response code: HTTP/1.1 200 OK

Create a WO Using AdditionalFields

When you want the WO Description field to include answers to the Interactive Troubleshooting questions, you need to form the whole description on your own. The ServiceChannel API does not provide this functionality.

To form the description in the right order, you should use the following template:

ExtendedAreaName / ProblemType / AssetType / ProblemCode / Field title: Answer / Field title: Answer / Field title: Answer / … / Description / Warning

Note: The field titles here correspond to AdditionalFields.Header parameters. The Description could be an answer to the troubleshooting tip or a comment to a WO. The Warning could contain information about a possible recall WO, for example, POSSIBLE RECALL FROM TR# closed WO tr num.

We recommend you to submit answers to the Interactive Troubleshooting questions not only through the Description parameter but also using the AdditionalFields parameter.

To create a WO that would contain answers to the Interactive Troubleshooting questions, send the following request:

POST /workorders

Header Value
Content-Type application/json
Parameter Parameter type Example value
request Body See below

Example request:

POST https://sb2api.servicechannel.com/v3/workorders HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "ContractInfo": {
    "LocationId": 2006071467,
    "TradeName": "ELEVATORS"
  },
  "Category": "REPAIR",
  "Priority": "P4 - 72 HOURS",
  "Nte": 1000,
  "CallDate": "2017-03-19T01:20:20Z",
  "Description": "ELEVATOR/ESCALATOR / Elevator / Freight Elevator / Freight Elevator Inspection / Client Name: Client Name Test / Client Street Address: Client Street Address Test / Client City: Client City Test / Client State: NM / Client Zip: 222 / Client Phone Number: 1234567 / Test description",
  "ProblemCode": "Freight Elevator Inspection",
  "IssueRequestInfo": {
    "AreaId": 4935,
    "ExtendedAreaName": "ELEVATOR/ESCALATOR",
    "ProblemType": "Elevator",
    "AssetType": "Freight Elevator"
  },
  "Attachments": [
    {
      "Name": "test attachment",
      "Description": "for test only",
      "Path": "201706/d8f0792e-81ef-4fcb-95df-1ae0c1be9cd9-test.txt"
    }
  ],
  "AdditionalFields": [
    {
      "Name": "Client Name",
      "Value": "Client Name Test"
    },
    {
      "Name": "Client Street Address",
      "Value": "Client Street Address Test"
    },
    {
      "Name": "Client City",
      "Value": "Client City Test"
    },
    {
      "Name": "Client State",
      "Value": "NM"
    },
    {
      "Name": "Client Zip",
      "Value": 222
    },
    {
      "Name": "Client Phone Number",
      "Value": "1234567"
    }
  ]
}

Example response:

{
  "id": 85039783
}

Response code: HTTP/1.1 201 Created

Additional Parameters to Consider

Each object in AdditionalFields has several parameters. Explore the information below to enter correct answers to the Interactive Troubleshooting questions.

ProblemType, Item, Problem
Specifies for which ProblemType, AssetType, and ProblemCode the field is applied.
For
The ID of the field to which the current field is connected. Applicable only for drop-down lists that can only be connected to numeric textboxes. For example, callers can enter a numeral into the numeric textbox and then select a unit of measurement from the drop-down list.

Interactive Troubleshooting

Id
The unique identification code of the field, for example, label2, label3, etc.
Header
The title of the field.
ErrorText
The error message that is displayed when the caller has not completed the required field.
AreaName
Specifies for which ExtendedAreaName the field is enabled.
Min, Max
Min specifies the minimum possible value, while Max specifies the maximum possible value. Applicable for numeric textboxes.
Step
Limits the possible numerical values that the caller can enter. The numeral is only accepted if it is divisible by the Step value. Applicable for numeric textboxes.
Helptip
The hint that is displayed inside the field.
Type
Determines the visual format of the field.
Value Field type
0 Textbox
1 Drop-down list
2 Numeric textbox (accepts only numerals)
3 Text label
Allow
Describes the acceptable entered value.
Value Data type
0 Whole numerals
1 Decimals
2 All
Size
Describers the drop-down list that is connected to the numeric text box.
Options
The list of values to select from, for example, [“YES”, ”NO”] or [“AZ”, ”CA”,”DC”, ”TX”]. Applicable for drop-down lists.
Required
Specifies if the field is required or optional.

Adding Information About an Asset

About Assets

When the Assets (Equipment) list is configured for a subscriber and the Enable asset option is selected in the Dashboard settings, the list of assets is shown when the caller creates a WO. In this case, the caller should choose the asset or equipment that is broken or damaged.

Asset Details

Note: You can configure the list of assets as well as all other associated settings in Assets (Equipment) section of Service Automation. You can find the Enable asset option on the Request tab of the Edit Dashboard Settings section.

After the WO is created, the information about the asset is stored both in the WO Description and the Asset Details section that is displayed when you view the WO.

Asset Details

Getting AssetInfo

AssetsInfo contains detailed information about assets as well as all other required settings.

When the Assets (Equipment) list is configured for the location, the issuelist/issuechoice or servicerequest/info request returns EquipmentsInfo and AssetsInfo:

GET /subscribers/current/servicerequest/info?areaName={ExtendedAreaName}&problemType={ProblemType}&equipmentType={AssetType}&problemCode={ProblemCode}&locationId={LocationId}

Parameter Parameter type Example value
areaName Query EMPLOYEE LOUNGE
problemType Query Electrical
equipmentType Query Ceiling Fan
problemCode Query Ceiling fan not working
locationId Query 2006071467

Example request:

GET https://sb2api.servicechannel.com/v3/subscribers/current/servicerequest/info?areaName=EMPLOYEE%20LOUNGE&problemType=Electrical&equipmentType=Ceiling%20Fan&problemCode=Ceiling%20fan%20not%20working&locationId=2006071467 HTTP/1.1
Authorization: Bearer {access_token}

Example response:

{
  "IssueChoice": {
    "Type": "Electrical",
    "EquipmentType": "Ceiling Fan",
    "Problem": "Ceiling fan not working",
    "Trade": "ELECTRICAL",
    "Priority": "P4 - 72 HOURS",
    "RequireAttachment": false,
    "EquipmentEntry": "",
    "Category": "REPAIR",
    "Comments": "",
    "TroubleshootingMessage": "Type a detailed description of the issue with this equipment in the \"enter complete problem description, referencing troubleshooting scripts above\" field.",
    "ProviderRank": 0,
    "ApprovalCode": "",
    "AdditionalFields": [],
    "Nte": "500",
    "RequireEquipment": false
  },
  "Providers": [
    {
      "Rank": 1,
      "Category": null,
      "Priority": null,
      "Nte": 400,
      "GeneralEmail": "",
      "IsDefault": true,
      "Phone": "7188675309",
      "FullName": "LF INCORPORATED LLC",
      "Address1": "18East 16th Street",
      "Address2": "Second Floor",
      "City": "New York",
      "State": "NY",
      "Zip": "10003",
      "Country": "US",
      "MainContact": null,
      "DateCreated": null,
      "LastUserDate": null,
      "SuperUser": null,
      "WebSite": "",
      "Email": "LFAlways1776@gmail.com",
      "TaxId": null,
      "Trade": null,
      "ProcessingEmail": "LFAlways1776@gmail.com",
      "FaxNumber": "",
      "SuiteFloor": null,
      "MailInfo": null,
      "ImageFile": null,
      "ReturnMail": null,
      "MailFrequency": null,
      "FormId": null,
      "Pager": "",
      "NightRequest": null,
      "ShortFormatEmail": null,
      "LastTrainingDate": null,
      "LastTrainingDateStr": null,
      "Users": null,
      "Id": 2000090505,
      "Name": "LF INCORPORATED LLC"
    }
  ],
  "ProvidersNotFoundMessage": null,
  "CallerName": "SC-Dev1",
  "ScheduledDateOffsetFromCallDate": 273608,
  "EquipmentsInfo": {
    "Equipments": [
      {
        "Location": "EMPLOYEE LOUNGE",
        "Id": 1339628,
        "Tag": "90099",
        "Manufacturer": "FAN TECH",
        "ModelNo": "AD-14",
        "SerialNo": null,
        "LocationId": 2006071467,
        "Area": "EMPLOYEE LOUNGE",
        "StoreId": "100",
        "Trade": "ELECTRICAL",
        "Type": "Ceiling Fan",
        "InstallDate": "8/3/2017 12:00:00 AM",
        "Warranty": {
          "WarrantyExpirationDate": "2018-08-03T00:00:00",
          "ExpirationDate": "2018-08-03T00:00:00",
          "WarrantyProviderId": 2000090505,
          "ProviderId": 2000090505,
          "NTE": null,
          "Priority": null,
          "Category": null,
          "Provider": {
            "Type": 0,
            "Value": 2000090505
          },
          "Expiration": {
            "Type": 1,
            "Period": 12
          }
        }
      }, ...
    ],
    "EquipmentRequired": false
  },
  "AssetsInfo": {
    "Assets": [
      {
        "Location": "EMPLOYEE LOUNGE",
        "Warranty": {
          "WarrantyExpirationDate": "2018-08-03T00:00:00",
          "ExpirationDate": "2018-08-03T00:00:00",
          "WarrantyProviderId": 2000090505,
          "ProviderId": 2000090505,
          "NTE": null,
          "Priority": null,
          "Category": null,
          "Provider": {
            "Type": 0,
            "Value": 2000090505
          },
          "Expiration": {
            "Type": 1,
            "Period": 12
          }
        },
        "IsReplaceEquipment": false,
        "Id": 1339628,
        "Tag": "90099",
        "Manufacturer": "FAN TECH",
        "ModelNo": "AD-14",
        "SerialNo": null,
        "LocationId": 2006071467,
        "Area": "EMPLOYEE LOUNGE",
        "StoreId": "100",
        "Trade": "ELECTRICAL",
        "Type": "Ceiling Fan",
        "InstallDate": "8/3/2017 12:00:00 AM",
        "PurchaseDate": ""
      }, ...
    ],
    "AssetRequired": false
  }
}

Response code: HTTP/1.1 200 OK

Note: EquipmentsInfo and AssetsInfo contain the same information. These two objects are present for historical reasons, but we recommend using AssetsInfo.

Use the response to get the following field:

Required field Response body field
AssetId AssetsInfo.Assets.Id

“AssetRequired”: false

In the example response above, the Assets information is present, but an asset is not required to create a WO. In this case, the caller can choose an asset, and the AssetsInfo information for this asset is added to the WO Description field.

“AssetRequired”: true

If AssetRequired is true, the caller must choose an asset from the list to submit a WO. In this case, add "AssetId": {AssetIdValue} to the WO creation request.

Creating a WO Using AssetId

When you want the WO Description field to include information about the asset, you need to form the whole description on your own. The ServiceChannel API does not provide this functionality.

To form the description in the right order you should use the following template:

ExtendedAreaName / ProblemType / AssetType / ProblemCode / Equip: Area “AreaName”, Tag ID “TagValue”, Brand “ManufacturerValue”, Model # “ModelNoValue”, Serial # “SerialNoValue”/ AdditionalFields / Description / Warning

Note: Description could be an answer to the troubleshooting tip or a comment to a WO. AdditionalFields could contain answers to the Interactive troubleshooting questions, and Warning could include information about a possible recall WO, for example, POSSIBLE RECALL FROM TR# closed WO tr num.

To create a WO using AssetId, send the following request:

POST /workorders

Header Value
Content-Type application/json
Parameter Parameter type Example value
request Body See below

Example request:

POST https://sb2api.servicechannel.com/v3/workorders HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "ContractInfo": {
    "StoreId": "100",
    "TradeName": "ELECTRICAL"
  },
  "Category": "REPAIR",
  "Priority": "P4 - 72 HOURS",
  "Nte": 500,
  "CallDate": "2017-08-04T13:09:38.694Z",
  "Description": "Asset Test for 1339628 with current time",
  "ProblemCode": "Ceiling fan not working",
  "IssueRequestInfo": {
    "ProblemType": "Electrical",
    "EquipmentType": "Ceiling Fan",
    "ExtendedAreaName": "EMPLOYEE LOUNGE"
  },
  "AssetId": 1339628
}

Example response:

{
  "id": 86338402
}

Response code: HTTP/1.1 201 Created

Find Duplicate WOs

Before you create a WO, you may need to find possible duplicates to avoid creating the same WO.

The following settings are configured through the Dashboard UI (Edit Dashboard Settings > Request tab) and cannot be obtained by an API request:

  • Days of History to Display
  • Filters for Duplicates
  • Excluded Categories For Open Duplicates
  • Excluded Categories For Closed Duplicates
  • Excluded Statuses

Request tab

Possible Duplicates (Open WOs)

There are one required and four optional parameters to get a list of potential duplicates when creating a WO.

Parameter Required
LocationId Required
Trade (= TradeName) Optional
ProblemCode Optional
ProblemType Optional
Equipment (= AssetType, EquipmentType) Optional

When you provide all these parameters in a request, the correct response is returned according to the Dashboard configuration.

GET /odata/locations({LocationId})/workorders/Service.GetDuplicates()?Trade={Trade}&ProblemCode={ProblemCode}&ProblemType={ProblemType}&Equipment={Equipment}

Parameter Parameter type Example value
locationId Path 2006071467
Trade Query DOORS
ProblemCode Query Handicap button is missing post broken
ProblemType Query Door - Automatic
Equipment Query Handicap Door

Example request:

GET https://sb2api.servicechannel.com/v3/odata/locations(2006071467)/workorders/Service.GetDuplicates()?Trade=DOORS&ProblemCode=Handicap%20button%20is%20missing,%20post%20broken&ProblemType=Door%20-%20Automatic&Equipment=Handicap%20Door HTTP/1.1
Authorization: Bearer {access_token}

Example response:

{
  "@odata.context": "http://sb2api.servicechannel.com/v3/odata/$metadata#workorders",
  "value": [
    {
      "Id": 85301981,
      "Number": "85301981",
      "PurchaseNumber": "85301981",
      "Status": {
        "Primary": "OPEN",
        "Extended": null
      },
      "Caller": "Joaquin",
      "CreatedBy": "SC-Dev1",
      "CallDate": "2017-07-04T03:57:00-04:00",
      "ReassignDate": null,
      "Priority": "P3 - 24 Hours",
      "Trade": "DOORS",
      "ApprovalCode": null,
      "ScheduledDate": "2017-07-05T03:57:00-04:00",
      "CompletedDate": null,
      "ExpirationDate": "2017-07-05T03:57:00-04:00",
      "UpdatedDate": "2017-07-04T04:00:15.01-04:00",
      "Description": "dskljfk jasdfj lasjdfklja skd",
      "Category": "WARRANTY",
      "Nte": 0,
      "Tax": null,
      "Tax2": null,
      "Tax2Type": null,
      "Price": null,
      "ProblemCode": null,
      "Resolution": null,
      "Attachments": {
        "Count": {
          "Total": 0,
          "Own": 0
        }
      },
      "Notes": {
        "Last": {
          "Id": 520274060,
          "Number": 1,
          "NoteData": "Service Request has been dispatched to LF Incorporated LLC via LFAlways1776@gmail.com.",
          "DateCreated": "2017-07-04T04:00:00-04:00",
          "ActionRequired": false,
          "MailedTo": "",
          "CreatedBy": "SC-Dev1"
        },
        "Count": {
          "Total": 1,
          "Own": 1
        }
      },
      "PostedId": 0,
      "IsCheckInDenied": false,
      "CheckInDeniedReason": null,
      "CheckInRange": 0,
      "RecallWorkOrder": null,
      "IsExpired": false,
      "IsEnabledForMobile": false,
      "Source": "Web Request",
      "ClosingAuthorizationNumber": "",
      "CallerId": 0,
      "AutoComplete": false,
      "AutoInvoice": false
    },
    {
      "Id": 85301990,
      "Number": "85301990",
      "PurchaseNumber": "85301990",
      "Status": {
        "Primary": "OPEN",
        "Extended": null
      },
      "Caller": "SC-Dev1",
      "CreatedBy": "SC-Dev1",
      "CallDate": "2017-07-04T08:11:00-04:00",
      "ReassignDate": null,
      "Priority": "P1 - 4 Hours",
      "Trade": "DOORS",
      "ApprovalCode": null,
      "ScheduledDate": "2017-07-04T12:11:00-04:00",
      "CompletedDate": null,
      "ExpirationDate": "2017-07-04T12:11:00-04:00",
      "UpdatedDate": "2017-07-04T08:11:52.9-04:00",
      "Description": "NOTE TEXT 01",
      "Category": "MAINTENANCE",
      "Nte": 131,
      "Tax": null,
      "Tax2": null,
      "Tax2Type": null,
      "Price": null,
      "ProblemCode": "",
      "Resolution": null,
      "Attachments": {
        "Count": {
          "Total": 1,
          "Own": 0
        }
      },
      "Notes": {
        "Last": {
          "Id": 520274074,
          "Number": 1,
          "NoteData": "Service Request has been dispatched to LF Incorporated LLC via LFAlways1776@gmail.com.",
          "DateCreated": "2017-07-04T08:12:00-04:00",
          "ActionRequired": false,
          "MailedTo": "",
          "CreatedBy": "SC-Dev1"
        },
        "Count": {
          "Total": 1,
          "Own": 1
        }
      },
      "PostedId": 0,
      "IsCheckInDenied": false,
      "CheckInDeniedReason": null,
      "CheckInRange": 0,
      "RecallWorkOrder": null,
      "IsExpired": false,
      "IsEnabledForMobile": false,
      "Source": "Archaio",
      "ClosingAuthorizationNumber": "",
      "CallerId": 0,
      "AutoComplete": false,
      "AutoInvoice": false
    }
  ]
}

Response code: HTTP/1.1 200 OK

As always for OData API calls, you can use $expand, $filter, $select, $orderby, $top, $skip, and $count parameters. Below is the example of the same request that returns only work order IDs for potential duplicates with NTE=131.

Example request:

GET https://sb2api.servicechannel.com/v3/odata/locations(2006071467)/workorders/Service.GetDuplicates()?Trade=DOORS&ProblemCode=Handicap%20button%20is%20missing,%20post%20broken&ProblemType=Door%20-%20Automatic&Equipment=Handicap%20Door&$select=Id&$filter=Nte%20eq%20131 HTTP/1.1
Authorization: Bearer {access_token}

Example response:

{
  "@odata.context": "http://sb2api.servicechannel.com/v3/odata/$metadata#workorders(Id)",
  "value": [
    {
      "Id": 85301990
    }
  ]
}

Response code: HTTP/1.1 200 OK

Potential Recalls (Closed WOs)

The ServiceChannel API provides the same functionality to find possible duplicates among work orders with a closed status. These settings are also configured through the Edit Dashboard Settings, and the API request uses the same parameters.

GET /odata/locations({LocationId})/workorders/Service.GetRecalls()?Trade={Trade}&ProblemCode={ProblemCode}&ProblemType={ProblemType}&Equipment={Equipment}&$expand=Provider

Parameter Parameter type Example value
locationId Path 2006071467
Trade Query DOORS
ProblemCode Query Interior door not opening/ closing properly
ProblemType Query Door - Manual
Equipment Query Interior Door

Example request:

GET https://sb2api.servicechannel.com/v3/odata/locations(2006071467)/workorders/Service.GetRecalls()?Trade=DOORS&ProblemCode=Interior%20door%20not%20opening/%20closing%20properly&ProblemType=Door%20-%20Manual&Equipment=Interior%20Door&$expand=Provider HTTP/1.1
Authorization: Bearer {access_token}

Example response:

{
  "@odata.context": "http://sb2api.servicechannel.com/v3/odata/$metadata#workorders",
  "value": [
    {
      "Id": 86075447,
      "Number": "86075447",
      "PurchaseNumber": "86075447",
      "Status": {
        "Primary": "COMPLETED",
        "Extended": ""
      },
      "Caller": "SC-Dev1",
      "CreatedBy": "SC-Dev1",
      "CallDate": "2017-07-25T06:17:08.643-04:00",
      "ReassignDate": null,
      "Priority": "P3 - 24 Hours",
      "Trade": "DOORS",
      "ApprovalCode": null,
      "ScheduledDate": "2017-07-26T06:17:00-04:00",
      "CompletedDate": "2017-07-25T06:17:00-04:00",
      "ExpirationDate": "2017-07-26T06:17:00-04:00",
      "UpdatedDate": "2017-07-25T06:18:20.32-04:00",
      "Description": "Employee Lounge / Door - Manual / Interior Door / Interior door not opening/ closing properly / left front door is mulfunction",
      "Category": "REPAIR",
      "Nte": 1000,
      "Tax": null,
      "Tax2": null,
      "Tax2Type": null,
      "Price": null,
      "ProblemCode": "Interior door not opening/ closing properly",
      "Resolution": "",
      "Attachments": {
        "Count": {
          "Total": 0,
          "Own": 0
        }
      },
      "Notes": {
        "Last": {
          "Id": 524486837,
          "Number": 2,
          "NoteData": "WO Edited: status changed from OPEN/ to COMPLETED/.",
          "DateCreated": "2017-07-25T06:18:00-04:00",
          "ActionRequired": false,
          "MailedTo": "",
          "CreatedBy": "SC-Dev1"
        },
        "Count": {
          "Total": 2,
          "Own": 2
        }
      },
      "PostedId": 0,
      "IsCheckInDenied": false,
      "CheckInDeniedReason": null,
      "CheckInRange": 0,
      "RecallWorkOrder": null,
      "IsExpired": false,
      "IsEnabledForMobile": false,
      "Source": "dashboard1775",
      "ClosingAuthorizationNumber": "341378632",
      "CallerId": 0,
      "AutoComplete": false,
      "AutoInvoice": false,
      "Provider": {
        "Id": 2000090505,
        "Name": "LF Incorporated LLC",
        "Phone": "7188675309",
        "FullName": "LF INCORPORATED LLC",
        "Address1": "18East 16th Street",
        "Address2": "Second Floor",
        "City": "New York",
        "State": "NY",
        "Zip": "10003",
        "Country": "US",
        "MainContact": "Pasquale Magneri",
        "DateCreated": "2017-04-12T11:29:27.487-04:00",
        "LastUserDate": null,
        "SuperUser": null,
        "WebSite": "",
        "Email": "LFAlways1776@gmail.com",
        "TaxId": null,
        "Trade": null,
        "ProcessingEmail": "LFAlways1776@gmail.com",
        "FaxNumber": "",
        "SuiteFloor": null,
        "MailInfo": null,
        "ImageFile": null,
        "ReturnMail": null,
        "MailFrequency": null,
        "FormId": null,
        "Pager": "",
        "NightRequest": null,
        "ShortFormatEmail": null,
        "LastTrainingDate": null,
        "LastTrainingDateStr": null
      }
    }
  ]
}

Response code: HTTP/1.1 200 OK

Create a Recall WO

It may happen sometimes that the quality of the service provided is unacceptable, or the problem has not been solved. In this case, create a recall WO based on the closed WO.

Copy the WO description from the closed WO. It should be proposed as an editable description for a new recall WO in addition to the description autogenerated by IssueChoice. When the caller creates a WO via the Dashboard UI or the SC Mobile app, “POSSIBLE RECALL FROM TR# old_WO_TR_NUM_value” string is added to the WO description.

When you create a recall WO, consider the following Dashboard settings:

  • NteToZeroForRecalls. If true, Nte should be 0.
  • SetOriginalVendorForRecalls. If true, include providerId of the closed WO into the request.

You can obtain these parameters through the servicerequest/info API call described above.

To create a recall WO, send the following request:

POST /workorders

Header Value
Content-Type application/json
Parameter Parameter type Example value
request Body See below

Example request:

POST https://sb2api.servicechannel.com/v3/workorders HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "ContractInfo": {
    "StoreId": "100",
    "TradeName": "DOORS",
    "ProviderId": 2000090505
  },
  "Category": "REPAIR",
  "Priority": "P3 - 24 HOURS",
  "Nte": 0,
  "CallDate": "2017-03-19T01:20:20Z",
  "Description": "TEST with EMPLOYEE LOUNGE / Door - Manual / Interior Door /Interior door not opening/ closing properly/Employee Lounge / Door - Manual / Interior Door / Interior door not opening/ closing properly / left front door is malfunction/New Manual Description/ POSSIBLE RECALL FROM TR#86075447",
  "ProblemCode": "Interior door not opening/ closing properly",
  "IssueRequestInfo": {
    "ProblemType": "Door - Manual",
    "EquipmentType": "Interior Door",
    "ExtendedAreaName": "EMPLOYEE LOUNGE"
  },
  "RecallWorkOrder": 86075447
}

Example response:

{
  "id": 86075448
}

Response code: HTTP/1.1 201 Created

As a result, the recall WO contains the POSSIBLE RECALL information in its description, is assigned to the same provider (LF INCORPORATED LLC), its NTE is set to 0, and Recall Yes - Orig. Tracking #: 86075447 is included in the WO details.

Updated: