How to Integrate Birdie + SalesForce

This integration is dedicated to import Case and Case Comments data from your SalesForce account.

Setup

To setup your SalesForce integration, you will need the following credentials that may depend on how your IT department define its security policies:

Grant Type: client_credentials (find salesforce doc here)

Domain
Client ID
Client Secret
Refresh Token (optional)

Grant Type: password (find salesforce doc here)

Domain
Client ID
Client Secret
User
Password

To start, once you are logged into your SalesForce account, you need to create a Connected App to obtain tokens.

Create a Connected App

Log in to Salesforce as an administrator. In the drop-down list of the account (in the upper-right corner), select Setup.
In the left-hand pane, go to Apps > App Manager.
Click on the New Connected App (in the upper right corner).
On the New Connected App page, fill the following required fields under Basic Information: Connected App Name, API Name and Contact Email.
Go to API (Enable OAuth Settings), and select Enable OAuth Settings.
1. In the Callback URL field, enter https://login.salesforce.com/.
2. In the Selected OAuth Scopes field, select
  1. Access and manage your data (api),
  2. Perform requests on your behalf at any time (refresh_token, offline_access),
  3. Provide access to your data via the Web (web),
3. and then click Add.
Click the Save button to save the new Connected App.
In the Connected Apps (Apps > App Manager) list, find the App that you just created, and then click Manage.
On the page that opens, click the Edit button. Under OAuth policies, select All users may self-authorize in the Permitted Users list, and then click the Save button.
Go back to the Connected Apps (Apps > App Manager) list, and click the App that you just created, and then click on View.
Go to API (Enable OAuth Settings), and note down the Consumer Key and Consumer Secret, which will be used for the configuration of Credential in Ballerina SFDC Integration.

Obtaining tokens

Get Code
1. Log in to Salesforce, then enter the following request Url in a new tab to get the code. <CONSUMER_KEY> should be replaced with the obtained Consumer Key in the above step. <YOUR_INSTANCE> should be replaced with your instance name, from your salesforce.com URL.
2. ```
https://<YOUR_INSTANCE>.salesforce.com/services/oauth2/authorize?response_type=code&client_id=<CONSUMER_KEY>&redirect_uri=https://login.salesforce.com/
```
3. Allow access if any alert popup. Then you will see browser is redirecting to a Url like this. You can obtain the code from that Url ?code=aPrxYX...
4. ```
https://login.salesforce.com/?code=aPrxYXyxzkuBzbDGdwv67qekAQredtrsWqty38LsdhfREyTRbvdjvTqdbvxPVC__4Cb9xGKDGErtOw%3D%3D
```

Get Access token & Refresh token

Send the following curl request to obtain the tokens. <CODE> (aPrcYX...) should be replaced with the code you obtained in the above step. <CONSUMER_KEY> and <CONSUMER_SECRET> should be replaced with obtained keys with the created Connected App.

curl -X POST https://<YOUR_INSTANCE>.salesforce.com/services/oauth2/token?code=<CODE>&grant_type=authorization_code&client_id=<CONSUMER_KEY>&client_secret=<CONSUMER_SECRET>&redirect_uri=https://login.salesforce.com/

You can obtain the access_token and refresh_token from the response.

{
"access_token":"00D2v000001XKxi__SOMETHING",
"refresh_token":"5Aep861dlMxAL.LhVTuPRa__SOMETHING",
"signature":"MK/YGMNQhPSSnKtYicXlaU__SOMETHING",
"scope":"refresh_token web api",
"instance_url":"https://ap15.salesforce.com",
"id":"https://login.salesforce.com/id/00D2vKxiEAG/0045Q09vAAL",
"token_type":"Bearer",
"issued_at":"1570030000198"
}

SalesForce Endpoint in scope and Access to info

Case

https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_case.htm

Case - Data Stream

    {
        "stream": {
            "name": "Case",
            "jsonSchema": {
                "type": "object",
                "$schema": "http://json-schema.org/draft-07/schema#",
                "properties": {
                    "Id": {"type": ["string", "null"]},
                    "Type": {"type": ["string", "null"]},
                    "Origin": {"type": ["string", "null"]},
                    "Reason": {"type": ["string", "null"]},
                    "Status": {"type": ["string", "null"]},
                    "AssetId": {"type": ["string", "null"]},
                    "OwnerId": {"type": ["string", "null"]},
                    "Subject": {"type": ["string", "null"]},
                    "Comments": {"type": ["string", "null"]},
                    "IsClosed": {"type": ["boolean", "null"]},
                    "ParentId": {"type": ["string", "null"]},
                    "Priority": {"type": ["string", "null"]},
                    "SourceId": {"type": ["string", "null"]},
                    "AccountId": {"type": ["string", "null"]},
                    "ContactId": {"type": ["string", "null"]},
                    "IsDeleted": {"type": ["boolean", "null"]},
                    "CaseNumber": {"type": ["string", "null"]},
                    "ClosedDate": {"type": ["string", "null"], "format": "date-time"},
                    "ContactFax": {"type": ["string", "null"]},
                    "Product__c": {"type": ["string", "null"]},
                    "CreatedById": {"type": ["string", "null"]},
                    "CreatedDate": {"type": ["string", "null"], "format": "date-time"},
                    "Description": {"type": ["string", "null"]},
                    "IsEscalated": {"type": ["boolean", "null"]},
                    "ContactEmail": {"type": ["string", "null"]},
                    "ContactPhone": {"type": ["string", "null"]},
                    "SuppliedName": {"type": ["string", "null"]},
                    "ContactMobile": {"type": ["string", "null"]},
                    "SuppliedEmail": {"type": ["string", "null"]},
                    "SuppliedPhone": {"type": ["string", "null"]},
                    "LastViewedDate": {"type": ["string", "null"], "format": "date-time"},
                    "MasterRecordId": {"type": ["string", "null"]},
                    "SystemModstamp": {"type": ["string", "null"], "format": "date-time"},
                    "SLAViolation__c": {"type": ["string", "null"]},
                    "SuppliedCompany": {"type": ["string", "null"]},
                    "LastModifiedById": {"type": ["string", "null"]},
                    "LastModifiedDate": {"type": ["string", "null"], "format": "date-time"},
                    "LastReferencedDate": {"type": ["string", "null"], "format": "date-time"},
                    "PotentialLiability__c": {"type": ["string", "null"]},
                    "EngineeringReqNumber__c": {"type": ["string", "null"]}
         
    }

Case Comments

https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_casecomment.htm

Case Comments - Data Stream

{
        "stream": {
            "name": "CaseComment",
            "jsonSchema": {
                "type": "object",
                "$schema": "http://json-schema.org/draft-07/schema#",
                "properties": {
                    "Id": {"type": ["string", "null"]},
                    "ParentId": {"type": ["string", "null"]},
                    "IsDeleted": {"type": ["boolean", "null"]},
                    "CommentBody": {"type": ["string", "null"]},
                    "CreatedById": {"type": ["string", "null"]},
                    "CreatedDate": {"type": ["string", "null"], "format": "date-time"},
                    "IsPublished": {"type": ["boolean", "null"]},
                    "SystemModstamp": {"type": ["string", "null"], "format": "date-time"},
                    "LastModifiedById": {"type": ["string", "null"]},
                    "LastModifiedDate": {"type": ["string", "null"], "format": "date-time"},
                }
    }