Skip to main content
Kinetic Community

Data Source Definition

The data source configuration file is responsible for defining where the event information comes from.

Description

Events can be anthing from change records, incident records, conference room reservations, etc..., but they must be related to the resuorce they are being mapped to.  This file also defines the field mappings used to identify certain pieces of information about the events, and also the criteria used to retrieve the appropriate information from the end system.

Events are displayed in the appropriate time slot for the resource they are associated with.  Therefore, it is important that the data source record has a foreign key or other type of relationship that respresents the sourceMapKey value identified by the resource configuration file.

Properties

All the following properties must be included in the configuration file, even if they are not used.  Properties that are not used should be set to the blank string "".

 

Property Description
uuid

A unique identifier comprised of an alpha-numeric string.

Example: "tickets"

calendarId

The unique identifer of the calendar that this data source belongs to.

Example: "site-tickets"

name

The name or label that end users will see that describe the data events.

Example: "Tickets"

connectionName

The name of the connection that is used to retrieve data source events.  This must match the "name" property of one of the connection configuration files.

Example: "ars-server"

color

The color used for events of this data source.  The summary row compounds events from all rows below it.  Can be any valid css color name or hex color value.

Example: "#dd0000"

type

Two event type options are available:  Normal or Unresourced.  Unresourced events do not require a value for the sourceMapResourceId property.  Unresourced events are drawn under the summary row, labeled with the value from the "name" property.

Example: "Normal"

summaryRollup

Identifies whether events for this data source should rollup into the Summary row.

Two possible values: "true" or "false"

Example: "true"

source

The name of the structure (database table, file, etc...) on the end point system that contains the event data.  

Adapter Specific - This value depends on the type of adapter used to retrieve the data.

 

Example: "CompanyTickets"

sourceMapResourceId

The name of the field or location on the end point system that contains the resource's unique identifier, or key.  The end user will not see this value, but it is used to link data events to the resource.  This is the foreign key, or similar relationship value to the resource.

Adapter Specific - This value depends on the type of adapter used to retrieve the data.

 

Example: "700000000"
sourceMapDatasourceValuesKeyId

The name of the field or location on the end point system that contains the unique identifier for the event.  This value will not be displayed to the end user, but is used to retrieve additional information about the event through the use of click handlers.

Adapter Specific - This value depends on the type of adapter used to retrieve the data.

 

Example: "1"

sourceMapName

The name of the field or location on the end point system that contains the event name or label.  This value will be displayed to the end user as the event name.

Adapter Specific - This value depends on the type of adapter used to retrieve the data.

 

Example: "700000001"

sourceMapDescription

The name of the field or location on the end point system that contains a description of the event.  This value will be displayed if the user hovers the mouse over the event, or can also be used in clickhandlers.

Adapter Specific - This value depends on the type of adapter used to retrieve the data.

 

Example: "700000002"

sourceMapStart

The name of the field or location on the end point system that represents the starting date/time for the event.

Adapter Specific - This value depends on the type of adapter used to retrieve the data.

 

Example: "700000003"

sourceMapEnd

The name of the field or location on the end point system that represents the ending date/time for the event.

Adapter Specific - This value depends on the type of adapter used to retrieve the data.

 

Example: "700000004"

sourceMapCriteria

The qualification or query string used to retrieve the list of events from the end point system.

NOTE - The start date and end date fields are automatically used in the criteria to retrieve events.  Any records that do not contain a value for both of these fields will not be retrieved and displayed on the schedule calendar.

 

