Case Management Service – Samples¶

Create Case¶

Note

Cases are referred as work orders for Private Cloud subscribers.

The case is created using the following request:

POST /cases

The following JSON structure is given to define the case:

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

{
    "message": "Case created with case-handle AA-002",
    "handle": "AA-002"
}

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

Assignment and Notification¶

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

POST /cases

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

assignedTo is used to assign case 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 case 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 cases. Here, case 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 case.

Association for existing case¶

To add associations to an existing case, use the following API with handle.

PATCH /cases/AA-000/associations

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

Here id cb72dfd7400e4fc6a275f22e6751cce6is the asset to be linked to case.

Association for new case¶

To define association while creation of cases, add associations field to case request.

Use the same API as create a case

POST /cases

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 case.

Attachments¶

Attachments field can be used to attach files to cases. Files stored in IoT File storage can be attached to a case.

Let's assume the file we want to attach to case 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 case¶

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

PATCH /cases/AA-000/attachments

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

Attachment for new case¶

To define attachment while creation of cases, add attachments field to case request.

Use same API as create case.

POST /cases

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 cases in a tenant.

GET /cases/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"
        }
      },
    }
  },
  "totalCases": 1
}

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

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

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

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

Last update: April 24, 2024

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