Administer > Calendar administration > Calendar administration tasks > Display records from an application module in the calendar

Display records from an application module in the calendar

The purpose of calendar mapping is to ensure that certain objects of Service Manager (such as Incident, Changes, and Time Periods) are properly displayed in the calendar. This feature also links the Time Period object with other objects in the system. Before proceeding with this task, you, as a system administrator, should have already specified the objects that you want to map with the Time Period object. See Configure calendar settings.

Now, you need to create a mapping record for each of these objects, including the Time Period object.

Caution Create only one mapping record for each object; otherwise, a duplicate record error occurs.

The Calendar Mapping form is accessible from System Administration > Ongoing Maintenance > Calendar Administration > Calendar Mappings. By default, there are three mapping records for Time Period, Change, and Change Task, respectively.

The following table describes the sections of the calendar mapping form.

Section Description
Header Displays general information of the mapping record, such as the ID, associated object, active or inactive state, and description.
Restricting Query Configuration

This is a default query that allows only relevant records of the selected object to be displayed in the calendar.

The query must use this format: field="value", where field is the name of a field in the object table, and value can be a static value, a RAD expression (for example, affected.item in $L.file), or a JavaScript call (for example, jscall("JS method");); or you can enter true for no restrictions.

Example value: 

                            status="closed" and category="Application"
Title Configuration

Specifies which fields of the object to display in the Title area (record list area) of the calendar.

All available fields of the selected object are displayed in the Available Fields box, and the fields that are used in the Title area are displayed in the Selected Fields box.

Note This is a mandatory setting.
Tooltip Configuration

Specifies which fields are displayed in the tooltip when you hover your mouse over a record (or a record bar) of the selected object in the calendar.

All available fields of the selected object are displayed in the Available Fields box, and the fields that are used in the tooltip are displayed in the Selected Fields box.
Color Preferences

Specifies color settings for the selected object.

To cover different requirements, you can enter a condition for each color. The conditions are evaluated in top-to-bottom order. As soon as one condition evaluates to true, the evaluation of the color preferences is stopped.

