Skip to content
kevinn-veeva edited this page Mar 2, 2019 · 45 revisions

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 page describes some example use cases 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-v2v-sample project covers a Vault-to-Vault integration that uses Spark Messaging to propagate messages from one vault (source) to another vault (target). The project will step through:

  • Setup of the necessary Vault to Vault components
    • Vault Connection records
    • Vault Queues for the inbound and outbound Spark Messages
    • Various Vault components for the sample project
  • Sample Code for:
    • Basic Message without a HTTP Callback - sends a Spark Message from a Bike Store record in the source vault that creates a blank Purchase Order record in the target vault.
    • Message with HTTP Callback - approve a Bike Store record in the source vault and then send a message from a source vault to a target vault. This initiates an HTTP Callout in the target vault using the Vault API to query for more information the source vault.
    • Create a Crosslink Document - send a Spark Message with document details from a source vault to a target vault. This initiates a local HTTP Callout in the target vault that creates a crosslink document against the document in the source vault.

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

Business Use Cases

Data Sync

A user needs to sync data from one source vault to another target vault. The data sync should only be synced when the object record enters certain states.

For an object, they want this to happen in two phases:

  • The pending state only creates a placeholder record in the target vault that is waiting for approval.
  • The approved state should then populate certain fields in the target vault based on values from the source vault.

The user needs to be able to tell if a data sync is successful from the source and target vault through the use of a Integration Status field.

Document Crosslink

A user needs to create CrossLink documents in a target vault when a document is created in a source vault. They want to be able to perform the crosslinking from the source target without having to log in to the target vault and creating the crosslink manually there.

The business administrators want to have this ability available as a custom document user action.

Setup

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

  1. Create Connection records in the source and target vaults that link them together.
  2. Import the vault packages to create necessary components.
  3. Create the Spark Message Queues.

The project contains separate vault packages (VPK) in the "deploy-vpk" directory with the necessary Objects and Vault Java SDK code. One is for your source vault - the vault where you want to send messages from - and the second one is for your target vault - the vault where you want the messages to be delivered.

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.

First, in the source vault

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

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

  3. Enter vSDK V2V Connection in the Name field.

  4. Enter vsdk_v2v_connection in the API Name field.

  5. Enter your target vault's ID in the Remote Vault Id field.

  6. Select your vault owner as the Authorized Connection User.

  7. Select Save.

  8. From the Actions menu of the new connection record, select Download Connection File

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

    image

Next, in the target vault

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

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

  3. Enter vSDK V2V Connection in the Name field.

  4. Enter vsdk_v2v_connection in the API Name field.

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

  6. Select Save.

  7. From the Actions menu of the new connection record, select Connect from File

    image

  8. At the prompt, select Choose and locate the connection file you downloaded from your source vault.

  9. Select Continue.

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.

First, you need to download the project

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

Target Vault - deploy the required code and components

  1. In the target vault, log in and navigate to Admin > Deployment > Inbound Packages and click Import.

  2. Select the following file:

    Object components and Message Processor code: <PROJECT_DIRECTORY>\deploy-vpk\target-vault\vsdk-v2v-target-object-components\vsdk-v2v-target-object-components.vpk

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

  4. Review the prompts to deploy the package. You will receive an email when the deployment is complete.

  5. Repeat steps 1-4 for one of the following vault document component VPKs. This should match your vault type:

    Base Vault components: <PROJECT_DIRECTORY>\deploy-vpk\target-vault\vsdk-v2v-target-document-components\Base_vsdk-v2v-document-components.vpk

    Quality Vault components: <PROJECT_DIRECTORY>\deploy-vpk\target-vault\vsdk-v2v-target-document-components\Quality_vsdk-v2v-document-components.vpk

    Multichannel Vault components: <PROJECT_DIRECTORY>\deploy-vpk\target-vault\vsdk-v2v-target-document-components\Multichannel_vsdk-v2v-document-components.vpk

    Clinical Vault components: <PROJECT_DIRECTORY>\deploy-vpk\target-vault\vsdk-v2v-target-document-components\Clinical_vsdk-v2v-document-components.vpk

    RIM Vault components: <PROJECT_DIRECTORY>\deploy-vpk\target-vault\vsdk-v2v-target-document-components\RIM_vsdk-v2v-document-components.vpk

