Configure Planon ProCenter

Additional products : Connect : Connect for Calendars : Connect for Calendars (C4C) : Configuration : C4C Configuration using C4C app for Microsoft Graph API : Configure Planon ProCenter

The following flow chart displays all the steps that have to be taken in the configuration of Planon ProCenter for Connect for Calendars (C4C).

Configure User Groups and Users

The following flow chart depicts a list of actions to be performed to correctly configure User groups and Users for C4C.

Create C4C Admin Group & C4C Admin User

1. Create a new User group: C4C Admins and create a new User linked to that User group: C4C Admin.

2. Make sure that the User Group has similar rights as the User group System Administrators.

3. Generate an access key for the C4C admin account.

Link product definitions

C4C requires that User groups (or account groups) involved in reservation management are linked to certain product definitions.

The following table provides an overview of the product definitions and to which type of User group they need to be linked.

Product Definition	User Group	Reason
EnterpriseServiceAPI	C4C Admins	This product definition is required by the C4C app such that it can use the PaaP API.
EventConnector	All Reservation Management related User Groups including the C4C Admins	This product definition is required so that the C4C app and C4C can use the Event Connector when an Event or a Reservation has to be synchronized.
JSONServices	C4C Admins	This product definition is required by the C4C app so that it can use the PaaP API.
Scheduler	C4C Admins	This product definition is required by the C4C app for Microsoft Graph API as it provides two scheduled tasks for subscription and recovery.
PPWeb	All Reservation Management related User Groups including the C4C Admins	This product definition allows a User to use the Task Specific Interfaces (TSIs) in the Web client.
PSS2	All Reservation Management related User Groups including the C4C Admins	This product definition allows a User to use the Reservation Wizard.

Provide contact's email address for each user

Provide a Contact's Email Address for each User (including the C4C Admin). This email address will be used by C4C to send notifications to a User about the status of synchronizing an Event and a Reservation.

If errors occur during synchronization, a notification will be sent to the C4C Admin.

Configuring notifications

There are three options for Connect for Calendars reporting:

• Do not configure Connect for Calendars reporting: Connect for Calendars will use default templates to send emails to a user about the status of the Reservation and the outcome of an action on the reservation;

• Configure simple templates on a C4C app Connection: The C4C app Connection has fields that allow one to provide simple templates. When provided, then this template will be used instead of the system’s default template;

• Configure templates, use them in a Report definition on Connect for Calendars Mail Report, create event-based notifications and link them to the appropriate external reservation unit;

Report selection process at runtime.

Default email templates

The product comes with default email templates that cannot be modified.

The default email templates have the look-and-feel as displayed below.

Screen capture of a default 'Accept' email sent by Connect for Calendars.

Format of default email sent by Connect for Calendars.

Simple email templates

The C4C app Connection has fields that allow you to create a simple email template.

The placeholders in this template should match the PnName (System name) of a field in the business object Connect for Calendars Mail Report. The following code-snippet displays a simple template.