Adapter Specific - This value depends on the type of adapter used to retrieve the data.

 

  • The quotation (") and backslash (\) characters may be used in the criteria string, but they must be escaped by prefixing the character with a backslash (\) character.
  • The entire criteria, or portions of the criteria may be passed as URL parameters. This allows the criteria to become dynamic. Dynamic portions of the criteria are denoted by the use of special delimiter characters enclosing the dynamic parameter name:
    {{parameterName}}
    Anything in between the delimiters is expected to be passed on the URL using the parameter name defined between the delimiters.
    • For Example, suppose an region was to be passed when the user clicks on a link or button in an external system.  The Kinetic Schedule URL could be built up by appending a parameter with the value of the region.
    • So if the the sourceMapCriteria was:
      "'Region'=\"{{region}}"
      the following information would be appended to the URL: &region=Midwest.
    • The resultant criteria would then be
      'Region'="Midwest".
 

Example: ""

displayedDatasourceValues

Additional fields from the end point that can be displayed on the event detail window.

 

Adapter Specific - This value depends on the type of adapter used to retrieve the data.

 

  • Configuration Properties
    • mapSourceId - The name of the field or location on the end point system where the value exists.
    • mapSourceName - not used, just use blank string - ""
    • mapSourceLabel - The label to apply to this value.
    • sortOrder - An integer value to define the order this value will appear in the result set. 

 

sourceJsp

Not used

Example: ""

sourceDetailsJsp

The name of the JSP page used to render the fields identified by the displayedDatasourceValues property.  The reference directory is relative to the "resources" directory in the web application.

If no value is provided, will display a simple list of name/value field mappings unless a clickhandler is defined for the data source.

Example: ""

filterFields

A structured list of fields or locations (and possible values) from the data source end system that may be used to filter the list of events that are displayed to the end user.

Please see the filter fields configuration page for more details.

clickHandler

If defined, allows an action to take place when a user clicks on an event.  This could be used to display more information about the event, or possibly open a form that is capable of editing the event.

Please see the click handlers configuration page for more details.

createdAt

Not used, may set to null.  If used, must be an ISO8601 formatted date string.

 

Formatyyyy-MM-ddTHH:mm:ssZ

Example: "2013-07-17T16:33:06-0500"

createdBy

Not used.

May set to blank string - ""

modifiedAt

Not used, may set to null.  If used, must be an ISO8601 formatted date string.

 

Formatyyyy-MM-ddTHH:mm:ssZ

Example: "2013-07-17T16:33:06-0500"

modifiedBy

Not used.

May set to blank string - ""

 

Sample Data Source Configuration File

A sample data source  configuration file that utilizes a BMC Remedy ARS connection.  Notice the source mapping properties and filter fieldIds all reference Remedy field ids.  These values would most likely have a different meaning or format if a different adapter was used.

 

{
    "datasource": {
        "uuid": "tickets",
        "calendarId": "site-tickets",
        "name": "Tickets",
        "connectionName": "ars-server",
        "color": "#2A7FFF",
        "summaryRollup": "true",
        "type": "Normal",
        "source": "CompanyTickets",
        "sourceMapResourceId": "700000000",
        "sourceMapDatasourceValuesKeyId": "1",
        "sourceMapName": "700000001",
        "sourceMapDescription": "700000002",
        "sourceMapStart": "700000003",
        "sourceMapEnd": "700000004",
        "sourceMapCriteria": "'Status' != \"Closed\"",
        "sourceJsp": "",
        "sourceDetailsJsp": "",
        "clickHandler": {
            "type": "url",
            "callback": "http://www.mycompany.com/myEventDetailsUrl",
            "target": "_blank",
            "parameters": [
                {
                    "name": "eventId",
                    "value": "{{sourceMapDatasourceValuesKeyId}}"
                },
                {
                    "name": "action",
                    "value": "edit"
                }
            ]
        },
        "filterFields": [
            {
                "fieldId": "7",
                "name": "Status",
                "values": [
                    {
                        "value": "Draft",
                        "color": "lightblue"
                    },
                    {
                        "value": "Scheduled",
                        "color": "orange"
                    }
                ]
            }
        ],
        "displayedDatasourceValues": [
            {
                "mapSourceId": "700000010",
                "mapSourceName": "",
                "mapSourceLabel": "Impact",
                "sortOrder": "1"
            }
        ],
        "createdAt": null,
        "createdBy": "",
        "modifiedAt": null,
        "modifiedBy": ""
    }
}