Skip to main content

Work Order Management API

Version 1.4 — March 2025

Authentication - Login API

To access the GraphQL APIs, users must first authenticate using the Xemelgo Login REST API.

Endpoint Details

  • URL: https://rest.api.xemelgo.com/login
  • Method: POST

Properties

PropertyTypeDescriptionRequired
emailStringbase64 Encoded email id for userYes
passwordStringbase64 encoded password for userYes

Password needs to be a minimum of 8 characters and should have a number in it.

Request Body

{
"email": "base64_encoded_email",
"password": "base64_encoded_password"
}

StatusCode - 200 on success

Response Body

{
"AccessToken": "$accessToken",
"ExpiresIn": 480,
"TokenType": "Bearer",
"RefreshToken": "$refreshToken",
"IdToken": "$idToken"
}

Use the $idToken as the authorization header for all API requests.

Errors

ErrorError codeException
In correct username and/or password400NotAuthorizedException

Create Work Order Set API

Create Work Order Set API allows to create multiple work orders at the same time and associate them to the respective RFID tracker serial number.

Endpoint Details

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Properties

PropertyTypeDescriptionRequired
order_numberStringWork order / Job numberYes
tracker_serialStringSerial number of the RFID tag associated to the specific work orderNo
start_dateAWSTimestampExpected start date for the work order in Epoch time in millisecondsNo
completion_dateAWSTimestampExpected completion date for the work order in Epoch time in millisecondsNo
onboarding_locationStringA Xemelgo verified location identifier to which the work order should be onboarded toNo
tenant_propertiesAWSJSONAdditional properties that a customer may want to specify for the work order. Example: const data = { Scheduling_code: "VHIGH" }; const tenant_properties = JSON.stringify(data);No

Headers

Authorization – $idToken

Request Body

mutation {
createWorkOrderSet(
input: [
{
order_number: "test-type-2",
tracker_serial: "test-type-2",
start_date: 1695968611000,
completion_date: 1698560611000,
onboarding_location: "Location A",
tenant_properties: "\"scheduling_code\":\"VHIGH\""
}
]
) {
work_order_numbers
}
}

Status Code - 200

Response Body

{
"data": {
"createWorkOrderSet": {
"work_order_numbers": [
// list of work order numbers
]
}
}
}

Errors

ErrorError codeException
Expired token401Unauthorized
Invalid token401Unauthorized
Missing Authorization Header401Unauthorized

Error Response Examples

Expired Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Token has expired."
}
]
}

Invalid token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Unable to parse JWT token"
}
]
}

Missing Authorization Header

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "User is not authorized to make this call."
}
]
}

Additional 400-Level Errors

ErrorError code
Duplicate tracker serial (RFID tag) in payload400
Invalid token400

Duplicate tracker_serial in Payload

{
"data": {
"createWorkOrderSet": null
},
"errors": [
{
"path": [
"createWorkOrderSet"
],
"data": null,
"errorType": null,
"errorInfo": null,
"locations": [
{
"line": 2,
"column": 9,
"sourceName": null
}
],
"message": "duplicate vid is not allowed, the vid provided in the payload is found in DB"
}
]
}

Update Work Order Properties API

The updateWorkOrderProperties API is a bulk operation that allows callers to update various properties of multiple work orders at once. This can be a useful feature when a caller needs to apply changes to multiple work orders efficiently. This API takes an array of objects, each representing a work order and the properties to be updated.

Endpoint Details

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Properties

PropertyTypeDescriptionRequired
workOrderNumberStringThe unique identifier for the work order to be updated.Yes
customerStringThe updated customer information for the work order.No
poNumberStringThe updated purchase order (PO) number associated with the work order.No
commentsStringAny additional comments or notes related to the work order.No
dueDateAWSTimestampThe updated expected due date for the work order in AWS timestamp format. The updated expected completion date of the work order in milliseconds.No
startDateAWSTimestampThe updated expected start date of the work order in AWS timestamp format (Epoch time in milliseconds).No
completionDateAWSTimestampThe updated expected completion date of the work order in AWS timestamp format (Epoch time in milliseconds).No
statusStatusThe updated status of the work order. Valid values are: PLANNED, IN_PROGRESS, COMPLETED, CANCELLED.No
stateStringThe updated state of the work order.No
priorityIntThe updated priority level of the work order.No
customPropertiesAWSJSONAny custom tenant-specific properties you want to update for the work order. This should be provided as a JSON string.No

