Adapter - Salesforce
This page describes version 2.0.7 of the adapter.
Overview
The Salesforce adapter integrates with Salesforce Platform and provides a small set of functions/commands. The idea behind this adapter is:
This adapter can add an account to Salesforce, get account details from Salesforce and update events for an account.
Salesforce Configuration (Trial version)
Salesforce provides 2 experiences - Lightning and Classic. The screenshots below are from Classic interface.
For a customer, who already has Salesforce platform, the sign-up step should be skipped.
You can directly go to Create a new ConnectedApp setup, if there is a user available for use for WFE.
Create a User Account / Sign up for Trial
- Go to https://developer.salesforce.com/signup and sign up for developer Trial Version.
- Once you complete registration process, a tenant uri will be created for your organization.
- e.g.
https://my-url.salesforce.com
- e.g.
- Use this to log into your Salesforce account and further set up.
Complete User Set up
- Log into Salesforce and browse to setup from top right corner.
- In the left Pane, under Administration > Users > Users, check your user and make sure it has System Administrator privileges. You can opt to give selective permissions also.
- Go Under User Settings and obtain Security Token.
- Maintain a note of username, password, and security token for this user it as this is needed by adapter.
When you access Salesforce from an IP address that isn’t trusted for your company and you use a desktop client or the API, you need a security token to log in. What’s a security token? It’s a case-sensitive alphanumeric code that’s tied to your password. Whenever your password is reset, your security token is also reset.
Add a Connected App
https://help.salesforce.com/articleView?id=connected_app_overview.htm&type=5.
- Under set up, browse as shown:
- Add Basic Information for the app. Leave Custom, web and other settings unfilled.
- Enter app name, and contact information.
- Make sure you grant full or selective access to this app. Enter any callback url, it doesn't have to be valid. We are not using this flow for OAuth. Adapter uses Username/password flow for OAuth.
- Make sure to Enable OAuth settings and require secret for web server flow.
- It may take a few minutes for the app to be available.
- Browse as shown:
- Note down the Consumer Key and Consumer Secret for this app. The adapter needs this to connect to sales force.
Basic sales force configuration is complete. Adapter uses the Salesforce RestApi to access Force database.
Properties
| Name | Display | Is Required | Comments | Type | Default Value | Maximum Value | Minimum Value | Maximum Length | Minimum Length |
|---|---|---|---|---|---|---|---|---|---|
| baseuri | Base URI | True | The base uri to log into Salesforce. | string | https://login.salesforce.com/ | 1024 | |||
| username | User Name | True | User's username for OAuth Username/password flow | string | 1024 | ||||
| password | Password | True | User's password for OAuth Username/password flow | password | 1024 | ||||
| securitytoken | Security Token | True | User's security token - generated by Salesforce. This is appended to the password field. | password | 1024 | ||||
| clientid | Client Id | True | Consumer key from the connected app definition | string | 1024 | ||||
| clientsecret | Client Secret | True | Consumer secret from the connected app definition | password | 1024 |
You can create multiple connected apps and users in Salesforce and split permissions across these entities to perform different functions for WFE.
For now, we have created a single connected app and user with administrative access to all services.
Login and Authentication with Sales Force
Salesforce adapter logs into Salesforce with the username, password, security token, client id/consumer key and consumer secret.
If authentication succeeds, Sales force provides a token to the adapter (which is valid for certain duration, and is configurable in Salesforce).
The adapter, then uses this token and the tenant url (also returned as part of authentication response) for subsequent calls.
If adapter receives a specific error from Salesforce indicating that the token or session id is invalid, adapter authenticates once again and gets a new token.
Before executing any command, adapter checks the validity of token by making a simple call to the Salesforce RestApi.
Commands Preface
The Salesforce adapter contains a few commands that allow for some basic integration with a Neoface Watch system.
These commands involve querying simple data, look up referenced data, foreign keys, relational tables etc. This requires some understanding of SOQL (Salesforce query language) and sobjects (Salesforce standard objects).
getaccount command retrieves the details of an account / customer in Salesforce by querying the account number.
In Salesforce, multiple accounts can have same account number, but in our implementation, each customer in Salesforce has a unique account number, which is Neoface Watch SubjectId.
The account details retrieved by adapter are a combination of subset of Salesforce account object fields and related tables (such as account owner).
The adapter has defined classes to deserialize data received from Salesforce.
Commands
Add Account/Customer (addAccount)
an account or customer to Salesforce
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| accountnumber | Account Number | Unique account number for a customer | True | string |
| name | Name | Account name | True | string |
| description | Description | Additional information of account | True | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| id | Account Id of newly added account | string |
| status | True / False | string |
Get Account/Customer (getAccount)
Get an account based on account number (neoface subjectId)
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| accountnumber | Account Number | Unique identifier for an account - neoface SubjectId in our case. | True | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| id | Account Id of the account | string |
| name | Account Name | string |
| type | Account Type - predefined types in Salesforce | string |
| status | True / False | string |
| description | Account Description | string |
| phone | Account Phone Number | string |
| activityhistory | An array of activity history objects. | array |
| activityhistory.Id | Unique id for activity history object. | string |
| activityhistory.ActivityDate | Date of activity history object. | string |
| activityhistory.Description | Description for activity history | string |
| activityhistory.Owner.Name | User's name who owns the activity history. | string |
| activityhistory.CreatedBy.Name | User's name who created the activity history | string |
| contacts | An array of contacts that belong to an account | array |
| contacts.Id | Unique Id of the contact | string |
| contacts.title | Title of the account contact | string |
| contacts.FirstName | Title of the account contact | string |
| contacts.LastName | Lastname of the account contact | string |
AddAccountEvent (addAccountEvent)
Add event data to an account
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| accountnumber | Account Number | Unique Account number for the account. | True | string |
| subject | Subject | Event Subject | True | string |
| description | Description | Additional information to log for the event | True | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| status | True / False | string |
Get Account Opportunities (getAccountOpportunities)
Get opportunities for an account.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| accountid | Account Id | Unique id for account to look up the opportunities. | True | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| opportunity | An array of account's opportunity objects. | array |
| opportunity.Name | Opportunity Name | string |
| opportunity.Account.Id | Account Id to which the opportunity belongs | string |
| opportunity.Type | Type of opportunity - Predefined types in Salesforce | string |
| opportunity.Owner.Name | Opportunity owner's/user's name | string |
| opportunity.CreatedBy.Name | Name of the person who created this opportunity | string |
| opportunity.IsWon | Whether the opportunity was won | string |
| opportunity.IsClosed | Whether the opportunity is in a closed status | string |
| opportunity.Amount | The amount associated with this opportunity | string |
| opportunity.ExpectedRevenue | The expected revenue from this opportunity | string |
| opportunity.CreatedDate | The create date of the opportunity | string |
| opportunity.LastModifiedDate | Date when the opportunity was last modified. | string |
Get User By Email (getUserByEmail)
Get Salesforce user details by email id.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| Email id of the user. | True | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| status | Command Status - true/false | string |
| name | User's Full Name | string |
| firstname | User's First Name | string |
| lastname | User's Last Name | string |
| User's Email | string | |
| username | User's Unique Username in Salesforce | string |
| mobile | User's Mobile Number | string |
| phome | User's Phone Number | string |
| extension | User's Extension as defined in Salesforce | string |
| division | Division the user belongs to | string |
| department | Department the user belongs to | string |
| company | Company the user belongs to | string |
| isactive | Is the User active in Salesforce | string |
Get User By Username (getUserBySFUsername)
Get Salesforce user details by Salesforce unique username.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| username | Username | Username of the user. | True | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| status | Command Status - true/false | string |
| name | User's Full Name | string |
| firstname | User's First Name | string |
| lastname | User's Last Name | string |
| User's Email | string | |
| username | User's Unique Username in Salesforce | string |
| mobile | User's Mobile Number | string |
| phome | User's Phone Number | string |
| extension | User's Extension as defined in Salesforce | string |
| division | Division the user belongs to | string |
| department | Department the user belongs to | string |
| company | Company the user belongs to | string |
| isactive | Is the User active in Salesforce | string |
Get Account/Customer By Phone Number (getAccountByPhone)
Get an account based on phone number
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| phone | Phone Number | Phone number assigend to an account in Salesforce | True | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| id | Account Id of the account | string |
| name | Account Name | string |
| type | Account Type - predefined types in Salesforce | string |
| status | True / False | string |
| accountnumber | The Salesforce account number. | string |
| description | Account Description | string |
| phone | Account Phone Number | string |
| activityhistory | An array of activity history objects. | array |
| activityhistory.Id | Unique id for activity history object. | string |
| activityhistory.ActivityDate | Date of activity history object. | string |
| activityhistory.Description | Description for activity history | string |
| activityhistory.Owner.Name | User's name who owns the activity history. | string |
| activityhistory.CreatedBy.Name | User's name who created the activity history | string |
| contacts | An array of contacts that belong to an account | array |
| contacts.Id | Unique Id of the contact | string |
| contacts.title | Title of the account contact | string |
| contacts.FirstName | Title of the account contact | string |
| contacts.LastName | Lastname of the account contact | string |
Release History
| Version | Type | Description | Tracking # | Date |
|---|---|---|---|---|
| 2.0.1 | Initial | First release in the Adapter Type store. | ||
| 2.0.6 | Maintenance | Updated third-party components and improved maintainability. | NAP-11518 | |
| 2.0.7 | Maintenance | Updated third-party components and improved maintainability. | NAP-23945 | 2022-11-30 |