Connecting Y Meadows and Salesforce

Configuring Salesforce

Y Meadows communicates with Salesforce using Salesforce’s REST API. To do so, you need to create a “connected application” for Y Meadows in Salesforce. Salesforce uses OAuth to allow 3rd party applications such as Y Meadows to authenticate with it. There are several possible OAuth flows. We use the “OAuth 2.0 JWT Bearer Flow for Server-to-Server Integration“. This allow Y Meadows servers to talk to Salesforce servers constantly, even when either application is not actively in use by anyone.

Step 1 - Create a certificate

Salesforce uses certificates to validate the identity of the Y Meadows application. Create a new certificate to use for this purpose. You can do this using a tool called openssl.

Windows users should follow instructions here: https://knowledge.digicert.com/solution/SO27347.html to install OpenSSL. Step 3 in those instructions involve creating a certificate. Use the settings below to create a certificate rather than the ones in the article.

macOS users should already have openssl installed. Linux users may need to install openssl using their package manager.

Use this command to create a new certificate.

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem

It will prompt you for the following:

• country code (e.g. US for the United States)

• state or province name (e.g. California)

• locality name (e.g. Los Angeles)

• organization name (use Y Meadows)

• organizational unit (use customer name, e.g. Acme Corp)

• common name (e.g. acmecorp.ymeadows.com)

• email address (use your own email address)

It will produce two files that will be needed later. A certificate file, certificate.pem, and a private key, key.pem.

This certificate has nothing to do with your web server's secure certificate. Generate a new certificate like this, specifically and only for the Y Meadows to Salesforce connection.

Step 2 - Create a new Salesforce Connected App

Go to Setup > Create > Apps or Setup > Apps > App Manager > New Connected App.

For Connected App Name enter Y Meadows.

Accept the default for API Name.

For Contact Email enter your own email address.

Check Enable OAuth Settings.

For callback URL use https://your-company.ymeadows.com replacing that with your actual Y Meadows URL.

Check “Use digital signatures”.

Clickon the “Choose File” button to upload the certificate.pem file that you created in Step 1.

Grant “Selected OAuth Scopes”: choose

• "Manage user data via APIS (api)"

• "Perform requests on your behalf at any time (refresh_token, offline_access)".

This is done by selecting those scopes from the list on the left and clicking the “Add” button. They then appear on the Selected OAuth Scopes list of the right.

Save your new app.

The resulting page will display a consumer key you'll need to complete your Y Meadows configuration.

Save this key somewhere. It will be need later in the process, or will need to be sent to the people configuring the Y Meadows application.

Other Salesforce Considerations

• Make sure that this user has create/update access to:

  • The case types that you want Y Meadows to act on

  • All the fields that are going to be updated by the Y Meadows system

• The user must have a regular user’s license. The Salesforce Integration user license will not work.

Step 3 - Manage OAuth Policies

From the app page click “Manage”.

From the manage page click “Edit Policies”.

From “Permitted users” select "Admin approved users are pre-authorized".

Save OAuth policies.

Step 4 - Add approved profiles

From the manage page scroll down to "Profiles" and click "Manage Profiles"

On the "Application Profile Assignment" page, choose the appropriate profile for the user(s) who will need access. Typically this means sufficient access to get and updates Cases. The profile also must have read access to the Contacts object (this is used to get the name and email address of the creator of the Case). You must pick a profile that exactly matches the profile of the user. This can be found under Settings > Users.

Specifically, in addition to access rights for cases it is important to grant the application user the Create permission on the PushTopic standard object. (from the profile go to Object Settings > Push Topics : then ensure that Create is checked) This action should be taken on the Profile assigned to the user.

Save profile assignments.

All the actions that Y Meadows takes will be associated with some user in Salesforce. Typically a new user is created for Y Meadows to use. The username for that use will be needed in a later step. Also, the user needs to be added to the same profiles as the application in order for permissions to work correctly.

Salesforce introduced a new type of license for users called the Salesforce Integration users license. This license costs less and is meant for integration use cases like our own.

Unfortunately, in our experience users of this license type cannot update cases or view list views. Error messages are reported when this is tried. This limitation is not currently mentioned in their documentation.

A regular user’s license must be used at this time.

Step 5 - (optional - if “all email messages” need to be processed)

Update Salesforce configuration to enable change events

• Go to Settings -> Search for Change Data Capture and open it

• Move Email Message (EmailMessage) entity to Selected Entities table

• Click Save.

• This should enable Change Events for EmailMessage objects

the permissions required to read all email is very broad. You can not ask for only read-all permission on the email object, you have to get full read-all access to the entire Salesforce account. Some clients may not be comfortable with this.

Step 6 - (optional - if “all email messages” need to be processed)

Grant View All Data permission to Salesforce user.

There is no option to grant read-all permission on the email object only, so user need to have View All Data permission.

1. Go to Permissions Sets setup page in Administration section and click on New button

2. Enter View All Data - YMeadows as label and click Save

3. Click on System Permissions in System section and click Edit button

4. Scroll to View All Data permission and enable the checkbox next to it

5. Click Save button and then Save again in confirmation dialog

6. Go to Users setup page in Administration section and click on user name for the user that you want to grant access

7. Click on Edit Assignments in Permission Set Assignments section

8. Move View All Data - YMeadows to Enabled Permission Sets table

9. Click Save

As an option, you can edit existing permission set and enable View All Data permission for it. To do this - edit existing permission set instead of creating new one on step #1 and skip step #2

Connecting Y Meadows

If different people are configuring Y Meadows then they will need the following information from the Salesforce process to complete these tasks

• The Consumer Key generated in Step 2

• The key.pem file that was generated in Step 1

The other file is private and should not be shared - keep the certificate.pem file secure

Step 7 - Setup in Y Meadows

On the Y Meadows main screen, click Components and then Connections. Click the Add Connection button. Click Salesforce.

Choose a name for this Salesforce instance (e.g. Acme Corp. Salesforce - Production).

Write a description (e.g. The Production CRM and ERP Salesforce instance for Acme Corp.).

Set one year from the day that you created the certificate in step 1 as the expiration date.

Set the “on/off” toggle to “on” to enable the connection.

For user, provide a username that we can use for authentication. The user must have the profile(s) assigned in Step 4.

For login domain, use https://login.salesforce.com (unless you use a different domain). For sandbox accounts you will likely need to use https://test.salesforce.com

For consumer key, use the key you saved from Step 2.

For private key, copy and paste the contents of the key.pem file that you produced in Step 1. Note that you need to include the first and last lines - the value pasted into the UI should start with -----BEGIN PRIVATE KEY----- and end with -----END PRIVATE KEY-----

Click “Save”.

Common Problems During Connection Creation

If there is an error message when trying to save the connection in Y Meadows here are the most common reasons for a failure.

• If you are working with a Saleforce Sandbox make sure that the Login Domain is set to https://test.salesforce.com for production Salesforce accounts use https://login.salesforce.com

• Make sure that the instructions for OAuth Polices are followed and under step 3: “Permitted users” select "Admin approved users are pre-authorized".

• Make sure that the user field is using the email address of the user if it is different than that login name

• Make sure that the user field is for a user that has the same profile as the application (see section 4 above for details)

• If all of the above are set up correctly then you need to check to see if API Access Controls are enabled in Salesforce