This document describes the actions that need to be performed in the Router and Workplace Management to get a synchronization between an external calendar and Workplace Management.
1. Scope
Setting up the Exchange Integration for Workplace Management.
2. Who is this document for?
Workplace Consultants
Workplace Integration Team
3. Prerequisites
The client needs to have Exchange and Azure set up correctly: /wiki/spaces/WM/pages/119668747
4. Reservation Sync interface / Router configuration (1)
The Reservation Sync interface or Router allows the synchronization of the external calendar (Exchange or Google) and Workplace Management. In the Router, the necessary settings can be set for both the external calendar and Workplace Management.
4.1 Login
You need to login into the Router via https://gcprouter.spacewell.com/login
If you do not have an account, this needs to be requested via the Integration team or the Product team.
4.2 Creating a new tenant
Create a new tenant for the customer. Go to Tenants -> Overview:
Click on + to create a new tenant:
Enter the name of the tenant. This has to be exactly the same as the client reference in Workplace Management.
4.3 Setting up API user and getting credentials
Go to Tenants -> Users:
Click on + to create a new user:
Fill in the values:
Select tenant: the tenant created in the steps above
First Name: optional
Last Name: optional
Email: noreply@spacewell.com can be entered as default value
User Name: A username related to the tenant (e.g. <tenant name>_api)
Password:
Click on Save after the relevant fields are filled in correctly:
Go back to Tenants -> Users and refresh the list.
Open the User just created.
Click on the Shield icon of the user:
Click on Get client credentials:
Copy the Client ID and Client Secret and keep them somewhere save. This information is needed later on in the configuration guide.
4.4 Setting up external calendar settings
Go to Configure -> Sync Settings:
Select the tenant created in the above steps. The following settings can be set. When setting this up for Workplace Management, no changes from the default should be necessary.
Sync Mode
Default: Bidirectional. This determines the sync directions. Inbound and outbound determine if Workplace Management needs to sync to the external calendar, or the other way around. Bidirectional indicates that it should sync in both ways.
Sync Scope
Default: Room Centric. Determines the method of synchronization. Leave this as is.
Calendar Provider
Default: Microsoft Exchange. Is based on the connection that needs to be setup.
IWMS Provider
Default: Axxerion. Leave this as is.
Failure Notifications via Email
Default: non-checked. By checking this, notification e-mail addresses can be provided (comma separated) whom will be reported when there are synchronization errors.
Max Occurrences
Default: 180. This prevents an unlimited number of occurrences from synchronization when looking at scheduled meetings.
Max Updates
Default: 50. This setting prevents a unlimited loop when updating a single reservation.
4.5 Setting up connection settings to external calendar
Go to Configure -> Technical:
Select the tenant created in the above steps. Select the option Microsoft Graph Settings:
Fill in the following fields:
Graph API version: This should be set to v1.0
Azure Account Directory ID: This is the Tenant ID value that has been provided by the client
Client ID: This is the Application (client) ID value that has been provided by the client
Client Secret: This is the Client Secret value that has been provided by the client
Email domains (CSV): This is the email domain that is used by the client. Most commonly this is the domain of the client (i.e. “acme.com”)
Click on Test to test if the integration from the Reservation Sync Interface and Exchange is succesfully working:
If the test is succesfull, click on Save, to save the entered configuration values. If not, some values are incorrect.
5. Workplace Management configuration (1)
5.1 Setting up webservice access in Workplace Management
Login with the system administrator to the Workplace Management environment of the client. Go to Client Settings:
Click on Authentication tab:
If there is already an Access rule to grant access for web services created, the following steps do not apply. Continue with chapter 4.7
Open te Access Rules include and click on New:
Fill in the fields:
Operation mode: Production
Access scope: Web services
Click on New on the Access rules Group include:
Select Grant access for the value Rule type. This will automatically set all the necessary values:
5.2 Setting up external application in Workplace Management
Navigate back to the “Setup > Authentication” tab. Scroll down and open the tab “External apps”. Click on “Create calendar integration”
5.2.1 Setup trust relationship
In the resulting external application, click on the tab “Trust relationship” and then on the link in the “key type” column
Set the “Authorized system user” to a user that has the system administrator group (G001) assigned
Make sure the selected user is unique from any other administrator user. This prevents the reservation synchronization from failing if that administrator user has been blocked due to a bad login attempt
Open the “Trust relationship”
Press on the button “Reveal secret key”
If the button “Reveal secret key” and the field “Secret key” are not visible, make sure the user has the group “License editor” (G101) assigned. Also, the user should be a partner user
When pressing “Reveal secret key”, you are prompted for a password. If you are using a partner user, you might need the “actual” password (not the client password). To gather that one, fill in your personal e-mail on the user, request a new password and use that password. This is a known improvement
Press on the button “Generate key”
When prompted, click on “ok”
Copy the value in the “Secret key” field somewhere where you can use it later on in this guide
5.2.2 Assign system users
Navigate back to the external application and navigate to the “System users” tab. After that, open the “System users” dropdown
Press on “Assign”
Search the users that you would like to add. Select the users and press on “ok”
Make sure that the user that was used during the trust relationship steps is also added here
5.2.3 Assign rooms
Navigate back to the external application and press on “Externally connected”. Then press on “Assign”
Search for the rooms that you would like to enable in the reservation sync and press on “ok”
Open each of the added rooms by clicking on the reference
Fill in the field “External reference” with the address of the room and click on “Save and return”
5.2.4 Create mappings
Navigate to the external application and press on “Mappings” and “New”
If you do not have the button “New”, make sure your user has the “Administrator” (G001) group assigned
Create the mappings in the table below by filling in the “Key” and “Value” fields and press on “Save and return”
key | value |
|---|---|
client_id | Client ID retrieved in user creation section (4.3) |
client_secret | Client secret retrieved in user creation section (4.3) |
grant_type | client_credentials |
token_url | Router URL, most likely https://gcprouter.spacewell.com/user/oauth/token |
webhook | Push URL, most likely https://gcprouter.spacewell.com/push/axxerion |
5.2.5 Set commission and operation mode
On the external application, make sure commission is set to “Active” and operation mode is set to the correct server (most of the times, this will be “production”)
5.2.6 Set default category
On the external application, navigate to the “Workflow interaction” tab and press on “Default for category”
Select the category in which the reservation synchronization should create the reservations. For Workplace, this is “FMB-RESC-19030001”. Than press on “Ok”
6. Reservation Sync interface / Router configuration (2)
6.1 Setting up connection settings to Workplace Management in router
In the router, go to Navigation > Technical
Select the tenant and click on “Generic Connector Settings”
In the resulting form, fill in the fields as below
Reservation Sync Router | Workplace Management value |
|---|---|
URL | URL of the client (https://<client>.axxerion.com/) |
Connector type | AXXERION |
Tenant ID | Leave as is |
Unique name | Client reference |
User or schema name | Username of the created external calendar user (see user that was set when creating the trust relationship) |
Password | This password is not used, but you need to fill in one to test the connection. Enter a random password with lower case, upper case, numbers and special characters. |
App ID | Reference of Workplace Management external application |
Preshared key | Generated key in Workplace Management of external application |
Salt | Static value: adfadf$kalf!@#+8 |
Encryption key | Access ID on ObjectTrustRelation |
Recursion limit | 0 |
Time out | 0 |
Wait period | 0 |
Once done, press on “Test”. You should receive a success message
Once you receive the “success message”, press on “Save” to save the current configuration
IMPORTANT: Do not press “Save” multiple times. If you do, multiple configurations will be created. If this happens, please contact Product and they will fix this for you
6.2 Setting up mappings in router
Press on Navigation > Outlook > Mapping
Select the tenant and press on the “add” button
There is a delay up to 48 hours before the room list is available in the Router.
In the resulting pop-up, select the Exchange room list and the room mailbox. Also select the Workplace room. Click on “Save”. If you do not want a room enabled at first, select the checkbox “enabled”
This will create the mapping between the room in Exchange and the room in Workplace
The initial status will be a triangle with an exclamation mark in it, stating that the connection is Inactive. This is due to the fact that no reservation has been synced yet. As soon as you create a reservation in this room, the status will have a green bell icon
7. Necesarry changes if customer uses custom reservation workflow
If the implementation is done for a none Workplace Management environment (FMB), then the custom reservation workflow needs some changes:
For all cancel connectors (to the status ‘Cancel’) need to have the postsetter: syncActionCode = Cancel.
Create a manual ‘Cancel via Exchange' task for the group ‘Integration external owner’
Set ‘Display in task list’ and 'Display task description’ to No
Link a Cancelgroup from reservation confirmed to the reservation ended
Connector from task to status Cancelled
Function: cancel
Presetter: reservationStatusCode = Cancelled
Set date: cancelTime
Create a manual ‘Change via Exchange' task for the group ‘Integration external owner’
Set ‘Display in task list’ and 'Display task description’ to No
Link a Cancelgroup from reservation confirmed to the reservation ended
Connector from task to status Change
Function: change
Presetter: reservationStatusCode = Change
For all connectors from the first task in the workflow need to have the postsetter: syncActionCode = Synchronize.
Create a connector from the first task in the workflow to reservation confirmed status
Presetter: reservationStatusCode = Confirmed
Condition: syncDirectionCode = Incoming
Add a script to the manual 'Change' connectors to prevent changes can be done to an Inbound reservation.
Recurring reservations
There are also some recurring reservation topics you have to take into account.
In Workplace Management (FMB) the synchronization for Outbound recurring reservations is triggered on the field ‘Schedule.scheduleGenerationStatusCode’. Once this field is set to 'Ready' (all occurences have been generated initially), the syncActionCode is set to Sync (which triggers the communication to Outlook).
In Workplace Management (FMB) a script is linked to Reservation.approveDate, Reservation.closeTime and Reservation.cancelTime. This script sets the corresponding fields on the ReservationSchedule in particular situations.
If all occurences are approved, the ReservationSchedule is also approved
If all occurences are cancelled, the ReservationSchedule is also cancelled
If all occurences are closed, the ReservationSchedule is also closed
If all occurences are cancelled, but some occurences where already closed or cannot be cancelled anymore, the ReservationSchedule is closed
If the client uses a custom reservation schedule workflow, keep these in mind. If you are not sure, contact Product to discuss the case and determine the best solution and possible changes needed to the worklfow.