Headers

Authorization – $idToken

Request Body

mutation {
updateWorkOrderProperties(
input: [
{
workOrderNumber: "W012345"
customer: "New Customer"
poNumber: "po-331-update"
priority: 1
dueDate: 1660732800000
startDate: 1660732800001
completionDate: 1650732800010
customProperties: "{\"quantity_ts\": 6}"
},
{
workOrderNumber: "W06789"
comments: "Additional Comments"
priority: 2
status: PLANNED
}
]
) {
id
number
epc
lastUpdatedTime
isActive
inputParts { id partNumber partName }
outputParts { id partNumber partName }
routeHistory { location { name }}
}
}

Status Code - 200

Response Body

{
"data": {
"updateWorkOrderProperties": [
{
"id": "6bc54005-ffc0-f604-1961-d19734fec7ca",
"number": "W06789",
"epc": null,
"lastUpdatedTime": null,
"isActive": null,
"inputParts": [],
"outputParts": [],
"routeHistory": null
},
{
"id": "4ac54005-ffaa-779d-4fc6-b781b678a1c4",
"number": "W012345",
"epc": null,
"lastUpdatedTime": null,
"isActive": null,
"inputParts": [],
"outputParts": [],
"routeHistory": null
}
]
}
}

Errors

ErrorError codeException
Expired token401Unauthorized
Invalid token401Unauthorized
Missing Authorization Header401Unauthorized

Error Response Examples

Expired Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Token has expired."
}
]
}

Invalid token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Unable to parse JWT token"
}
]
}

Missing Authorization Header

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "User is not authorized to make this call."
}
]
}

Payload Validation Errors

Before making requests to the updateWorkOrderProperties API, payload validation is performed to ensure that the provided input adheres to certain requirements.

Validation Rules

  • Work Order Number Uniqueness: Each work order within the payload must have a unique workOrderNumber. This uniqueness requirement ensures that there are no duplicate work order numbers in the payload, preventing conflicts and ambiguities during the update process.

  • Work Order Existence: Each workOrderNumber provided in the payload must correspond to an existing work order in the system. If any work order numbers cannot be found, an error will be thrown.

Additional 200-Level Errors

ErrorError codeError Category
Duplicates in workOrderNumber values: [WO001, WO002]. The values must be unique.200Resolver error
Cannot find work order number(s): [WO12345k, WO6789a, WO6789b]200Resolver error

Missing Work Orders Error Example

{
"data": {
"updateWorkOrderProperties": null
},
"errors": [
{
"path": [
"updateWorkOrderProperties"
],
"data": null,
"errorType": "ResourceNotFoundError",
"errorInfo": null,
"locations": [
{
"line": 2,
"column": 5,
"sourceName": null
}
],
"message": "Cannot find work order number(s): [WO12345k, WO6789a, WO6789b]"
}
]
}

Attach Work Order Tracker API

The attachWorkOrderTracker API is a bulk operation that allows you to associate tracker serial numbers (RFID) with work orders. This functionality is useful for tracking and managing work orders by linking them to physical orders. The API accepts an array of AttachWorkOrderTrackerInput objects, each specifying the work order and the tracker serial number to be associated.

Endpoint Details

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Properties

PropertyTypeDescriptionRequired
workOrderNumberStringThe unique identifier for the work order to which the tracker is to be attached.Yes
trackerSerialStringThe serial number of the tracker that is being associated with the work order.Yes
reuseTrackerBooleanIndicates whether the tracker can be reused. If set to true, the tracker will be reused from a previous work order if available. If set to false and the tracker already exists, an error will be generated for this node. Default value: false.No
detachTrackerBooleanSpecifies whether the tracker should be detached from any previous work order it may have been associated with. If true, the tracker will be detached; if false and the tracker already exists and is attached, an error will be generated for this node. Default value: false.No

