Work-In-Process Tracking

Modified on Fri, 21 Feb at 2:03 PM

TABLE OF CONTENTS (Click to Expand/Collapse)

Release Versions:
API:
Login API:
Create Work Order Set API:
Update Work Order Properties API:
Attach Work Order Tracker API:

Release Versions:

Version	Description	Author	Release Date
1.0	Login and Create APIs for Work Orders	Francis Wu	2/17/2022
1.1	Update Branding	Connie Wong	5/31/2023
1.2	Update Properties for Work Orders	Renuka Agrawal	9/28/2023
1.3	Update Work Order and Attach Work Order Tracker APIs	Renuka Agrawal	2/4/2024

API:

Xemelgo APIs are primarily GRAPH QL APIs.

API Error Categories:

Various types of errors may occur during the execution of requests. These errors fall into several categories, each with its own distinct characteristics and implications. Understanding these error categories is crucial for efficient troubleshooting and issue resolution.

Authorization Errors (HTTP 401):

Authorization errors relate to issues surrounding access control and authentication. These errors typically involve problems with verifying user credentials and permissions and token management. When these errors occur, they result in an HTTP status code of 401 (Unauthorized). Common authorization errors include:

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": "You are not authorized to make this call."
    }]
}

Resolver Errors (HTTP 200):

Resolver errors are conveyed through the errors array within the response and HTTP status code 200 (OK). If a resolver encounters an issue, the errors array will contain one or more error objects with relevant details.

Error Response Example, StatusCode - HTTP 200 (OK):

{
  "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): [WO12345]."
    }
  ]
}

Server Errors (HTTP 500):

Server errors encompass a wide range of issues that are not directly related to authentication, authorization, or GraphQL resolvers. They are typically related to the infrastructure and resources supporting the API. Common server errors includes timeout.

To access the Graph QL APIs users need to first access the Xemelgo login REST API to authenticate their credentials and then use the token to access the Graph QL APIs.

Rest API:

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

Property	Type	Description	Required
email	String	base64 Encoded email id for user	Yes
password	String	base64 encoded password for user password needs to be a minimum of 8 characters and should have a number in it	Yes

Request Body:

{
  "email": String,
  "password": String
}

StatusCode - 200 on success

Response Body:

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

Use the $idToken as the authorization header to make any subsequent API request.

Errors:

Error	Error Code	Exception
Incorrect username and or password	400	NotAuthorizedException

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.

Graph API:

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

Property	Type	Description	Required
order_number	String	Work order / Job number	Yes
tracker_serial	String	Serial number of the RFID tag associated to the specific work order	No
start_date	AWSTimestamp	Expected start date for the work order (Epoch time in milliseconds)	No
completion_date	AWSTimestamp	Expected completion date for the work order (Epoch time in milliseconds)	No
onboarding_location	String	A Xemelgo verified location identifier to which the work order should be onboarded	No
tenant_properties	AWSJSON	Additional properties that a customer may want to specify for the work order Example: const data = { Scheduling_code: "VHIGH" }; const tenant_properties = JSON.stringify(data, null, 2);	No

Request Headers:

Header	Value	Notes
Authorization	$idToken	Use the idToken from the response of the Login API

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 on success

Response Body:

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

Response consists of a list of all order numbers that were created

Errors:

401 Errors:

Error	Error Code	Exception
Expired Token	401	Unauthorized
Invalid Token	401	Unauthorized
Missing Authorization Header	401	Unauthorized

400 Errors:

Error	Error Code
Duplicate tracker_serial (RFID Tag) in payload	400
Invalid Token	400

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.

Graph API:

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

Property	Type	Description	Required
workOrderNumber	String	The unique identifier for the work order to be updated	Yes
customer	String	The updated customer information for the work order	No
poNumber	String	The updated purchase order (PO) number associated with the work order	No
comments	String	Any additional comments or notes related to the work order.	No
dueDate	AWSTimestamp	The updated expected due date for the work order in AWS timestamp format (Epoch time in milliseconds)	No
startDate	AWSTimestamp	The updated expected start date for the work order in AWS timestamp format (Epoch time in milliseconds)	No
completionDate	AWSTimestamp	The updated expected completion date of the work order in AWS timestamp format (Epoch time in milliseconds)	No
status	Status	The updated status of the work order, valid values are: PLANNED IN_PROGRESS COMPLETED CANCELLED	No
state	String	The updated state of the work order	No
priority	Int	The updated priority of the work order	No
customProperties	AWSJSON	Any custom tenant-specific properties you want to update for the work order. This should be provided as a JSON string.	No

Request Headers:

Header	Value	Notes
Authorization	$accessToken	Use the acessToken from the response of the Login API

Request Body:

