Planon Connect for MazeMap

Introduction

This document describes the functionality and usage of the Planon Connect for MazeMap integration app.

This digital wayfinding solution boosts productivity and improves the experience for occupants and visitors at campus sites and in large buildings such as universities, hospitals, offices and conference venues, by making it easier for them to navigate from A to B, both indoors and outdoors.

Indoor visualisation and wayfinding is an important element in occupant-centric processes and services like room reservations, workplace booking and visitor management. Combining MazeMap’s digital wayfinding solution with Planon’s platform enables organisations to offer a valuable navigation solution and enhanced experience to building users.

Prerequisites

Environment

This solution is designed to work with Planon Live L71 and above.

Constraints

• In order to use meeting room integration it is required to have OAuth configured with Planon. This app has been tested on the Planon cloud using keycloak OAuth. Configuring OAuth is out of scope for this guide.

Required (free)fields

• A (free) field on Property of type ‘CodesCodeName’ with default ‘YESNO’ picklist linked to indicate whether the property has been synchronized to MazeMap

• A (free) field on Floors of type ‘CodesCodeName’ with default ‘YESNO’ picklist linked to indicate whether the floor (the DWG) should be synchronized with MazeMap

• The user defined system name of the fields above should be ‘UsrMazeMapFlag’

Assumptions

This design and functionality of the solution is based on the following assumptions:

1. The filenames for the DWG drawings in Planon are unique

2. Labels of spaces in the DWG drawings are mapped to the space code in Planon

3. The free fields that have to be configured on property and floor BO’s to indicate whether the BO has been synchronized to MazeMap should have the user defined systemname ‘UsrMazeMapFlag’.

4. It is assumed you are in posession of a MazeMap API Key and API Key ID (required for base data synchronization)

Features

The purpose of this app is to provide integration between Mazemap and Planon. This allows Planon customers to synchronize their CAD drawings and Planon data with Mazemap for indoor navigation and wayfinding.

Feature 1 - Update campus map and base data in MazeMap

In Planon ProCenter, data from an AutoCAD drawing (.dwg format) can be imported, by mapping Planon ProCenter business objects and fields with the entities (polylines, blocks, attributes, and text) that are present in the layers of the AutoCAD drawing. The CAD drawings are read into Planon per building, per floor (so not one drawing for the entire campus).

To provide this data to MazeMap both the drawings (DWG) and base data such as property and floor data can be sent to MazeMap using an TSI action in the Planon client.

Feature 2 - Synchronize space details and POI’s with MazeMap

To provide MazeMap with the latest space details from Planon and display these on the map this data can be automatically synchronized with MazeMap every 24 hours. If the user selects a space on the map, the following basic data, which is stored in Planon ProCenter, can be displayed:

• Space number and floor

• Space name

• Space type

Feature 3 – Meeting room integration

The meeting room integration feature allows users to book spaces and/or workspaces in Planon from MazeMap. Besides this the current reservation unit availability will also be displayed in MazeMap.

• Display reservation unit status (available, occupied)

• Boom reservation unit from MazeMap

• Cancel reservation from MazeMap (only for bookings created by user)

• Display upcoming bookings

Feature 4 – Route optimization

The route optimization feature allows your workers to plan an optimal route when working at a specific site.

Feature 5 – Integrate MazeMap in Planon Mobile App

A mobile module has been created that loads in the Mazemap view into the Planon app. This is a full size mobile page. A user is able to do the following in this page:

• scroll through the Mazemap campus

• search for rooms using the search bar

• zoom in and out

• select a floor and look at the rooms on this floor

• view extra information in the information window

The mobile extension also consists of multiple cards that can be added to specific pages in the mobile app.The cards all have the same functionality of showing a location on the Mazemap view. The cards have a few minor changes as in what page it is shown and what (referenced) location it must show.

How does it work

This chapter contains the functional and technical description of the solutions proposed.

TSI Action to upload (initial) manifest

The first step in setting up the integration is uploading manifest data to MazeMap. Uploading a manifest to Mazemap is only required when setting up for the first time or in case (major) changes have been made to a campus, a new campus has to be added etc.. Uploading a manifest also requires manual intervention on the Mazemap side. Therefore this is a deliberate action which has to be triggered by the user and not something that is automatically triggered. When uploading a new manifest any previous manifest will be overwritten!

The screenshot above shows the Campus Manifest Synchronization TSI Action. Once opened from the action panel it displays the information which will be synchronized with MazeMap. Pressing the ‘Send to MazeMap’ button will provide the information to the MazeMap updates API and a success or failure message will be displayed.

