1. General

An external app is an object in Workplace Management that is used to configure and monitor the connection to an external system. An external app makes sure that the external system can access the Workplace Management environment to fetch all relevant data and input data, if applicable. The external app will also facilitate in the Workplace Management environment being able to access the external system.

All the external apps that are configured for a tenant can be found via Client settings → Authentication → Page include ‘External apps’

This external apps are also used when setting up the integration between the Spacewell products (e.g. Workplace Experience and Workplace Analytics). Most of the configuration is done automatically when following the relevant module activation steps. However, some specific steps require manual actions and it can be relevant to know some details about the external app for debugging purposes. Therefor the next steps go into detail about the general settings and options that apply to every external app, as well as the specify details of the specific external apps for the native Spacewell products

1.1 Trust relation

Each external app should consists of a trust relation. A trust relation is used to configure the authentication needed to access the Workplace Management environment via the external app. The type of authentication is configured in the trust relation and is automatically determined by the external app type. A authentication type can be a username/password, two-way SSL certificate, a secret key, etc. Depending on the authentication type, the username/password or (access ID) key needs to be shared with the external system to be able to access the external app.

1.3 Operation mode

The operation mode of the external app determines on which server the external app is accessible. The operation modes Production, Backup, Test and Development are available and refer to the server of the Workplace Management environment (axpr, axbk, axts, etc. (Clusters and Servers)). If the operation mode is set to Production, then the external app will not be accessible via the backup or test server for the external system, for example. If the operation mode is empty, the external app is accessible on all servers (as soon as the external app is synced to all servers, which is daily for the backup and every 6-8 weeks for the test server).

1.4 Commission

The commission of the external app determines if the external app is active or not or in which direction the external app is accessible. The commission options are Active, Deactivated, Incoming allowed and Outgoing allowed. By default the external app commission should be active. If an external app is no longer used, then the commission can be set to Deactivated and the external app will no longer be accessible, even with the secret key used by the external system. If for some reason the external app should only go uni-directional, then this can be determined via the commission Incoming allowed or Outgoing allowed, but this will be considered as non-default configuration (deviating from the default/customization).

Additional configuration on the external app depends on the external app type. More on the different types in the next chapter.

2. Types

When an external app is created, the category determines the external app type. The external app type determines specific options and setting relevant for the specific external system the external app is used for. By default the following categories/types are available:

• Workplace Experience

• Analytics

• Calendar integration

It is also possible to create an external app in the default category (via the ‘New’ button in the external app overview shown above). This can be used for setting up an external app (for authentication purposes) for a custom integration.

Next to the above mentioned general external app configuration, each of the 3 standard types has additional specific configuration. In the next chapters, the different types and additional configuration and options are described for each type.

2.1 Workplace Experience

The external app type 'Workplace Experience' is used to expose the Workplace Management environment to Workplace Experience touchpoints such as the Workplace App, Go, Room displays, Kiosks and Floor displays. Workplace Experience can fetch the relevant user data, reservation data and reservable object data. Reservations and/or visitors created via a Workplace Experience touchpoint are created in Workplace Management via the external app. Reservations created in Workplace Management, will also be visible on the Workplace Experience touchpoints.

The Workplace Experience external app is by default created by Customer Support when setting up the new Workplace Management environment for the customer.

2.1.1 Linking objects

The Workplace Experience external app consists of several includes, which are used to link all relevant master data objects applicable for the Workplace Experience touchpoints. The Buildings, Areas, Assets (Equipment), Catering items (Services), Cost centers and System users can be linked via the corresponding includes and will be exposed to the Workplace Experience touchpoints. Objects not linked to the external app, will not be available/visible in the Workplace Experience touchpoints.

Via the module activation settings or via ‘Module settings' → 'Workplace Experience’ tab it is possible to determine if new Buildings, Areas, Reservable assets, Reservable catalog items and Cost centers are automatically added to the Workplace Experience external app or manually. So if the customer wants all Workplace Management buildings and areas exposed for example, they can set the corresponding setting to automatic and prevent the user from having it to do manually.

2.1.2 Skip checks

In Workplace Management there are several configuration options which are relevant when using the reservations module:

