Lifecycle Services

The services in the lifecycle package provide methods that allow custom code to interact with object and document lifecycles.

Object Lifecycle Services

ObjectLifecycleMetadataService: Provides getter methods to retrieve metadata for object lifecycles. For example, you can retrieve all lifecycle metadata fields for a single object record, or retrieve a collection of all object lifecycles available in a Vault.
ObjectLifecycleStateUserActionMetadataService: Provides methods to retrieve metadata about an object lifecycle user action.
ObjectLifecycleStateUserActionService: Provides methods to execute an object lifecycle user action.

Object Lifecycle User Action Services

The Vault Java SDK supports initiating object lifecycle user actions, which are available to users on an object record in a specific lifecycle state. User actions can begin a workflow, move the record into a new lifecycle state, etc. Learn more about object lifecycle user actions in Vault Help.

The ObjectLifecycleStateUserActionMetadataService provides methods to retrieve configuration metadata about user actions, while ObjectLifecycleStateUserActionService provides methods to execute those actions.

The following example illustrates how to retrieve configuration metadata about available lifecycle user actions.

ObjectLifecycleStateUserActionMetadataService service = ServiceLocator.locate(ObjectLifecycleStateUserActionMetadataService.class);
      LogService logService = ServiceLocator.locate(LogService.class);

      // Retrieve metadata about user actions on a particular lifecycle state
      // Build the metadata request
      ObjectLifecycleUserActionMetadataRequest request = service.newLifecycleUserActionMetadataRequestBuilder()
          .withLifecycleName(lifecycleName)
          .withLifecycleState(lifecycleState)
          .withActionType("LIFECYCLE_RUN_WORKFLOW_ACTION") // Optional: filter the type of the user actions to be returned
          .build();

      ObjectLifecycleUserActionCollectionResponse response = service.getLifecycleUserActions(request);
      List<ObjectLifecycleUserActionMetadata> userActionMetadata = response.getUserActions();

      for (ObjectLifecycleUserActionMetadata data : userActionMetadata) {
          logService.info("User action metadata: label {}, component name {}, user action name {}," +
               "type {}, workflow name {}, record action class name {}, fully qualified name {}",
              data.getLabel(), data.getName(), data.getUserActionName(), data.getType(),
              data.getWorkflowName(), data.getRecordActionClassName(), data.getFullyQualifiedActionName());
     }

     // Retrieve metadata about user actions on an object record
     // Build the metadata request
     ObjectRecordLifecycleUserActionMetadataRequest request = service.newRecordLifecycleUserActionMetadataRequestBuilder()
         .withObjectName("object__c")
         .withRecordId("V6U000000001001")
         .withLifecycleState("inactive_state__c") // Optional: set the lifecycle state for the record, otherwise use the state the record is currently on
         .build();
     ObjectRecordLifecycleUserActionCollectionResponse response = service.getRecordLifecycleUserActions(request);
     List<ObjectRecordLifecycleUserActionDetail> details = response.getUserActions();

     for (ObjectRecordLifecycleUserActionDetail detail : details) {
         logService.info("User action is executable {}, is viewable {}", detail.isExecutable(), detail.isViewable());

         ObjectLifecycleUserActionMetadata metadata = detail.getMetadata();
         logService.info("User action metadata: label {}, component name {}, ...",
              metadata.getLabel(), metadata.getName());
     }

The following example illustrates how to retrieve and use input parameter metadata for user actions. This service returns metadata about RecordActions annotated with a user_input_object, configured as a user action.

ObjectLifecycleStateUserActionService service = ServiceLocator.locate(ObjectLifecycleStateUserActionService.class);
      // Build the request
      ObjectLifecycleUserActionInputParameterMetadataRequest request = service.newInputParameterMetadataRequestBuilder()
          .withUserActionName("Objectlifecyclestateuseraction.object__c.active_state__c.action__c")
          .build();
      ObjectLifecycleUserActionInputParameterMetadata metadata = service.getInputParameterMetadata(request);

      // Get the metadata for the input parameter
      String userInputObjectName = metadata.getUserInputObjectName();
      String userInputObjectType = metadata.getUserInputObjectTypeName():

      // Use the metadata to create a record of that object
      Record input = recordService.newRecord(userInputObjectName);
      input.setValue("name__v", "new name");
      input.setValue("field__c", "new value");
      RecordBatchSaveRequest saveRequest = recordService.newRecordBatchSaveRequestBuilder()
          .withRecords(VaultCollections.asList(input))
          .build();
      recordService.batchSaveRecords(saveRequest)
          .rollbackOnErrors()
          .execute();
      String userInputObjectRecordId = input.getValue(RECORD_ID, ValueType.STRING);

      // Use the userInputObjectRecordId to build a request to execute an action with an input
      UserActionExecutionRequest request = userActionService.newExecutionRequestBuilder()
          .withObjectName("object__c")
          .withObjectRecordId("V6U000000001001")
          .withUserInputRecordId(userInputObjectRecordId)
          .withUserActionName("Objectaction.object__c.action__c") // Use the fully qualified name of the action
          .build();

