Skip to main content
Kinetic Community

Event Type Configuration

An event type configuration defines where events are retrieved from, and how they map to data source. The event type configuration file must follow the naming convention as defined on the Configuration Files page: beginning with the "et_" prefix, and ending with the ".json" suffix.  Kinetic Calendar does not limit the number of event types that can exist in a single calendar, so if multiple event types are used, each configuration file must contain a unique file name.

File Structure

Below is a sample event type configuration file.  As with all configuration files, it uses the JSON format to define the event type properties.

{
    "name": "Completed Changes",
    "status": "Active",
    "defaultFilter": "",
    "detailsPage": "/themes/default/event.jsp",
    "clickHandler": {},
    "color": "grey",
    "source": {
        "connectionName": "ITSM ARS",
        "configuration": {
            "Form": "CHG:Infrastructure Change",
            "Qualification": "'1000002195'!=$\\NULL$"
        },
        "coreMappings": {
            "Id": "{{1000000182}}",
            "Name": "{{1000000182}}",
            "Description": "{{1000000000}}",
            "Start": "{{1000000348}}",
            "End": "{{1000000364}}"
        },
        "detailMappings": {
            "Manager Group": "{{1000000015}}",
            "Change Manager": "{{1000000403}}",
            "Change Location": "{{303935100}}",
            "Change Reason": "{{1000000294}}",
            "Service": "{{303497300}}",
            "Class": "{{1000000568}}",
            "Priority": "{{1000000164}}",
            "Urgency": "{{1000000162}}",
            "Impact": "{{1000000163}}",
            "Risk Level": "{{1000000180}}",
            "Status": "{{303502600}}",
            "Status Reason": "{{1000000881}}"
        },
        "filterMappings": [
            {
                "name": "Manager Group",
                "value": "{{1000000015}}",
                "values": {}
            },
            {
                "name": "Change Manager",
                "value": "{{1000000403}}",
                "values": {}
            },
            {
                "name": "Priority",
                "value": "{{1000000164}}",
                "values": {
                    "Critical": "red",
                    "High": "chocolate",
                    "Medium": "cornflowerblue",
                    "Low": "#333333"
                }
            },
            {
                "name": "Urgency",
                "value": "{{1000000162}}",
                "values": {}
            },
            {
                "name": "Impact",
                "value": "{{1000000163}}",
                "values": {}
            }
        ]
    }
}

 
Like the calendar configuration, Kinetic Calendar only expects one group of event type properties in this file.  So the file is wrapped with opening and closing braces instead of brackets like the connections configuration file.
 
Since the JSON format was discussed in more detail on the connection configuration page and calendar configuration page, this page will focus on the event type properties and how the data source mappings work.
 

Event Type Properties

Not all of the properties defined in the listing above are required.  Some properties can assume a default value if not provided.  This is a listing of all the event type properties, indicating which ones are required, and what the default values are for those that are not required.
 
Property Name Required? Description
name Yes A name that describes the events that are being retrieved.  This name will be displayed when the calendar is loaded, so it should be a name that represents what the events are (Changes, Incidents, Room Reservations, etc...).
status Yes Active or Inactive.  Only active event types will be loaded and displayed with the calendar.  Inactive event types are ignored.
defaultFilter No This value indicates what filter mapping should be used to filter the events when the page is initially loaded.  It should reference the 'name' property of the filter mapping.  If blank, the events will not be filtered when the page is initially loaded.
detailsPage No Indicates what JSP should be used to render the event details when a user clicks on an event.  By default, the /themes/default/event.jsp page will be used.  If a clickHandler is defined for the event type, then the clickHandler will be executed when the user clicks an event and this property will not be used.
clickHandler No Click handlers can override the default behavior of displaying the event details in a popup window by defining a different action to take when the event is clicked.  See the Click Handlers page for details.
color No Specifies the color that all unfiltered events for this event type will be displayed with.  When the events are filtered, the filter values will determine the color of the events.  If a color is not defined, the application will randomly assign a color to this event type.  Supported colors are any of the html hex colors in the range #000000 - #FFFFFF, or any of the standard css color names.
displayOnLoad No Indicates whether these events should be displayed when the calendar page is first loaded.  The default value is true, which means that the events will be displayed when the calendar loads.  If set to false, the events will not be displayed until the user clicks the checkbox next to the event type name to display the events.
source Yes The source is a property object that contains the name of the connection used to retrieve the event data, along with some optional field mappings to relate additional data fields to the event.
source::connectionName Yes Contains one of the connection names defined in the connections configuration file.  This determines what sytem the event data comes from.
source::configuration Yes The source configuration is dependent on the adapter used in the connection for this event type.  Not all adapters require additional configuration, such as the Microsoft Exchange adapter.  In this case, the configuration value should be the empty hash object {}.  The BMC Remedy ARS Adapter does require additional configuration because it needs to know what form the data comes from, and what qualification to use to retrieve the data.  Please see documentation for the specific adapter for configuration details.
source::coreMappings No

