Case History#

The case history API provides a full transaction log for all changes to the case: https://api.mnemonic.no/cases/v2/case/21238064/history

The endpoint returns one transaction for each API invocation that changes the case. The format of each transaction is as detailed under Case Transaction below.

Case Transaction#

To fetch a specific transaction, use the single-transaction fetch endpoint, e.g. https://api.mnemonic.no/cases/v2/case/21238064/history/a9674701-4df3-4783-89a1-e6bb1b28cc1e

Example:

$ http get https://api.mnemonic.no/cases/v2/case/21238064/history/2b00286e-364a-468a-9097-36d27583c872 Argus-API-Key:my/api/key

{
    "count": 0,
    "data": {
        "changes": [
            {
                "field": "status",
                "flags": [
                    "SUBMITTED_BY_TECH"
                ],
                "id": "e34fd296-bc0c-4801-99b1-7119ed3f1530",
                "object": "pendingSoc",
                "objectType": "status",
                "previousObject": "pendingCustomer",
                "previousValue": "pendingCustomer",
                "transactionIndex": 1,
                "value": "pendingSoc"
            }
        ],
        "flags": [
            "SUBMITTED_BY_TECH"
        ],
        "id": "2b00286e-364a-468a-9097-36d27583c872",
        "notified": 2,
        "operation": "updateCase",
        "time": "2023-08-01T13:34:44.659Z",
        "timestamp": 1690896884659,
        "user": {
            "customer": {
                "domain": {
                    "id": 1,
                    "name": "MNEMONIC"
                },
                "id": 1,
                "name": "mnemonic",
                "shortName": "mnemonic"
            },
            "customerID": 1,
            "domain": {
                "id": 1,
                "name": "MNEMONIC"
            },
            "id": 1151,
            "name": "Joakim von Brandis (admin)",
            "type": "user",
            "type": "user",
            "userName": "joakim.adm"
        }
    },
    "limit": 0,
    "messages": [],
    "metaData": {},
    "offset": 0,
    "responseCode": 200,
    "size": 0
}

Each API invocation records a transaction with the following information:

an operation
the timestamp when the operation was executed
the user which executed the operation
a notification count
a list of Change Events (“changes”)

Because an API operation may perform multiple changes (depending on parameters), each transaction contains a set of Change Events, specifying what has changed.

Each transaction has at least one Change Event.

If the change is the operation itself (e.g. createCase, publishCase or deleteCaseComment), it will contain an Event with field set to null, returning an object with the result of the operation. A few operations return a null object, as there is nothing to return (publishCase and deleteCase).

Any additional changes to the case due to this operation will be returned as separate Events with a specified field (see Fields below), such as

workflows changed
flags added/removed
etc.

The change behaviour of a specific field is always the same, regardless of the operation. Clients should therefore focus on the behaviour of fields wherever the field is set.

The object returned in an Event is always the same for a specific field, but is also specified by the objectType parameter. Clients should use the objectType parameter to determine how to parse the object data.

Operations#

The operation of the transaction is determined by the API endpoint invoked. Each operation is named after the endpoint it invokes.

This table specifies each operation, what it means, and if it has a “main” event (without a field). Where the operation has no “main” event (marked with “None”), all events will specify a field. Operations marked with null as main change event, have a change event that does not return any object.

Operation	Meaning	Main change event
createCase	Creation of a case	The case itself
updateCase	Update some field in the case	None
moveCase	Move a case	None
publishCase	Mark a case as published (available to non-tech customers)	Returns object `null`
closeCase	Close the case	None
mergeCases	Merge cases (This operation is recorded on both the source and target case)	None
updateCaseAccessSettings	Change access mode settings of the case	None
addCaseComment	Add a comment to the case	None. The comment itself is always marked with field `addComment`
editCaseComment	Edit a case comment	The comment itself
deleteCaseComment	Delete a case comment	The deleted comment
addCaseAttachment	Add an attachment	The attachment itself
deleteCaseAttachment	Delete an attachment	The attachment itself
addCaseLink	Add a link to another case	None
deleteCaseLink	Delete a link from a case	The link itself
addCaseWatcher	Add an explicit watcher to the case	None. The watcher is always marked with field `addWatcher`
updateCaseWatcher	Update a case watcher	None
deleteCaseWatcher	Delete a watcher from a case	None
currentUser	Change watcher settings for the current user	None
updateWatcherSettings	Update case watcher settings	None
requestWorkflow	Request a new workflow	None. The workflow itself is always marked with `resetWorkflow`
acknowledgeWorkflow	Acknowledge an open workflow	The workflow itself
updateWorkflow	Update an existing workflow	The workflow itself
addCaseTag	Add a tag to a case	None. The tag itself is always marked with field `addTag`
removeCaseTag	Remove a tag from the case	The tag itself
grantCaseAccess	Grant explicit access to a case	The access entry
revokeCaseAccess	Revoke explicit access from a case	The access entry
setCaseField	Set a case field on a case	None. Added/removed field values are always marked with field `fieldAdded`/`fieldRemoved`
clearCaseField	Clear a custom case field	None. Removed field values are always marked with field `fieldRemoved`
deleteCase	Mark case as deleted	Returns object `null`
enquiryCreate	Add new enquiry to case	Returns the enquiry object
enquiryAnswer	Answer an existing enquiry on the case	Returns the enquiry object
enquiryReject	Reject an existing enquiry on the case	Returns the enquiry object
enquiryDelete	Delete an existing enquiry on the case	Returns the enquiry object