Executing a Lifecycle User Action

The following example illustrates how to execute an action. An action can be a user action, such as a state change, or an object action that is either available on all lifecycle states or configured on a particular state.

The UserActionExecutionRequest.Builder is used to construct the request, which is submitted in a UserActionExecutionRequest. Optionally, you can specify success and error handlers on the UserActionExecutionOperation before execution.

ObjectLifecycleStateUserActionService userActionService = ServiceLocator.locate(ObjectLifecycleStateUserActionService.class);
      LogService logService = ServiceLocator.locate(LogService.class);

      // Build user action execution request for the record
      UserActionExecutionRequest request = userActionService.newExecutionRequestBuilder()
          .withObjectName("object__c")
          .withObjectRecordId("V6U000000001001")
          .withUserInputRecordId(userInputObjectRecordId) // Optional: if the user action is a RecordAction annotated with a user_input_object.
          .withUserActionName("Objectaction.object__c.action__c") // Use the fully qualified name of the action.
          .build();

      // Execute the user action
      userActionService.executeUserAction(request)
          .onSuccess(userActionExecutionResponse -> {
              // Logic to be executed if the user action completes successfully.
              logService.info("Successfully executed user action");
           })
          .onError(error -> {
              // Logic to be executed if the user action encounters an error when executing.
              if (error.getErrorType().equals(ActionErrorType.PERMISSION_DENIED)) {
                  logService.error("Failed to execute user action: " + error.getMessage());
              }
          })
          .execute();

Document Lifecycle Services

DocumentLifecycleMetadataService: Provides getter methods to retrieve metadata for document lifecycles. For example, you can retrieve metadata for all document roles for a lifecycle, or retrieve a collection of all document lifecycles available in a Vault.
DocumentLifecycleStateUserActionMetadataService: Provides getter methods to retrieve metadata about a document lifecycle user action, document version lifecycle user action, and user action input.
DocumentLifecycleStateUserActionService: Provides methods to execute a document lifecycle user action.

Document Lifecycle User Action Services

The Vault Java SDK supports initiating document lifecycle user actions, which are available to users on a document in a specific lifecycle state. User actions can begin a workflow, move the document into a new lifecycle state, and more. Learn more about document lifecycle user actions in Vault Help.

DocumentLifecycleStateUserActionMetadataService provides methods to retrieve configuration metadata about user actions, while DocumentLifecycleStateUserActionService provides methods to execute those actions.

The following example illustrates how to retrieve configuration metadata about available lifecycle user actions.

DocumentLifecycleStateUserActionMetadataService service = ServiceLocator.locate(DocumentLifecycleStateUserActionMetadataService.class);
      LogService logService = ServiceLocator.locate(LogService.class);

      // Retrieve metadata about user actions on a particular lifecycle state
      // Build the metadata request
      DocumentLifecycleUserActionMetadataRequest request = service.newUserActionRequestBuilder()
          .withLifecycleName(lifecycleName)
          .withStateName(lifecycleState)
          .build();

      DocumentLifecycleUserActionMetadataResponse response = service.getUserActions(request);
      List<DocumentLifecycleUserActionMetadata> userActionMetadata = response.getUserActions();

      for (DocumentLifecycleUserActionMetadata data : userActionMetadata) {
          logService.info("User action metadata: label {}, user action name {}," +
               "workflow name {}, document action class name {}",
              data.getLabel(), data.getUserActionName(),
              data.getWorkflowName(), data.getDocumentActionClassName());
     }

     // Retrieve metadata about user actions on a document version
     // Build the metadata request
     DocumentVersionLifecycleUserActionMetadataRequest request = service.newDocumentVersionUserActionRequestBuilder()
         .withDocumentVersionId("1_2_3")
         .build();
     DocumentVersionLifecycleUserActionMetadataResponse response = service.getDocumentVersionUserActions(request);
     List<DocumentVersionLifecycleUserActionDetail> details = response.getUserActions();

     for (DocumentVersionLifecycleUserActionDetail detail : details) {
         logService.info("User action is executable {}, is viewable {}", detail.isExecutable(), detail.isViewable());

         DocumentLifecycleUserActionMetadata metadata = detail.getMetadata();
         logService.info("User action metadata: label {}, user action name {}, ...",
              metadata.getLabel(), metadata.getUserActionName());
     }

