Create a Work Order. Classic Approach

7 minute read

There are two ways to create a work order: the “wizard” approach and the classic approach. To follow the “wizard” approach, see Create a WO. IssueList Approach. The second “classic” approach is described in this guide.

Get Initial Information

Before you can create a work order, you need to get some initial information that is specific to each subscriber. Collect the values of the following parameters:

  • LocationId or StoreId
  • Category
  • TradeName
  • Priority
  • Status.Primary and Status.Extended

Important: When you run API requests as a subscriber, the current SubscriberId is automatically used in the requests. When you send API calls under provider credentials, you usually need to include SubscriberId into your request. This guide provides examples for both subscribers and providers.

After you obtain all the required parameters, you can send a request to create a WO.

LocationId

LocationId usually represents a subscriber’s property, such as a store, restaurant, or gym.

This parameter is required to create a WO, but you can use StoreId instead. LocationId can also be optional when you add AssetId to the WO creation request. In this case, the location of the asset is used as LocationId.

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

GET /odata/locations?$select=Id

Parameter Parameter type Example value
$select Query Id
$filter (required for providers only) Query SubscriberId eq 2014917243

Example request for subscribers:

GET https://sb2api.servicechannel.com/v3/odata/locations?$select=Id HTTP/1.1
Authorization: Bearer {access_token}

Example request for providers:

GET https://sb2api.servicechannel.com/v3/odata/locations?$select=Id&$filter=SubscriberId%20eq%202014917243 HTTP/1.1
Authorization: Bearer {access_token}

Example response:

{
  "@odata.context":" http://sb2api.servicechannel.com/v3/odata/$metadata#locations(Id)",
  "value":[
    {"Id":2006071467},
    {"Id":2006085096},
    {"Id":2006085097},
    {"Id":2006085098},
    {"Id":2006137159},
    {"Id":2006194283},
    {"Id":2006200649}
  ]
}

Response code: HTTP/1.1 200 OK

Use the response to get the following field:

Required field Response body field
LocationId value.Id

StoreId

The StoreId parameter represents the same subscriber’s property as LocationId. However, many subscribers and providers prefer to use StoreId to refer to a particular location as StoreId is usually shorter and more meaningful to them. StoreId is also used in the UI but can come under different names, for example, Store Number or even Location ID. Be careful and always double-check.

Important: The StoreId parameter is not as unique as LocationId. When using StoreId in the API request to create a WO, also include SubscriberID for proper location identification.

You can get a complete list of store IDs for a specific subscriber through the following request:

GET /odata/locations?$select=StoreId

Parameter Parameter type Example value
$select Query StoreId
$filter (required for providers only) Query SubscriberId eq 2014917243

Example request for subscribers:

GET https://sb2api.servicechannel.com/v3/odata/locations?$select=StoreId HTTP/1.1
Authorization: Bearer {access_token}

Example request for providers:

GET https://sb2api.servicechannel.com/v3/odata/locations?$select=StoreId&$filter=SubscriberId%20eq%202014917243 HTTP/1.1
Authorization: Bearer {access_token}

Example response:

{
  "@odata.context":"http://sb2api.servicechannel.com/v3/odata/$metadata#locations(StoreId)",
  "value":[
    {"StoreId":"100"},
    {"StoreId":"102"},
    {"StoreId":"103"},
    {"StoreId":"104"},
    {"StoreId":"106"},
    {"StoreId":"107"},
    {"StoreId":"108"}
  ]
}

Response code: HTTP/1.1 200 OK

Use the response to get the following field:

Required field Response body field
StoreId value.StoreId

Category

Category is the overall classification of a WO, such as Maintenance, Repair, or CAPEX.

You can retrieve a complete list of categories through the following request:

GET /workorders/categories

Parameter Parameter type Example value
subscriberId (required for providers only) Query 2014917243

Example request for subscribers:

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

Example request for providers:

GET https://sb2api.servicechannel.com/v3/workorders/categories?subscriberId=2014917243 HTTP/1.1
Authorization: Bearer {access_token}

Example response:

[
  {
    "Id": 10769,
    "SubscriberId": 2014917243,
    "Name": "CAPEX",
    "HasDependency": false,
    "PrimaryCategoryID": 1,
    "PrimaryCategoryName": "CAPEX"
  },
  {
    "Id": 10768,
    "SubscriberId": 2014917243,
    "Name": "MAINTENANCE",
    "HasDependency": false,
    "PrimaryCategoryID": 6,
    "PrimaryCategoryName": "MAINTENANCE"
  }, ...
]

Response code: HTTP/1.1 200 OK

Use the response to get the following field:

Required field Response body field
Category Name

TradeName

TradeName describes a type of work a service provider performs. This parameter is required to create a WO. TradeName can become optional when you include AssetId in a request. In this case, the trade of the asset is used as TradeName.

Note: TradeName has a narrower definition than Category. For instance, if Doors is a category, then Door-Manual can be an example of a trade.

Request for Subscribers

When you send requests under subscriber credentials, you can get a complete list of trades for all subscriber’s locations through the following request:

GET /odata/trades

Example request for subscribers:

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

Example response:

[
  {
    "Id": 90480,
    "Name": "DOORS",
    "SubscriberId": 2014917243
  },
  {
    "Id": 90474,
    "Name": "HVAC",
    "SubscriberId": 2014917243
  }, ...
]

Response code: HTTP/1.1 200 OK

Use the response to get the following field:

Required field Response body field
TradeName Name

Request for Providers

Under provider credentials, you can retrieve a complete list of trades for a specific subscriber’s location through the following request:

GET /odata/locations({locationId})/trades