Technical details

This TSI Action calls the MazeMap manifest endpoint as described on the following URL; https://updates.mazemap.com/v1/docs/.

TSI Action to upload DWG drawing

Once the manifest has been uploaded we can upload the drawings. Uploading a DWG to Mazemap is only required when setting up for the first time or in case (major) changes have been made to a floor layout. Uploading a DWG also requires manual intervention on the Mazemap side. Therefore this is a deliberate action triggered by the user and not something that is automatically triggered.

The screenshot above shows the Floor Drawing Synchronization TSI Action. Once opened from the action panel it displays the floors for which the drawing will be synchronized with MazeMap. Pressing the ‘Send to MazeMap’ button will provide the information to the MazeMap updates API and a success or failure message will be displayed.

Technical details

This TSI Action calls the MazeMap drawings endpoint as described on the following URL; https://updates.mazemap.com/v1/docs/.

Task extension to synchronize POI’s

In order to provide POI’s to MazeMap a task extension has been developed which provides the POI’s to a REST service provided by MazeMap. On the MazeMap side POI’s are updated once every 24hrs. All spaces that are part of the property / floors synchronized to MazeMap are send as POI.

Technical details

This task extension calls the MazeMap manifest pois as described on the following URL; https://updates.mazemap.com/v1/docs/.

REST service to allow booking and display of room availability in MazeMap

In order for a user to be able to book rooms and display room status from MazeMap, Planon provides a REST service that exposes this information to MazeMap. The REST service exposes this data for all spaces that are linked to a reservation unit in Planon. Creation of new reservations is done based on a configurable standard order. The app adds the reservation unit, requestor and start/end datetime fields to this.

• This service requires OAuth and only works on Planon environments with OAuth configuration in place!

• All date/time interactions between Planon and MazeMap are in UTC timezone

Technical details

In the document ‘MazeMap Requirements for meeting room integration.pdf’ MazeMap has provided a list of functionalities that the endpoint should have. This includes;

1. Get current room availability

**

2. Get room schedule

3. Create event

Notice the URL for create event is using the services sdk since for this request the actual user session is used (via OAuth) instead of a Planon accesskey

5. Get user events

Notice the URL for user events is using the services sdk since for this request the actual user session is used (via OAuth) instead of a Planon accesskey

6. Cancel event

All the features above have been implemented in the REST service mentioned which are deployed by this app. An ‘event’ is a Planon reservation in this case.

BR and REST service to allow MazeMap to retrieve work assignment, order, and asset details

In order for workers in the field to generate an optimal route for handling their work on a campus MazeMap offers a route optimization service. This service can be started from the Planon Mobile field services app. This works in the following way:

1. When a order is assigned to a tradesperson a business rule generates a communication log that contains a MazeMap link. This link contains information such as the campus and the tradesperson for which it is generated.

2. When the link is opened, MazeMap requests a REST service on the Planon side to provide more details on all the work assignments for the engineer on the campus on that day. Based on this information an optimal route will be generated.

Technical details

The webservice that provides MazeMap with the Work Assignment details is implemented on the following endpoint: “…/sdk/platform/jaxrs/planonsoftware/apps/connectformazemap/routeoptimization/workassignments”. As URL parameters the webservice accepts ‘buildingid’ (planon property syscode), ‘engineerid’ (person syscode) and ‘date’.

An example response of this webservice looks like this:

[
    {
        "description": "Check Air Conditioning Units (1M)",
        "plannedBeginDatetime": "2021-05-11T14:00:00",
        "plannedEndDatetime": "2021-05-11T14:30:00",
        "resourcePerson": "Adrian Mease",
        "workOrder": {
            "orderNumber": "243.00",
            "description": "Check Air Conditioning Units (1M)",
            "spaceNumber": "0.16",
            "spaceName": "Office",
            "floorCode": "00",
            "floorName": "Ground",
            "campusCode": "14",
            "campusName": "Columbus Square",
            "propertyCode": "14",
            "propertyName": "Columbus Square",
            "assets": [
                {
                    "code": "000244",
                    "description": "Airco Unit",
                    "vendor": "Hitachi",
                    "classification": "Control climate",
                    "informationText": "Unit is located in top left corner",
                    "spaceNumber": "1.12",
                    "spaceName": "Office",
                    "floorCode": "01",
                    "floorName": "First",
                    "propertyCode": "14",
                    "propertyName": "Columbus Square"
                }
            ]
        }   
    }
]

Installation

This chapter describes the steps required to install this app on your Planon environment.

Installation Process