Relates the field or property from the source where the data comes from to the Event core properties (id, name, description, start time, end time, all-day) .  See the Adapter page for the connection specific adapter for more information about which mappings are required and the proper syntax: Adapters

source::detailMappings No Relates the field or property from the source where the data comes from to additional custom properties that are defined by the customer.  This information is not available in the event on the main calendar page, but it is fetched when the user clicks on the event to see additional details about the event.  See the Adapter page for the connection specific adapter for more information about which mappings are required and the proper syntax: Adapters
source::filterMappings No Relates the field or property from the source where the data comes from to values that will be filterable by the end user.  For instance, events may be representing your Change Requests, which have a priority and impact value.  You may wish to add these two properties to the filter mappings so the end user can drill down to view changes by a specific priority value or a specific impact value, and filter out the events that don't match the selected value.  See the Adapter page for the connection specific adapter for more information about which mappings are required and the proper syntax: Adapters

Mappings

The mapping properties (coreMappings, detailMappings, and filterMappings) are used to map values from the data source to a Kinetic Calendar event.  The syntax used for the mappings will be dependent on the adapter used in the event type connection.

 

Core Mappings

A Kinetic Calendar event contains six core properties that are used internally by the calendar application to determine how the event is displayed in the calendar view.  The core event properties are the following:

  • ID - the field or property used to uniquely identify the record.
  • Name - the field or property that should be used as the event name.
  • Description - the field or property that should be used as the event description.
  • Start Date/Time - the field or property that indicates when the event starts.  This must be mapped to a Date or Date/Time value.
  • End Date/Time - the field or property that indicates when the event ends.  If used, This must be mapped to a Date or Date/Time value.
  • All Day - the field or property that indicates if the event is an all day event.

 

Required Core Mappings

Three of the core mapping properties must be mapped to a piece of data from the data source so the event can properly be identified and rendered in the calendar.

  • ID - used to uniquely identify the event to retrieve additional information for the event.  
  • Name - displayed on the calendar so users can quickly and easily identify what the event does or relates to based on the type of events the user is viewing.

Detail-EventName.png

  • Description - provides more information than just the event name provides, somewhat like a summary.  The value of this property is also displayed as hover text when the user hovers the mouse over the event. Detail-EventHoverDescription.png
  • Start Date/Time - required so Kinetic Calendar can determine where to draw the event in relation to the calendar days or time slots available in the current view.

The following image shows what an event might look like on the calendar monthly view.  This event starts on July 27 at 1:55 PM, and the name is CRQ000000000201.  If the start date/time was missing, the event would not be displayed on the calendar view because Calendar wouldn't know where to draw it.  If the name was missing, the user would only see the time the event started, and nothing else.  The ID is not displayed on the event, but it is used in the underlying html code that represents the event.

 

Optional Core Mappings

