Skip to main content

Setting Up The Salesforce Lambdas Manually

Below are manual setup instructions for the Salesforce Lambdas.

Salesforce Lambda Prerequisites

Consider the following prerequisites before you install the Lambda package.

Determine your production Environment

In your installation notes, enter the value for "Production Environment" as "true" or "false", depending on whether the Salesforce environment that you are deploying the package into is a production or a sandbox. For Production, enter "true". For Sandbox enter "false".

Determine your Consumer Key and Secret

To leverage the full potential of the integration, Salesforce data needs to be accessed from AWS environment. The AWS Serverless package comes with a set of pre-built queries to lookup, update and create Salesforce objects within Amazon Connect Contact Flows, in form of AWS Lambda functions.

The Lambda function access Salesforce using the Salesforce REST API. To get access to the environment, a Connected App must be configured with OAuth settings enabled.

  1. Log in to Salesforce

  2. Navigate to Setup > Create > Apps

  1. Click on the "New" button for the Connected Apps at the bottom of the page

  2. In the following form, fill out the Connected App Name, API Name and Contact Email with values of your choice. We recommend "Amazon Connect Integration" as the Connected App Name and the default value for the API name.

  1. Select the checkbox next to "Enable OAuth Settings" as shown below.
  1. Set the Callback URL to your domain url. Find the domain at Setup -> My Domain.
  1. Ensure Selected OAuth Scopes has the following values selected:

a. Access the identity URL service (id, profile, email, address, phone)

b. Manage user data via APIs (api)

  1. Select the checkbox "Require Secret for Web Server Flow", and the checkbox "Require Secret For Refresh Token Flow"
  1. Click "Save" at the bottom of the screen.

  2. Click "Continue" on the next screen

  1. Once the app has been created, on the app's detail screen, please copy the "Consumer Key" value to your installation notes
  1. Select "Click to reveal" next to Consumer Secret and record this value to "Consumer Secret" in your installation notes.

  2. Click "Manage" at the top of the page

  1. On the page that appears, click "Edit Policies"

  2. Set "Permitted Users" to "Admin approved users are pre-authorizes"

  1. Click "OK" on the pop-up dialog:
  1. Set "IP Relaxation" to "Relax IP restrictions"
  1. Click "Save"

Determine your Username, Password and Security Token