There are two ways to install the app:

1. Using the Marketplace
2. Manual installation

Install the app by using the marketplace

In case your environment is configured to use the Planon app store the only thing required to install the app is to add the app license in the AppCenter TSI. Planon will automatically download and install the app.

Manual installation

In case you want to perform a manual installation follow the steps below.

1. Open AppCenter TSI from Planon webclient and click on install from action menu

2. Browse to the .ppk file

3. Click OK to install the app and follow the installation process
4. When the app is successfully installed, the app will appear in the AppCenter

5. Add the app license in Apps TSI

App Settings

This chapter describes which settings are available for the connect for MazeMap app. After installation, we can see all the modules in details in the ‘Modules’ section. It is not mandatory to configure all modules, you only have to configure the modules that are applicable for your use cases.

Updates API module

The updates API module contains all features related to synchronizing base data between Planon and MazeMap.

Meeting room integration module

The meeting room module contains all settings required to create bookings from MazeMap and display room availability.

Route optimization module

The route optimization module does not have any settings. All settings related to the route optimization are set on the component settings of the route optimization business rule.

Route optimization Business Rule component settings

Translations

The app contains several translations which can be used to change the labels used in the space description which is send to MazeMap. The translations can be changed in the AppCenter. Select the app and drilldown to ‘Details 🡪 Translations’.

Module settings

The settings for the mobile module page can be found in the TSI AppCenter.

1. Go to the AppCenter or Apps TSI.

2. Select the app ‘connectformazemap’.

3. Go to the Details 🡪 Module settings.

4. Select the module ‘mobilepageservermodule’. Here you can set the module settings for the mobile module:

Activation

Once the app has been configured, you can activate the app by pressing the Active status transition from the action panel. Always make sure that the required User groups are linked correctly and the Configure action is executed before activating the App.

Planon Configuration

After successful installation and activation of the app we need to configure some components in Planon. It is not mandatory to configure all components, you only have to configured what is needed for your business case.

UploadCampusManifest TSI Action configuration

1. Open Field Definer TSI

2. Search BO with system name ‘Property’

3. Select the base BO (in case searched with UDBO name) and update the status to ‘Under Construction’

4. Now go to the ‘Details’ level and select the ‘Extended actions’ section.

5. Click on the ‘Add’ link which is available right side under Extended actions.

6. After clicking on the Add link a new page will be opened and select the ‘General’ tab.

7. Here we need to mention our TSI action details.

8. Select ‘planonsoftware.apps.mazemap.wcx.MazeMapCampusManifestClientExtension’ TSI action class for ‘Web2Client class name’ field.

9. Partner Identifier, App name, App module name fields will be populated automatically after selecting the Web2Client class name field.

10. Now, provide a unique name for the ‘System name’ field and provide values for ‘Code’, ‘Icon’ fields.

11. Now Save the changes.

12. After saving the changes we get an option to update names for the configured TSI action in different languages.

13. Provide names in the ‘Translated name’ section and save the changes.

14. After completing all the above changes now update the base BO status to ‘Completed’.

15. Now, we need to configure the above TSI action in ‘Layouts’.

16. Select the TSI action configured BO and click on ‘Jump to Layouts’.

17. Select the corresponding layout and update the status to ‘Under Construction’.

18. Add the configured TSI action under the ‘Actions’ section and Save the changes

19. After saving the changes update the layout status to ‘Completed’.

20. Now logout and login to reflect the changes.

FloorPlanDrawing TSI action configuration

1. Open Field definer TSI

2. Search BO with system name ‘Floor’

3. Select the base BO (in case searched with UDBO name) and update the status to ‘Under Construction’

4. Now go to the ‘Details’ level and select the ‘Extended actions’ section.

5. Click on the ‘Add’ link which is available right side under Extended actions.

6. After clicking on the Add link a new page will be opened and select the ‘General’ tab.

7. Here we need to mention our TSI action details.

8. Select ‘planonsoftware.apps.mazemap.wcx.MazeMapFloorPlanDrawingClientExtension’ TSI action class for ‘Web2Client class name’ field.

9. Partner Identifier, App name, App module name fields will be populated automatically after selecting the Web2Client class name field.

10. Now, provide a unique name for the ‘System name’ field and provide values for ‘Code’, ‘Icon’ fields.

11. Now Save the changes.

12. After saving the changes we get an option to update names for the configured TSI action in different languages.

13. Provide names in the ‘Translated name’ section and save the changes.

14. After completing all the above changes now update the base BO status to ‘Completed’.

15. Now, we need to configure the above TSI action in ‘Layouts’.

