Package com.veeva.vault.sdk.api.lifecycle

package com.veeva.vault.sdk.api.lifecycle

This package provides interfaces to retrieve configuration metadata for object and document lifecycles and actions, and to execute actions.

Object Lifecycle User Action Services

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

Example: Retrieving configuration metadata about Lifecycle User 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());
     }
 
 

Example: Retrieving input parameter metadata for user actions

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();
     
 

Example: 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 User Action Services

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

Example: Retrieving configuration metadata about Lifecycle User 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());
     }
 
 

Example: Retrieving input metadata for user actions

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();
     
 

Example: Executing a 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();
     
 

Class	Description
ActionErrorType	Error types that can occur during SDK action execution.
DocumentLifecycleMetadata	Provides methods to retrieve metadata fields for a specific document lifecycle.
DocumentLifecycleMetadataRequest	Represents a request to retrieve multiple document lifecycles in the format of DocumentLifecycleMetadata collection.
DocumentLifecycleMetadataRequest.Builder	Creates an instance of DocumentLifecycleMetadataRequest.
DocumentLifecycleMetadataResponse	Holds a DocumentLifecycleMetadata collection.
DocumentLifecycleMetadataService	Provides methods to retrieve document lifecycle, state, stage group, stage, and role metadata.
DocumentLifecycleRoleMetadata	Provides methods to retrieve metadata fields for a specific document lifecycle role.
DocumentLifecycleRoleMetadataRequest	Represents a request to retrieve multiple document lifecycle roles in the format of DocumentLifecycleRoleMetadata collection.
DocumentLifecycleRoleMetadataRequest.Builder	Creates an instance of DocumentLifecycleRoleMetadataRequest.
DocumentLifecycleRoleMetadataResponse	Holds a DocumentLifecycleRoleMetadata collection.
DocumentLifecycleStageGroupMetadata	Provides methods to retrieve metadata fields for a specific document lifecycle stage group.
DocumentLifecycleStageGroupMetadataRequest	Represents a request to retrieve multiple document lifecycle stage groups in the format of DocumentLifecycleStageGroupMetadata collection.
DocumentLifecycleStageGroupMetadataRequest.Builder	Creates an instance of DocumentLifecycleStageGroupMetadataRequest.
DocumentLifecycleStageGroupMetadataResponse	Holds a DocumentLifecycleStageGroupMetadata collection.
DocumentLifecycleStageMetadata	Provides methods to retrieve metadata fields for a specific document lifecycle stage.
DocumentLifecycleStageMetadataRequest	Represents a request to retrieve multiple document lifecycle stages in the format of DocumentLifecycleStageMetadata collection.
DocumentLifecycleStageMetadataRequest.Builder	Creates an instance of DocumentLifecycleStageMetadataRequest.
DocumentLifecycleStageMetadataResponse	Holds a DocumentLifecycleStageMetadata collection.
DocumentLifecycleStartWorkflowInputParameter	Container for input parameters necessary to execute a Run Workflow document lifecycle user action.
DocumentLifecycleStartWorkflowInputParameter.Builder	Creates an instance of DocumentLifecycleStartWorkflowInputParameter.
DocumentLifecycleStateMetadata	Provides methods to retrieve metadata fields for a specific document lifecycle state.
DocumentLifecycleStateMetadataRequest	Represents a request to retrieve multiple document lifecycle states in the format of DocumentLifecycleStateMetadata collection.
DocumentLifecycleStateMetadataRequest.Builder	Creates an instance of DocumentLifecycleStateMetadataRequest.
DocumentLifecycleStateMetadataResponse	Holds a DocumentLifecycleStateMetadata collection.
DocumentLifecycleStateUserActionMetadataService	Provides methods to retrieve metadata about document lifecycle user action, document version lifecycle user action, and user action user input.
DocumentLifecycleStateUserActionService	Provides methods to execute a document lifecycle user action.
DocumentLifecycleUserActionExecutionError	Represents an error encountered during a DocumentLifecycleUserActionExecutionOperation.
DocumentLifecycleUserActionExecutionOperation	A sequence of instructions that can be chained together, building a document lifecycle user action execution operation that can be executed with DocumentLifecycleUserActionExecutionOperation.execute().
DocumentLifecycleUserActionExecutionRequest	Provides methods to set the parameters necessary to execute a document lifecycle user action.
DocumentLifecycleUserActionExecutionRequest.Builder	Creates an instance of DocumentLifecycleUserActionExecutionRequest.
DocumentLifecycleUserActionExecutionResponse	Represents the result of the execution of a document lifecycle user action.
DocumentLifecycleUserActionMetadata	Provides methods to retrieve metadata fields for a specific document lifecycle user action.
DocumentLifecycleUserActionMetadataRequest	Represents a request to retrieve metadata about document lifecycle user actions in the format of DocumentLifecycleUserActionMetadataResponse.
DocumentLifecycleUserActionMetadataRequest.Builder	Creates an instance of DocumentLifecycleUserActionMetadataRequest.
DocumentLifecycleUserActionMetadataResponse	Holds a DocumentLifecycleUserActionMetadata collection.
DocumentLifecycleUserActionUserInputMetadata	Provides methods to retrieve metadata fields for a specific document action's input.
DocumentLifecycleUserActionUserInputMetadataRequest	Represents a request to retrieve user action user input metadata, in the format of DocumentLifecycleUserActionUserInputMetadata.
DocumentLifecycleUserActionUserInputMetadataRequest.Builder	Creates an instance of DocumentLifecycleUserActionUserInputMetadataRequest.
DocumentVersionLifecycleUserActionDetail	Represents the metadata associated with a lifecycle user action for a particular document version.
DocumentVersionLifecycleUserActionMetadataRequest	Represents a request to retrieve metadata about document lifecycle user actions on a specific document version in the format of DocumentVersionLifecycleUserActionMetadataResponse.
DocumentVersionLifecycleUserActionMetadataRequest.Builder	Creates an instance of DocumentVersionLifecycleUserActionMetadataRequest.
DocumentVersionLifecycleUserActionMetadataResponse	Holds a DocumentVersionLifecycleUserActionDetail collection.
ObjectLifecycleMetadata	Provides methods to retrieve metadata fields for a specific object lifecycle.
ObjectLifecycleMetadataCollectionRequest	Represents a request to retrieve multiple object lifecycles in the format of ObjectLifecycleMetadata collection.
ObjectLifecycleMetadataCollectionRequest.Builder	Creates an instance of ObjectLifecycleMetadataCollectionRequest.
ObjectLifecycleMetadataCollectionResponse	Holds an ObjectLifecycleMetadata collection.
ObjectLifecycleMetadataRequest	Represents a request to retrieve a single object lifecycle in the format of ObjectLifecycleMetadata.
ObjectLifecycleMetadataRequest.Builder	Creates an instance of ObjectLifecycleMetadataRequest.
ObjectLifecycleMetadataService	Provides methods to retrieve object lifecycle, state, state type, stage group, and stage metadata.
ObjectLifecycleRoleMetadata	Provides methods to retrieve metadata fields for a specific object lifecycle role.
ObjectLifecycleRoleMetadataCollectionRequest	Represents a request to retrieve multiple object lifecycle roles in the format of ObjectLifecycleRoleMetadata collection.
ObjectLifecycleRoleMetadataCollectionRequest.Builder	Creates an instance of ObjectLifecycleRoleMetadataCollectionRequest.
ObjectLifecycleRoleMetadataCollectionResponse	Holds an ObjectLifecycleRoleMetadata collection.
ObjectLifecycleRoleMetadataRequest	Represents a request to retrieve a single object lifecycle role in the format of ObjectLifecycleRoleMetadata.
ObjectLifecycleRoleMetadataRequest.Builder	Creates an instance of ObjectLifecycleRoleMetadataRequest.
ObjectLifecycleStageGroupMetadata	Provides methods to retrieve metadata fields for a specific object lifecycle stage group.
ObjectLifecycleStageGroupMetadataCollectionRequest	Represents a request to retrieve multiple object lifecycle stage groups in the format of ObjectLifecycleStageGroupMetadata collection.
ObjectLifecycleStageGroupMetadataCollectionRequest.Builder	Creates an instance of ObjectLifecycleStageGroupMetadataCollectionRequest.
ObjectLifecycleStageGroupMetadataCollectionResponse	Holds an ObjectLifecycleStageGroupMetadata collection.
ObjectLifecycleStageGroupMetadataRequest	Represents a request to retrieve a single object lifecycle stage group in the format of ObjectLifecycleStageGroupMetadata.
ObjectLifecycleStageGroupMetadataRequest.Builder	Creates an instance of ObjectLifecycleStageGroupMetadataRequest.
ObjectLifecycleStageMetadata	Provides methods to retrieve metadata fields for a specific object lifecycle stage.
ObjectLifecycleStageMetadataCollectionRequest	Represents a request to retrieve multiple object lifecycle stages in the format of ObjectLifecycleStageMetadata collection.
ObjectLifecycleStageMetadataCollectionRequest.Builder	Creates an instance of ObjectLifecycleStageMetadataCollectionRequest.
ObjectLifecycleStageMetadataCollectionResponse	Holds an ObjectLifecycleStageMetadata collection.
ObjectLifecycleStageMetadataRequest	Represents a request to retrieve a single object lifecycle stage in the format of ObjectLifecycleStageMetadata.
ObjectLifecycleStageMetadataRequest.Builder	Creates an instance of ObjectLifecycleStageMetadataRequest.
ObjectLifecycleStateMetadata	Provides methods to retrieve metadata fields for a specific object lifecycle state.
ObjectLifecycleStateMetadataCollectionRequest	Represents a request to retrieve multiple object lifecycle states in the format of ObjectLifecycleStateMetadata collection.
ObjectLifecycleStateMetadataCollectionRequest.Builder	Creates an instance of ObjectLifecycleStateMetadataCollectionRequest.
ObjectLifecycleStateMetadataCollectionResponse	Holds an ObjectLifecycleStateMetadata collection.
ObjectLifecycleStateMetadataRequest	Represents a request to retrieve a single object lifecycle state in the format of ObjectLifecycleStateMetadata.
ObjectLifecycleStateMetadataRequest.Builder	Creates an instance of ObjectLifecycleStateMetadataRequest.
ObjectLifecycleStateTypeMetadata	Provides methods to retrieve metadata fields for a specific object lifecycle state type.
ObjectLifecycleStateTypeMetadataCollectionRequest	Represents a request to retrieve multiple object lifecycle state types in the format of ObjectLifecycleStateTypeMetadata collection.
ObjectLifecycleStateTypeMetadataCollectionRequest.Builder	Creates an instance of ObjectLifecycleStateTypeMetadataCollectionRequest.
ObjectLifecycleStateTypeMetadataCollectionResponse	Holds an ObjectLifecycleStateTypeMetadata collection.
ObjectLifecycleStateTypeMetadataRequest	Represents a request to retrieve a single object lifecycle state type in the format of ObjectLifecycleStateTypeMetadata.
ObjectLifecycleStateTypeMetadataRequest.Builder	Creates an instance of ObjectLifecycleStateTypeMetadataRequest.
ObjectLifecycleStateUserActionMetadataService	Provides methods to retrieve metadata about an object lifecycle user action.
ObjectLifecycleStateUserActionService	Provides methods to execute an object lifecycle user action.
ObjectLifecycleUserActionCollectionResponse	Holds an ObjectLifecycleUserActionMetadata collection.
ObjectLifecycleUserActionInputParameterMetadata	Provides methods to retrieve metadata fields for a specific object action's input object.
ObjectLifecycleUserActionInputParameterMetadataRequest	Representation of a request to retrieve metadata about user action input parameters, in the format of ObjectLifecycleUserActionInputParameterMetadata.
ObjectLifecycleUserActionInputParameterMetadataRequest.Builder
ObjectLifecycleUserActionMetadata	Provides methods to retrieve metadata fields for a specific object lifecycle user action.
ObjectLifecycleUserActionMetadataRequest	Representation of a request to retrieve metadata about user actions, in the format of ObjectRecordLifecycleUserActionCollectionResponse.
ObjectLifecycleUserActionMetadataRequest.Builder
ObjectRecordLifecycleMetadata	Provides methods to retrieve object lifecycle metadata fields for a specific object record.
ObjectRecordLifecycleMetadataCollectionRequest	Represents a request to retrieve the object lifecycle metadata fields of multiple object records in the format of ObjectRecordLifecycleMetadata collection.
ObjectRecordLifecycleMetadataCollectionRequest.Builder	Creates an instance of ObjectRecordLifecycleMetadataCollectionRequest.
ObjectRecordLifecycleMetadataCollectionResponse	Holds an ObjectRecordLifecycleMetadata collection.
ObjectRecordLifecycleMetadataRequest	Represents a request to retrieve the object lifecycle metadata fields of a single object record in the format of ObjectRecordLifecycleMetadata.
ObjectRecordLifecycleMetadataRequest.Builder	Creates an instance of ObjectRecordLifecycleMetadataRequest.
ObjectRecordLifecycleUserActionCollectionResponse	Holds an ObjectRecordLifecycleUserActionDetail collection.
ObjectRecordLifecycleUserActionDetail	Represents the metadata associated with a lifecycle user action for a particular record.
ObjectRecordLifecycleUserActionMetadataRequest
ObjectRecordLifecycleUserActionMetadataRequest.Builder
UserActionExecutionOperation<T>	A sequence of instructions that can be chained together, building a user action execution operation that can be executed with UserActionExecutionOperation.execute().
UserActionExecutionOperationError	Represents an error encountered during a UserActionExecutionOperation.
UserActionExecutionRequest	Provides methods to set the parameters necessary to execute a User Action.
UserActionExecutionRequest.Builder
UserActionExecutionResponse	Represents the result of the execution of a user action.