Home

Vault Spark is a message queue system that allows developers to use the Vault Java SDK to send and receive messages from a durable queue. It can be used to allow for loosely coupled, asynchronous integration within a Vault, between different Vaults, or between Vault and an external system. This example use case focuses on using Spark Messaging to initiate the copying of documents from a source Vault to a target Vault and describes an example use case along with sample code that you can use with your Vault to step through the code in the Vault Java SDK Debugger.

Introduction

The vsdk-spark-doc-copy-sample project explains how to use Spark Messaging to send a message from a source Vault to notify a target Vault that a document needs copying. Details of individual documents to be copied are held in the integration transactions record of the source Vault, which are processed within the target Vault using various document copy methods. The project will step through:

• Setting up the necessary Vault to Vault components:
  • Vault Connection records
  • Vault Queues for the inbound and outbound Spark Messages
  • Vault Connection Integrations to organize an integration business process
  • Vault Integration Integration Points to organize full round-trip step in an integration
  • Various Vault components for the sample project
• Sample Code for:
  • Marking a record for copy and notifying the target Vault. When a document's lifecycle state changes to approved, a pending entry is placed in the integration transactions record of the source Vault and a Spark message is sent to the target Vault to notify it that changes have occurred.
  • Retrieving and copying the documents into the target Vault. When the spark message is received it initiates a message processor in the target Vault, which uses HTTP callouts to retrieve details of the pending integration transaction and the subsequent source documents to be copied. The copy of the document is then created in the target Vault, and the integration transactions record is updated so the record isn't reprocessed.

You will need two sandbox Vaults to run through this project.

Business Use Case: Connected Data

A user needs to copy a document from a source Vault to a target Vault. The new document in the target Vault must include some of the document metadata, all document versions, the document rendition from the source Vault, and any document attachments. The document copy process should start automatically when the document lifecycle state changes to Approved using a state change action.

Setup

There are five main steps to setup this project for use.

1. Create and configure Connection records in the source and target Vaults to link them together.
2. Import the Vault Packages (VPKs) to create necessary components.
3. Create and configure the Spark Message Queues.
4. Create and configure Integrations.
5. Create and configure Integration Points.

The project contains separate Vault packages (VPK) in the "deploy-vpk" directory with the necessary Objects, Vault Java SDK code and example document. One is for your source Vault - the Vault where you want to copy documents from - and the second one is for your target Vault - the Vault where you want the documents to be copied to.

Create Connections

The Connection object is used to create records that define connections between different Vaults or between a Vault and an external system.

In this use case, we will create Vault to Vault records to link a source Vault to a target Vault.

Source Vault: Create Vault to Vault Records

1. Log in and navigate to Admin > Connections click Create.

2. Choose the Vault to Vault connection type. Select Continue.

3. Enter Doc Copy Connection in the Name field.

4. Enter vsdk_doc_copy_connection in the API Name field.

5. Select your Vault owner as the Authorized Connection User.

6. Select Save.

7. From the connection record, click on the ellipsis in the top right corner, and select Download Connection file.

   
   • This connection file is uploaded into the target Vault to authorize a connection back to the source Vault.

   

Target Vault: Create Vault to Vault Records

1. Log in and navigate to Admin > Connections and click Create.
2. Choose the Vault to Vault connection type. Select Continue.
3. Enter Doc Copy Connection in the Name field.
4. Enter vsdk_doc_copy_connection in the API Name field.
5. Select your Vault owner as the Authorized Connection User.
6. Click Save.
7. From the Actions menu of the new connection record, select Connect from File
8. At the prompt, select Choose and locate the connection file you downloaded from your source Vault.
9. Click Continue.

Approve the Connections

To activate the connection between your two Vaults you must approve the connection on both Vaults.

1. Log into your Source Vault and navigate to Admin > Connections.
2. Click on your newly created Connection, which should be called Doc Copy Connection.
3. Click on the Complete button in the green is a prompt at the top of the page as shown in the screen shot below.
4. In Review Connection dialog, select the Approve Connection radio button, and click the Complete button.
5. Repeat steps 1 through 5 on your Target Vault.

After a successful upload of the connection file, the connections in both Vaults should have a Lifecycle State of Active, and the Remote Vault Details section should be populated.

The connection between Vaults is now validated and ready for use.

Import Vault Packages

The VPKs need to be deployed to your Vault prior to debugging these use cases.

Download the project

1. Clone or download the sample Maven project vSDK Spark Doc Copy Sample from GitHub.
2. Run through the Getting Started guide to set up your deployment environment.

Source Vault: Deploy the Required Components

1. Navigate to Admin > Settings and click Edit.

2. In the Configuration Management section, ensure that the Allow Inbound Packages checkbox is selected.

3. Navigate to Admin > Deployment > Inbound Packages and click Import.

4. Select the following file:

   Object and code components: <PROJECT_DIRECTORY>\deploy-vpk\source-vault\vsdk-spark-doc-copy-source-obj-components.vpk.

5. From the Actions menu, select Review & Deploy. Vault displays a list of all code components in the package.

6. Review the prompts, then click Next and Finish to deploy the package. You will receive an email when the deployment is complete.

7. Repeat steps 4-7 for the following Vault document component VPK:

   Document components: <PROJECT_DIRECTORY>\deploy-vpk\source-vault\vsdk-spark-doc-copy-source-doc-components.vpk.

Once the packages have been deployed, you will want to review the configuration and understand the normal behavior so you can observe the effects of the sample code. Any warnings in the deployment logs or a status of Blocked can be ignored.

Target Vault: Deploy the Required Code and Components

1. Navigate to Admin > Settings and click Edit.

2. In the Configuration Management section, ensure that the Allow Inbound Packages checkbox is selected.