16. Select the TSI action configured BO and click on ‘Jump to Layouts’.

17. Select the corresponding layout and update the status to ‘Under Construction’.

18. Add the configured TSI action under the ‘Actions’ section and Save the changes

19. After saving the changes update the layout status to ‘Completed’.

20. Now logout and login to reflect the changes.

POI Upload Task Scheduler

1. Open Scheduled tasks TSI

2. Select ‘SYSTASKUSEREXTENSION’ job in Scheduled jobs level

3. Now, go to ‘Task user extension’ level

4. Click on ‘Add’ link which is available right side under Scheduled task user extension.

5. After clicking on the Add link a new page will be opened and select the ‘General’ tab.

6. Here we need to mention our task scheduler details.

7. Select ‘planonsoftware.apps.mazemap.tsx.MazeMapPOIsUploadScheduler’ scheduler class for ‘Class name’ field.

8. Partner Identifier, App name, App module name fields will be populated automatically after selecting the Class name field.

9. Now provide the Code, Start date-time, Schedule, User fields as per requirement.

10. After updating the fields save the changes.

11. After saving we need to update the scheduler status to ‘Active’ and also update the ‘SYSTASKUSEREXTENSION’ job status to ‘Active’ in Scheduled job level.

CreateMazeMapComlog BR configuration

1. Open the ‘Field definer’ TSI

2. Search for the Order BO(s) for which you would like to generate MazeMap route optimization comlogs

3. Select the base BO (in case searched with the UDBO name) and update the status to ‘Under Construction’

4. Now go to the ‘Details’ level and select the ‘Extensions’ section.

5. Click on the ‘Add’ link which is available on the right side under ‘Extension usage’.

6. After clicking on the Add action a new page will be opened, fill out the following details:

   1. Classname: “planonsofware.apps.mazemap.CreateMazeMapComlog”

   2. Event type: AU

   3. Sequence: depening on your configuration

7. Fill out the settings as described in the settings chapter

Freefield Configuration

As described in the prerequisites the solution requires two free fields to be available in order to work. One on the Properties BO and one on the Floors BO. Both fields should be of the type ‘CodesCodeName’ with the standard ‘YESNO’ picklist linked to it. Please see the webhelp for more details on how to configure freefields in Planon.

Mobile card configuration

Every mobile card is created for a specific Mobile page. When the ConnectForMazemap app is installed and active, the cards become available in the TSI App configuration. Here you can make the card visible, set the position of the card/block on the page and fill the card settings. When the card is made visible and this is saved, the card will appear in the mobile app.

Mobile card settings

Below is a table that outlines the mobile card settings, including the setting name, its default value, and a description of each setting. These settings can be set in the TSI App configuration.

Mobile card module settings

There are also module settings that have to be configured once and is used for all cards in this app. These settings can be found in the TSI AppCenter.

1. Go to the AppCenter or Apps TSI.

2. Select the app ‘connectformazemap’.

3. Go to the Details 🡪 Module settings.

   Select the module ‘mobilecardservermodule’. Here you can set the module settings for the mobile cards:

Mobile module configuration

The Mazemap mobile module page can be added to the mobile app, using the following steps.

1. Make sure the ConnectForMazemap app is installed and active in the AppCenter TSI.

2. Go to the TSI named ‘TSIs’ and select the ‘Live app – app configuration’ TSI.

3. Set the TSI under construction by clicking on the lock icon.

4. Click the ‘+’ at the selection steps and add the selection step ‘Mazemap’.

5. Complete the action by clicking on the lock icon again.

6. Navigate to the TSI ‘App configuration’ and select the newly added ‘Mazemap’ step.

7. Add a new Mazemap definition and save.

   

8. Make sure the new definition is linked to the correct UserGroups, by linking the user groups in the Action menu:

MazeMap configuration

To fully integrate MazeMap and Planon there is also some configuration required on the MazeMap side. MazeMap will need you to provide the following information in order to do a full configuration.

• Inform MazeMap once you have send the Manifest, Floor drawings and POIs (for basic data integration)

• Provide MazeMap with an Planon access key (for meeting room integration and/or route optimization). See the webhelp on how to generate an access key.

• Provide MazeMap with the OAuth login URL (for meeting room integration)

Troubleshooting

Error handling

For all server side component the errors will be written in the logs. Component that also have an UI (like TSI Actions) should also display any errors in the interface.

Additionaly it must be possbile to enable debug logging which provides more insights in the steps that the code carries out.

The required webservices will return the standard HTTP response codes such as 200, 403, 500 etc.