Headers

Authorization – $idToken

Request Body

mutation {
attachWorkOrderTracker(
input: [
{
workOrderNumber: "W012345"
trackerSerial: "TS-12345"
},
{
workOrderNumber: "W06789"
trackerSerial: "TS-6789"
}
]
) {
id
number
epc
lastUpdatedTime
isActive
inputParts { id partNumber partName }
outputParts { id partNumber partName }
routeHistory { location { name } }
}
}

Status Code - 200

Response Body

Response consists of a list of all work orders that were updated:

{
"data": {
"attachWorkOrderTracker": [
{
"id": "6bc54d05-ffc0-f604-1961-d19734fec7ca",
"number": "W06789",
"epc": "TS-6789",
"lastUpdatedTime": null,
"isActive": null,
"inputParts": [],
"outputParts": [],
"routeHistory": null
},
{
"id": "4ac54d05-ffaa-779d-4fc6-b781b678a1c4",
"number": "W012345",
"epc": "TS-12345",
"lastUpdatedTime": null,
"isActive": null,
"inputParts": [],
"outputParts": [],
"routeHistory": null
}
]
}
}

In the case of a resolver error the attachWorkOrderTracker node of the response will be null and the errors array will have the error details

Missing Work Orders Error Example

Status Code: - 200

{
"data": {
"attachWorkOrderTracker": null
},
"errors": [
{
"path": [
"attachWorkOrderTracker"
],
"data": null,
"errorType": "ResourceNotFoundError",
"errorInfo": {
"workOrderNumber": "W067890",
"statusCode": 404
},
"locations": [
{
"line": 2,
"column": 5,
"sourceName": null
}
],
"message": "W067890: Cannot find work order with number: W067890"
}
]
}

Errors

ErrorError codeException
Expired token401Unauthorized
Invalid token401Unauthorized
Missing Authorization Header401Unauthorized

Error Response Examples

Expired Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Token has expired."
}
]
}

Invalid token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Unable to parse JWT token"
}
]
}

Missing Authorization Header

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "User is not authorized to make this call."
}
]
}

Resolver Errors

API Payload Validation

Before making requests to the updateWorkOrderProperties API, payload validation is performed to ensure that the provided input adheres to certain requirements.

Validation Rules

  • Maximum Payload Size: The payload size is limited to a maximum number of nodes (50), which is enforced to prevent excessively large requests. This limitation helps maintain the efficiency and reliability of the API.

  • Work Order Number Uniqueness: Each work order within the payload must have a unique workOrderNumber. This ensures no duplicate work order numbers are included, preventing conflicts and ambiguities during the update process.

  • Work Order Existence: Each workOrderNumber in the payload must correspond to an existing work order in the system. If any are not found, an error will be thrown.

  • Tracker Serial Uniqueness: Each trackerSerial within the payload must be unique.

  • Tracker Serial Validation: If trackerSerial exists, the API will:

    • Only use it if reuseTracker is true.
    • If the tracker is already in use (attached to another work order), it can only be reused if detachTracker is true.
    • Otherwise, a validation error will occur.

List of Resolver Errors

ErrorError codeError Category
Too many elements (51), maximum number allowed is 50200Resolver error
Duplicates in workOrderNumber values: [WO001, WO002]. The values must be unique.200Resolver error
Cannot find work order number(s): [WO12345k, WO6789a, WO6789b]200Resolver error

List Work Orders API

List Work Orders API allows to retrieve all the work orders and view their statuses. It also allows to filter the list of work orders based on different properties.

Endpoint Details

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Input Properties

PropertyTypeDescriptionRequired
filterStringFilter for work order propertiesNo
nextTokenStringPagination supportNo

Response Properties

