Microsoft Exchange calendars

Introduction to Microsoft Exchange calendars in ConSol CM

You can integrate a Microsoft Exchange calendar into ConSol CM. The calendar can be shown in the Calendar section on case, contact or resource pages or on the dashboard of the Web Client. The users can create new appointments, view existing appointments and edit existing appointments.

Integrating a Microsoft Exchange calendar

Perform the following steps to integrate a Microsoft Exchange calendar:

1. Decide where to place the calendar. You can either place it in an object or on the dashboard:

   • Enable the Calendar section on the desired page (case, person, company or resource) using the page customization. You need to set the state attribute in calendar from hidden to expanded or collapsed.

   • Add a calendar widget to the dashboard by adding it to the layout attribute in widgetsGrid.

2. Write the calendar script (type Calendar integration) on the Scripts page of the Web Admin Suite, and reference it in the page customization, calendarInitializationScript attribute of calendar, see Writing the calendar script.

3. If the users should be allowed to create and edit appointments, set the editable attribute of calendar to true.

Writing the calendar script

The calendar script needs to return a map with the information to access the Microsoft Exchange server. The following parameters can be used in the script: 

• name
  String. The name to identify the source (no function yet).

• color
  String. Background color for appointment entries in the HTML color format, e.g. red or #D80000

• editable
  Boolean. Indicates whether appointments can be created, edited or removed. If not set, the value from the page customization will be used (default: false).

  In addition, the current user needs write permissions to the object where the calendar is shown in order to be able to edit appointments.
  

• access.*
  Properties for determining the access to the calendar:
  

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

    For EXCHANGE:

    • access.url
      URL. The URL of the .asmx 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 used to log in to the Exchange server.

    • access.password
      String. The password of the technical user used to log in to the Exchange server.

    • access.domain
      String. The Windows domain of the Exchange server. The technical user has to be a member of this domain.

    • access.impersonation
      String. Email account of an Exchange calendar user. The login to the Exchange server is performed using the technical user. Then the user is changed to the individual user indicated here using the Exchange server function Impersonation. The calendar of this impersonated user is the shown. If the name of the user is the same in Exchange and ConSol CM, you can simply pass the current user’s name to Exchange using the method workflowApi.getCurrentEngineer().getName() or engineerService.current.name.

      The impersonation function can only be used by an account which has been granted the ApplicationImpersonation role by the Exchange administrator. Consider all security aspects when you set up this role.

    For 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.

Example script:

Code example 41: Example calendar integration script

Additional variables available in the script:

• Case page: ticket
• Contact page: unit
• Resource page: resource

Configuring the calendar

The appearance and behavior of the calendar can be fine-tuned in the page customization. You can set the following attributes in calendar:

• All-day slot (allDaySlot)
  Boolean. Determines if the all-day slot is displayed at the top of the calendar. Default true.
• Appointment background color (appointmentBackgroundColor)
  String. Sets the background color for all appointments in the calendar. You can use any CSS color format, such as #f00, #ff0000, rgb(255,0,0), or red.
• Appointment border color (appointmentBorderColor)
  String. Sets the border color for all appointments in the calendar. You can use any CSS color format, such as #f00, #ff0000, rgb(255,0,0), or red.
• Appointment color (appointmentColor)
  String. Sets the background and border colors for all appointments in the calendar. You can use any CSS color format, such as #f00, #ff0000, rgb(255,0,0), or red.
• Appointment dragging and resizing (appointmentConstraint)
  String. Limits appointment dragging and resizing to certain windows of time.

  Possible values:

  • <appointment_ID>
    Appointments that are being dragged or resized must be fully contained by at least one of the appointments linked to by the given appointment ID.
  • businessHours
    Appointments being dragged or resized must be fully contained within the week's business hours (default: Monday-Friday 9am-5pm), see businessHours attribute.
  • <start-time>-<end_time>;<days_of_week>
    A custom time window in the same format as the businessHours attribute. Days of week are optional.
    Examples: 10:00-18:00; 1,2,3,4 or 10:00-18:00
• Appointment resizing (appointmentDurationEditable)
  Boolean. Allows appointments’ durations to be editable through resizing. Default true.