• Access to reservable object: Only users from a particular system group are allowed to reserve the object

• Blocked dates: Reservable objects are blocked during a specified period

• Regime: Regimes are linked to reservable objects with a limited availability (only reservable between 08:00 AM and 05:00 PM)

If a user opens a floorplan in the Workplace App for example, the application will show the user all available and not available (reservable) objects. Objects being not available can be due to several reasons:

• No access to the object

• Object is already reserved

• Object is not reservable at all

• Blocked date apply to the object within the period

• Regime with limited availability linked to object

The application needs to check each of the above, to determine if a reservable object is available. A lot of reservable objects on a floorplan means the above checks need to be executed for all reservable objects on the floorplan.

If customers do not use blocked dates, specific access to reservable objects or regimes with limited availability, each of these checks can be disabled (skipped) via the settings on the external app. Skipping these checks will result in faster fetching of the relevant data and thus a better user experience.

2.1.3 Cache configuration

The cache configuration linked to the external app is also an important additional configuration for Workplace Experience. The applicable cache configuration (version) is automatically added to the external app by default. A cache configuration consists of several filters and reports which can be used by the external system to fetch data. For each filter or report it is determined, if the data needs to be cached or not.

Caching data is used to make fetching data periodically much faster. For example, data which does not change often (like buildings) are cached once every x hours. Every next request for building data does not have to search for the buildings and can simply consult the already cached data, which makes it a lot faster.

Next to cached data, other data can not be cached. Data which can change and always needs to be up-to-date, cannot be cached. For example, if a user looks at a floorplan from the Workplace App, the user should see up-to-date reservation data to determine which workplaces or meeting rooms are available to reserve.

2.1.4 Check-in options

In the external app, it can be specified per category and building if the user needs to check-in the reservation, when it is about to start. More information about the check-in settings can be found in the module activation additional settings.

2.1.5 Workflow interaction

In the external app the workflow interaction determines which categories are used for single and recurring reservations created from the external system. By default the correct categories are automatically used and the workflow interaction on the external app should only be used, if there is a deviation from the default categories.

2.1.6 Ticketing

It is possible to create a ticket via the Workplace App. More information about ticketing from the Workplace app can be found via the Workplace Experience integration: simple ticketing module activation and information.

2.2 Analytics

By activating the Analytics integration via the module activation, the external app is automatically created and configured correctly. There are no additional configuration options in the external app for Analytics apart from the general settings described above.

2.3 Calendar integration

The external app type 'Calendar integration' is used to expose the Workplace Management environment to Exchange or Google Workspace. Room- and reservation data can be exchanged between Workplace Management and the calendar application in order to sync meetings created in one of the two applications.

The calendar integration external app is by default created and configuration to a certain extend via the module activation. Additional (manual) configuration is described below.

2.3.1 Mappings

The mappings to establish the integration between Workplace and Exchange/Google Workspace are created and partly pre-configured via the calendar integration module activation. The client_id and client_secret still need to be filled in. More information about obtaining the client_id and client secret can be found in the /wiki/spaces/KB/pages/362545217 for the calendar integration.

2.3.2 Linking reservable rooms

The Calendar integration external app consist of an include, which is used to link all relevant reservable rooms, which are in scope for the calendar integration. Reservables not linked to the external app, are not in scope for the calendar integration and thus will also not sync reservations/meetings created from Workplace to the external calendar application and visa versa.

2.3.3 Observations

Once the reservable objects are linked to the external app, the reservable resources need to be mapped to the corresponding resource from Exchange or Google Workspace. Mapping the resources is described in the configuration guide.

Once a mapping is created between a Workplace Management reservable resource and a resource from Exchange/Google Workspace, an observation is automatically created in the external app. The observation is used to bundle all notifications related to a specific resource.

2.3.4 Workflow interaction

In the external app the workflow interaction determines which categories are used for single and recurring reservations created from the external system. By default the correct categories are automatically used and the workflow interaction on the external app should only be used, if there is a deviation from the default categories.

2.3.5 Event log

The event log on the calendar integration external app is an overview of all events send and received from the calendar integration. This overview can be used for debugging purposes.