Source vault - deploy the required components

  1. In the source vault, log in and navigate to Admin > Deployment > Inbound Packages and click Import.

  2. Select the following file:

    Document action code: <PROJECT_DIRECTORY>\deploy-vpk\source-vault\vsdk-v2v-source-code\vsdk-v2v-source-code.vpk.

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

  4. Review the prompts to deploy the package. You will receive an email when the deployment is complete.

  5. Repeat steps 1-4 for the vault object component VPK:

    Object components and trigger code: <PROJECT_DIRECTORY>\deploy-vpk\source-vault\vsdk-v2v-source-object-components\vsdk-v2v-source-object-components.vpk

  6. Repeat steps 1-4 for one of the following vault document components VPKs. This should match your vault type:

    Base Vault components: <PROJECT_DIRECTORY>\deploy-vpk\source-vault\vsdk-v2v-source-document-components\Base_vsdk-v2v-document-components.vpk

    Quality Vault components: <PROJECT_DIRECTORY>\deploy-vpk\source-vault\vsdk-v2v-source-document-components\Quality_vsdk-v2v-document-components.vpk

    Multichannel Vault components: <PROJECT_DIRECTORY>\deploy-vpk\source-vault\vsdk-v2v-source-document-components\Multichannel_vsdk-v2v-document-components.vpk

    Clinical Vault components: <PROJECT_DIRECTORY>\deploy-vpk\source-vault\vsdk-v2v-source-document-components\Clinical_vsdk-v2v-document-components.vpk

    RIM Vault components: <PROJECT_DIRECTORY>\deploy-vpk\source-vault\vsdk-v2v-source-document-components\RIM_vsdk-v2v-document-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.

Below is a rundown of the included components.

Objects
  • Bike Store (vsdk_bike_store__c)
  • Bike Store User (vsdk_bike_store_user__c)
  • Purchase Order (vsdk_purchase_order__c)
Document Types
  • vSDK Document
Document Fields
  • vSDK Integration Status (vsdk_integration_status__c)

Picklists

  • vSDK Models (vsdk_models__c)
  • vSDK Integration Status (vsdk_integration_status__c)
Lifecycles
  • Bike Store Lifecycle
  • Purchase Order Lifecycle
  • Document Lifecycle
Workflows
  • Bike Store Workflow
  • Purchase Order Worfklow
Code

Source Vault:

  • Bike Store Trigger: com.veeva.vault.custom.triggers.vSDKVaultToVaultTriggerAll.java
  • vSDK Document Action: com.veeva.vault.custom.actions.vSDKCrosslinkDocumentAction.java

Target Vault:

  • Message Processor: com.veeva.vault.custom.processors.vSDKMessageProcessor.java

Create Queues

A Queue on each of the target and source vaults needs to be configured to utilize the Spark messaging functionality. These queues will handle messages that are produced via the Vault Java SDK Message and QueueService.

Target Vault Queue

  1. The target vault queue needs to be configured first.
  2. In the target vault, log in and navigate to Admin > Configuration > Queue Setup > Queues and click Create.
  3. Set the following values:
    • Label: vSDK V2V In Queue
    • Name: vsdk_v2v_in_queue
    • Queue Type: Inbound
    • Message Processor: com.veeva.vault.custom.processors.vSDKMessageProcessor
    • Message Processor User: your Vault Owner user.
  4. Click Save
  5. On the new Queue, scroll down to the Queue Connections section and click Create.
  6. Select the vsdk_v2v_connection and click Save.

Source Vault Queue

  1. The source vault queue needs to be configured second.
  2. In the source vault, log in and navigate to Admin > Configuration > Queue Setup > Queues and click Create.
  3. Set the following values:
    • Label: vSDK V2V Out Queue
    • Name: vsdk_v2v_out_queue
    • Queue Type: Outbound
  4. Click Save
  5. On the new Queue, scroll down to the Queue Connections section and click Create.
  6. Select the vsdk_v2v_connection.
  7. For Deliver to Queue, select the vsdk_v2v_in_queue__c.
  8. 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 data sync.

CrossLinks

  • Run the project provides details of how to run the project.
  • Code logic provides a detailed understanding of how the sample components work for cross-links.
You can’t perform that action at this time.