Skip to main content
Kinetic Community

Salesforce Adapter

The Salesforce Adapter allows you to access data from the Salesforce service using. The adapter uses the REST API to retrieve this information. Note: The Salesforce REST API is limited to a maximum of 2000 records returned. By extension, this limit also currently applies to this calendar adapter.

Adapter Download

  • The Kinetic Calendar web server must be using JDK 6.0 or higher.
  • The following java libraries must be included in the Kinetic Calendar web application classpath:​
    • Http Client 4.1.2 (httpclient-4.1.2.jar)
    • Http Core 4.1.2 (httpcore-4.1.2.jar)
    • Apache Commons Logging (commons-logging-1.1.1.jar)
  • The adapter and required jars can be downloaded using this zip file

Adapter Configuration

  • Adapter Class - This value must be added to the adapters.json configuration file:
    • com.kineticdata.calendar.adapters.salesforce.SalesforceAdapter

Connection Configuration

  • Properties
    • Username - The username used to login to Salesforce.
    • Password - The password used to login to Salesforce.
    • Security Token - (Optional) A security token that is appended onto the end of the password. If your instance uses the security token it can be obtained by going to 'Reset my Security Token' under personal settings.
    • Consumer Id - The consumer id of the application.
    • Consumer Token - The consumer secret of the application.
    • Salesforce Instance - The Salesforce instance that the account is tied to. Can be found to the left of the Salesforce URL.

Where to find the Consumer ID, Consumer Secret, Security Token and Instance.

1. After logging into Salesforce, the Instance can be found in the URL to the left of the salesforce.com (ie. na15, cs13, etc.)

2. Go to Setup, which is in the dropdown menu under your name in the upper righthand corner.

3. Your Security Token (if applicable) can be found under Personal Setup > My Personal Information > Reset My Security Token on the left sidebar.

4. To get the Consumer ID and Consumer Secret, Navigate back to Setup and go to Manage Apps.

5. Create a new Connected App, and fill in the basic information for the app.

6. Check the Enable OAuth Settings checkbox and put https://auth for your callback url.

7. Under selected OAuth scopes, add Access and manage your data (api) to your selected scopes and save.

8. Your Consumer ID and Consumer Secret will be found on the app information page that you were redirected to upon saving.

Event Type Source Configuration

The event type source for a Salesforce Adapter defines the name of the connection for the calendar events and configuration parameters. Under configuration, you will define which Salesforce object you want to retrieve data from (ie. Account, Event, Task, etc.). 

"source": {
  "connectionName": "Salesforce",
  "configuration": {"Object" : "Event"}
}

Event Type Mappings

Event type mappings create a relationship between Salesforce object attributes and one of the event properties.

The syntax used to parse Salesforce attributes must be consistent with the rules for mappings, which means that all Salesforce properties must be enclosed in mustaches (double braces). These rules apply to all event type mappings - core mappings, details mappings, and filter mappings.

Note: In Salesforce, all attribute names capitalize the first letter of every word (ie: The field 'All Day Event' has the name of 'IsAllDayEvent'). This standard is also followed in this adapter, and if a mapping uses a different capitalization an error will be thrown.

Core Mappings

In the core mappings there are 5 required properties to map and one optional property.

"coreMappings": {
  "Id" : "{{Id}}",
  ​"Name" : "{{Name}}",
  ​"Description" : "{{Description}}",
  ​"Start" : "{{StartDate}}",
  ​"End" : "{{EndDate}}",
  ​"IsAllDay" : "{{IsAllDayEvent}}" //Optional
}

IsAllDay is an optional field because not all object contain 'All Day Event' attributes. For example, the Campaign object StartDate and EndDate attributes are just xsd:date objects instead of xsd:datetime (which means they don't have a time of the day associated with them), so they are automatically made All Day Events.

Detail Mappings

An example of a Salesforce property mapping:

"detailMappings": {
  "Account": "{{Account.Name}}",
  ​"Location" "{{Location}}"
}

In the detail mappings, you have the freedom to name and map fields that will show up when a specific event is clicked in the form of "Name" : "{{FieldName}}" where 'Name' is the label that will be shown on the calendar while 'FieldName' is what the field is named in Salesforce. 

Filter Mapping Properties

An example of an Salesforce filter mapping.

"filterMappings": [
  {
    "name": "Location",
    "value": "{{Location}}",
    "values": {}
  },
  {
    "name": "Show Time As",
    "value": "{{ShowAs}}",
    "values": {
        "Busy": "red",
        "OutOfOffice": "blue",
        "Free": "green"
    }
  }
]

Filter mappings can be created to allow the calendar events to be filtered based on the field values.  For example, in the first filter mapping will allow a user to filter out events based on the event's location. As shown when filtering by 'Show Time As' in this example, you can also relate filter values with colors. So in this example, events sorted as 'Busy' would show up red, 'OutOfOffice' events would show up blue, and 'Free' events would show up green.

Finding Field Names

One of the most important things to be able to do when mapping fields in this adapter is to know what the proper API Name of a particular field is. The easiest way to figure out this name is by going into the Salesforce 'Setup' menu (found in the dropdown under your username in Salesforce). 

  • If you are looking for a standard object, there are multiple ways to find the Object and Field Names
    • A list of Standard Objects and Fields can be found here.
    • If you want to map to a custom field that is contained under a Standard Object, navigate to the Customize header in the App Setup section
      • Click on the object you wish to map under this header to find the labels and names of its fields. (ie. To get event fields, go to App Setup > Customize > Activities > Event Fields)
  • If you are looking for a custom object, go to the Object link under the Create header (App Setup >Create >Objects).
    • Click on the object that you wish to map in Kinetic Calendar to pull up a description of the object and a list of its fields.
    • On the top of the page, the API Name is what will be used for the 'Object' value in the configuration file
    • This page also lists all the Standard and Custom fields that are connected to a particular object along with the name for each field
      • For a custom field, map the Adapter to the API Name
      • For a standard field, map the Adapter to the Field Name

Complex Objects

The Salesforce adapter also supports using complex objects when mapping fields. This means that any field with the Data Type of 'Lookup' will be able to map to another field under that lookup value. For example if the Lookup is related to the Account object, you could map a calendar field to the Name of the Account (as opposed to just the Id) by mapping it to Account.Name. This can be done with any Lookup field in the form of Object.Field (remember to capitalize every word in the field to avoid errors). 

Changelog

v1.0.0 (2013-09-23)

  • Initial Version.