################
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 <https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_annotation_InvocableMethod.htm>`_, 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:

.. code-block:: java

	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:

.. code-block:: java

	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 :doc:`/guides/sending-realtime-records-to-salesforce`

.. note:: In order to accept records like this, the source Adapter on the Link must implement :doc:`/adapter-interfaces/source-adapter-for-raw-data-push`.


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

.. code-block:: java

	/**
	 * 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. Bypasses the Source Adapter and immediately starts processing
	 *
	 * @param linkName Unique identifier for the Link that should be run (Must be a ValenceDataLink__mdt.QualifiedAPIName)
	 * @param records Some RecordInFlight 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<valence.RecordInFlight> 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