3. Navigate to Admin > Deployment > Inbound Packages and click Import.

4. Select the following file:

   Object and code components: <PROJECT_DIRECTORY>\deploy-vpk\target-vault\vsdk-spark-doc-copy-target-obj-components.vpk.

5. From the Actions menu, select Review & Deploy. Vault displays a list of all components in the package.

6. Review the prompts, then click Next and Finish to deploy the package. You will receive an email when the deployment is complete.

7. Repeat steps 4-7 for the following Vault document component VPK:

   Document components: <PROJECT_DIRECTORY>\deploy-vpk\target-vault\vsdk-spark-doc-copy-target-doc-components.vpk.

Once the packages have been deployed, you will want to review the configuration and understand the normal behavior so you can observe the effects of the sample code. Any warnings in the deployment logs can be ignored.

Below is a rundown of the included components.

Objects

Source Vault:

• Integration Transaction (integration_transaction__c)

Document Types

Source Vault:

• vSDK Spark Copy Document (vsdk_spark_copy_document__c)

Target Vault:

• vSDK Spark Copy Document (vsdk_spark_copy_document__c)

Document Lifecycles

Source Vault:

• vSDK Spark Copy Doc Lifecycle (vsdk_spark_copy_doc_lifecycle__c)

Target Vault:

• vSDK Spark Copy Doc Lifecycle (vsdk_spark_copy_doc_lifecycle__c)

Picklists

Source Vault:

• Transaction Status (transaction_status__c)

Page Layouts

Source Vault:

• Integration Transaction Detail Page Layout (integration_transaction_detail_page_layo__c)

Code

Source Vault:

• Record Action: com.veeva.Vault.custom.actions.vSdkDocCopyDocumentAction.java

Target Vault:

• Message Processor: com.veeva.vault.custom.processors.vSDKDocCopyMessageProcessor.java
• User Defined Class: com.veeva.vault.custom.udc.vSDKDocCopy
• User Defined Class: com.veeva.vault.custom.udc.vSDKSparkHelper

Create Queues

You must confugure a Queue on each of the target and source Vaults to utilize Spark Messaging functionality. These queues will handle messages that are produced via the Vault Java SDK Message and QueueService.

Target Vault Queue

You must configure the target Vault queue first.

1. In the target Vault, navigate to Admin > Connections > Spark Queues and click Create.
2. Set the following values:
   • Label: vSDK Doc Copy In Queue
   • Name: vsdk_doc_copy_in_queue
   • Queue Type: Inbound
   • Message Processor: com.veeva.vault.custom.processors.vSDKDocCopyMessageProcessor
   • Message Processor User: <Vault Owner>
3. Click Save.
4. On the new Queue, scroll down to the Queue Connections section and click Create.
5. Select the vsdk_doc_copy_connection and click Save.

Source Vault Queue

You must configure the source Vault queue second.

1. In the source Vault, navigate to Admin > Connections > Spark Queues and click Create.
2. Set the following values:
   • Label: vSDK Doc Copy Out Queue
   • Name: vsdk_doc_copy_out_queue
   • Queue Type: Outbound
3. Click Save.
4. On the new Queue, scroll down to the Queue Connections section and click Create.
5. Select the vsdk_doc_copy_connection.
6. For Deliver to Queue, select the vsdk_doc_copy_in_queue.
7. Click Save.

Create Integration

An Integration is a way to organize the business process supported by the Spark integration. It gives non-coders insight into the configuration and goals of an integration. We recommend using a descriptive name that indicates to a non-technical viewer what an integration does.

Source Vault: Create the Document Copies Integration

1. In the source Vault, navigate to Admin > Connections.
2. Select the Connection you created earlier called Doc Copy Connection.
3. Expand the Integrations section and click Create.
4. Set the following values:
   • Name: Doc Copies
   • Integration API Name: document_copies__c
   • Status: Active
5. Click Save.

Target Vault: Create the Document Copies Integration

1. In the target Vault, navigate to Admin > Connections.
2. Select the Connection you created earlier called Doc Copy Connection.
3. Expand the Integrations section and click Create.
4. Set the following values
   • Name: Document Copies
   • Integration API Name: document_copies__c
   • Status: Active
5. Click Save

Create Integration Points

Integration Points are a way to organize a complete round trip of data flows. There are multiple integration points for each integration. Integration points give a non-coder user insight into some of the details of an integration.

Source Vault: Create the Outbound Integration Point

1. In the source Vault, navigate to Admin > Connections.
2. Select the Connection you created earlier called Doc Copy Connection.
3. Expand the Integration section and click on the Doc Copies integration you just created.
4. Expand the Integration Points - Inbound and Integration Point - Outbound sections.
   • Note: There is no Inbound Integration Point configured on the source system. In this demo, data only flows outbound from the source system with no inbound messages.
5. In the Integration Points - Outbound section, click Create.
6. Set the following values:
   • Name: Send Doc Copies
   • Integration Point API Name: send_document_copy__c
   • Description: Send document for copy
   • Status: Active
7. Click Save.

Target Vault

For the Target Vault we will setup Inbound Connections to support the movement of documents from the Source Vault.

Configure Inbound

1. In the target Vault, navigate to Admin > Connections.
2. Select the Connection you created earlier on the source system called Doc Copy Connection.
3. Expand the Integration section and click on the Document Copies integration you just created.
4. Expand the Integration Points - Inbound and Integration Point - Outbound sections.
5. In the Integration Points - Inbound section, click Create.
6. Set the following values:
   • Name: Receive Doc Copies
   • Integration Point API Name: receive_document_copy__c
   • Description: Receive document to copy
   • Status: Active
7. Click Save.

Next Steps

Data Sync

• Run the project provides details of how to run the project.
• Code logic provides a detailed understanding of how the sample components work for document copy.