Data Source Configuration

Last updated
Save as PDF

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. Format: `yyyy-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. Format: `yyyy-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": ""
    }
}