Parameter Parameter type Example value
locationId Path 2006071467

Example request for providers:

GET https://sb2api.servicechannel.com/v3/odata/locations(2006071467)/trades HTTP/1.1
Authorization: Bearer {access_token}

Example response:

[
  {
    "Id": 90480,
    "Name": "DOORS",
    "SubscriberId": 2014917243
  },
  {
    "Id": 90474,
    "Name": "HVAC",
    "SubscriberId": 2014917243
  }, ...
]

Response code: HTTP/1.1 200 OK

Use the response to get the following field:

Required field Response body field
TradeName Name

Priority

Priority refers to the period during which a service provider should complete the work.

Get a complete list of WO priorities through the following request:

GET /workorders/priorities

Parameter Parameter type Example value
subscriberId (required for providers only) Query 2014917243

Example request for subscribers:

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

Example request for providers:

GET https://sb2api.servicechannel.com/v3/workorders/priorities?subscriberId=2014917243 HTTP/1.1
Authorization: Bearer {access_token}

Example response:

[
  {
    "Id": 5778,
    "Name": "P1 - 4 Hours",
    "PriorityName": "P1 - 4 Hours",
    "SubscriberId": null,
    "Eta": "4 Hrs",
    "SkipNights": false,
    "SkipWeekends": false,
    "LocationId": null,
    "Trade": null,
    "ScheduledDate": null
  },
  {
    "Id": 5779,
    "Name": "P2 - 8 Hours",
    "PriorityName": "P2 - 8 Hours",
    "SubscriberId": null,
    "Eta": "8 Hrs",
    "SkipNights": false,
    "SkipWeekends": false,
    "LocationId": null,
    "Trade": null,
    "ScheduledDate": null
  }, ...
]

Response code: HTTP/1.1 200 OK

Use the response to get the following field:

Required field Response body field
Priority Name

Status.Primary and Status.Extended

Status.Primary describes the general situation with a WO at a particular time, for example, OPEN or IN PROGRESS.

Status.Extended provides more details about a WO, for example, ON SITE means that a contractor has checked into a WO, while PARTS ON ORDER indicates that a contractor needs to order parts after the visit.

Obtain a complete list of statuses through the following request:

GET /workorders/statuses

Parameter Parameter type Example value
subscriberId (required for providers only) Query 2014917243

Example request for subscribers:

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

Example request for providers:

GET https://sb2api.servicechannel.com/v3/workorders/statuses?subscriberId=2014917243 HTTP/1.1
Authorization: Bearer {access_token}

Example response:

[
  {
    "Id": 3,
    "Name": "COMPLETED",
    "Extended": [
      "",
      "CANCELLED",
      "CONFIRMED",
      "NO CHARGE",
      "PENDING CONFIRMATION"
    ]
  },
  {
    "Id": 2,
    "Name": "IN PROGRESS",
    "Extended": [
      "DISPATCH CONFIRMED",
      "INCOMPLETE",
      "ON SITE",
      "PARTS ON ORDER",
      "PROPOSAL APPROVED",
      "UNSATISFACTORY",
      "WAITING FOR QUOTE"
    ]
  }, ...
]

Response code: HTTP/1.1 200 OK

Use the response to get the following fields:

Required field Response body field
Status.Primary Name or Id
Status.Extended Extended

Note: You can use either Name or ID as a Status.Primary value.

Create a Work Order

After you obtain the values of all the required parameters, you can create a WO.

Request for Subscribers

When you play a subscriber’s role, send the following request to create a WO:

POST /workorders

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

Example request for subscribers:

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

{
  "ContractInfo": {
    "StoreId": "100",
    "TradeName": "HVAC",
    "ProviderId": 2000090505
  },
  "Category": "CAPEX",
  "Priority": "P2 - 8 Hours",
  "Nte": 110,
  "CallDate": "2017-09-28T15:00:00Z",
  "ScheduledDate": "2017-09-28T23:00:00Z",
  "Description": "Test description",
  "Status": {
    "Primary": "Open",
    "Extended": ""
  }
}

Important: Indicate CallDate and ScheduledDate time in UTC. Status is not a required parameter to create a WO but is recommended.

Example response:

{
  "id": 88472932
}

Response code: HTTP/1.1 201 Created

Congratulations! You have created a work order with the following properties:

  • Store ID: 100
  • Provider ID: 2000090505 (test provider)
  • Category: CAPEX
  • Trade: HVAC
  • Priority: P2 - 8 Hours
  • Status: Open

Request for Providers

In some cases, providers can create a WO for their subscribers. The request is almost the same, but you need to add SubscriberId:

POST /workorders

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

Example request for providers:

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

{
  "ContractInfo": {
    "SubscriberId": 2014917243,
    "StoreId": "100",
    "TradeName": "HVAC",
    "ProviderId": 2000090505
  },
  "Category": "CAPEX",
  "Priority": "P2 - 8 Hours",
  "Nte": 110,
  "CallDate": "2017-09-28T15:00:00Z",
  "ScheduledDate": "2017-09-28T23:00:00Z",
  "Description": "Test description",
  "Status": {
    "Primary": "Open",
    "Extended": ""
  }
}

Example response:

{
  "id": 88486021,   
}

Response code: HTTP/1.1 201 Created

Well done! You have created a work order for our test subscriber API SANDBOX with the following properties:

  • Subscriber ID: 2014917243 (test subscriber)
  • Store ID: 100
  • Provider ID: 2000090505 (test provider)
  • Category: CAPEX
  • Trade: HVAC
  • Priority: P2 - 8 Hours
  • Status: Open

Updated: