**Source URL:** https://general.veevavault.dev/vault-sdk/services/lifecycle-services.md # Lifecycle Services The services in the `lifecycle` package provide methods that allow custom code to interact with [object](/vault-sdk/services/lifecycle-services/#Object_Lifecycle_Services) and [document](/vault-sdk/services/lifecycle-services/#Document_Lifecycle_Services) lifecycles. ## Object Lifecycle Services {#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 {#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](https://platform.veevavault.help/en/gr/59885/#user-actions). The `ObjectLifecycleStateUserActionMetadataService` provides methods to retrieve configuration metadata about user actions, while `ObjectLifecycleStateUserActionService` provides methods to execute those actions. ### Retrieving Configuration Metadata About Lifecycle User Actions {#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 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 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()); } ``` ### Retrieving Input Parameter Metadata for User Actions {#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(); ``` ### Executing a Lifecycle User Action {#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 {#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 {#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](https://platform.veevavault.help/en/gr/12339). `DocumentLifecycleStateUserActionMetadataService` provides methods to retrieve configuration metadata about user actions, while `DocumentLifecycleStateUserActionService` provides methods to execute those actions. ### Retrieving Configuration Metadata About Document Lifecycle User Actions {#retrieving-configuration-metadata-about-document-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 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 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()); } ``` ### Retrieving Input Metadata for Document Lifecycle User Actions {#retrieving-input-metadata-for-document-lifecycle-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(); ``` ### Executing a Document Lifecycle User Action {#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(); ``` --- **Previous:** [Record Service & Document Service](/vault-sdk/services/recordservice-documentservice) **Next:** [Workflow Services](/vault-sdk/services/workflow-services)