1. General

An external app in Workplace Management is an object used to configure and monitor the connection to an external system. It ensures that the external system can access the Workplace Management environment to retrieve relevant data and, if applicable, provide input. Additionally, the external app facilitates access for the Workplace Management environment to communicate with the external system.

All configured external apps for a tenant can be found under:
Client settings → Authentication → Page include ‘External apps’.

Open

Open

Example of an external app

External apps are also used when setting up integrations between Spacewell products (e.g., Workplace Experience and Workplace Analytics). Most of the configuration is automated during the relevant module activation steps. However, certain steps may require manual actions, and understanding the details of the external app can be helpful for debugging purposes.

The following sections provide an in-depth explanation of the general settings and options applicable to all external apps, as well as specific details for the external apps used with native Spacewell products.

1.1 Trust relation

Each external app includes a trust relation, which is used to configure the authentication required for accessing the Workplace Management environment through the external app. The authentication type is determined automatically based on the external app type and is set within the trust relation.

Authentication types can vary and may include:

• Username/password

• Two-way SSL certificate

• Secret key

Depending on the chosen authentication type, credentials such as a username/password or an access ID/key must be shared with the external system to enable access to the external app. Details about this can be found via the relevant module activation

1.3 Operation mode

The operation mode of an external app specifies which server the app is accessible from. The available operation modes are:

• Production

• Backup

• Test

• Development

These modes correspond to the Workplace Management environment's servers (e.g., axpr, axbk, axts, etc., based on clusters and servers).

For example, if the operation mode is set to Production, the external app will not be accessible through the backup or test servers for the external system. The selected operation mode ensures that the app's accessibility aligns with the intended server environment.

1.4 Commission

The commission of an external app defines its status (active or inactive) and the direction of its accessibility. The available commission options are:

• Active: The external app is fully functional and accessible.

• Deactivated: The external app is inactive and inaccessible, even if the secret key is still used by the external system.

• Incoming Allowed: The external app only allows incoming connections.

• Outgoing Allowed: The external app only allows outgoing connections.

By default, the external app commission should be set to Active. If the app is no longer in use, it should be set to Deactivated to ensure it is no longer accessible.

In cases where the external app needs to operate in a unidirectional mode (e.g., only incoming or outgoing), the appropriate option can be selected. However, such configurations are considered non-default and are regarded as customizations.

Further configuration options for the external app depend on its type. Details about different app types will be covered in the next chapter.

2. Types

When creating an external app, its category determines the app’s type. The type defines specific options and settings relevant to the external system the app will interact with. By default, the following categories/types are available:

• Workplace Experience

• Analytics

• Calendar Integration

Additionally, it is possible to create an external app in the default category by clicking the ‘New’ button in the external app overview. This option is useful for setting up an external app for authentication purposes as part of a custom integration.

Beyond the general external app configurations mentioned earlier, each of the three standard types has additional, type-specific configurations and options. These will be explained in detail in the following chapters.

2.1 Workplace Experience

The Workplace Experience external app type is designed to expose the Workplace Management environment to Workplace Experience touchpoints, such as the Workplace App, Go, Room displays, Kiosks and Floor displays.
This integration allows Workplace Experience to fetch relevant data, including user information, reservation details, and reservable objects. Reservations or visitors created via Workplace Experience touchpoints are synchronized with Workplace Management through the external app. Similarly, reservations made in Workplace Management are visible on Workplace Experience touchpoints, ensuring seamless data exchange.

By default, the Workplace Experience external app is set up by Customer Support during the initial configuration of a new Workplace Management environment for the customer.

2.1.1 Linking objects

The Workplace Experience external app consists of several includes used to link relevant master data objects to Workplace Experience touchpoints. The following objects can be linked through the corresponding includes:

• Buildings

• Areas

• Assets (Equipment)

• Catering Items (Services)

• Cost Centers

• System Users

Only objects linked to the external app will be available and visible in Workplace Experience touchpoints. Unlinked objects will not be accessible in the Workplace Experience touchpoints.

You can configure whether new objects (e.g., Buildings, Areas, Reservable Assets, Reservable Catalog Items, or Cost Centers) are automatically or manually added to the Workplace Experience external app. This setting can be adjusted via the Workplace Experience module activation or via Module Settings → Workplace Experience tab

For example, if a customer wants all Workplace Management buildings and areas to be automatically exposed in Workplace Experience, the corresponding setting can be enabled to avoid manual linking.

2.1.2 Cache configuration

