Case management
This document describes a basic implementation for a customer-facing front end for case management.
Creating cases
A customer can create a case using CustomerCreateCase
, a service expecting four properties;
{
"TopicID": int,
"Title": "string",
"Description": "string",
"OrderID": int
}
Note how this service is missing something resembling a CustomerID
. This is because the service is only available to customers and therefore expect a proper authorization header, allowing it to determine the correct customer ID.
TopicID
can be determined by calling ListCaseTopics
with an empty request body and having the customer choose from the returned options. Example response;
{
"Results": [
{
"ID": 7,
"Name": "Other",
"Description": "Anything not covered by the other topics."
},
{
"ID": 6,
"Name": "Promotions",
"Description": "Anything related to promotions or discounts."
},
{
"ID": 5,
"Name": "Account",
"Description": "Anything related to your account."
},
{
"ID": 4,
"Name": "Returns",
"Description": "Anything related to returns."
},
{
"ID": 3,
"Name": "Payment",
"Description": "Anything related to pending or past payments."
},
{
"ID": 2,
"Name": "Shipping",
"Description": "Anything related to shipments for your order(s)."
},
{
"ID": 1,
"Name": "Products",
"Description": "Anything related to products."
}
]
}
OrderID
is optional and can be determined by calling SearchOrders
with your desired filtering and presenting the customer with some sort of dropdown. Alternatively, you could decide to only allow creating cases from an order detail view and having this property prefilled.
CustomerCreateCase
will return an ID for the newly created case.
Editing cases
Editing cases is possible through CustomerUpdateCase
. This works exactly the same as creating a case, with the only differences being that the case ID
is required in the request and the OrderID
can't be altered.
Listing cases
In order to display an overview of cases for a customer, call CustomerListCases
. This can be an empty request, but it also supports pagination. The service returns an array of cases with some properties that can be rendered. The case ID
can be used for concurrent requests. Example response;
{
"Results": [
{
"ID": 10,
"TopicID": 1,
"TopicName": "Products",
"StatusID": 1,
"StatusName": "New",
"Priority": 0,
"Title": "The stitching on my T-shirt isn't right!!",
"OrderID": 325,
"ReportingTime": "2023-03-30T16:30:57.947Z"
}
]
}
Fetching case information
In order to fetch all information for a case, use CustomerGetCaseByID
;
{
"ID": 10
}
Example response:
{
"ID": 10,
"TopicID": 1,
"TopicName": "Products",
"StatusID": 1,
"StatusName": "New",
"Priority": 0,
"Title": "The stitching on my T-shirt isn't right!!",
"Description": "I ordered your Unisex T-shirt a while ago. When I received it yesterday I immediately noticed there was something off. The logo stitching seems to be majorly messed up; every letter is crooked and some are even backwards lol.",
"OrderID": 325,
"IsWarranty": false,
"ReportingTime": "2023-03-30T16:30:57.947Z",
"DescriptionCanBeModified": true,
"BlobIDs": [
"b832ece7-93ea-4c5e-ad64-11402201315d"
]
}
Interactions
Render interactions for a case using CustomerListCaseInteractions
with your CaseID
:
{
"CaseID": 10
}
Example response:
{
"Results": [
{
"ID": 39,
"CaseID": 10,
"Type": 0,
"CanBeModified": true,
"Text": "We are so sorry to hear about this. We've sent you an e-mail with a gift card for your order amount, hope this helps you out, cheers!",
"CreationTime": "2023-03-30T16:39:42.963Z",
"CreatedByID": 118744,
"CreatedBy": {
"FirstName": "Pedro",
"LastName": "Pascal",
"FullName": "Pedro Pascal"
}
},
{
"ID": 38,
"CaseID": 10,
"Type": 2,
"CanBeModified": true,
"Text": "Case status set to `New`",
"CreationTime": "2023-03-30T16:30:57.947Z",
"CreatedBy": {
"FirstName": "Pedro",
"LastName": "Pascal",
"FullName": "Pedro Pascal"
}
},
{
"ID": 37,
"CaseID": 10,
"Type": 2,
"CanBeModified": true,
"Text": "Case created with priority `Low`",
"CreationTime": "2023-03-30T16:30:57.947Z",
"CreatedBy": {
"FirstName": "Pedro",
"LastName": "Pascal",
"FullName": "Pedro Pascal"
}
}
]
}
New interactions can be created using CustomerCreateCaseInteraction
:
{
"CaseID": 10,
"Text": "YourMessageHere"
}
Pushing cases
PushCases permission is required in order to be able to perform pushing cases. Permissions are managed from the Roles and rights chapter namely, from the functionalities card of a user's role.
The CustomerCreateCase service allows cases to be pushed to EVA.
Some things to keep in mind:
- If a case with the same
BackendSystemID
andBackendID
already exists, the request will fail (note: updates are not supported). - The pushed customer details will either create a new customer or update an existing one, whichever is appliacable.
- The pushed addresses (shipping/billing) will either create a new address for that customer or update an existing one, whichever is appliacable.
- The
Assignee
can be provided by using the EVAID
,CustomID
, orEmailAddress
. If no match, an assignee will not be resolved and theAssignedOn
will be left empty. Further, in scenarios where the assignee is not allowed to be assigned cases (not of type employee or system), an assignee will also not be resolved. - There are 2 impactful settings when it comes to Case topic and Case status, as follows:
Setting | Value | Description |
---|---|---|
PushCases:AutoCreateTopic | true | If a case topic with the pushed name does not exist, one will be created. |
PushCases:AutoCreateTopic | false | If a case topic with the pushed name does not exist, the request will fail. |
PushCases:AutoCreateStatus | true | If a case status with the pushed name does not exist, one will be created. |
PushCases:AutoCreateStatus | false | If a case status with the pushed name does not exist, the request will fail. |
Here is a sample pushed request and response:
{
"BackendSystemID": "Sys123",
"BackendID": "ID-A-123",
"Topic": "TopicName",
"Title": "Something wrong",
"Description": "It rings, but it's not a phone",
"Summary": "After investigating, it was a phone",
"Solution": "Gave customer a banana so it wouldn't ring",
"Customer": {
"BackendID": "CUST123",
"EmailAddress": "cust@om.er",
"Gender": "O", -- options are M/F/O
"Initials": "",
"FirstName": "",
"LastName": "",
"PhoneNumber": "",
"DateOfBirth": 01/01/11 00:00:00.000,
"PlaceOfBirth": "CUST123",
"BankAccount": "CUST123",
"BackendID": "CUST123",
"Nickname": "CUST123",
"ShippingAddress": {
"Address1": "",
"Address2": "",
"HouseNumber": "", -- including extensions
"FirstName": "",
"LastName": "",
"ZipCode": "",
"City": "",
"Region": "",
"District": "",
"Subdistrict": "",
"EmailAddress": "",
"PhoneNumber": "",
"State": "", -- ISO 3166-2
"CountryID": "", -- ISO 3166-2
},
"BillingAddress": { /* Same as ShippingAddress */ },
"LanguageID": "CUST123", -- ISO 639-1
"CountryID": "CUST123", -- ISO 639-1
"FiscalID": "CUST123",
"SocialSecurityNumber": "CUST123",
"Title": "CUST123",
"Salutation": "CUST123",
"AccountType": 0, -- UserAcctionType enum
"Company": {
"Name": "",
"RegistrationNumber": "",
"VatNumber": "",
"FiscalID": "",
},
"BackendRelationID": "CUST123",
},
"OriginatingOrganizationUnitBackendID": "",
"Assignee": {
"ID": 1,
"CustomID": "",
"EmailAddress": "",
},
"AssignedOn": 01/01/11 00:00:00.000,
"Priority": 1,
"IsWarranty": false, -- if exists
"Status": "SomeStatus",
"ReportingTime": 01/01/11 00:00:00.000,
"LastInteractionTime": 01/01/11 00:00:00.000,
"ClosingTime": 01/01/11 00:00:00.000,
"CustomFields": {
"CustomField1": "true",
"CustomField2": "yes",
}
}
{
"ID": 1
}
Custom field for cases
In order to create custom fields for use with Cases, the CreateCustomField service can used with TypeID
9
.
Using the GetCustomFieldTypes you can double check the TypeID
for Case
.
Here is an example:
{
"Name": "Car brand",
"DataType": 4,
"IsArray": false,
"TypeID": 9,
"EnumValues": {
"audi": "Audi",
"bmw": "BMW",
"tesla": "Tesla",
"ford": "Ford"
}
}
{
"ID": 37
}
This should be followed by SetCustomFieldOptions to set viewing and editing permissions.
Here is an example:
{
"CustomFieldID": 37,
"OrganizationUnitSetID": 9,
"IsRequired": false,
"VisibleByUserTypes": 3,
"EditableByUserTypes": 3
}
{}