The authentication of the Lambda Functions requires valid user credentials. It is a common practice to create an API user account for this purpose.

  1. Log in to Salesforce

  2. Navigate to Setup > Manage Users > Profiles

  3. Click "New Profile"

  4. Enter the Profile Name (i.e. "API Only")

  5. Select the existing profile to clone (The integration user\'s access to just those objects required for the integration)

NOTE: You\'re advised to use a full Salesforce License for the user to be able to set the below permissions and have full access to avoid any other errors.

  1. Click "Save". A New Profile is created:
  1. Once the new profile page opens, select the System Permissions button
  1. If the Lightning Experience User checkbox is selected, clear it
  1. Save the system permissions, then go back to Profile Overview

  2. Select the Password Policies link, click edit

  1. Set User password expire in to Never expires NOTE: Failure to this may lead to production outages.
  1. Select Save

  2. Navigate to Setup > Manage Apps > Connected Apps

  3. Select the app you have created in the previous step (i.e. Amazon Connect Integration)

  1. Click "Manage Profiles"
  1. Ensure the "API Only" profile is selected:
  1. Click "Save" at the bottom of the page

  2. Navigate to Setup > Manage Users > Users

  3. Click "New User"

  1. Set necessary fields: Last Name, Alias, Email, Username, Nickname
  1. On the right-hand side, set the User License and Profile
  1. Click "Save"

  2. In Quick Find, search for "Permission Sets". Select the AC_Administrator permission set.

  1. Select Manage Assignments. Add the apiuser you just created to the permission set.

  2. A confirmation email will be sent, with an activation link. Click the link to activate your user.

Change (set) a password for apiuser (Considered a strong that contains at least 20 random characters):

  1. Click "Change Password"

  2. Access the apiuser personal settings by selecting the username in the top right corner, then "My Settings".

  1. Type "Security Token" in the Quick Find box and click "Reset My Security Token".
  1. Your security token will be emailed to you
  1. Copy the security token from the email in to your installation notes for the "Access Token" value.

Allowing the API user to authenticate using password

The api user created above authenticates using username-password flow in Salesforce. This flow needs to be unblocked and to do that, go to Setup and in the Quick Find box, search for OAuth and OpenID Connect Settings. After that, make sure that the toggles for Allow OAuth Username-Password Flows and Allow OAuth User-Agent Flows are turned ON, as shown in below image.

Store Salesforce credentials in AWS Secrets Manager

To ensure that your Salesforce credentials are secure, the Lambdas require that the credentials are stored in AWS Secrets Manager. AWS Secrets Manager is a highly secure service that helps you store and retrieve secrets.

  1. In a new browser tab, login to the AWS console

  2. Make sure you are in the same region as your Amazon Connect instance. You can set the region by expanding the region selector in the upper right and choosing the region

  1. Navigate to the Secrets Manager console

  2. Select Secrets

  3. Select Store a new secret

  4. Select Other types of secrets

  5. Make sure Secret key/value is selected

  6. Enter key value pairs that match the following:

    a. Key: Password, Value: the password for the API user that you configured in the previous section

    b. Key: ConsumerKey, Value: the Consumer Key for the Connected App you created in the previous section

    c. Key: ConsumerSecret, Value: the Consumer Secret for the Connected App you created in the previous section

    d. Key: AccessToken, Value: this is the access token for the API user that you configured in the previous section

  7. For the encryption key, click "Add new key"

  8. Select Create Key

  9. Make sure key type is set to symmetric

  10. Give your key an alias, like SalesforceCredentialsSecretsManagerKey

  11. Click Next

  12. Select administrators you want to have access permission to change the key policy. Make sure you are being as restrictive as possible

  13. Click Next

  14. Select the users and roles you want to have access to the Salesforce credentials in Secrets Manager. Make sure you are being as restrictive as possible

  15. Click Next

  16. Click Finish

  17. Navigate back to the Secrets Manager setup tab

  18. Select the key you just created

  1. Click Next

  2. Give your secret a name, like SalesforceCredentials

  3. Click Next

  4. Make sure automatic rotation is disabled.

  5. Click Next

  6. Click Store

  7. Select the secret you just created, and copy the Secret ARN

  1. You should now have all of the information you need to install the package

Install the Amazon Connect Salesforce Lambda package

Compatibility Table

The following table instructs users on the best CTI Adapter version to use with the corresponding lambda version. If a minor version for the CTI Adapter is not listed (ex. v5.21.1), it will be grouped with with its major version unless otherwise specified

CTI Adapter VersionLambda Version
v5.22v5.22
v5.21v5.19 - v5.19.7
v5.20v5.19 - v5.19.7
v5.19v5.19 - v5.19.7
v5.18v5.18
v5.17v5.17
v5.16v5.16
v5.15v5.15
v5.14v5.14
v5.13v5.13
v5.12v5.11 - v5.12
v5.11v5.11 - v5.12
v5.10v5.10
v5.9v5.9
v5.7v5.7 - v5.8
v5.6v5.7 - v5.8

Instructions

  1. Login into your AWS Account

  2. Navigate AWS Serverless Application Repository (https://aws.amazon.com/serverless/serverlessrepo/)

  1. Click on the Search (magnifying glass) and type in Amazon Connect Salesforce.
  1. Select AmazonConnectSalesForceLambdas and click "Deploy"
  1. Fill in all Salesforce related fields in "Configure application parameters".\ All values should be available in your installation notes:
  1. The Lambda package includes additional features which can be enabled or disabled, based on particular use-case:

    1. Application name: You can accept the default here or change it as desired

    2. AmazonConnectInstanceId: You Amazon Connect Instance Id. Only required if you enable real time reporting

    3. CTRKinesisARN: This is the ARN for the Kinesis stream that was configured for Contact Trace Record streaming in Amazon Connect. This is the complete ARN. Amazon Kinesis Firehose is not supported.

    4. ConnectReportingS3BucketName: This is the name of the S3 bucket used to store exported reports for your Amazon Connect instance. This is ONLY the bucket name, no sub-folders or suffixes

    5. HistoricalReportingImportEnabled: true | false - if set to true, the package will include a feature to import Amazon Connect Queue and Agent Historical Metrics into your Salesforce Org. This feature requires you to provide ConnectReportingS3BucketName

    6. LambdaLoggingLevel: DEBUG | INFO | WARNING | ERROR | CRITICAL - Logging level for Lambda functions

    7. PrivateVpcEnabled: Set to true if functions should be deployed to a private VPC. Set VpcSecurityGroupList and VpcSubnetList if this is set to true.

    8. RealtimeReportingImportEnabled: true | false - if set to true, the package will include a feature to publish Amazon Connect Queue Metrics into your Salesforce Org. This feature requires you to provide AmazonConnectInstanceId

    9. SalesforceAdapterNamespace: This is the namespace for CTI Adapter managed package. The default value is amazonconnect. If a non-managed package is used, leave this field blank.

    10. SalesforceCredentialsKMSKeyARN: This is the ARN for KMS customer managed key that you created in the previous section.

    11. SalesforceCredentialsSecretsManagerARN: This is the ARN for the Secrets Manager Secret that you created in the previous section.

    12. SalesforceHost: The full domain for your salesforce org. For example https://mydevorg-dev-ed.my.salesforce.com. Please make sure that the host starts with https, and that the url ends with .my.salesforce.com. This url can be found in Setup -> My Domain.

    13. SalesforceProduction: true | false - True for Production Environment, False for Sandbox

    14. SalesforceUsername: The username for the API user that you configured in the previous section. Salesforce usernames are in the form of an email address.

    15. SalesforceVersion: This is the Salesforce.com API version that you noted in the previous section. The pattern of this value is vXX.X.

    16. TranscribeOutputS3BucketName: This is the S3 bucket where Amazon Transcribe stores the output. Typically, this is the same bucket that call recordings are stored in, so you can use the same value as found in ConnectRecordingS3BucketName. Not required if PostcallRecordingImportEnabled, PostcallTranscribeEnabled, ContactLensImportEnabled set to false.

    17. VpcSecurityGroupList: The list of SecurityGroupIds for Virtual Private Cloud (VPC). Not required if PrivateVpcEnabled is set to false.

    18. VpcSubnetList: The list of Subnets for the Virtual Private Cloud (VPC). Not required if PrivateVpcEnabled is set to false.

    19. AmazonConnectQueueMaxRecords: Enter record set size for list queue query. Max is 100.

    20. AmazonConnectQueueMetricsMaxRecords: Enter record set size for queue metrics query. Max is 100.

    21. CTREventSourceMappingMaximumRetryAttempts: Maximum retry attempts on failure for lambdas triggered by Kinesis Events.

    22. ConnectRecordingS3BucketName: This is the name of the S3 bucket used to store recordings for your Amazon Connect instance. This is ONLY the bucket name, no sub-folders or suffixes

    23. ContactLensImportEnabled: true | false - Set to false if importing Contact Lens into Salesforce should not be enabled.

    24. PostcallCTRImportEnabled: true | false - Set to false if importing CTRs into Salesforce should not be enabled on the package level. This setting can be disabled on a call-by-call basis.

    25. PostcallRecordingImportEnabled: true | false - Set to false if importing call recordings into Salesforce should not be enabled on the package level. This setting can be disabled on a call-by-call basis.

    26. PostcallTranscribeEnabled: true | false - Set to false if post-call transcription should not be enabled on the package level. This setting can be disabled on a call-by-call basis.

    27. TranscriptionJobCheckWaitTime: Time between transcription job checks

  2. Once completed, click "Deploy" function:

  1. The package provides a single Lambda function (sfInvokeAPI) that supports multiple operations, like lookup, create and update. For the initial validation, sample events are provided within the function. Click on the function name and check the list of files in the editor.
  1. To validate a phone number lookup, double-click on event-phoneLookup.json file and copy the text in your clipboard.
  1. In the top-right corner, click the drop-down arrow next to the "Test" button and select "Configure test events"
  1. Select "Create new test event", set Event name (i.e. phoneLookup) and paste the JSON payload you've copied in the previous step.
  1. Click "Create" button

  2. From the drop-down list, select your "eventLookup" and click "Test" button

  1. If successful, the result will contain fields defined in "sf_fields" parameter in the invocation event
  1. As a next step, we are going to use the ContactId provided and create a Case in Salesforce. Double-click on "event-create.json" file and set the ContactId value from the previous step. Copy the JSON text into your clipboard.
  1. In the top-right corner, click the drop-down arrow next to the "Test" button and select "Configure test events"
  1. Select "Create new test event", set Event name (i.e. createCase) and paste the JSON payload you've copied in the previous step.
  1. Click "Create" button

  2. From the drop-down list, select your "createCase" and click "Test" button

  1. If successful, the result will contain a Case Id for newly created case:
  1. As defined in the event payload, Status is "New" and Priority is "Low". We are going to use the update operation to close the case. Copy the Case Id provided in the previous step, then double-click on "event-update.json" file and paste the Case Id in "sf_id" parameter:
  1. In the top-right corner, click the drop-down arrow next to the "Test" button and select "Configure test events"
  1. Select "Create new test event", set Event name (i.e. closeCase) and paste the JSON payload you've copied in the previous step.
  1. Click "Create" button

  2. From the drop-down list, select your "closeCase" and click "Test" button

  1. If successful, the result will be HTTP code 204 ("No Content" success code):
  1. Login in to Salesforce and search for Case and it's details. The Case status should be "Closed".