Note that the placeholders are surrounded by ‘[' and ‘]’. In addition, you can reference every field on a Reservation and Reservation Unit by using ‘[Reservation.<PNNAME OF FIELD>]’ and '[ReservationUnit.<PNNAME OF FIELD>]’ respectively.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-GB">
<head>
<meta charset="utf-8"/>
<meta http-equiv="x-ua-compatible" content="ie=edge"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<meta name="x-apple-disable-message-reformatting"/>
<title>[MailReservationAcceptedTitle]</title>
</style>
</head>
<body style="margin: 0; padding: 0;">
<h1 class="webfont h1" style="font-size: 36px; font-weight: 300; line-height: 100%; margin: 0 0 16px;">
[MailReservationAcceptedHeader]
</h1>
<h3 class="h3" style="color: #232323; font-size: 18px; font-weight: 400; margin: 0 0 8px;">
[MailMeeting]
</h3>
<p style="color: #888888; margin: 0;">[CalendarItemSubject] ([Reservation.OrderNumber])</p>
<br/>
<h3 class="h3" style="color: #232323; font-size: 18px; font-weight: 400; margin: 0 0 8px;">
[MailLocation]
</h3>
<p style="color: #888888; margin: 0;">[ReservationUnit.Name] ([CalendarItemResourceIdentifier])<br></p>
<br/>
<h3 class="h3" style="color: #232323; font-size: 18px; font-weight: 400; margin: 0 0 8px;">
[MailWhen]
</h3>
<p style="color: #888888; margin: 0;">
<b>[CalendarItemStartDateTime]</b><br> <span>-</span></br> <b>[CalendarItemEndDateTime]</b><br>
</p>
<br/>
<h3 class="h3" style="color: #232323; font-size: 18px; font-weight: 400; margin: 0 0 8px;">
[MailWho]
</h3>
<p style="color: #888888; margin: 0;">
[MailOrganizer]:</br>
<b>[CalendarItemOrganizerAccountIdentifier]</b></br>
[MailBooker]:</br>
<b>[CalendarItemBookerAccountIdentifier]</b>
</p>
</body>
</html>

Simple Notification template

Email template, report definition and event-based notification definition

Using your own custom mail templates requires further configuration. You can create Report definitions for each type of email that is sent by Connect for Calendars in the regular way that reports are being defined. This requires you to upload the mail templates to Planon’s WebDAV location for templates.

In addition, you must define a Recipients report on the business object Connect for Calendars Mail report. This report is used by the Event-based notification to determine the addressees to which an email should be sent.

Next you must define Event-based notification definitions for each type of email for which a report definition is constructed.

An External reservation unit has several fields that reference an Event-based notification definition related to the type of email that is to be sent.

Procedure

Configuring Connect for Calendars Mail Reports

1. Open a browser and navigate to the Planon Web client

2. Navigate to the TSI C4C Mail reports

3. On the level C4C Mail Reports click the Report button and add a new report for each of the following email types:

◦ ACCEPTED: The Reservation’s status is REQUESTED/MADE/COMPLETED

◦ CANCELLED: The Reservation’s status is CANCELLED

◦ CHANGED: The Reservation’s details have changed

◦ DECLINED: The Reservation could not be made

◦ DELETED: The Reservation is deleted

◦ EXCEPTION: There was an exception in the synchronization process of a Reservation;

◦ TENTATIVELY ACCEPTED: The Reservation’s status is IN OPTION

Configuring a Recipients report

4. On the Connect for Calendars mail reports level click the Report button and add a new report for a generic recipient report.

This recipient report requires at least two fields ID and To. Optional are CC and BCC.

◦ The ID field is the Syscode field of the C4C Mail Report;

◦ The To field is an expression that consists of the To field of the Connect for Calendars Mail Report.

Configuring an Event-based Notification

5. Navigate to the TSI Alerts and select the step Event-based notifications.

6. Click Add to create a new Event-based notification.

7. Configure the following fields of this Event-based notification:

a. Code: Provide a recognizable code for the event-based notification.

b. Description: Provide a description for the event-based notification.

c. Alert Condition: Create a new condition, select the BO Connect for Calendars mail report and add the condition that the To field should contain a value.

d. Mail template: Select a Report definition created on the Connect for Calendars mail report.

e. Recipient Report: Select the Recipient report definition created on the C4C mail report.

f. Schedule: Define a schedule for this Event-based notification (for example, it should run every 5 minutes).

8. Set the status of the event-based notification to Active.

Configuring the notifications for an External reservation unit

9. Navigate to the TSI Connect for Calendars – processing.

10. Drill-down to the level Accounts & reservation units and select the step External reservation units.

11. Select the External reservation unit that needs to be configured.

12. Set the reference to the Event-based notification definition on the appropriate fields.

Including a link to the reservation wizard

In confirmations sent to the organizer you can include a link to the reservation wizard overview page.

To make this possible, you need to enable a setting and adapt your mail merge report for confirmations.

Procedure

1. Go to Self-Service modules > Reservations.

2. Select a Reservation wizard (if not already present, create one).

3. Set the field Allow access from Connect for Outlook to Yes

For more information, see Reservation wizard fields.

4. Save the configuration of the Reservation wizard.

5. In your mail merge that you send out as confirmation include an expression such as the following:

<a href="<https://your reservation wizard URL/case/BP/B001>?action=InitialMM4OAction&PK=" + formatNumeric('Connect for Calendar – mail reports'.Reservation.'System code', "###############")>Click here</a>

Replace the URL in bold in between and including the angle brackets with your reservation wizard URL.

Install & configure C4C app for Microsoft Graph API

Prior to installing the C4C-App you should get its license from the Planon License Desk.

Once the license for the C4C-App for Microsoft Graph API has been acquired you can add it through the TSI - AppCenter.

Adding the license through the AppCenter will cause Planon to download and install the C4C-App from the Planon Marketplace.

Procedure

1. Acquire the license for the C4C app for Microsoft Graph API.

2. Navigate to the TSI AppCenter.

3. Click Add License and provide the license acquired.

This will cause Planon ProCenter to download & install the latest version of the C4C app for Microsoft Graph API compatible for the version of the Planon ProCenter environment.

4. Click Configure.

The C4C-App will be in the status Configuration.

5. Click Link App User Group and select the C4C Admin user's user group.

6. Drill-down to the Level Apps > Modules > Details and select the step Module Settings.

7. Select the module c4cappgraph.

8. Provide the following settings:

◦ Access Key: The generated access key for the C4C Admin User.

◦ Notification URL: The URL that Exchange will use to send notifications to the C4C app is:

https://<your Planon environment>/sdk/platform/jaxrs/planonsoftware/com/c4cappgraph/c4cappgraphrest/rest/notification

◦ Subscription Duration: The C4C app for Microsoft Graph API uses the subscription model of Office365 to get notified about events it is interested in for the resources (rooms or equipment) it monitors.

Office365 offers a subscription to last for 4230 minutes, which corresponds to nearly three days. The C4C app allows a subscription duration between 5 minutes and 4230 minutes.

If no subscription duration is provided through the app module settings, the default subscription duration is 6 hours. It is recommended to use 120 minutes as the subscription duration.

◦ (Follows only!) Event Recovery days past: This value is used in the recovery task and determines the start date of the period for which Events are retrieved from a resource's calendar (now - days past = start date).

◦ (Follows only!) Event Recovery days future: This value is used in the recovery task and determines the end date of the period for which Events are retrieved from a resource's calendar (now + days future = end date).

Configure C4C linking objects

External Account

An external account links an account in Planon ProCenter to an account in the third-party reservation management system. The account of the third-party reservation management system will be linked through an account identifier, which depends on the related C4C app (e.g. the C4C app for a Microsoft Graph API requires an account identifier to be the email address of an user in Exchange).

External Reservation Unit

An external reservation unit links a reservation unit in Planon ProCenter to a resource in the third-party reservation management system. The resource of the third-party reservation management system will be linked through a resource identifier, which depends on the related C4C app (e.g. the C4C app for Microsoft Graph API requires the resource identifier to be the email address of the resource in Exchange).

For reservation units, make sure that it's property has a time zone linked. The Reservation time zone column (element's panel) displays the time zone of the reservation unit's property - this time zone is leading. Invites are sent in the reservation unit's time zone.