• Overlapping appointments (appointmentOverlap)
  Boolean. Determines if appointments in the calendar, when dragged and resized, are allowed to overlap each other. Default true.
• Appointment start date (appointmentStartEditable)
  Boolean. Allows appointments’ start times to be editable through dragging. Default true.
• Appointment text color (appointmentTextColor)
  String. Sets the text color for all appointments in the calendar. You can use any CSS color format, such as #f00, #ff0000, rgb(255,0,0), or red.
• Aspect ratio (aspectRatio)
  String. Determines the width-to-height aspect ratio of the calendar. Default value 1.35.
• Business hours (businessHours)
  String. Emphasizes certain time slots in the calendar.
  Format: <start-time>-<end_time>;<days_of_week>
  Example: 10:00-18:00; 1,2,3,4 (from 10am to 6pm, Monday-Thursday)
• Calendar event handler script (calendarEventHandlerScript)
  String. Name of the script which handles calendar events. Besides standard context variables like ticket, there are additional ones:
  
  • eventType
    enum (values: CREATE, UPDATE, DELETE)
  • appointment
    with appointment data (uid, subject, location, etc.).
• Calendar script (calendarInitializationScript)
  String. Name of the script which produces the calendar configuration. If the value is empty or the script returns null the calendar is not shown.
• Content height (contentHeight)
  String. Makes the calendar’s content area this many pixels tall. By default, this option is not set and the calendar’s height is calculated based on the aspectRatio attribute.
• Default all-day duration (defaultAllDayAppointmentDuration)
  String. A fallback duration for all-day appointments without a specified end time value. Default value 1 (one day).
• Default date (defaultDate)
  String. The initial date displayed when the calendar first loads. Accepts an ISO8601 date string like 2020-02-01.
• Default timed appointment duration (defaultTimedAppointmentDuration)
  String. A fallback duration for timed appointments without a specified end time value. If not set, the default value is 02:00:00 (2 hours). This attribute also affects the default duration of appointments during creation.
• Default view (DefaultView)
  String. Default calendar view.
  Possible values: month, basicWeek, basicDay, agendaWeek, agendaDay. Default agendaWeek.
  See Available Views for view examples.
• Enable editing (editable)
  Boolean. Whether the appointments can be created, dragged and resized. This value overwrites the source configuration. Default false.
• First day of the week (firstDay)
  String. The day that each week begins with. (Sunday=0, Monday=1, Tuesday=2, etc.). If empty, the value is based on browser’s locale.
• Force appointment duration (forceAppointmentDuration)
  Boolean. A flag to force calculation of an appointment’s end if it is unspecified. Default false.
• Resize automatically (handleWindowResize)
  Boolean. Whether to resize the calendar automatically when the browser window resizes. Default true.
• Header content - center (headerCenter)
  String. Defines the buttons and title at the top/center of the calendar. See headerLeft description for details. Default title.
• Header content - left side (headerLeft)
  String. Defines the buttons and title at the top/left of the calendar. Comma- or space-separated list values (values separated by a comma are displayed adjacently). Default prev,next today.

  Possible values:

  • title
    Text for the current month/week/day.
  • prev
    Button for moving the calendar back one month/week/day.
  • next
    Button for moving the calendar forward one month/week/day.
  • prevYear
    Button for moving the calendar back one year.
  • nextYear
    Button for moving the calendar forward one year.
  • today
    Button for moving the calendar to the current month/week/day.
  • <view name>
    Button that will switch the calendar to any of the available views (see defaultView description for available views).

  The header is not shown if all three header attributes (headerCenter, headerLeft, headerRight) are empty.

• Header content - right side (headerRight)
  String. Defines the buttons and title at the top/right of the calendar. See headerLeft attribute description for details. Default month,agendaWeek.
• Height (height)
  String. Sets the height, in pixels, of the entire calendar (including header). By default, this option is not set and the calendar’s height is calculated based on the aspectRatio attribute.
• Hidden days (hiddenDays)
  String. Excludes certain days of the week from being displayed. Comma separated list of day-of-week indices (Example: 1,3,5). Each index is zero-based (Sunday=0) and ranges from 0-6.