mutation {
  updateWorkOrderProperties(
    input: [
      {
        workOrderNumber: "WO12345",
        customer: "New Customer",
        poNumber: "po-331-update",
        priority: 1,
        dueDate: 1660732800000,
        startDate: 1660732800001,
        completionDate: 1650732800010,
        customProperties: "{\"quantity_ts\": 6}"
      },
      {
        workOrderNumber: "WO6789",
        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 on success

Response Body:

Response consists of all work orders that were updated.

{
  "data": {
    "updateWorkOrderProperties": [
      {
        "id": "f6c5d405-ffc0-f064-1961-d19734fec7ca",
        "number": "WO6789",
        "epc": null,
        "lastUpdatedTime": null,
        "isActive": null,
        "inputParts": [],
        "outputParts": [],
        "routeHistory": null
      },
      {
        "id": "4ac5d405-ffae-779d-4fc6-b781b678a1c4",
        "number": "WO12345",
        "epc": null,
        "lastUpdatedTime": null,
        "isActive": null,
        "inputParts": [],
        "outputParts": [],
        "routeHistory": null
      }
    ]
  }
}

Errors:

Authorizations Errors:

Error	Error Code	Error Type	Error Category
Expired Token	401	UnauthorizedException	Authorization Error
Invalid Token	401	UnauthorizedException	Authorization Error
Missing Authorization Header	401	UnauthorizedException	Authorization Error

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:

Maximum Payload Size: The payload size is limited to a maximum number of nodes (100), 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 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.

Error	Error Code	Error Category
Too many elements (103), maximum number allowed is 100	200	Resolver Error
Duplicates in workOrderNumber values: [WO001, WO002]. The values must be unique.	200	Resolver Error
Cannot find work order number(s): [WO12345k, WO6789a, WO6789b]	200	Resolver 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 assets or devices. The API accepts an array of AttachWorkOrderTrackerInput objects, each specifying the work order and the tracker serial number to be associated.

Graph API:

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

Property	Type	Description	Required
workOrderNumber	String	The unique identifier for the work order to be updated	Yes
trackerSerial	String	The serial number of the tracker that is being associated with the work order	No
reuseTracker	Boolean	Indicates 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
detachTracker	Boolean	Specifies whether the tracker should be detached from any previous work order it may have been associated with. If set to true, the tracker will be detached from a previous work order if attached, if set to false, and the tracker already exists and attached, an error will be generated for this node. Default value: false	No

Request Headers:

Header	Value	Notes
Authorization	$idToken	Use the idToken from the response of the Login API

Request Body:

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

Response Body:

Status Code - 200

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

{
  "data": {
    "attachWorkOrderTracker": [
      {
        "id": "f6c5d405-ffc0-f064-1961-d19734fec7ca",
        "number": "WO6789",
        "epc": "TS-6789",
        "lastUpdatedTime": null,
        "isActive": null,
        "inputParts": [],
        "outputParts": [],
        "routeHistory": null
      },
      {
        "id": "4ac5d405-ffae-779d-4fc6-b781b678a1c4",
        "number": "WO12345",
        "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

Status Code - 200

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

Errors:

Authorizations Errors:

Error	Error Code	Error Type	Error Category
Expired Token	401	UnauthorizedException	Authorization Error
Invalid Token	401	UnauthorizedException	Authorization Error
Missing Authorization Header	401	UnauthorizedException	Authorization Error

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 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
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, and if the tracker is in use (attached to another work order) it only can be re-used if detachTracker is true, otherwise a validation error will occur

List of Resolver Errors:

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

{
  "data": {
    "createWorkOrderSet": null
  },
  "errors": [
    {
      "path": [
        "createWorkOrderSet"
      ],
      "data": null,
      "errorType": "ExecutionTimeout",
      "errorInfo": null,
      "locations": [
        {
          "line": 2,
          "column": 5,
          "sourceName": null
        }
      ],
      "message": "Execution timed out."
    }
  ]
}

Work-In-Process Tracking

Release Versions:

API:

API Error Categories:

Authorization Errors (HTTP 401):

Expired Token:

Invalid Token:

Missing Authorization Header:

Resolver Errors (HTTP 200):

Server Errors (HTTP 500):

Login API:

Request Body:

Response Body:

Errors:

Create Work Order Set API:

Request Headers:

Request Body:

Response Body:

Errors:

401 Errors:

400 Errors:

Duplicate tracker_serial in Payload:

Update Work Order Properties API:

Request Body:

Response Body:

Errors:

Authorizations Errors:

Payload Validation Errors:

Missing Work Orders Error Example:

Attach Work Order Tracker API:

Request Headers:

Request Body:

Response Body:

Errors:

Authorizations Errors:

Resolver Errors:

API Payload Validation:

List of Resolver Errors: