API - service orders

To create service order through the API, you need to retrieve an access token. API documentation is here.

A service order is a specification of one or more jobs to be done on a set of objects. The objects must exist in SIRK:tag before the service order is created.

See API - create new asset for how to create new objects.

Lifecycle of a service order

A service order goes through the following steps:

1. Creation: A user creates a service order on behalf of an organization (the owner of the assets/objects). This organization will have a set of approved service providers that can execute the service order (an organization may also execute their own service orders).
2. Approval: A user from the owner organization approves the service order. The third-party service providers cannot start (or view) a service order before it is approved
3. Execution: The third-party service providers performs the actual service. This will necessitate logistical steps such as transport that must be co-ordinated between the owner and the service provider.
   
4. Completion: When the service provider completes the work and close the service order, an event message containing the updated object will be published on a message queue (at host mq.sirktek.com). The JSON messages will follow the AssetDto schema from https://test-api.sirktek.com/assets/v1/q/swagger-ui/

Get list of possible services for given asset

When creating an asset you  can assign it to one or more categories. The categories are taken from SIRK:catalog, a taxonomy consisting of a hierarchy of inventory types (such as "sitting furniture" -> "chair" -> "office chair"), manufacturers, and models. A model will typically be linked to a manufacturer and an inventory type.

The catalog can be retrieved in JSON format from the /assets/v1/category API endpoint.

The third-party service providers will offer services based on these categories. Ie one particluar service provider may offer the service REUPHOLSTER for the "Chair" category, which will then include sub-categories such as "Office Chair".

It is possible to get a list of available services (from the approved service providers) for a given object:

curl -s  -X 'GET' \
  "https://test-api.sirktek.com/assets/v1/order/type?assetId=<assetId>" \
  -H 'accept: application/json' \
  -H "Authorization: Bearer eyJhbG..." | jq --color-output .

{
  "sirktek": [
    {
      "inventoryType": "Furniture",
      "type": "REDESIGN",
      "description": null
    },
    {
      "inventoryType": "Chair",
      "type": "REUPHOLSTER",
      "description": null
    }
  ]
}

Create a new service order

A new service order is created like this:

curl -iv -X 'POST' 'https://test-api.sirktek.com/assets/v1/order' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer eyJHbG..." \
-d '{
      "name": "test service order",
      "description": "this is my test service order",
      "type": "SERVICE",
      "plannedStart": "2024-10-10T12:15:50",
      "properties": {
        "color": "red"
      },
      "orderLines": [
        {
          "assetId": 43102,
          "description": "first asset",
          "type": "REUPHOLSTER",
          "properties": {
            "textile": "wool"
          }
        },
        {
            "assetId": 43103,
            "description": "second asset",
            "type": "REUPHOLSTER",
            "properties": {
                "textile": "wool"
            }
        },
        {
            "assetId": 43104,
            "description": "third asset",
            "type": "REUPHOLSTER",
            "properties": {
                "textile": "leather"
            }
        } 
     ]
    }'

curl -iv -X 'GET' 'https://test-api.sirktek.com/assets/v1/order/<orderId>' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer eyJhbG..."

A new batch will be created for the service order if there is no <batchId> included in the service order create JSON.

Note that the assets in the service order must already exist in SIRK:tag.

Get list of service orders

Use this GET request to get a list of all available orders:

curl  -X 'GET' 'https://test-api.sirktek.com/assets/v1/order' \ 
-H 'accept: application/json' \
-H "Authorization: Bearer eyJhbG..." | jq .

This endpoint use paging to limit the number of entries in the response. Use the query parameters <pageSize> and <pageOffset> to retrieve the correct part. The total number of pages available is returned in the <X-page-total> response header.

Approve order

To approve the order, update the state of that particular order:

curl -iv -X 'POST' 'https://test-api.sirktek.com/assets/v1/order/<orderId>' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer eyJhbG...." \
-d '{
  "state": "APPROVED"
}'