The cache configuration linked to the external app is an essential part of the Workplace Experience setup. By default, the appropriate cache configuration (version) is automatically added to the external app. A cache configuration includes multiple filters and reports, which the external system can use to fetch data. For each filter or report, it is defined whether the data should be cached or fetched directly.

Benefits of Caching

Caching is used to improve performance by reducing the time needed to fetch data periodically. For example:

• Data that does not change frequently (e.g., building information) is cached every x hours.

• Subsequent requests for such data can simply retrieve it from the cache, significantly speeding up the process.

Non-Cached Data

Some types of data cannot be cached because they need to remain up-to-date. For example:

• When a user views a floorplan in the Workplace App, the reservation data must reflect the latest state to show which workplaces or meeting rooms are available for booking.

In such cases, the data is not cached and retrieves the most recent data directly.

The cache configuration is disabled by default. The implementation consultant needs to enable the cache configuration after the Workplace Experience module activation. This is done by opening the relevant cache configuration (use the highest version if more than 1 is available) and press ‘Enable’:

2.1.3 Optimizing Availability Checks

In Workplace Management, several configuration options influence the reservations module. These include:

• Access to Reservable Objects:
  Custom access settings can restrict reservations to specific users or system groups. Only users from the assigned group can reserve certain objects.

• Blocked Dates:
  Reservable objects can be blocked for specific periods, making them unavailable for reservation. For more details, see Reservable objects.

• Regimes:
  Regimes define the availability of reservable objects (e.g., only available from 08:00 AM to 05:00 PM). For more information, see Managing regimes.

When a user, for example, opens a floorplan in the Workplace App, the application displays all available and unavailable reservable objects. Objects may be unavailable for reasons such as:

• The user lacks access to the object.

• The object has blocked dates within the selected period.

• The object is restricted by a regime with limited availability.

For each reservable object on the floorplan, the application must perform these checks to determine availability. If the floorplan contains a large number of reservable objects, these checks can significantly impact performance.

To improve data fetching speed and enhance the user experience, customers who do not use blocked dates, specific access restrictions, or regimes with limited availability can disable these checks via the external app settings:

• Skip Access Check when searching for reservables

• Skip Blocked Date Check when searching for reservables

• Skip Regime Check when searching for reservables

Disabling unnecessary checks reduces processing time and allows Workplace Experience to display relevant data faster.

2.1.3.1 Selective Access Checking for Reservable Objects

If access to certain reservable resources (e.g., specific meeting rooms) is restricted through custom access settings, and the general 'Skip access check when searching for reservables' setting is not enabled, it is still possible to selectively check access for only those specific resources. This allows the system to skip access checks for other resources where access restrictions are not relevant, improving data-fetching performance and enhancing the user experience in Workplace Experience touchpoints.

This configuration ensures that the system only verifies access for specific reservable resources (e.g., meeting rooms restricted to SMT members) when users search for available resources via Workplace Experience.

By default, access checks are disabled for all reservable objects (e.g., Areas, Assets, Catalog Items) added to the Workplace Experience external app. To enable the access check for specific objects:

1. Open the tagged object.

2. Enable the access check setting for that object.

This selective approach optimizes performance while maintaining access control where needed.

Important: If access checks for specific reservable resources need to be enabled, ensure that the general 'Skip access check when searching for reservables' setting is disabled. Otherwise, all access checks will be skipped, including for those specific resources.

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 Calendar Integration external app type allows the Workplace Management environment to integrate with Exchange or Google Workspace. This enables the synchronization of room and reservation data between Workplace Management and the calendar application, ensuring meetings created in either system are automatically reflected in the other.

By default, the Calendar Integration external app is created and partially configured during the module activation process. Additional manual configuration steps, as outlined below, may be required to complete the setup.

2.3.1 Mappings

The mappings required to establish the integration between Workplace Management and Exchange/Google Workspace are created and partially pre-configured during the Calendar Integration module activation. However, the client_id and client_secret must still be manually entered.

For more information on how to obtain the client_id and client_secret, refer to the Workplace Management configuration guide.

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. Reservable rooms 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 corresponding reservable resources must be mapped to their counterparts in Exchange or Google Workspace. Instructions for mapping resources are detailed in the configuration guide..

After a mapping is successfully created between a Workplace Management reservable resource and an Exchange/Google Workspace resource, an observation is automatically generated within the external app. This observation serves to bundle all notifications related to the specific resource, ensuring streamlined communication and synchronization.

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.