If you specify no color preferences, a default color is used. In the Default Color field, you can configure a default color by using HTML color codes (for example, #000000).
Default Sort Preferences

Specifies the default sort preferences for the Title area and calendar entry area in the calendar.

If you specify no default sort preferences, records will be sorted by record ID in ascending order.
Time Period Field Mapping

This section is available only for objects other than Time Period. It creates a link between Time Period and the object. The mapping is used for conflict detection and overlapping functionality in the calendar.

  • Field for Start Date and Field for End Date (Mandatory): Specify which fields of the object are mapped with the Start Date and End Date of the Time Period object. The calendar displays records of the object as a record bar whose length is calculated based on the Start Date and End Date values.

  • Time Period Mapping Query: This query defines which time period objects are used for detecting the conflict for the object. When a conflict is detected, the calendar displays a conflict icon for a record. It also displays a gray background bar ("overlap shadow bar") behind the record bar when the record either overlaps with, exceeds, or misses a freeze window or maintenance window (see Conflict Icon Custom Messages for more information). You can use $L.file as a reference to the current record.

    The following is a query example:

    current.phase="published" and (affected.services=affected.item in $L.file or affected.services="all") and (location=location.full.name in $L.file or location="all")

  • Query for Time Period Conflict Calculation: You can enter a query against the selected object to restrict the records for conflict calculation with Time Period.

    The following is aquery example :

    category in $L.file ~={"CI Group","Default","KM Document","Unplanned Change","Subscription"} and open in $L.file=true

Conflict Icon Custom Messages

A conflict icon refers to a small red or yellow triangle icon that is displayed at the top left corner of an object record cell (see Full calendar and embedded calendar). The red triangle indicates the current record overlaps with one or more time periods of the Freeze Period type, while the yellow triangle indicates the record either exceeds or misses one or more time periods of the Maintenance Window type. When both types of conflicts occur, only the red triangle is displayed. The icon tooltip displays specific conflict information of the record.

You can configure additional custom messages to be displayed as part of the tooltip of a conflict icon. For example, you can specify the following configuration so that the "This is an emergency change" message is displayed in the conflict icon tooltip for each Emergency Change record.

  • Condition: emergency in $L.file=true

  • Message: scmsg(1,"timeperiodCalendarMapping")

Note If a record has no conflicts with any time periods but has one or more custom messages configured, a blue triangle is displayed instead of the red or yellow one.

Example: Display Time Period, Change, and Incident in the calendar

This example configuration assumes that you have specified the cm3r (Change) and probsummary (Incident) objects for calendar mapping in the calendar global settings. Now you need to configure a mapping record for each of the objects: Time Period, Change, and Incident.

By default, there are two mapping records for Time Period and Change, respectively. You may want to edit the existing mapping records to better suit your needs, and add one new mapping record for Incident.

To display Time Period, Change, and Incident in the calendar, follow these steps:

  1. Click System Administration > Ongoing Maintenance > Calendar Administration > Calendar Mappings.

  2. Click Search.

    A list of existing mapping records is displayed. Out-of-the-box, only the mapping records for Time Period, Change and Change task are displayed.

  3. Edit the CALMAP01 (for Time Period), the CALMAP02 (for Change), and the CALMAP03 (for Change Task) records as needed.

    1. In the Header section, edit the optional Description field and make sure the Active option is selected.

      Only active objects can be displayed in the calendar. Canceling this option will disallow records of the object to appear in the calendar.

    2. In the Restricting Query Configuration section, enter a query. See the following table for examples.

      Object Restricting Query Configuration Note
      Time Period true This query filters the records to be retrieved from the timeperiodDefinition table.
      Change

      true

      		This query filters the records to be retrieved from the cm3r table.
      Change Task true This query filters the records to be retrieved from the cm3t table.

    3. In the Title Configuration section, enter a field separator or leave the field empty to use the default (a hyphen), and move the fields that you want to display in the Title area to the Selected Fields box. See the following table for examples.

      Object Selected Fields
      Time Period 
      ID
      Name
      Change 
      Change ID
      Title
      Change Task 
      Incident ID
      Title

    4. In the Tooltip Configuration section, move the fields that you want to display in the object's tooltip (hover-over text) to the Selected Fields box, and use the up/down arrow button to change the sort order of the fields. See the following table for examples.

      Object Selected Fields
      Time Period 
      ID
      Type
      Category
      Scope
      Name
      Owner Group
      Services
      Change 
      Change ID
      Title
      Description
      Service
      Change Task 
      Status
      Priority
      Affected Services

    5. In the Color Preferences section, click Add to add color preferences. See the following table for examples, where you specify three colors for three types of time periods, and one color for all change records.

      Object Color Name Condition
      Time Period #FF0000 Freeze Period (Red)

      (type in CurrentRecord = "nogo")

      Time Period #018424 Maintenance Window (Green) (type in CurrentRecord = "go")
      Time Period #0197D6 Neutral Period Period (Blue) (type in CurrentRecord = "neutral")
      Change #FFD800 Hardware (Yellow) ( assign.dept in CurrentRecord = "Hardware")
      Change Task #FFB11B Hardware (Yellow) ( assign.dept in CurrentRecord = "Hardware")

    6. In the Default Sort Preferences section, select the fields by which you want to sort records of the object, and select Ascending or Descending order. See the following table for example.

      Object Sort Field Sort Type
      Time Period ID Ascending
      Change Change ID Ascending
      Change Task Task ID Ascending

    7. In the Time Period Field Mapping section, select the fields to map with the Start Date and End Date in the calendar, and specify a mapping query as necessary.

      Note The Time Period Field Mapping section is not available for Time Period objects.

      See the following table for an example.

      Object Field for Start Date Field for End Date Time Period Mapping Query Query for Time Period Conflict Calculation
      Change Planned Start Planned End current.phase="published" and (affected.services=affected.item in $L.file or affected.services="all") and (location=location.full.name in $L.file or location="all") category in $L.file ~={"CI Group","Default","KM Document","Unplanned Change","Subscription"} and open in $L.file=true

    8. Configure conflict icon custom messages for the Change mapping record. See the following table for examples.

      Condition Message
      emergency in $L.file=true scmsg(1,"timeperiodCalendarMapping")
      foreign.id in $L.file~=NULL scmsg(2,"timeperiodCalendarMapping") + foreign.id in $L.file
    9. Save the mapping records.

  4. follow these steps to add a mapping record for Incident.

    1. Click System Administration > Ongoing Maintenance > Calendar Administration > Calendar Mappings.
    2. In the Object field, select Incident.
    3. In the Description field, enter a description of the mapping (optional).

    4. Click New, and then click Save.

      The record is added and automatically assigned with an ID.

    5. Select the Active check box.

      Note By default, each mapping record is created as Inactive. Only active mappings take effect. Once a mapping is created, you can update it but can no longer delete it. If a mapping is no longer needed, disable it by clearing the Active check box.

    6. In the Restricting Query Configuration section, enter a query. For example, use the default value: true.

    7. In the Title Configuration section, enter a field separator or leave the field empty to use the default (a hyphen) , and move the fields that you want to display in the Title area to the Selected Fields box. See the following table for an example.

      Object Selected Fields
      Incident 
      Incident ID
      Title

    8. In the Tooltip Configuration section, move the fields that you want to display in the object's tooltip (hover-over text) to the Selected Fields box, and use the up/down arrow to change the sort order of the fields. See the following table for an example.

      Object Selected Fields
      Incident 
      Status
      Priority
      Affected Services

    9. In the Color Preferences section, configure a default color for the Incident object, and if needed add more color preferences.

      To configure a default color, in the Default Color field, enter an HTML color code (for example, FF8000).

      To add more color preferences, click Add, select a color from the color palette, enter a name for the selected color, if needed click Edit to enter a condition (RAD Expression) using the Condition Editor, and then click OK.

      See the following table for an example, where you specify one color for incident records that are in Closed status, which implies that incident records in any other status will display in the default color.

      Object Color Name Condition
      Incident #01DF01 Closed Incidents (Green) ( Expression: problem.status in $L.file = "Closed")

    10. In the Default Sort Preferences section, select the fields by which you want to sort records of the object, and select the Ascending or Descending order. See the following table for an example.

      Object Sort field Sort type
      Incident Incident ID Ascending

    11. In the Time Period Field Mapping section, select the fields to map with the Start Date and End Date of the Time Period object, and if needed specify a mapping query for conflict detection. See the following table for an example.

      Object Field for Start Date Field for End Date Time Period Mapping Query
      Incident Outage Start Outage End true

    12. In the Conflict Icon Custom Messages section, configure messages and their conditions for conflict icon tooltip display.

    13. Save the mapping record.

  5. Similarly, add a mapping record for other objects (Problem, Interaction, and so on) as necessary.

Related topics

Calendar Administration
Full calendar and embedded calendar
Calendar security area and role
Release Control Calendar

Enable or disable the calendar
Configure calendar settings
Display an embedded calendar on an incident form, an interaction form, or a problem form
Configure search filters for the full calendar
Localize a filter field
Test your calendar