Configure Planon ProCenter

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

The following figure displays all steps for configuring Planon ProCenter with respect to Connect for Calendars (C4C).

Configure User Groups and Users

The sequence below shows a list of actions to perform such that the User groups and Users are correctly configured for Connect for Calendars.

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 for User Groups (aka Account Groups) involved in Reservation Management are linked to certain Product Definitions. The table below provides an overview of the Product Definitions and to which type of User Group need to be linked.

Product Definition	User Group	Reason
EnterpriseServiceAPI	C4C Admins	This product definition is required by the C4C app so 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/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 so that it can use the PaaP API.
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 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 duing 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 EWS API

Prior installing the C4C app you should acquire its license from the Planon License Desk. Once the license for the C4C app for Microsoft Graph API has been acquired you can add that license through the TSI - AppCenter. By adding the license through the AppCenter, the C4C app will be downloaded and installed from the Planon Marketplace.

Procedure

1. Acquire the license for the C4C app for Microsoft EWS 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 compatible version of the C4C app for Microsoft EWS API for the version of the Planon ProCenter environment.

4. Click Configure.

The C4C app will be in the state Configuration.

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

6. Go to Apps > Modules > Details and select the step Module Settings.

7. Select the module c4cappews.

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/c4cappews/c4cappewsrest/rest/notification

◦ Subscription check frequency (in minutes): The C4C app for Microsoft EWS API uses the subscription model of an on-premise Exchange environment. The Subscription check frequency will be used by Exchange to send a Status notification when the Room Resource has been idle for the provided time.

The C4C app for Microsoft EWS API will process this Status notification so that it knows that the subscription is still active.

We recommend to use 30 minutes as the subscription check frequency.

◦ (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

Once the C4Ca pp for Microsoft EWS API is installed, you can start to configure the C4C linking objects:

• C4C app Connection

• External Accounts

• External Reservation Units.

The following figure shows the steps that need to be performed.

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. Configure the account that is used as C4C Administrator. This account will receive the notifications of the type EXCEPTION, when there is a problem in the synchronization.

6. Select the Classname belonging to the installed C4C app's implementation of the Calendar Item Processor.

7. Provide the settings for the Calendar Item Processor. For C4C app for Microsoft EWS API, these are:

a. Authentication-related:

- Exchange EWS URL: The URL of the Exchange Web Services for the Exchange Server.

- Exchange Version: The version of the Exchange Server. Valid values are 2013, 2016 and 2019.

- Username: The email address of a service account in AD that is allowed to impersonate the Room Resources.

- Password: The password belonging to the service account in AD.

b. Synchronization-related:

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

- Prevent inbound decline (Y/N): Indication whether the C4C-App should decline the inbound synchronization of an Event in case no Reservation could be created for it.

This setting is useful in the “true”-FOLLOWS scenario and when performing a dry-run of a C4C Onboarding scenario.

- Delete original subject (Y/N): Deletes the original subject when enabled (if Append Organizer to Subject is not enabled, then subject will be replaced by a translation of “No subject”)

- Append Organizer to Subject (Y/N): Adds either the name (inbound sync) or email address (outbound sync) to the subject.

8. (Optional) Configure a password (can be used instead of the Client Secret)

9. Configure the notification behavior:

◦ Notification Behavior: Configure who should receive the notification: No notifications, Booker, Organizer or Booker and Organizer

◦ Use User's Sender's email address (Y/N): Configure whether Planon should use the sender's email address of the User if applicable (default: Yes).

◦ Separate notifications for occurrences (Y/N): Configure whether Planon should send separate notifications for occurrences or one notification for the recurrent Meeting (default: No).

10. (Optional) Configure C4C Notification Templates.

11. Save the C4C app connection.

12. Change status to 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

Complete the following steps to configure the External accounts for a C4C app connection.

Procedure

1. Navigate to the TSI Enterprise Talk.

2. Import Enterprise Talk definition C4C-ONB-EA.

3. Select the imported Enterprise Talk definition and go to the level Documents and select the document C4C-ONB-IMP-EA1.

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

5. Go to and 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 Enterprise Talk definition C4C-ONB-EA

8. After the run is done, you can go to the TSI C4C Processing and select the step External Accounts to verify the outcome.

Configure external accounts - without Enterprise Talk definition

If you do not want to run the Enterprise Talk definition, you can also add an External Account by completing 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

Complete 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 EWS 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 status corresponding with an Event being ACCEPTED.

◦ (Optional) Provide a user status for a reservation's status 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 EWS API.

Configure system scheduled tasks for C4C

The product C4C has three System scheduled tasks that can be configured in a similar way. Complete the following steps 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 the 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, 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 each 5 minutes.

The C4C app for Microsoft Graph API provides two Task user extensions that can be configured in a similar way. Take the following steps 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. The behavior of this recovery depends on the Synchronization behavior of the C4C app connection.

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 change it to 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.