User Exception Messages

With Spark user exceptions, your Vault to Vault integrations can display custom exception messages to Business Admins in the Vault UI. This helps Business Admins track and resolve any errors that occur with your integrations.

For example, if your integration fails to process an incoming message, you can create custom SDK logic to create a User Exception Message (exception_message__sys) record to capture the failure and display information to a Business Admin. This record can contain information for how to troubleshoot, what action is necessary, who to contact if the failure persists, and so on.

User exception messages are tied to individual Integration Points (integration_point__sys). Because of this, you cannot leverage user exception messages without setting up integrations and integration points. Learn more in Vault Help.

Creating exceptions which appear in the Vault UI is as simple as creating User Exception records with RecordService.

Developing User Exception Messages

First, your Spark message format must include an attribute pointing to the corresponding integration_point__sys API name. This ties all of your user exceptions to the appropriate integration point. It doesn’t matter what you name this attribute, but we recommend a meaningful name, such as integration_point.

To add an attribute to a Spark message, call Message#setAttribute(). For example:

QueueService queueService = ServiceLocator.locate(QueueService.class);
    Message outboundMessage = queueService.newMessage("outbound_queue__c");
    outboundMessage.setAttribute("integration_point", "integration_point_api_name");
    queueService.putMessage(outboundMessage);

Which will add the attribute to your Spark message:

"message":{
  "attributes":{
    "integration_point": "create_regulatory_event__v"
  }
}

Next, add your user exception logic inside of a MessageProcessor. This logic must create a exception_message__sys record, and can optionally create exception_item__sys child records for each item in the exception. For example:

@MessageProcessorInfo()
  public class ProcessStudy implements MessageProcessor {
    public void execute(MessageContext messageContext) {
      Message incomingMessage = messageContext.getMessage();
      String integrationApiName = "integration_api_name";
      String integrationPointApiName = incomingMessage.getAttribute("integration_point", MessageAttributeValueType.STRING);
      createUserExceptionMessage(integrationApiName, integrationPointApiName);
    }

    private void createUserExceptionMessage(String integrationApiName, String integrationPointApiName) {
      RecordService recordService = ServiceLocator.locate(RecordService.class);
      String integrationId = getIntegrationId(integrationApiName);
      String integrationPointId = getIntegrationPointId(integrationPointApiName);
      List<Record> recordsToSave = getUserExceptionMessageRecord(integrationPointApiName, integrationId, integrationPointId);
      recordService.batchSaveRecords(recordsToSave)
        .rollbackOnErrors()
        .execute();
    }

    private List<Record> getUserExceptionMessageRecord(String integrationPointApiName, String integrationId, String integrationPointId) {
      RecordService recordService = ServiceLocator.locate(RecordService.class);
      Record userExceptionMessage = recordService.newRecord("exception_message__sys");
      List<String> errorTypePicklistValues = VaultCollections.newList();
      errorTypePicklistValues.add("message_processing_error__sys");
      userExceptionMessage.setValue("integration__sys", integrationId);
      userExceptionMessage.setValue("integration_point__sys", integrationPointId);
      userExceptionMessage.setValue("error_type__sys", errorTypePicklistValues);
      userExceptionMessage.setValue("error_message__sys", "Error message from IntegrationRuleService or RecordService");
      userExceptionMessage.setValue("name__v", integrationPointApiName);
      List<Record> recordsToSave = VaultCollections.newList();
      recordsToSave.add(userExceptionMessage);
      return recordsToSave;
    }
}