Developer Guides

Create Service Events

Suggest Edits

An integration can send service events to the lender by:

  • Creating a transaction with a response that returns the required field values
  • Including a response result object with the action CREATE_SERVICE_EVENTS

The integration can also send additional loan data to be updated in Encompass within the same transaction response. The specific fields that are sent as part of the response loan data follow the standard data entitlement model and process.

📘

Prerequisites

The product must be entitled to the CREATE_SERVICE_EVENTS action to use it in a transaction PATCH.

To entitle a product, add the action to the response.results array of the relevant request type within $.entitlements.data.transaction:

  {
    "action": "CREATE_SERVICE_EVENTS",
    "formats": [
      "application/vnd.service-events-create-1.0.0.json"
    ]
  }

{
   "status": "processing",
   "loanFormat": "application/vnd.plm-2.0.0+json",
   "loan": {
      ... // Additional loan data, sent as part of standard transaction loan update
   },
   "result": {
      "format": "application/vnd.service-events-create-1.0.0.json",
      "action": "CREATE_SERVICE_EVENTS",
      "details": {
         ... // Create service events action details
      }
   },
   "partnerStatus": "partner status"
}

📘

format and action

The Encompass Partner Connect (EPC) Platform uses $.result.format and $.result.action to determine how to process the action details sent in the transaction PATCH payload. Make sure you use:

"format": "application/vnd.service-events-create-1.0.0.json"
"action": "CREATE_SERVICE_EVENTS"

Fields in the CREATE_SERVICE_EVENTS result action

FieldAdditional Information
$.result.details.serviceEvents[].codeRequired. Partner-defined unique identifier of the service event within the partner product. Maximum 128 characters.
$.result.details.serviceEvents[].titleRequired. Partner-defined, user-friendly title of the service event. Maximum 1,000 characters.
$.result.details.serviceEvents[].descriptionOptional. Partner-defined description of the service event.
$.result.details.serviceEvents[].referenceIdOptional. Partner-defined reference ID of the service event.
$.result.details.serviceEvents[].senderOptional. String.
$.result.details.serviceEvents[].providerOptional. String.
$.result.details.serviceEvents[].comments[].commentOptional. Comments on the service event. Each comment must not be empty.

The serviceEvents array must contain at least one item, and code and title must not be empty or contain only whitespace.

The complete list of supported fields in the CREATE_SERVICE_EVENTS action details object is defined in the JSON schema below. You can use online tools such as JSON Schema Validator to manually validate the contents of a details object.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "validationMessage": {
    "invalid-string": "a valid String. Please provide a valid string."
  },
  "properties": {
    "serviceEvents": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/serviceEventItem"
      },
      "minItems": 1,
      "description": ""
    }
  },
  "required": [
    "serviceEvents"
  ],
  "additionalProperties": false,
  "definitions": {
    "non-empty-string": {
      "type": "string",
      "pattern": "^(?!\\s*$).+",
      "validationMessage": {
        "$ref": "#/validationMessage/invalid-string"
      }
    },
    "non-empty-code-string": {
      "type": "string",
      "pattern": "^(?!\\s*$).+",
      "maxLength": 128
    },
    "serviceEventItem": {
      "type": "object",
      "properties": {
        "code": {
          "$ref": "#/definitions/non-empty-code-string",
          "description": "Represents the code of the service event."
        },
        "title": {
          "type": "string",
          "pattern": "^(?!\\s*$).+",
          "maxLength": 1000,
          "description": "Represents the status of the service event."
        },
        "description": {
          "type": "string",
          "description": "Represents the description of the service event."
        },
        "referenceId": {
          "type": "string"
        },
        "sender": {
          "type": "string"
        },
        "provider": {
          "type": "string"
        },
        "comments": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/definitions/commentItem"
          }
        }
      },
      "required": [
        "code",
        "title"
      ],
      "additionalProperties": false
    },
    "commentItem": {
      "type": "object",
      "properties": {
        "comment": {
          "$ref": "#/definitions/non-empty-string"
        }
      },
      "required": [
        "comment"
      ],
      "additionalProperties": false
    }
  }
}

Below is a sample create service events request payload:

{
    "status": "completed",
    "loanFormat": "application/vnd.plm-2.0.0+json",
    "result": {
        "action": "CREATE_SERVICE_EVENTS",
        "format": "application/vnd.service-events-create-1.0.0.json",
        "details": {
            "serviceEvents": [
                {
                    "code": "EVENT-001",
                    "title": "EVENT-001 review is required",
                    "description": "Review is required to fulfill the transaction.",
                    "referenceId": "100000991"
                },
                {
                    "code": "EVENT-002",
                    "title": "EVENT-002 Transaction fulfillment will be delayed.",
                    "description": "Transaction fulfillment will be delayed due to technical issues.",
                    "referenceId": "100000992"
                }
            ]
        }
    },
    "partnerStatus": "partner status"
}

When the transaction PATCH is processed successfully, the transaction events reflect the outcome for the service events that the lender has mapped. In the sample payload above, if the lender mapped EVENT-001 to a task and a notification but did not map EVENT-002, the EPC Platform does not process EVENT-002. It processes EVENT-001 and attempts to create a task and a notification in Encompass. If it succeeds, the transaction events reflect the result as shown below:

[
    {
        "id": "7f91afe7-80e2-4312-b92d-8e03e34db0b3",
        "text": "Transaction Response Updated",
        "type": "urn:elli:epc:transaction:response:updated",
        "from": "System",
        "sent": "2024-07-22T21:20:50Z"
    },
    {
        "id": "a6e2f584-9e6f-42e9-af13-97e138226cbc",
        "text": "Transaction response successfully processed",
        "type": "urn:elli:epc:transaction:response:processed",
        "from": "System",
        "sent": "2024-07-22T21:20:56Z",
        "comments": "Transaction response successfully processed",
        "details": {
            "action": "create_service_events",
            "status": "Success",
            "requestType": "NewOrder",
            "serviceEvents": [
                {
                    "success": [
                        {
                            "code": "EVENT-001",
                            "title": "EVENT-001 review is required",
                            "referenceId": "100000991",
                            "lenderEntities": [
                                {
                                    "id": "edd3a1fe-d6a1-497b-ab1c-762d9276785b",
                                    "type": "task"
                                },
                                {
                                    "type": "notification"
                                }
                            ]
                        }
                    ]
                }
            ],
            "transactionId": "8ff703e8-ae7f-4b44-966e-1d5abdd273a5",
            "requestCorrelationId": "fbab77c8-6723-4794-a0f8-d8f67ccede08"
        }
    }
]

For more information, see Service Events.

Updated about 1 year ago