Work Order Management Service – Samples¶

Create Work Order¶

The work order is created using the following request:

POST /workorders

The following JSON structure is given to define the work order:

{
  "notifyAssignee": false,
  "dueDate": "2022-11-25",
  "title": "Floor Machine Maintenance",
  "priority": "LOW",
  "status": "OPEN",
  "type": "PLANNED",
  "description": "Dismantle and clean parts"
}

{
    "message": "Work order created with wo-handle AA-002",
    "woHandle": "AA-002"
}

In the response, woHandle is a unique identifier for a given tenant and work order which will be used for further operations such update/delete.

Assignment and Notification¶

While creating work order, it can be assigned to an email address and optionally notify the assignee with email.

POST /workorders

In the following request, the field descriptions are as below:

assignedTo is used to assign work order to a user. The value of this field is the email address of the user.
notifyAssignee, if this field is set to true, then email notification is sent to the assigned email address. The Default value for this field is false. So, if work order is assigned to a user, by default notification is not sent.

{
  "notifyAssignee": true,
  "assignedTo": "test@siemens.com",
  "dueDate": "2022-11-25",
  "title": "Floor Machine Maintenance",
  "priority": "LOW",
  "status": "OPEN",
  "type": "PLANNED",
  "description": "Dismantle and clean parts"
}

Associations¶

Associations are used to link entities to work orders. Here, work order service allows linking assets using assetId.

In the following request, the field descriptions are as below:

id field which is id of entity to be associated.
type field is the type of entity to be associated.
Currently, only ASSET or EVENT type is supported, so the id is asset or event id.
Maximum 1 asset and 10 events can be associated with a work order.

Association for existing work order¶

To add associations to an existing work order, use the following API with woHandle.

PATCH /workorders/AA-000/associations

{
  "associations": [
    {
      "id": "cb72dfd7400e4fc6a275f22e6751cce6",
      "type": "ASSET"
    }
  ]
}

Here id cb72dfd7400e4fc6a275f22e6751cce6is the asset to be linked to work order.

Association for new work order¶

To define association while creation of work orders, add associations field to work order request.

Use the same API as create a work order

POST /workorder

In the following request, notice the association field

{
  "notifyAssignee": false,
  "dueDate": "2022-11-25",
  "title": "Floor Machine Maintenance",
  "priority": "LOW",
  "status": "OPEN",
  "type": "PLANNED",
  "description": "Dismantle and clean parts",
  "associations": [
    {
      "id": "cb72dfd7400e4fc6a275f22e6751cce6",
      "type": "ASSET"
    }, 
    {
      "id": "ad0e4fc6a275f22e6751",
      "type": "EVENT"
    }
  ]
}

Here, id cb72dfd7400e4fc6a275f22e6751cce6 is the asset and ad0e4fc6a275f22e6751 is the event to be linked to work order.

Attachments¶

Attachments field can be used to attach files to work orders. Files stored in IoT File storage can be attached to a work order.

Let's assume the file we want to attach to work order exists at /api/iotfile/v3/files/cb72dfd7400e4fc6a275f22e6751cce6/AA-000/file.pdf.

In request below, observe the following fields according example above

name is the name of file, file.pdf. *- assetId is the asset id where file is uploaded, cb72dfd7400e4fc6a275f22e6751cce6.
path is the relative path to the file from asset, AA-000.

Refer IoT File Service for more information about uploading files.

Attachments for existing work order¶

To attach the above file on work order AA-000, use the following API:

PATCH /workorders/AA-000/attachments

{
  "attachments": [
    {
      "name": "file.pdf",
      "assetId": "cb72dfd7400e4fc6a275f22e6751cce6",
      "path": "AA-000"
    }
  ]
}

Attachment for new work order¶

To define attachment while creation of work orders, add attachments field to work order request.

Use same API as create work order.

POST /workorder

In the following request, notice the attachments field

{
  "notifyAssignee": false,
  "dueDate": "2022-11-25",
  "title": "Floor Machine Maintenance",
  "priority": "LOW",
  "status": "OPEN",
  "type": "PLANNED",
  "description": "Dismantle and clean parts",
  "attachments": [
    {
      "name": "file.pdf",
      "assetId": "cb72dfd7400e4fc6a275f22e6751cce6",
      "path": "AA-000"
    }
  ]
}

IoT File Service

Get Aggregate Summary¶

This API is useful for getting overview of work orders in a tenant.

GET /workorders/aggregate