The rest of the core mappings are optional.  

  • End Date/Time - The mapping of the end date determines when the event ends.  In the example above, the event ended on July 28.  The value of the End Date/Time property can affect how the event is displayed.
  • All Day - The mapping of the All Day property can determine how the event is displayed.  If the event is determined as All Day, then the event will be displayed with white text and a solid background.  If the event is determined as a timed event (that starts and ends on the same day), or point in time event, then the event will be displayed with colored text on white background.

 

Detail Mappings

Detail mappings are simply a list of name/value pairs that provide additional event information when the user clicks on the event.  The detail mappings instruct Kinetic Calendar to fetch more information from the data source for this event, and return it using the labels provided in the mappings.

The format of the name side of the mapping is simply a label that represents the meaning of the data value.  The format of the value side of the mapping will be dependent on the adapter used in the event type connection.  Please find the specific adapter used in the event type connection to determine the proper syntax: Adapters.

In the example listed at the top of this page, the first mapping is as follows:

"Manager Group": "1000000015"

In this example, the name of the detail mapping is "Manager Group".  The value of the detail mapping references a field on the data source - in this case it is field 1000000015 on the Remedy ARS Form "CHG:Infrastructure Change".  This tells Kinetic Calendar to retrieve the record from the "CHG:Infrastructure Change" form that matches the event ID, and return the value of field 1000000015 identified as "Manager Group".  

When the user clicks on this event to retrieve additional details, the user will see the following information:

Detail-EventDetails.png

 

Filter Mappings

Filters provide a way to allow end users to display events based on values that they select from a list of filterable criteria.  That list of filterable criteria is controlled with filter mappings.  Filter mappings are a bit different than detail mappings because they can define the color events should be displayed in when the field value of the event matches the corresponding filter value.  So instead of a list of name/value pairs, the filter mappings are an ordered list of properties that define the filter name, the filter value, and the a list of colored filter values.

Take the event type configuration listed at the top of this page for instance.  The filter mappings are defined as follows:

"filterMappings": [
    {
        "name": "Manager Group",
        "value": "{{1000000015}}",
        "values": {}
    },
    {
        "name": "Change Manager",
        "value": "{{1000000403}}",
        "values": {}
    },
    {
        "name": "Priority",
        "value": "{{1000000164}}",
        "values": {
            "Critical": "red",
            "High": "chocolate",
            "Medium": "cornflowerblue",
            "Low": "#333333"
        }
    },
    {
        "name": "Urgency",
        "value": "{{1000000162}}",
        "values": {}
    },
    {
        "name": "Impact",
        "value": "{{1000000163}}",
        "values": {}
    }
]
 

This code is building up a list of 5 filter fields, each with a name or label, the field or property on the data source where the value is retrieved, and a list of possible values that will be defined with a predetermined color.  

The name is simply a text label that represents the criteria of what the field value relates to.

The format of the value property will be dependent on the adapter used in the event type connection.  Please find the specific adapter used in the event type connection to determine the proper syntax: Adapters.  In this example, the value references a field on the data source - in this case it is a field on a Remedy ARS Form.  This tells Kinetic Calendar to retrieve the record from the form that matches the event ID, and return the value of this field identified as the label used in the name property.

The values property is a list of name/value pairs that represent possible values for the field, with the color that events with this field value should be displayed as.  The color will only be used when the events are being filtered on this filter mapping.  

Take a look at the filter mapping identified with the name "Priority" in the listing above.  This filter mapping defines four values that will display events with specified colors.  When the event type is filtered on the Priority filter mapping, all events that have a priority value of "Critical" will be displayed in red.  All "High" priority events will be displayed in chocolate, all "Medium" priority events will be displayed in cornflowerblue, and all "Low" priority events will be displayed in #333333, which is a shade of grey resembling black.  Events that have any other priority value will be assigned a color by the system since it wasn't defined in the event type configuration.

 

Detail-FilteredEvents.png

 

Supported colors for filtered event values are the same as supported colors for event types.  Color values may be any of the html hex colors in the range #000000 - #FFFFFF, or any of the standard css color names: http://www.w3schools.com/cssref/css_colornames.asp