The following example illustrates how to retrieve and use input metadata for user actions. This service returns metadata about DocumentActions annotated with a user_input_object.

DocumentLifecycleStateUserActionMetadataService service = ServiceLocator.locate(DocumentLifecycleStateUserActionMetadataService.class);
      // Build the request
      DocumentLifecycleUserActionUserInputMetadataRequest request = service.newUserInputRequestBuilder()
          .withUserActionName("sdkDocLifecycleUA134c9hshe71tc__c")
          .build();
      DocumentLifecycleUserActionUserInputMetadata metadata = service.getUserInput(request);

      // Get the metadata for the input
      String userInputObjectName = metadata.getUserInputObjectName();
      String userInputObjectType = metadata.getUserInputObjectTypeName():

      // Use the metadata to create a record of that object
      Record input = recordService.newRecord(userInputObjectName);
      input.setValue("name__v", "new name");
      input.setValue("field__c", "new value");
      RecordBatchSaveRequest saveRequest = recordService.newRecordBatchSaveRequestBuilder()
          .withRecords(VaultCollections.asList(input))
          .build();
      recordService.batchSaveRecords(saveRequest)
          .rollbackOnErrors()
          .execute();
      String userInputObjectRecordId = input.getValue(RECORD_ID, ValueType.STRING);

      // Use the userInputObjectRecordId to build a request to execute an action with an input
      DocumentLifecycleUserActionExecutionRequest request = documentLifecycleStateUserActionService.newExecutionRequestBuilder()
          .withDocumentVersionId("1_2_3")
          .withUserInputRecordId(userInputObjectRecordId)
          .withUserActionName("sdkDocLifecycleUA134c9hshe71tc__c")
          .build();

Executing a Document Lifecycle User Action

The following example illustrates how to execute an action.

The DocumentLifecycleUserActionExecutionRequest.Builder is used to construct the request, which is submitted in a DocumentLifecycleUserActionExecutionRequest. Optionally, you can specify success and error handlers on the DocumentLifecycleUserActionExecutionOperation before execution.

DocumentLifecycleStateUserActionService userActionService = ServiceLocator.locate(DocumentLifecycleStateUserActionService.class);
      LogService logService = ServiceLocator.locate(LogService.class);

      // Build user action execution request for the document version
      DocumentLifecycleUserActionExecutionRequest request = userActionService.newExecutionRequestBuilder()
          .withDocumentVersionId("1_2_3")
          .withUserInputRecordId(userInputObjectRecordId) // Optional: if the user action is a DocumentAction annotated with a user_input_object.
          .withUserActionName("sdkDocLifecycleUA134c9hshe71tc__c")
          .build();

      // Execute the user action
      userActionService.executeUserAction(request)
          .onSuccess(userActionExecutionResponse -> {
              // Logic to be executed if the user action completes successfully.
              logService.info("Successfully executed user action");
           })
          .onError(error -> {
              // Logic to be executed if the user action encounters an error when executing.
              if (error.getErrorType().equals(ActionErrorType.PERMISSION_DENIED)) {
                  logService.error("Failed to execute user action: " + error.getMessage());
              }
          })
          .execute();

Lifecycle Services

Object Lifecycle Services

Object Lifecycle User Action Services

Retrieving Configuration Metadata About Lifecycle User Actions

Retrieving Input Parameter Metadata for User Actions

Executing a Lifecycle User Action

Document Lifecycle Services

Document Lifecycle User Action Services

Retrieving Configuration Metadata About Document Lifecycle User Actions

Retrieving Input Metadata for Document Lifecycle User Actions

Executing a Document Lifecycle User Action