External Reservation / Non-Bookable Period

An external reservation links a reservation in Planon ProCenter to an event in the Calendar of the corresponding resource in the third-party reservation management system, whereas an external non-bookable period links a (virtual) occurrence of a non-bookable period to an event in the calendar of the corresponding resource.

Configure C4C app connection

Procedure

1. Navigate to the TSI C4C-App Connection.

2. Click Add to create a new C4C-App Connection.

3. Provide a Name.

4. Provide a Synchronization behavior (In-the-Lead or Follows) for the C4C-App Connection.

5. Select the Classname belonging to the installed C4C-App's implementation of the Calendar item processor.

6. Provide the settings for the Calendar item processor. For the C4C-App for Microsoft Graph API these are:

◦ Tenant ID: The Tenant ID for which the app was registered in Azure AD.

◦ Client ID: The Client ID of the app registered in Azure AD.

◦ Client Secret: The Client Secret of the app registered in Azure AD.

◦ Prevent Inbound Decline: This setting allows you to surpress or prevent Planon from proactively canceling a reservation when not intended or desired.

When set to Yes, the C4C-App will not decline the Event in Exchange if the corresponding reservation could not be made in Planon.

When set to No (default), the C4C-App will decline the Event in Exchange if the corresponding reservation could not be made in Planon.