The following is the sample response from above API:

{
  "statusInfo": {
    "OPEN": {
      "count": 1,
      "fieldName": "OPEN"
    },
    "INPROGRESS": {
      "count": 0,
      "fieldName": "INPROGRESS"
    },
    "ONHOLD": {
      "count": 0,
      "fieldName": "ONHOLD"
    },
    "DONE": {
      "count": 0,
      "fieldName": "DONE"
    },
    "OVERDUE": {
      "count": 1,
      "fieldName": "OVERDUE"
    },
    "CANCELLED": {
      "count": 0,
      "fieldName": "CANCELLED"
    },
    "ARCHIVED": {
      "count": 0,
      "fieldName": "ARCHIVED"
    }
  },
  "priorityInfo": {
    "EMERGENCY": {
      "count": 0,
      "fieldName": "EMERGENCY"
    },
    "MEDIUM": {
      "count": 0,
      "fieldName": "MEDIUM"
    },
    "HIGH": {
      "count": 0,
      "fieldName": "HIGH"
    },
    "LOW": {
      "count": 1,
      "fieldName": "LOW"
    }
  },
  "severityByStatus": {
    "overview": {
      "OPEN": {
        "EMERGENCY": {
          "count": 0,
          "fieldName": "EMERGENCY"
        },
        "MEDIUM": {
          "count": 0,
          "fieldName": "MEDIUM"
        },
        "HIGH": {
          "count": 0,
          "fieldName": "HIGH"
        },
        "LOW": {
          "count": 1,
          "fieldName": "LOW"
        }
      },
      "INPROGRESS": {
        "EMERGENCY": {
          "count": 0,
          "fieldName": "EMERGENCY"
        },
        "MEDIUM": {
          "count": 0,
          "fieldName": "MEDIUM"
        },
        "HIGH": {
          "count": 0,
          "fieldName": "HIGH"
        },
        "LOW": {
          "count": 0,
          "fieldName": "LOW"
        }
      },
      "ONHOLD": {
        "EMERGENCY": {
          "count": 0,
          "fieldName": "EMERGENCY"
        },
        "MEDIUM": {
          "count": 0,
          "fieldName": "MEDIUM"
        },
        "HIGH": {
          "count": 0,
          "fieldName": "HIGH"
        },
        "LOW": {
          "count": 0,
          "fieldName": "LOW"
        }
      },
      "DONE": {
        "EMERGENCY": {
          "count": 0,
          "fieldName": "EMERGENCY"
        },
        "MEDIUM": {
          "count": 0,
          "fieldName": "MEDIUM"
        },
        "HIGH": {
          "count": 0,
          "fieldName": "HIGH"
        },
        "LOW": {
          "count": 0,
          "fieldName": "LOW"
        }
      },
      "OVERDUE": {
        "EMERGENCY": {
          "count": 0,
          "fieldName": "EMERGENCY"
        },
        "MEDIUM": {
          "count": 0,
          "fieldName": "MEDIUM"
        },
        "HIGH": {
          "count": 0,
          "fieldName": "HIGH"
        },
        "LOW": {
          "count": 1,
          "fieldName": "LOW"
        }
      },
      "CANCELLED": {
        "EMERGENCY": {
          "count": 0,
          "fieldName": "EMERGENCY"
        },
        "MEDIUM": {
          "count": 0,
          "fieldName": "MEDIUM"
        },
        "HIGH": {
          "count": 0,
          "fieldName": "HIGH"
        },
        "LOW": {
          "count": 0,
          "fieldName": "LOW"
        }
      },
      ,
      "ARCHIVED": {
        "EMERGENCY": {
          "count": 0,
          "fieldName": "EMERGENCY"
        },
        "MEDIUM": {
          "count": 0,
          "fieldName": "MEDIUM"
        },
        "HIGH": {
          "count": 0,
          "fieldName": "HIGH"
        },
        "LOW": {
          "count": 0,
          "fieldName": "LOW"
        }
      },
    }
  },
  "totalWorkOrders": 1
}

The statusInfo field retrieves the count of work orders for a tenant by status.

The priorityInfo field retrieves the count of work orders for a tenant by priority.

The severityByStatus field retrieves the count of work orders for a tenant by status and then further segregated by severity.

In the above example, there is only one work order with LOW priority and OPEN status, so we can verify aggregate status.

Last update: October 3, 2023

Except where otherwise noted, content on this site is licensed under the Development License Agreement.