Invoke a Function

Salesforce Functions only run when invoked. Functions are not services that are always running and waiting for requests, but rather run on-demand when invoked. When no one is invoking a Function, the Function is in an idle state and elastically scaled down to use minimal system resources.

Functions are invocation agnostic. Salesforce will provide several ways to invoke Functions from your org, but Functions are not tightly coupled to any Salesforce invocation implementation.

Deployed Functions can be invoked from Apex, either synchronously or asynchronously. Functions can also be invoked locally for development and testing purposes.

Local Invocation

You can run and invoke your Function on your local development machine using CLI commands, or via VS Code. Local invocation of a Function should only be used during Function development and testing. Before invoking locally, make sure you've created a scratch org with Functions enabled, as described in Develop Functions Using Scratch Orgs. Also make sure your Functions permission set is configured properly as described in Function Permissions.

Start the Function Locally Using CLI

First change to the directory in your DX project that has your Function code. Then, use the sf run function start command to build a local image for your Function and run it. The following example sets the current directory to the "SendSMS" directory in the project's functions directory, and starts the SendSMS Function locally:

When you see the following output, your Function is ready to receive requests:

Once you’ve started your Function locally, the start command will wait for any local invoke calls, and output any run-time information, such as log messages, to the shell. You can quit the local running Function using Ctrl-C in your terminal window.

Invoke the Locally Running Function Using CLI

To invoke a locally running Function use sf run function, specifying the URI for your local machine, typically localhost plus a port number (default 8080). Also provide a test payload that gets passed to your Function. The following example invokes the Function running on localhost:8080 with a simple payload:

On Windows, you may have to escape any double-quote marks (“) in the payload with a backslash (”\“). For example:

If you need to provide a large payload, you can reference a payload file:

On Windows, remove single quotes:

where payloadFile.json is a local file in the current directory containing JSON-formatted payload data:

If you’ve created and configured a scratch org for your Function DX project, you can have your locally running Function connect to the scratch org by providing the scratch org alias with the -u argument.

The scratch org alias is usually set when you create your scratch org, as described in Develop Functions Using Scratch Orgs.

Start and Invoke the Function Locally Using VS Code

Use the SFDX: Start Function palette command to build and start the Function on your local machine. If you have multiple Functions in your DX project, you can select the Function directory you want to start, and use SFDX: Start Function from the right-click context menu. You can only have one Function running locally at a time. Output from the Function container will print to the Output panel in VS Code.

Once the Function is running, create or open a payload JSON file and in the editor view, click Invoke.

VSCode Send Request Screenshot

This will invoke the currently running function with the payload file content.

If you want to invoke your Function and debug in VS Code, use Debug Invoke. This invokes the Function and attaches the VS Code debugger to the local running Function container. See Test and Validate Function - Debug Using VS Code for details on debugging using VS Code.

Use SFDX: Start Function to stop any currently running Function.

Deployed Function Invocation Using Apex

Functions can be invoked directly from a Salesforce org via Apex. The Function and Project must be deployed to a compute environment connected to the org, as described in Deploying a Function. The org must be enabled for Salesforce Functions development.

You can use Apex to invoke your Functions synchronously or asynchronously. Functions can be invoked from anywhere you can use Apex code. So, for example, you could invoke or asynchronously queue your Function within workflows that use Apex Actions in Flow, Batch Jobs, Apex Triggers, and Apex Platform Event Subscriptions.

Use classes in the functions Apex namespace to find and invoke deployed Functions. Reference documentation for the Apex functions namespace and classes is available in the Apex Reference Guide: Functions Namespace.

Get Function Reference

You'll retrieve a reference to a deployed Function using the name of the Function and the Functions Project that the Function is part of. Using the functions.Function.get() method, pass the Project and Function in a single string of the format “project name.function name”. For example, to retrieve the "GeneratePDF" Function in the "Onboarding" Function Project, use "Onboarding.GeneratePDF".

The following Apex example gets a reference to the AccountFunction deployed as part of the MyProject Project:

Synchronous Invocation

Use Function.invoke(payload) to invoke your Function synchronously. The Function will be invoked with the payload you provide, and response data and results will be returned from the invoke() call in a FunctionInvocation instance.

For synchronous invocations, there is a maximum limit of 2 minutes for your Function to run and complete. If your Function requires more than 2 minutes to complete, consider using asynchronous invocation instead. If you can't use asynchronous invocation, see Limits for other approaches.

The follow example synchronously invokes the accountFunction reference:

Asynchronous Invocation

Invoking a Function directly through Apex is similar to making an Apex callout. If your Function takes longer than 2 minutes to return, the request will time out. To avoid this, consider invoking your Function asynchronously, using the asynchronous Function.invoke(payload, callback) method rather than the Function.invoke(payload) synchronous method. You'll need to provide an Apex callback class that implements functions.FunctionCallback in your call to Function.invoke(payload, callback).

Calling Function.invoke(payload, callback) will queue your Function to be invoked through asynchronous Apex. Once your queued Function is invoked, your Apex callback's handleResponse() method is called with the invocation results. Your method should process the FunctionInvocation results, which might include actions such as modifying org data, sending platform events, or sending custom notifications. If the Function invocation failed, error information is provided in the FunctionInvocation results.

The following example invokes a Function asynchronously and uses a FunctionCallback class to handle the invocation results:

The Apex Callback runs as the user that invoked the Function and runs in system mode.

Invoking a Function asynchronously does not count against asynchronous Apex limits, such as Apex Queueable limits.

To get the status of all pending Functions invoked asynchronously, you can use a query on FunctionInvocationRequest similar to the following:

You can get the status for a specific asynchronous invocation by using the ID returned from FunctionInvocation.getInvocationId() as a filter on FunctionInvocationRequest: