This integration is dedicated to import Case and Case Comments data from your SalesForce account.
Setup
To setup your Salesforce integration, you will need to configure a connected app.
For the official documentation on setting up a connected app, see the following docs.
For Birdie to authenticate as your connected app, you'll need to generate one of the credentials listed below. The one you will use may depend on how your IT department define its security policies. Later on, we will walk you through on how to configure a connected app, and then walk through the process of generating these credentials.
Client credentials Flow
Find Salesforce documentation here.
Domain: Something like
{DOMAIN}.salesforce.com.Client ID: A public key for authenticating as the connected app. Also called consumer key.
Client Secret: A private key for authenticating as the connected app. Also called consumer secret.
Refresh Token Flow
Find Salesforce documentation here.
Domain: Something like
{DOMAIN}.salesforce.com.Client ID: A public key for authenticating as the connected app. Also called consumer key.
Client Secret: A private key for authenticating as the connected app. Also called consumer secret.
Refresh Token: A token generated with the Client ID and secret.
Username-Password Flow
Find Salesforce documentation here.
Domain: Something like
{DOMAIN}.salesforce.com.Client ID: A public key for authenticating as the connected app. Also called consumer key.
Client Secret: A private key for authenticating as the connected app. Also called consumer secret.
User: The user to authenticate as for the connected app.
Password: The password of the user to authenticate as for the connected app.
We recommend following the setup steps for the Refresh Token Flow.
Creating a connected App
Begin by logging into Salesforce as administrator. On the Gear Icon on the top left, open the Setup page.
In the left hand pane, go to Platform Tools > Apps > App Manager:
Click on New Connected App (upper right corner):
On the new connected app page, fill in the following required fields under Basic information:
Connected App Name: Birdie Integration
API Name: Birdie_Integration
Contact Email: [email protected]
Scroll down to API (Enable OAuth Settings) and select Enable OAuth Settings. Fill in the following information:
Callback URL: https://login.salesforce.com
Select the following OAuth Scopes:
Manage user data via APIs (api);
Manage user data via Web browsers (web);
Perform requests at any time(refresh_token, offline_access)
Uncheck Require Proof Key for Code Exchange (PCKE) Extension for Supported Authorization Flows
Check Enable Client Credentials flow (Optional - for client credentials flow)
Click save at the bottom of the page
After you've saved your connected app, you'll be redirected to the "View" for your connected App.
Manage your connected app
You can also access the View connected App Page by Going to Platform Tools > Apps > App Manager, finding your connected app and navigating through Dropdown > View button.
You should navigate to the Manage screen for your connected app, either by clicking on the View page, or by selecting it from the dropdown for the App inside the app manager.
You'll be redirected to the Page to the management page for your app. From here, you can click the Edit Policies button:
This will redirect you to the page where you can manage a couple of safety configurations for your connected app.
Some configurations that we recommend you to double check:
Permitted Users: All users may self-authorize.
IP Relaxation: Relax IP restrictions (Optional - Only if your organization uses IP Enforcement).
Refresh token policy: Refresh token is valid until revoked (Optional - Avoids needing to frequently regenerate the refresh token).
Clients Credentials Flow - Run as: You'll need to select a user that has API permissions and permissions to access the connected app (Optional - only for client credentials flow).
Getting the credentials for your connected app
From the view page for your connected app, you can click on Manage consumer Details. This will redirect you to a page with a Consumer Key and Secret.
Copy and save these for later, they are your Client ID and Client Secret we mentioned in the start of this section.
If you have opted to authenticate with the Client credentials flow, send these values along with your domain to the Birdie team.
Generating a refresh token
If you have opted to authenticate via a refresh token (which is simpler since it doesn't require you to configure a user), you'll need to do two more steps.
First, using the template we will share below, generate a URL and access it via your web browser:
https://{DOMAIN}.my.salesforce.com/services/oauth2/authorize?client_id={CLIENT_ID}&redirect_uri=https%3A%2F%2Flogin.salesforce.com&response_type=code
So, assuming your domain was birdie and the client id was 1234, the link would be:
https://birdie.my.salesforce.com/services/oauth2/authorize?client_id=1234&redirect_uri=https%3A%2F%2Flogin.salesforce.com&response_type=code
Next, open this link in your web browser. It will ask you to authorize Birdie to access information in your Salesforce account:
Once you do that, you'll be redirected to the Salesforce Login Page. Notice that the URL inside your browser has a URL in the following pattern:
https://login.salesforce.com/?code={CODE}Please copy the code from the URL, we will use it to generate your refresh token.
Next, build the folowing post POST request and run it your terminal:
curl -X POST 'https://{DOMAIN}.my.salesforce.com/services/oauth2/token?code={CODE}&grant_type=authorization_code&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&redirect_uri=https%3A%2F%2Flogin.salesforce.com'
This will return a JSON result that will look something link this:
{
"access_token":"123",
"refresh_token":"456",
"signature":"789",
"scope":"refresh_token web api full",
"id_token":"...",
"instance_url":"https://{DOMAIN}.my.salesforce.com",
"id":"https://login.salesforce.com/...",
"token_type":"Bearer",
"issued_at":"1726008721576"
}
Please save the refresh token, and send it along with the client id, secret and domain to the Birdie team.
Salesforce Endpoint access
In this section, we will share the objects Birdie will import from your Salesforce Platform.
Case
Endpoint:
https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_case.htm
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 Comment
Endpoint:
https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_case.htm
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"},
}
}
}
}