This functionality applies to both In -the-lead and Follows connections.

◦ Send Outbound Invitation (Y/N): Indication whether C4C should add the organizer as an attendee to the event that is created in a Room resource for an outbound synchronization. Adding an attendee to the event will cause Exchange to send an invite to that attendee.

◦ Add Virtual Meeting (Y/N): Indication whether C4C should ask Exchange to create a Virtual Meeting when a Reservation gets synchronized to Exchange.

On Orders, a field of type URL will be used to save the virtual meeting.

◦ Use proxy (Y/N): Indication whether the C4C-App should set up a connection to O365 through a proxy. If enabled, then it will use the values provided in proxy host name and proxy host port.

◦ Proxy host name: The host name of the proxy to be used.

◦ Proxy host port: The port number of the proxy to be used.

◦ Delete original subject: Deletes the original subject when enabled (if Append Organizer to Subject is not enabled, then the subject will be replaced by a translation of No subject)

◦ Append Organizer to Subject: Adds either the name (inbound sync) or email address (outbound sync) to the subject.

7. (Optional) Provide custom generic templates for the notifications sent by C4C upon a synchronization action (e.g. Accept, Decline, Cancel, etc.).

8. Save the C4C-App Connection.

9. Perform a status transition to the status ACTIVATED (for the C4C-App for Microsoft Graph API this will trigger a subscription process for each External reservation unit that is active and belongs to the activated C4C-App connection).

Configure external accounts

Take the following steps to configure the external accounts for a C4C app connection.

Procedure

1. Navigate to the TSI Enterprise Talk (PEET).

2. Import PEET definition C4C-ONB-EA.

3. Select the imported PEET definition and drill-down to the level Documents and select the document C4C-ONB-IMP-EA1.

4. Navigate to the step Business Objects and select the business object related to External Accounts.

5. Select the field definition C4CAppConnectionRef, which is the reference to a C4C app connection.

6. Configure the default value for this to be the C4C app Connection that was created in the previous step.

7. Go back to the level Definitions and run the PEET definition C4C-ONB-EA.

8. After the run is completed you can go to the TSI C4C Processing, to the step External Accounts to verify the result.

Configure external accounts - without Enterprise Talk definition

If you do not want to run the PEET definition, then you can also add an External Account by taking the following steps.

Procedure

1. Navigate to the TSI, C4C Processing.

2. Go to the step External Accounts.

3. Click Add to create a new External account.

4. Provide the following details:

◦ Account Identifier: the identifier for the user, which is used by the installed C4C app (e.g. the C4C app for Microsoft Graph API requires this to be the email address of the user)

◦ Account: The account in Planon ProCenter to which the user should be linked

◦ C4C app connection: The C4C app connection for which this External Account is active

◦ Is primary?: Whether the External Account should be used as the primary External Account in an outbound synchronization

5. Save the External Account.

Configure external reservation unit

Take the following steps to configure an external reservation unit.

Procedure

1. Navigate to the TSI, C4C processing.

2. Go to the step External Reservation Units.

3. Click Add to create a new external reservation unit.

4. Provide the following details:

◦ Resource Identifier: The identifier for the resource, which is used by the installed C4C app (e.g. the C4C app for Microsoft Graph API requires this to be the email address of the resource).