PropertyTypeDescriptionRequired
numberStringWork order numberYes
descriptionStringWork order descriptionNo
trackerSerialStringEPC for the work orderNo
startDateAWSTimestampStart date of the work orderNo
CompletionDateAWSTimestampCompletion date of the work orderNo
dueDateAWSTimestampAny other applicable due date for the work orderNo
commentsStringAny remarks for the work ordersNo
customPropertiesAWSJSONAdditional properties applicable to work ordersNo
inputsArray [Object]Input part as an input to work orderNo
outputsArray [Object]Output part producedNo
lastDetectedAtLocationObjectLocation at which the work order was last seen at (view table below)No
lastDetectedAtLocationEntryDateAWSTimestampTimestamp at which work order entered the locationNo
trackerSerialAttachDateAWSTimestampTimestamp at which tag was attached to the work orderNo

lastDetectedAtLocation

PropertyTypeDescriptionRequired
idStringLocation identifierYes
nameStringLocation NameNo

inputs/outputs

PropertyTypeDescriptionRequired
idStringPart IdentifierYes
nameStringPart NameNo
trackerSerialStringEPC for the partNo
partObjectPart Type (view details below)No
shipmentStateStringShipment status of the partNo

part

PropertyTypeDescriptionRequired
idStringPart type identifierYes
numberStringPart type numberNo
nameStringPart type nameNo
descriptionStringPart type descriptionNo
customPropertiesAWSJSONAdditional properties applicable to the work orderNo

Headers

Authorization – $idToken

Request Body

query workOrders($filter: String, $nextToken: String) {
workOrders(input: {filter: $filter, nextToken: $nextToken}) {
nextToken
workOrders{
number
trackerSerial
startDate
completionDate
dueDate
comments
description
lastUpdatedDate
lastDetectedAtLocation {
id
name
}
lastDetectedAtLocationEntryDate
trackerSerialAttachDate
State
customProperties
inputs{
id
number
name
description
customProperties
}
}
}
}
----------------------------------------------------------------------
Filter input
{
"filter": "lastUpdatedDate > 1716621117144"
}

StatusCode - 200

Response Body

{
"data": {
"workOrders": {
"nextToken": null,
"workOrders": [
{
"number": "Work Order 01",
"lastUpdatedDate": 1712126425177,
"lastDetectedAtLocation": {
"id": "Shop Floor",
"name": "Shop Floor"
},
"trackerSerial": "E280689400005013D8128491",
"inputs": {
"name": "JN01-Part1",
"id": "JN01-Part1"
}
},
{
"id": "Work Order 02",
"lastUpdatedDate": 1712215816754,
"lastDetectedAtLocation": {
"id": "MULTIS",
"name": "MULTIS"
},
"trackerSerial": "E280689400005013D8127891",
"inputs": {
"name": "JN02-Part1",
"id": "JN02-Part1"
}
}
]
}
}
}

Errors

ErrorError codeException
Expired token401Unauthorized
Invalid token401Unauthorized
Missing Authorization Header401Unauthorized

Error Response Examples

Expired Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Token has expired."
}
]
}

Invalid token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Unable to parse JWT token"
}
]
}

Missing Authorization Header

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "User is not authorized to make this call."
}
]
}

List Work Order Counts At Locations API

List counts of Work Orders at a location API allows to retrieve the counts of work order by different status at the locations. List can be retrieved for any or all locations.

Endpoint Details

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Input Properties

PropertyTypeDescriptionRequired
filterStringFilter for any propertiesNo
nextTokenStringPagination supportNo

Response Properties

PropertyTypeDescriptionRequired
workOrdersArray [Object]List of count of work orders by location (view table below)Yes
nextTokenStringNext token to retrieve the next pageNo

workOrders

PropertyTypeDescriptionRequired
totalCountNumberTotal number of work orders at the locationNo
expeditedCountNumberCount of expedited work orders at the locationNo
startCountNumberCount of work orders that are in started state at the locationNo
operationStartedCountNumberCount of work orders for which operation has started at the locationNo
timeExceededObjectCount of work orders that have exceeded the time threshold at the location (view table below)No
locationObjectLocation details (view table below)No

timeExceeded

PropertyTypeDescriptionRequired
warningCountNumberCount of work orders that exceeded warning thresholdYes
criticalCountNumberCount of work orders that exceeded critical thresholdNo
expeditedWarningCountNumberCount of expedited work orders that exceeded warning thresholdNo
expeditedCriticalCountNumberCount of expedited work orders that exceeded critical thresholdNo

