Invoking Valence

“Invoking Valence” means, “causing Valence to run”, typically programmatically.

Most of the time you will configure Valence Links on a schedule or chain, and let them hum away on their own.

There are other uses cases, such as realtime runs, where you will need to kick off Link runs in a different way. Here are your options.

Process Builder or Flow

Salesforce supports something called Invocable Apex, which allows a bit of Apex code to be an Action within a process or flow. Valence supports this mechanism with two ways you can invoke a Link run:

1. Start a Link run that will fetch its own records

InvocableValencePull (Label=’Run Valence Pull Link’ Description=’Kick off a Valence Link.’)

Accepts a List<Request>, where Request looks like:

global class Request {

        @InvocableVariable(Label='Link Name' Description='The Link to run' Required=true)
        global String linkName;
}

2. Start a Link run with specific records

InvocableValencePush (Label=’Run Valence Push Link’ Description=’Kick off a Valence Link that will process the passed records.’)

Accepts a List<Request>, where Request looks like:

global class Request {

        @InvocableVariable(Label='Link Name' Description='The Link to run' Required=true)
        global String linkName;

        @InvocableVariable(Label='Record ID' Description='A record for the Link to process' Required=true)
        global Id recordId;
}

Apex REST API

An external system that has Salesforce User credentials can call into Valence using the Salesforce REST API to drop off data for Link processing. This is often used in realtime push-style Links where an external system is emitting records to Valence as they are modified or created.

This is done with a HTTPS POST being sent to a unique URL for each Link, which is in the format:

https://<org_base_url>/services/apexrest/valence/link/v1/<link api name>

You can read more about this method in our guide Sending Realtime Records To Salesforce

Note

In order to accept records like this, the source Adapter on the Link must implement SourceAdapterForRawDataPush.

Apex

You can invoke a Link programmatically from Apex a number of different ways using the valence.LinkEngine global class.

/**
 * Attempt to run a Link in this same execution context. This only works for Links that do not perform any callouts, as
 * a SyncEvent record will be created before calling Adapters, and DML before callouts causes an exception.
 *
 * @param linkName Unique identifier for the Link that should be run (Must be a ValenceDataLink__mdt.QualifiedAPIName)
 * @throws LinkException if the Link cannot be found or is not the right type of Link for this method
 */
global static void runLinkSynchronously(String linkName);

/**
 * Attempt to run a Link. This only works for Links that use a Source Adapter that knows how
 * to fetch its own data (a Pull).
 *
 * @param linkName Unique identifier for the Link that should be run (Must be a ValenceDataLink__mdt.QualifiedAPIName)
 * @throws LinkException if the Link cannot be found or is not the right type of Link for this method
 */
global static void runLink(String linkName);

/**
 * Attempt to run a Link. This only works for Links that use a Source Adapter that knows how
 * to fetch its own data (a Pull).
 *
 * This version of the method ignores Valence's normal behavior of using Sync Event timestamps to only fetch deltas.
 *
 * @param linkName Unique identifier for the Link that should be run (Must be a ValenceDataLink__mdt.QualifiedAPIName)
 * @throws LinkException if the Link cannot be found or is not the right type of Link for this method
 */
global static void runFullLink(String linkName);

/**
 * Attempt to immediately run a Link. This method only works for Links that use a Source Adapter that knows
 * how to consume SObject records (a Source Adapter that implements SourceAdapterForSObjectPush).
 *
 * @param linkName Unique identifier for the Link that should be run (Must be a ValenceDataLink__mdt.QualifiedAPIName)
 * @param records Some SObject records that will be fed to the Link for processing
 * @throws LinkException if the Link cannot be found or is not the right type of Link for this method
 */
global static void runLink(String linkName, List<SObject> records);

/**
 * Attempt to immediately run a Link. This method only works for Links that use a Source Adapter that knows
 * how to consume SObject records (a Source Adapter that implements SourceAdapterForRawDataPush).
 *
 * @param linkName Unique identifier for the Link that should be run (Must be a ValenceDataLink__mdt.QualifiedAPIName)
 * @param recordData Some raw data that will be fed to the Link for processing
 * @throws LinkException if the Link cannot be found or is not the right type of Link for this method
 */
global static void runLink(String linkName, String recordData);

Here are some ways you might invoke Valence from Apex:

In an Apex trigger so you can do realtime outbound record flows from Salesforce
In reaction to a user action, such as clicking a button in a custom app in your own interface
As part of an automated process of your own, such as processing job that sends records out to an external system at the end of the job