Skip to main content
Kinetic Community

Microsoft Exchange Adapter

The Microsoft Exchange Adapter is used to retrieve data from a Microsoft Exchange server.  It uses the Microsoft Exchange web service running on the Exchange server.

Requirements

  • Microsoft Exchange Server 2010 (Microsoft Exchange Server 2007 appears to work, but is not fully tested)
  • 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:
    • Exchange Web Service API (kinetic-ews.jar)
    • Apache Commons Http Client (commons-httpclient-3.1.jar)
    • Apache Commons Logging (commons-logging-1.1.1.jar)
    • Java CIFS Client Library (jcifs-1.3.17.jar)

Adapter Configuration

  • Adapter Class - One or more of these values must be added to the adapters.json configuration file:
    • com.kineticdata.calendar.adapters.exchange.ExchangeAdapter
    • com.kineticdata.calendar.adapters.exchange.ExchangeWithProxyAdapter

Connection Configuration

  • Adapter Class:
    • com.kineticdata.calendar.adapters.exchange.ExchangeAdapter
  • Properties
    • Domain - The Active Directory domain of the account specified by the Username property.
    • Username - The username for the proxy account that the connection will use to connect to Exchange.
    • Password - The password for the account specified by the Username property.
    • Web Service Url - the address the Microsoft Exchange web service is listening on.  NOTE: this value can also be left blank and the adapter will attempt to use auto-discovery to find the exchange web server.
      • Example: https://exchange.mycompany.com/EWS/exchange.asmx
         
  • Adapter Class:
    • com.kineticdata.calendar.adapters.exchange.ExchangeWithProxyAdapter
  • Properties
    • HTTP Proxy Host - Host name or IP address of the HTTP proxy server to send EWS traffic through
    • HTTP Proxy Port - Port number the proxy server is listening on (e.g. 8080 or 80)
    • Domain - The Active Directory domain of the account specified by the Username property.
    • Username - The username for the proxy account that the connection will use to connect to Exchange.
    • Password - The password for the account specified by the Username property.
    • Web Service Url - the address the Microsoft Exchange web service is listening on.  NOTE: this value can also be left blank and the adapter will attempt to use auto-discovery to find the exchange web server.
      • Example: https://exchange.mycompany.com/EWS/exchange.asmx

Event Type Source Configuration

The event type source for a Microsoft Exchange Adapter defines the name of the connection for the calendar events, and optional configuration parameters.

On the event type configuration page, we saw that the source configuration property was dependent on the adapter used by the connection.  The Microsoft Exchange Adapter doesn't require any additonal properties.  By default, the adapter will assume the calendar owner is the email address that is specified in the connection configuration, and will assume the calendar is using the default calendar for that account.

If the calendar belongs to a different owner, or is located in a folder other than the default location, either or both of those properties my be specified in the source configuration object.  The two optional properties are described below:

  • Owner - The email address for the account that owns the calendar being accessed.
  • Path - the path to the folder where the desired calendar is located.  The user accessing this calendar (defined in the connection configuration) must have access to this calendar.

Proxy User's Default Calendar

"source": {
  "connectionName": "Microsoft Exchange",
  "configuration": {}
}

Shared Default Calendar

The proxy user accessing this calendar (defined in the connection configuration) must have access to this calendar.  Note that if the value of "Owner" corresponds to the proxy user, this will have the same effect as showing the proxy user's default calendar.

"source": {
  "connectionName": "Microsoft Exchange",
  "configuration": {
    "Owner": "joe.blow@company.com"
  }
}

Shared Custom Calendar (Or Proxy User's Custom Calendar)

The proxy user accessing this calendar (defined in the connection configuration) must have access to this calendar.  To show a custom calendar that belongs to the proxy user, set the value of "Owner" to be the email address associated to the proxy user.

"source": {
  "connectionName": "Microsoft Exchange",
  "configuration": {
    "Owner": "joe.blow@company.com",
    "Path": "Joe's Shared Calendars/Important Dates"
  }
}

Public Calendar

The proxy user accessing this calendar (defined in the connection configuration) must have access to this calendar.

"source": {
  "connectionName": "Microsoft Exchange",
  "configuration": {
    "Path": "Public Calendars/PTO"
  }
}

Event Type Mappings

Event type mappings create a relationship between Exchange appointment or meeting properties, and one of the event properties.

The syntax used to parse data Exchange properties must be consistent with the rules for mappings, which means that all Exchange properties must be enclosed in moustaches (double braces).  Currently event type mappings only support a direct mapping to one Exchange property.  These rules apply to all event type mappings - core mappings, details mappings, and filter mappings.

Core Mappings

Core mappings are not configurable in the Kinetic Exchange adapter.

Detail Mappings

An example of an Exchange property mapping:

"detailMappings": {
  "Priority": "{{Importance}}"
}

In this example, a mapping has been created to add a "Priority" property to the event details.  The value for this property will come from the Exchange appointment's "Importance" property.

Valid Detail Mappings

  • Categories
  • Created At
  • Created By
  • Importance
  • Location
  • Modified At
  • Modified By
  • Sensitivity
  • Body

Filter Mapping Properties

An example of an Exchange filter mapping:

"filterMappings": [
  {
    "name": "Category",
    "value": "{{Categories}}",
    "values": {}
  },
  {
    "name": "Priority",
    "value": "{{Importance}}",
    "values": {
        "High": "red",
        "Normal": "green",
        "Low": "blue"
    }
  }
]

In this example, filter mappings have been created allow the calendar events to be filtered by Category and Priority (which maps to the Exchange appointment's "Importance" property).  Further, when filtering by Priority, Exchange appointment's with a priority of 'High' will show up in red, priority of 'Normal' will show up in green, and a priority of 'Low' will show up in blue.

Valid Filter Mapping Properties

  • Categories
  • Created By
  • Importance
  • Location
  • Modified By
  • Sensitivity

Changelog

v1.0.3 (2013-06-27)

  • Added support for using a HTTP proxy server to send the Exchange Web Service calls via the new adapter class com.kineticdata.calendar.adapters.exchange.ExchangeWithProxyAdapter

v1.0.2 (2013-04-19)

  • Adds the 'Domain' connection configuration value (this was necessary to support Exchange environments that have a different Active Directory and email domain. IE: KINETICDATA and kineticdata.com), changes the event type configuration to look for public calendars if the 'Owner' configuration parameter is not included.

v1.0.1 (2013-04-11)

  • Resolves minor edge case same-day sorting issue caused by the application of incorrect millisecond values.