Change event#

Each change event specifies:

a field, which is the part of the case being changed, or null if it is the main entity of the operation.
a value, which is the raw value of the field being set.
a previous value, which is the raw value of the field before the transaction, or null if not relevant.
an object, which is the formatted value of the field being set.
a previous object, which is the formatted value of the field before the transaction, or null if not relevant.
an object type, which specifies the type of the returned object.
a transaction index, which specifies the order in which the change was applied to the case in the transaction. This is mostly not relevant to users.

Fields#

Change events which are not considered the “main event” of an operation specifies a “field”, which specify which part of the case has changed. This table specifies the meaning of each field in the case change event:

Field	Meaning
customerID	The customer of the case.
service	The service of the case.
category	The category of the case.
type	The type of the case.
status	The status of the case.
fieldAdded	This field references a “custom field” being added to the case.
fieldRemoved	This field references the removal of a “custom field” from the case.
priority	The priority of the case.
subject	The subject of the case.
description	The description of the case
setProperties	This field references one or multiple properties being set on the case.
removeProperties	This field references one or multiple properties being removed from the case.
customerReference	The customer reference of the case.
accessMode	The access mode of the case.
reporterID	The reporter of the case.
assignedUserID	The customer user assigned to the case.
assignedTechID	The tech user assigned to the case.
setFlag	This field references a flag being set on the case.
unsetFlag	This field references the removal of a flag from the case.
addComment	This field references a comment being added to the case. Note A comment may be added as part of multiple operations, not just `addCaseComment`.
addTag	This field references a tag being added to the case.
addWatcher	This field references a watcher being added to the case.
addLink	This field references a link being added to the case.
updateWatcher	This field references a watcher being updated on the case.
deleteWatcher	This field references a watcher being updated on the case.
sentNotification	This field contains a notification record documenting a notification being sent for this case. If there are multiple users being notified, the transaction will contain one change event of this type for each notification contact.
resetWorkflow	This field references a workflow being reset, which may be as part of another transaction than the explicit “requestWorkflow” operation.
updateWorkflow	This field references a workflow being updated.
deleteWorkflow	This field is currently not in use.
enableVerbose	This field is set when a watcher is updated to enable verbose settings. The change event will return the ID of the referenced watcher.
disableVerbose	This field is set when a watcher is updated to disable verbose settings. The change event will return the ID of the referenced watcher.
customerDueTimestamp	The customer due timestamp, in milliseconds since Epoch.
techDueTimestamp	The tech due timestamp, in milliseconds since Epoch.
enquiry	An enquiry on the case.

Object types#

In each change event, the “value” will contain the raw value set on the field. This raw value may be an object ID, or a string literal (enum name), or the user provided value which is set on a text field. The “object” in the change event is a formatted object representing the referenced object, or the same string literal, or if the value is indeed a user text field, the object will be the same as the value.

The type of data of a change event will consistently be the same for a given field. However, the client should not attempt to predict/code the returned data type based on the field.

Instead, each change event specifies an “object type”, which specifies the data type of the returned object. If the change event contains a previous value/object, the data type of the previous object is the same as the value/object.

The object types are as specified below (referencing the data models specified in swagger):

Object Type	Data Model
access	CaseAccess
attachment	CaseAttachment
caseVO	CaseVO
caseType	CaseVO.Type
category	CategoryInfo
comment	CaseComment
customer	CustomerInfo
field	CaseField
flag	CaseVO.EncodedFlag
link	CaseLink
notification	CaseNotificationRecord
priority	CaseVO.Priority
service	ServiceInfo
status	CaseVO.Status
string	A string
timestamp	A timestamp (millis since epoch)
tag	CaseTag
user	UserInfo
watcher	CaseWatcher
workflow	CaseWorkflow
enquiry	CaseEnquiry