A connection defines the data adapter that will be used to retrieve calendar event data from the back end data source, and the properties to use the adapter. An adapter is code that is written specifically to connect to one type of data system, such as BMC Action Request System, or Microsoft Exchange.
Since each adapter is written for a specific type of system, multiple connections can be configured to use the same adapter yet retrieve data from different servers. For example, the ArsAdapter can be used to connect to both the ITSM Remedy server, and the HR Remedy server. Each server (ITSM Remedy server, and HR Remedy server) will contain its own connection definition in the connections configuration file.
The connections configuration file is essentially a list of available connections that calendars can use. This file must be named connections.json, and must exist in the root of the configuration directory, as specified here: Configuration Files.
A list of available adapters for Kinetic Calendar can be found here: Adapters.
Below is a sample connections configuration file. As stated, the file uses the JSON format to define the connection properties.
The file structure is explained below so that you understand the structure and syntax of the configuration file. The connections.json file should not be manually modified, as connections are managed and configured from the Configuration tab on the Administration Console, and the connections.json file is automatically generated from the Kinetic Calendar web application. On the Administration Console, connections can be added, modified, or deleted.
All connection property values all encrypted in the connections.json file. The property values shown here are in plain text for demonstration purposes only.
"name": "ITSM ARS",
"description": "Connection to the ITSM ARS server.",
"name": "Kinetic Exchange",
"description": "Connection to the Microsoft Exchange server.",
"Web Service Url": "https://exchangesever.kineticdata.com/EWS/exchange.asmx"
This example shows two connections defined in the file. The first connection uses the ArsAdapter, so it connects to a Remedy server. The second connection uses the ExchangeAdapter, so it connects to a Microsoft Exchange server. Lets walk through the file and explain what each line means.
On line 1, there is a opening bracket. Since Kinetic Calendar supports multiple connections, it expects a list of connections in the configuraton file, even if only one connection will ever be used. The opening bracket indicates this is the start of a list of items.
On line 2, there is an opening brace, this indicates the start of a collection of properties that belong together. This collection is grouped until a paired closing brace is encountered, which occurs on line 13. So lines 2 through 13 define one connection. The lines between these are basically just a key/value pair of data that define individual pieces of data about the connection. The exception is on line 6 where the connection expects a list of properties, and therefore has a nested set of braces indicating the properties are a collection of name/value pairs instead of a single name/value pair.
Line 3 defines the name of the connection. In this example we called it "ITSM ARS". This name will be used later on when defining calendar event types that need to connect to this data source. Instead of defining all the properties in the event type, we will just tell the event type to use the "ITSM ARS" connection, and get the connection details from that configuration.
Notice that line 3 has a comma at the end of the line. This indicates there are more properties that belong in this collection.
Line 4 indicates the adapter class to use for this connection. Typically adapters are packaged as Jar files, and must exist in the web application's classpath. The name of the Jar file can be anything, that is not the value to use on this line. Look into the documentation that comes with the adapter to get the fully qualified name of the class file to use on this line. In this example we are connecting to a BMC Remedy ARS server, so we are specifying that adapter - or com.kineticdata.calendar.adapters.ars.ArsAdapter.
Line 5 is the description of the connection. This can be blank, but really should have some comments in it describing what it is or what it connects to.
Line 6 starts the collection of properties that define what values the adapter class will use to connect to the data source, in this case the Remedy server. Notice that the value starts with another opening brace, this indicates there are multiple properties or key/value pairs that will be listed. This collection will be group all the items between the opening brace and the matching closing brace, which occurs on line 12. The key/value pairs in this collection are specific to the adapter, and will be different depending on what adapter is used. You will need to look at the documentation for the specific adapter to know what properties are required.
Line 13 is the end of the connection, but since there is another connection in the list you see a comma after the closing brace.
Lines 14 - 23 define another connection. This one uses the Microsoft Exchange adapter, and contains a different set of properties that are specific to the Exchange adapter.
Notice that line 23 does not have a comma at the end of the line. A comma would indicate there is at least one more connection in the list, but since this is the last connection, a comma here would make file contain invalid syntax. The last item in a list cannot contain a comma at the end of the line.