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

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

Authorization

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 and BackendID 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 EVA ID, CustomID, or EmailAddress. If no match, an assignee will not be resolved and the AssignedOn 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:

CustomerCreateCase

{  
  "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": "[email protected]",
    "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",
  }
}

Response

{ 
  "ID": 1
}

Custom field for cases

In order to create custom fields for use with Cases, the CreateCustomField service can used with TypeID 9.

tip

Using the GetCustomFieldTypes you can double check the TypeID for Case.

Here is an example:

CreateCustomField

{
  "Name": "Car brand",
    "DataType": 4,
    "IsArray": false,
    "TypeID": 9,
    "EnumValues": {
    "audi": "Audi",
    "bmw": "BMW",
    "tesla": "Tesla",
    "ford": "Ford"
    } 
}

Response

{
  "ID": 37
}

This should be followed by SetCustomFieldOptions to set viewing and editing permissions.

Here is an example:

SetCustomFieldOptions

{
    "CustomFieldID": 37,
    "OrganizationUnitSetID": 9,
    "IsRequired": false,
    "VisibleByUserTypes": 3,
    "EditableByUserTypes": 3
}

Response

{}