Salesforce is the most popular, and most powerful, platform for managing your business' data. Whether you use it to help your sales reps manage deals in the pipeline, or your support reps to manage cases, or your marketing team to connect with your target demographic, Salesforce is your single source of truth.

With Meya's Salesforce CRM integration you can:

• Search your Salesforce data using SOQL queries
• Create new contacts from users who interact with the app

Keep reading to learn how to set up the integration.

📘

If you've already set up the Salesforce Cases integration you can skip ahead to the Add the integration section, since the same credentials are used by both integrations.

Find your Salesforce instance base URL

Your instance base URL will look like this: https://INSTANCE.salesforce.com.

🚧

The instance base URL is not necessarily the URL you see in the address bar. The domain in the address bar can be affected by things like a custom My Domain. Keep reading to learn how to find your instance base URL.

To find your instance base URL, open Setup. In the search bar, type company information. Select Company Information from the search results.

In the Organization Detail section, find Instance and make a note of the value. It will start with two letters and end with a few numbers.

Once you have your instance, insert it into the URL like this: http://INSTANCE.salesforce.com. Keep this URL handy since you'll be adding it to the vault at a later step.

Create a connected app

A connected app allows external systems to authenticate against, and interact with, your Salesforce instance in a secure way. In this section, you'll create a connected app that your Meya app can use.

In Salesforce, click the gear icon in the top corner, then click Setup. In the search bar, type app manager. Select App Manager from the search results.

Click the New Connected App button in the top right corner.

Enter a meaningful name for your app, such as Meya. The API name will fill in automatically once you move to another input.

Add an email to the Contact Email field. You can use your own, a support address, or your Salesforce admin's address.

In the API (Enable OAuth Settings) check the Enable OAuth Settings checkbox. In the list of available OAuth scopes, choose:

• Access and manage your data (api)
• Perform requests on your behalf at any time (refresh_token, offline_access)

Leave the other settings as-is. Your page will look something like this:

Click Save to create the app. You'll be redirected to the connected app's detail page.

🚧

If you have login IP ranges enabled for your app, you will also need to change the IP Relaxation setting of the connected app to "Relax IP restrictions":

Retrieve the client key and secret

In Salesforce, connected apps with OAuth enabled will have a consumer key and consumer secret. These are also sometimes referred to as a client key and client secret.

In the API (Enable OAuth Settings) section of your connected app, copy the Consumer Key and Consumer Secret since you'll need those in a later step.

Update the vault

Now that we have all of our secrets, it's time to add them to your app's vault.

In your app's root folder, open vault.yaml and add this code to the bottom:

salesforce.instance_base_url: https://your_salesforce_instance.salesforce.com
salesforce.client_id: xxx
salesforce.client_secret: xxx
salesforce.username: xxx
salesforce.password: xxx

🚧

Remember not put actual secrets in vault.yaml, since it's committed to version control. The actual values should go in vault.secret.yaml, as described below, since it is not committed to version control.

Now open vault.secret.yaml and add this code to the bottom:

salesforce.instance_base_url: https://your_salesforce_instance.salesforce.com
salesforce.client_id: CLIENT_ID
salesforce.client_secret: CLIENT_SECRET
salesforce.username: USERNAME
salesforce.password: PASSWORD

Replace the values to the actual values.

📘

You may want to create a dedicated Salesforce user whose credentials will be used here. Alternatively, you can use the credentials of an existing user as long as they're okay with your developers potentially seeing them (depending on their Meya Team permissions).

Save the files and upload the secrets to your remote vault using this command in your terminal:

meya vault upload --file vault.secret.yaml

Add the integration

Now that your secrets are in the vault, you can reference them in the integration file.

In your app's integration folder, create a subfolder called salesforce. Inside that folder, create a file called salesforce.yaml and copy this code into it:

type: meya.salesforce.integration
instance_base_url: (@ vault.salesforce.instance_base_url)
client_id: (@ vault.salesforce.client_id)
client_secret: (@ vault.salesforce.client_secret)
username: (@ vault.salesforce.username)
password: (@ vault.salesforce.password)

Save the file.

Add a flow

The Salesforce Cases integration comes with components that allow your app to create a case, update a case, and add a comment to a case. There are also a few non-case-specific components like contact.create and query you can use as well. Let's add some flows to your app to demonstrate how they work.

In your app's flow folder, create a folder called salesforce. Inside, create a file called query.yaml and copy this code into it:

triggers:
  - regex: ^salesforce_query.*$
    action:
      jump: (@ flow.result )

steps:
  - (salesforce_query_user_by_email)
  - ask: What's the user's email?
    expect: email_address
  - flow_set: search_query

  - type: meya.salesforce.component.query
    soql_query: SELECT name, id from User WHERE email = '(@ flow.search_query)'
    integration: integration.salesforce.salesforce

  - flow_set: search_result
  - jump: check_result

  - (salesforce_query_contact_by_email)
  - ask: What's the contact's email?
    expect: email_address
  - flow_set: search_query

  - type: meya.salesforce.component.query
    soql_query: SELECT name, email, id from Contact WHERE email = '(@ flow.search_query)'
    integration: integration.salesforce.salesforce
  - flow_set: search_result
  - jump: check_result

  - (check_result)
  - if: (@ flow.search_result.records)
    then:
      jump: render user id
    else: next

  - say: No results found for '(@ flow.search_query)'
  - end

  - (render user id)
  - say: User ID (@ flow.search_result.records[0].Id )

📘

SOQL

Lines 12 to 14: Notice how the query component supports SOQL queries? This is an easy, yet powerful, way to retrieve data from Salesforce.

Save the file and upload it to the Grid by running these commands in your terminal:

meya format
meya push

Test it out

We're ready to test the flow!

Open your app's simulator and type salesforce_query_user_by_email. Enter your email address. If there is a Salesforce user in your Salesforce instance with that email address, you should see your user's ID appear.

👍

Great! You've successfully added the Salesforce CRM integration to your app and can now explore your Salesforce data from your Meya app.

Suggested reading

📘

• meya.salesforce.component.contact.create
• meya.salesforce.component.query