◦ Reservation Unit: A reservation unit in Planon ProCenter to which the resource should be linked.

The reservation unit must reference a Standard Order or a Standard Order has been configured in Order Settings.

◦ Is production mailbox?: Indicator whether the external reservation unit is in use given the environment (e.g. in non-production environments this indicator should be set to No when you want to be able to synchronize the resource).

◦ C4C app connection: The C4C app connection for which this external reservation unit is active.

◦ Provide a user status for a reservation's status corresponding with an event being CANCELED.

◦ (Optional) Provide a user status for a reservation's state corresponding with an event being ACCEPTED.

◦ (Optional) Provide a user status for a reservation's state corresponding with an event being TENTATIVELY ACCEPTED.

◦ (Optional) Provide links to Event-Based Notifications for the notifications sent by C4C upon a synchronization action (e.g. Accept, Decline, Cancel, etc.).

5. Save the External reservation unit.

6. Change status to ACTIVATED.

For the C4C-App for Microsoft Graph API this will trigger a subscription process for the involved resource.

After a subscription attempt, the field App - custom field will show the outcome of the subscription).

Configure C4C scheduled tasks

The following diagram shows a series of scheduled tasks related to C4C that have to be configured.

There are system scheduled tasks that come with the product C4C and there are user scheduled tasks that come with the C4C app for Microsoft Graph API.

Configure system scheduled tasks for C4C

The product C4C has three System Scheduled Tasks that can be configured in a similar way. Follow the steps below to configure the task.

Procedure

1. Navigate to the TSI Scheduled Tasks and step Scheduled Tasks.

2. Select one of the following System Scheduled Tasks.

◦ Remove obsolete External Reservations & External Non-Bookable Periods (including C4C Processing Items).

◦ Archive External Reservations (including C4C Processing Items) that are successfully synchronized and for which the start date/time of the reservation is 30 days ago.

◦ Remove C4C Mail Reports that are older than 7 days.

3. Select and configure the frequency of the task.

◦ Remove obsolete External Reservations: each day

◦ Archive External Reservations: each week

◦ Remove C4C Mail Reports: each week

4. Save the task.

5. Activate the task.

Configure user scheduled tasks for C4C

Prior to the configuration, you must check the configuration of the existing system scheduled task Task User Extension, which has to be configured correctly for the task user extensions.

This task needs to run every 5 minutes.

The C4C app for Microsoft Graph API provides two Task User Extensions that can be configured in a similar way. Follow the steps below to configure the tasks.

Procedure

1. Navigate to the TSI Scheduled Tasks and step Task User Extensions.

2. Click Add to create a new task.

3. Provide a Code for the task (e.g. C4C-SUB for the Subscription Task).

4. Select a Classname:

◦ C4C Subscription: This Task User Extension will periodically create and patch subscriptions for resources that are linked to active External Reservation Units.

◦ C4C Recovery: This Task User Extension will periodically recover Events and Reservations. This behavior of this recovery depends on the synchronization behavior of the C4C app connection.

There will only be five recovery attempts for an external reservation. After five attempts, inbound events will be declined. Outbound events remain as is and can be followed up. After resolving the issue, you can click Reset recovery attempts on the external reservation after which recovery will be re-attempted.

5. Select the C4C Admin User for the field User.

6. Select the and configure the frequency of the task.

◦ C4C Subscription: This depends on the number of External Reservation Units configured and when one run of subscription completes for them. If this is less than 110 minutes, then put 110 minutes.

◦ C4C Recovery: This depends on the synchronization behavior of the C4C app connection and the number of External Reservation Units configured.

For Synchronization Behavior In-the-Lead: 4 hours (as it only needs to synchronize pending Event Messages).

For Synchronization Behavior Follows: 12 hours (as it needs to synchronize all events in the calendar of the resource for a period bounded by the C4C app module settings configuration for recovery number of days past and future).

7. Provide a start date/time (in the future).

8. Save the task.

9. Activate the task.