• Lazy fetching (lazyFetching)
  Boolean. Determines when appointment fetching should occur. Setting this attribute to false makes sense when there are a lot of external changes to the user’s calendar. Default true.
• End time (maxTime)
  String. Determines the end time (exclusively) which will be displayed, even if the scrollbars have been scrolled all the way down. Default value is 24:00:00.
• Start time (minTime)
  String. Determines the starting time that will be displayed, even if the scrollbars have been scrolled all the way up. Default value is 00:00:00.
• Next day threshold (nextDayThreshold)
  String. When an appointment’s end time spans into another day, the minimum time it must be in order for it to render as if it were on that day. Default: 09:00:00 (9am). Only affects timed appointments that appear on whole days. Whole day cells appear in month view, basicDay, basicWeek and the all-day slots in the agenda views.
• Appointments visible (readable)
  Boolean. Determines if the user can see the calendar entries. Set true to make the calendar entries visible and false if the user should not see the calendar entries. In the latter case, the calendar widget is still displayed. Only available if the calendar is displayed as a calendar widget on the dashboard.
• Left-to-right display (rightToLeftMode)
  Boolean. If enabled, displays the calendar in right-to-left mode. Default false.
• Initial scrolling (scrollTime)
  String. Determines how far down the scroll pane is initially scrolled. Default is 06:00:00 (6am).
• Overlapping display (slotAppointmentOverlap)
  Boolean. Determines whether timed appointments in agenda view should visually overlap. Default true.
• Slot duration (slotDuration)
  String. The frequency for displaying time slots. Default is 00:30:00 (30 minutes).
• Snap duration (snapDuration)
  String. The time interval at which a dragged appointment will snap to the agenda view time grid. Also affects the granularity at which selections can be made. Default value is set to slotDuration.
• state
  String. The visibility mode of the section, possible values are [expanded, collapsed, collapsed_and_preload, hidden]. Default: expanded. Only available if the calendar is displayed on the case, contact, or resource page.
• Week numbers (weekNumbers)
  Boolean. Determines if week numbers should be displayed in the calendar. Default true.
• Weekend (weekends)
  Boolean. Whether to include Saturday/Sunday (i.e., weekend) columns in any of the calendar views. Default true.

See http://fullcalendar.io/docs for further details.

Configuring the behavior after calendar events

You can define the behavior after the following events in the script referenced in the calendarEventHandlerScript attribute of calendar:

• Creation of an appointment (event type CREATE)
• Editing of an existing appointment (event type UPDATE)
• Removal of an existing appointment (event type DELETE)

The following variables are available:

• ticket
  The current case (only calendars on case pages)

• unit
  The current contact (only calendars on contact pages)

• resource
  The current resource (only calendars on resource pages)

• eventType
  The type of event, possible values are: CREATE, UPDATE or DELETE.

• appointment
  The appointment object (class com.consol.cmweb.server.common.model.calendar.AppointmentVo, the availability of the properties depends on the Exchange server type and version).

  Basic:

  • subject
    String. Subject of the appointment.

  • startDate
    Date. Start date and time of the appointment.

  • endDate
    Date. End date and time of the appointment.

  • allDayEvent
    Boolean. Defines whether an appointment is an all day event, i.e. lasts the whole day or many days.

  • location
    String. Location of the appointment.

  • meeting
    Boolean. Is true if the an appointment is a meeting (with invited people who attend)

  • cancelled
    Boolean. Indicates whether the appointment is marked as cancelled.

  • recurring
    Boolean. Indicates whether the appointment is a part of recurring set.

  • busyStatus
    Possible values are FREE, TENTATIVE, BUSY, OUT_OF_OFFICE, WORKING_ELSEWHERE or NONE.

  • body
    String. Content of the appointment. The format depends on the bodyType property)

  • bodyType
    Format of the appointment content. Possible values are TEXT, HTML or NONE
    

  Advanced:

  • uid
    String. Unique identifier of the appointment in the Exchange server.

  • start
    Start date and time in joda format

  • end
    End date and time in joda format

  • timeZone
    Timezone of the appointment in joda format (used to correctly show all-day appointments in different timezones)