Salesforce: Native

Integrate Lob with Salesforce using External Services

Integration Overview

Lob is pleased to offer a direct integration within Salesforce, the world’s #1 CRM. With an integration via External Services, any Salesforce user can send automated direct mail, easily and at scale.

External Services in Salesforce allow you to connect your Salesforce org to an external API. Using declarative tools and OpenAPI specifications to describe the external API functionality, External Services automatically creates invocable actions within Salesforce.

Set up the integration

First things first!

1. Download this JSON file (Lob OpenAPI specs) to be used in Step 2.

266KB

Lob Openapi.json

Step 1: Set up a Named Credential

1. First, create a new legacy credential for Lob.com in Salesforce.

2. Give it a label, a name, and set the URL field to https://api.lob.com/

3. Under Authentication, set the identity type to Named Principle, and set the authentication protocol to Password Authentication. In the username field, enter your test or live Lob API key. For the password field, copy and paste an empty character from a website like https://emptycharacter.com/.

4. Under Callout Options, there are no changes needed to the default selections.

5. Save the Named Credential.

Step 2: Create an External Service

1. Next, go to the External Services page and create a new External Service from API specification.

2. Fill in an External Service Name, an optional Description, then select "Complete JSON" for Service Schema, and select the Named Credential you just created.

3. In the JSON field, paste the entirety of the Lob OpenAPI specs you downloaded.

4. Click Save and Next. This will bring up a list of operations that you can do that were imported from those Lob OpenAPI specs.

Step 3: Use External Services in a Flow

In this step, we will set up the trigger and corresponding flow; in this example, when a lead is updated in SF, send a postcard from Lob.

Although this documentation uses a postcard flow as an example, you can still follow along for letter and self-mailer creation. (Swap in "letter" or "self-mailer" where you see "postcard" if using those form factors.)

An example SF flow. Note the names and order of the nodes.

1. Create a new Flow Trigger explorer and set it as an Actions and Related Records type.

2. Choose the object field and configure it for when the record is created or updated. (Ensure that Actions and Related Records is selected.)

3. Add a Scheduled Path called "zero hour delay" and set it to 0 hours after the record is created.

4. Next, create a new resource called "postcard_payload" with the data type as Apex defined and set it to postcard editable.

5. Use the Assignment node to map the required fields for creating a mail piece in Lob.

6. Map merge variables (optional)

If you plan to send creatives as HTML templates, you'll need to map out merge variables. One of the limitations of this integration within Salesforce is in how merge_variables are named. You'll notice that within the <mailpiece>_payload.merge_variables field that there are parameters variable1 - variable10 listed. This is because there is no way to name merge variables dynamically within External Services for Salesforce. So to work around it, any HTML templates used with Salesforce can only have merge variables named the same way, variable1 - variable10. The values of these can then be set accordingly within the Assignment action.

7. Back in the Flow, add an Action node to send a mailpiece creation request to Lob's API using the External Service you created earlier.

8. Map the "postcard_payload" resource to the "body" field in the Action.

9. Save and activate the flow. (You can debug it by selecting a test record and pressing the Debug button.)

Pro tip: Add a Fault Path for the action in case the SalesForce flow (not Lob API) fails at this step.

Retrieving data back from Lob

From the mail execution action, there was a resource created called Outputs from send_<mailpiece>. There are three subfields; this data can be used within the flow to map information back into records.

• 200: the body of the successful request - this includes all data returned in the Lob API response, including "id," recipient information, "URL," "send_date" and so forth

• default Exception: if the mailpiece was unsuccessful, including the error message and code

• responseCode: the status code of the API request made to Lob, which is useful for making decision trees

Evaluating the response

Although you have successfully integrated and know where to retrieve output data, it's important to evaluate your responses. It's the difference between knowing whether your request to create a mailpiece was successful or not!

We can see this detail above in the image of a sample Salesforce flow, where we use the "Decision" action to evaluate if the mailpiece was sent.

1. You can edit the Decision:

2. Now, you have two forked paths:

• success - your mailpiece request was successfully processed

• Default Outcome - your mailpiece request failed (for example, because the address passed was undeliverable)

3. Now, you can add actions to the success path to act on the data you received back from the successful send (Outputs from send_postcard -> 200), or you can add actions to the Default Outcome path and perhaps notify an admin of the reason why the mailpiece request was denied (Outputs from send_postcard -> defaultExc -> error -> message )

Congratulations! You've successfully integrated Lob.com's API with Salesforce using External Services.

Monitoring computing resources

There are a number of computing resources that need to be monitored for SalesForce activities in order to ensure uninterrupted operations, Flows included!

These computing resources include:

1. CPU Time: There is a limit on how much CPU time can be consumed during a single transaction (e.g., 10 seconds). When your flow or other processes exceed this limit, you'll get a CPU time limit exceeded error.

2. SOQL Queries: Salesforce imposes a limit on the number of SOQL (Salesforce Object Query Language) queries that can be executed per transaction.

3. DML Operations: There's also a limit on the number of DML (Data Manipulation Language) operations like INSERT, UPDATE, DELETE etc. that can be performed per transaction.

4. Heap Size: This is essentially the limit on the memory storage space used by variables, objects, etc., during a single transaction.

5. Callouts: These are HTTP requests to external services. There are limits on the number of callouts that can be made.

6. Elements: For flows specifically, there are limits on how many elements (like assignments, decisions, loops, etc.) you can have in a single flow.

If a flow exceeds a hard limit (like CPU time), it will be terminated immediately, and an error will be thrown. This can disrupt the business process that the flow was designed to manage. To manage these limitations, Salesforce administrators and developers have to keep a close eye on resource consumption and optimize flows and other customizations accordingly. Using tools like Salesforce Health Check can help you monitor your organization’s performance and stay within limits.

Need support? You can reach us at [e-mail] or submit a request.