Doctype Triggers

Doctype triggers are a Vault Java SDK entry point which executes custom business logic whenever a document or document version is created, updated, or deleted. When these operations occur, Vault Java SDK provides interfaces to interact with document version data BEFORE and AFTER the data operation occurs.

This event-driven programming model allows developers to write small programs to address common business requirements which standard application configurations cannot address. For example, your organization can use doctype triggers to populate and clear field values, create related records, start SDK jobs and workflows, or perform complex validation logic.

These triggers are called doctype triggers because they are scoped to a specific Doctype, although these triggers can be scoped to all documents by using the base_document__v doctype.

Before developing document type triggers, you should be familiar with the following:

Doctype Trigger Scope

Defining when a doctype trigger fires in Vault involves three key elements:

Document Type: The name of a single, top-level document type where this trigger should fire. For example, document_type__c. If set to the Base document type (base_document__v), this trigger will fire for all documents. Only one document type can be specified per trigger.
Trigger Events: The type of data change that causes this trigger fire. For example, triggers can fire before or after create (called insert), update, and delete events. The same trigger can be configured to fire on multiple events, for example, the same trigger can execute every time a document is created or updated. Available events are BEFORE_INSERT, AFTER_INSERT, BEFORE_UPDATE, AFTER_UPDATE, BEFORE_DELETE, or AFTER_DELETE.
Trigger Event Level: Specifies if the trigger fires when data operations occur at the DOCUMENT_VERSION level or the DOCUMENT level. Each doctype trigger can only fire at one event level, and some Vault operations trigger both events. For example, creating a new document is both a document-level event and a document version event.

What Events Fire Doctype Triggers?

With a few exceptions, all changes to a document’s content or metadata fire doctype triggers. These events are classified as either document version events or document-level events.

Doctype triggers do not fire on updates to:

Document attachments
Document relationships
Document roles
Annotations

Sample Code

The following sample code is a doctype trigger that prevents a document’s Name (name__v) from starting with a lowercase letter.

This trigger fires on BEFORE_UPDATE, which means whenever an existing document is updated, this trigger fires right before the document saves and checks if the name__v field starts with a lowercase letter. If it does, this trigger throws an error and prevents the save of the document.

@DocumentTypeTriggerInfo(
    documentType = "base_document__v",
    events = {DocumentVersionEvent.BEFORE_UPDATE, BEFORE_INSERT},
    level = DocumentVersionEventLevel.DOCUMENT_VERSION)
public class PreventLowerCase implements DocumentTypeTrigger {

  public void execute(DocumentTypeTriggerContext context) {
    LogService logService = ServiceLocator.locate(LogService.class);

    //get the document field metadata for name__v, to use in error messages
    DocumentMetadataService documentMetadataService = ServiceLocator.locate(DocumentMetadataService.class);
    DocumentField nameField = documentMetadataService.getField("name__v");

    for (DocumentVersionChange documentVersionChange : context.getDocumentVersionChanges()) {
      DocumentVersion documentVersion = documentVersionChange.getNew();

      //if the title starts with a lowercase character, set a row-level error (other document updates are not failed)
      String title = documentVersion.getValue("name__v", ValueType.STRING);
      if (title != null && !title.isEmpty() && Character.isLowerCase(title.charAt(0))) {
        documentVersionChange.setError("OPERATION_NOT_ALLOWED", nameField.getLabel() +  " cannot start with a lowercase character");

        if (logService.isErrorEnabled()) {
          logService.error("Blocked document save on [{}] due to starting with a lowercase character", title);
        }
      }
    }
  }
}

Find more examples of doctype triggers in our sample code.