location

PropertyTypeDescriptionRequired
idStringLocation identifierYes
nameStringLocation NameNo

Headers

Authorization – $idToken

Request Body

query workOrderLocationMetrics($filter: String, $nextToken: String) {
workOrderLocationMetrics (input: {filter: $filter, nextToken: $nextToken})
{
nextToken
workOrders {
totalCount
expeditedCount
startedCount
operationStartedCount
timeExceeded {
warningCount
criticalCount
expeditedWarningCount
expeditedCriticalCount
}
location {
id
name
}
}
}
}
----------------------------------------------------------------------
Filter input
{
"filter": "location.name == \"Location A\""
}

StatusCode - 200

Errors

ErrorError codeException
Expired token401Unauthorized
Invalid token401Unauthorized
Missing Authorization Header401Unauthorized

Error Response Examples

Expired Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Token has expired."
}
]
}

Invalid token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Unable to parse JWT token"
}
]
}

Missing Authorization Header

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "User is not authorized to make this call."
}
]
}

Get Work Order Route API

Query Work Orders API allows to retrieve all the work orders and view their statuses. It also allows to filter the list of APIs based on different properties.

Endpoint Details

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Input Properties

PropertyTypeDescriptionRequired
numberStringWork order numberYes
startDateAWSTimestampStart date for routeNo
endDateAWSTimestampEnd date for routeNo

Response Properties

PropertyTypeDescriptionRequired
stateStringCurrent state of Work Order at locationNo
startDateAWSTimestampFirst detection timestamp at locationNo
endDateAWSTimestampLast detection timestamp at locationNo
locationObjectLocation where work order was last seenNo
durationNumberTime spent at that locationNo

Location Properties

PropertyTypeDescriptionRequired
idStringLocation identifierYes
nameStringLocation nameNo

Request Body Example

query workOrderRoute ($number: String!, $startDate: AWSTimestamp, $endDate: AWSTimestamp, $nextToken: String) {
workOrderRoute(input: { number: $number, startDate: $startDate, endDate: $endDate, nextToken: $nextToken }) {
nextToken
route {
location {
id
name
},
state,
startDate,
endDate,
duration
}
}
}
----------------------------------------------------------------------
Input
{
"number": "WO12345",
"startDate": 1719730800000,
"endDate": 1719903600000
}

Response Body

{
"data": {
"workOrderRoute": {
"route": [
{
"location": {
"id": "Paint",
"name": "Paint"
},
"startDate": 1719864278922,
"endDate": 1719864496290,
"duration": 217368
},
{
"location": {
"id": "Fabrication",
"name": "Fabrication"
},
"startDate": 1719864496290,
"endDate": 1719864827571,
"duration": 331281
},
{
"location": {
"id": "Quality",
"name": "Quality"
},
"startDate": 1719864827571,
"endDate": 1719866988210,
"duration": 2160639
},
{
"location": {
"id": "Paint",
"name": "Paint"
},
"startDate": 1719866988210,
"endDate": 1719867246015,
"duration": 257805
},
{
"location": {
"id": "Welding",
"name": "Welding"
},
"startDate": 1719867246015,
"endDate": 1719867531089,
"duration": 285074
},
{
"location": {
"id": " Quality ",
"name": " Quality "
},
"startDate": 1719867531089,
"endDate": 1719867581293,
"duration": 50204
},
{
"location": {
"id": " Final Prep",
"name": " Final Prep"
},
"startDate": 1719867581293,
"endDate": 1719867614996,
"duration": 33703
},
{
"location": {
"id": "Staging",
"name": "Staging"
},
"startDate": 1719867614996,
"endDate": null,
"duration": 3122990
}
]
}
}
}

Errors

ErrorError codeException
Expired token401Unauthorized
Invalid token401Unauthorized
Missing Authorization Header401Unauthorized

Error Response Examples

Expired Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Token has expired."
}
]
}

Invalid token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Unable to parse JWT token"
}
]
}

Missing Authorization Header

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "User is not authorized to make this call."
}
]
}