Microsoft Exchange Calendar Integration

Introduction

Starting with CM version 6.10, it is possible to include a Microsoft Exchange calendar view in the Web Client.

Please refer to the ConSol CM System Requirements of your CM version for a list of supported Exchange Server versions.

The calendar view can be displayed...

The calendar will be displayed in a distinct section of the ticket, customer, or resource page.

An engineer who works with the calendar view can ...

Figure 174: ConSol CM Web Client - Ticket with Calendar section (monthly view)

Figure 175: ConSol CM Web Client - Adding an appointment in the calendar

Configuring the Microsoft Exchange Calendar Integration

Basic Configuration

The integration of a Microsoft Exchange server to provide calendar data is done based on page customization. For a detailed introduction to this topic, please read the section about Page Customization. Here, only the calendar-specific configuration is explained.

Perform the following steps:

  1. Make the calendar section visible (example for the Ticket Edit page):

    Log in as an administrator and open a ticket. Select Enable page customization in the main menu. Since the calendar section is not yet displayed, you cannot mark the element you want to configure, but instead have to select it in the page customization tree. Select calendar/ticketEditPage/calendarSection and set the attribute state from hidden to expanded. Alternatively, you can set collapsed. This will initially display a collapsed Calendar section and the engineer can expand it manually. In both cases, the calendar section of the ticket will be visible. As header No Calendar will be displayed. The configuration of the calendar follows in step 2.

    Figure 176: ConSol CM Web Client - Using page customization to make the Calendar section of a ticket visible

    Figure 177: ConSol CM Web Client - Page Customization Definition Section (PCDS) for the Calendar section of tickets

  2. Configure the calendar script:

    The connection to a Microsoft Exchange server calendar is implemented using an Admin Tool script. The script has to be stored in the Admin Tool script section, i.e., navigation group System, navigation element Scripts and Templates, and must be of script type Calendar integration. The name of this script has to be entered as the value for the attribute calendarInitializationScript in the page customization (see step 1). This Admin Tool script is used to initialize the calendar source and has to return a map which contains all parameters describing the source. If the returned map is empty or is null, no calendar will shown (the section will be empty with the label No calendar).

    The script has to be coded as shown in the following example:

    return [

    name: 'Exchange Source',

    'access.type': 'EXCHANGE',

    'access.url': 'https://exchange1.server.net/EWS/Exchange.asmx',

    'access.username': 'exchange-user',

    'access.password':'exchange-password',

    'access.domain': 'SSO',

    'access.impersonation':'somebody@sso.server.net',

    'access.version': '2013'

    ]

    Code example 22: Example calendar integration script

    The following parameters can be used in the script: 

    • name
      String. The name of the source. For now it has no functional use, but in future CM versions, when multiple sources can be used in the calendar section, it will be used to identify them in the user interface.
    • color
      String. Background color for appointment entries. Format: HTML colour format (e.g., red or #D80000)
    • editable
      Boolean. Indicates whether appointment creation/editing/removal should be enabled. If this value has not been set explicitly, the value from the section customization will be used, which by default is set to false. NOTE: appointments are editable only if the current user has write permissions to the ticket in which the calendar section is shown.
    • access.*
      Properties describing access to the calendar: credentials, connection details, URLs ... etc.

      • access.type
        String parameter. Possible values EXCHANGE (MS Exchange Server), RANDOM (randomly generated appointments for testing purposes).

        For access.type EXCHANGE:

        • access.url
          URL. The url of the .asmx file (Active Server Method File) on the Exchange server. The file is usually located in the EWS (Exchange Web Services) directory and provides the exchange access web service.
        • access.username
          String. The name of a technical user under which the access/login at the Exchange server is performed.
        • access.password
          String. The password of the technical user under which the access/login at the Exchange server is performed.
        • access.domain
          String. The Windows domain of the Exchange server. The technical user (used for access.username and access.password, see above) has to be a member of this domain.
        • access.impersonation
          String. Email account of an Exchange calendar user. The calendar on the ticket page or on the customer page will be based on the view of this Exchange calendar user. For example, somebody could be the Exchange login of the ConSol CM engineer who is currently logged in. If the name of an engineer is the same in Exchange and ConSol CM, you can simply pass the current engineer's name to Exchange using the method workflowApi.getCurrentEngineer().getName() or engineerService.current.name.

        For access.type RANDOM:

        • access.calendar
          Name of the calendar file. Random calendar provider stores generated appointments on disk (files will be automatically removed when CM server is stopped). Using same name in configuration ensures that user will have the same set of appointments.

      Additional variables available in the script:

      • Ticket context: ticket
      • Contact/customer context: unit
  3. Enable edit mode for the calendar:
    To allow full access (i.e., to create and/or edit appointments) for engineers, set the page customization attribute editable to true.

Basic principle of Exchange server calendar access

The configured Exchange server is contacted, namely the  Web Service indicated in the url. The login at this server is performed using the technical user (access.username, access.password). Then the user is changed to the person/user indicated under access.impersonation. The latter is performed using the Exchange server function Impersonation. The calendar of this impersonated user is the displayed on the ticket or customer page.

The impersonation function can only be used by an account which has been granted the ApplicationImpersonation role by the Exchange administrator. Please make sure all security aspects are taken into consideration when you set up this role!

Advanced Configuration: Page Customization Parameters for the Microsoft Exchange Calendar Integration

Short Background Information about the Microsoft Exchange Calendar Integration

The integration (more precisely, the display) of Microsoft Exchange calendars in ConSol CM is based on the jQuery fullcalendar plugin. For complete details on that API, please refer to the fullcalendar web site.

Pages for the Configuration of the calendarSection

The Calendar section can be configured on these pages:

In addition, the calendar can be displayed as a widget on the Web Client dashboard. See Attributes for Calendar Widgets for details.

Page Customization Attributes

The following attributes can be used to configure the appearance and behavior of the integrated Exchange calendar.

Attributes:

Defining Event Handlers for Appointment Events

Using the Page Customization attribute calendarEventHandlerScript, you can define actions which should be triggered in case a certain event has occurred. The events which can be used are:

For example, you can define that when a new appointment is made, an email is automatically sent to all contacts of the ticket.

The following variables are available in a calendarEventHandlerScript: