Create Service Events

An integration can send service events to lender by:

Creating a transaction with a response that returns the required field values
With 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
Product has to be entitled to CREATE_SERVICE_EVENTS action in order to use it via transaction patch.
A product can be entitled to CREATE_SERVICE_EVENTS action by adding it in the response.results array of the specific request type within $.entitlements.data.transaction.
          {
            "action": "CREATE_SERVICE_EVENTS",
            "formats": [
              "application/vnd.service-events-create-1.0.0.json"
            ]
          }

The specific fields that are sent as part of the response loan data follow the standard data entitlement model and process.

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

📘
format and action
The Encompass Partner Connect Platform (EPC) uses $.result.format and $.result.action to properly handle 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"

List of fields which when sent as part of rate lock operation is saved in the lock snapshot:

Fields	Additional Information
`$.result.details.serviceEvents[].code`	Partner defined unique identifier of the serviceEvent within the partner product.
`$.result.details.serviceEvents[].title`	Partner defined user-friendly title of the serviceEvent.
`$.result.details.serviceEvents[].description`	Partner defined description of the serviceEvent.
`$.result.details.serviceEvents[].referenceId`	Partner defined referenceId of the serviceEvent.

The complete list of supported fields in the create service event action details is captured in the JSON-schema object definition below. You can use online resources such as JSON Schema Validator to manually validate result details objects content.

{
  "$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"
      }
    },
    "serviceEventItem": {
      "type": "object",
      "properties": {
        "code": {
          "$ref": "#/definitions/non-empty-string",
          "description": "Represents the code of the service event."
        },
        "title": {
          "$ref": "#/definitions/non-empty-string",
          "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
    }
  }
}

Sample create service event request payload with most of the fields supported:

{
    "status": "completed",
    "loanFormat": "application/vnd.plm-2.0.0+json",
    "loan": {
        ... // Additional loan data, sent as part of standard transaction loan update
    },
    "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"
}

Upon successful processing of the transaction PATCH, transaction events will reflect the outcome of serviceEvents that lender mapped. For the above sample payload if the lender mapped EVENT-001 to a task and a notification, but didn't map EVENT-002, EPC Platform will not process EVENT-002but will process EVENT-001 and attempt to create a task and notification on Encompass. If it succeeds, the transaction event will reflect that as 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"
        }
    }
]

Create Service Events

📘
Prerequisites

📘
format and action

📘Prerequisites

📘format and action

📘
Prerequisites

📘
format and action