| Table of Contents | ||
|---|---|---|
|
| Info |
|---|
This article provides background information about the concept ‘External app’ and should be read in context of setting up an integration with one of the other Spacewell products (e.g. Workplace Experience or Workplace Analytics) |
1. General
An external app is an object in Workplace Management that is an object used to configure and monitor the connection to an external system. An external app makes sure It ensures that the external system can access the Workplace Management environment to fetch all retrieve relevant data and input data, if applicable. The external app will also facilitate in , provide input. Additionally, the external app facilitates access for the Workplace Management environment being able to access communicate with the external system.
All the configured external apps that are configured for a tenant can be found via under:
Client settings → Authentication → Page include ‘External apps’.
...
This external External apps are also used when setting up the integration integrations between the Spacewell products (e.g., Workplace Experience and Workplace Analytics). Most of the configuration is done automatically when following automated during the relevant module activation steps. However, some specific certain steps may require manual actions and it can be relevant to know some details about , and understanding the details of the external app can be helpful for debugging purposes. Therefor the next steps go into detail about
The following sections provide an in-depth explanation of the general settings and options that apply applicable to every all external appapps, as well as the specify specific details of for the specific external apps for the used with native Spacewell products.
1.1 Trust relation
Each external app should consists of includes a trust relation. A trust relation , which is used to configure the authentication needed to access required for accessing the Workplace Management environment via through the external app. The authentication type of authentication is configured in the trust relation and is automatically determined by is determined automatically based on the external app type . A authentication type can be a username/password, twoand 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, the credentials such as a username/password or (an access ID) /key needs to must be shared with the external system to be able enable access to access the external app. Details about this can be found via the relevant module activation
| Info |
|---|
Via the different applicable module activations, a dedicated ‘Spacewell Integration’ user is automatically created and/or linked to all the trust relations as the default authorized system user. |
| Note |
|---|
Make sure Important: Ensure that the Authorized authorized system user linked to the trust relation is an active user that has with administrator access, as this . This user is ( automatically ) used utilized to perform the ‘administrator’ administrator actions via the external application. If this the user is not active or not allowed to perform the relevant actions inactive or lacks the required permissions (e.g., to fetch certain specific master data), the integration will not workfail to function properly. |
1.3 Operation mode
The operation mode of the an external app determines on specifies which server the external app is accessible from. The available operation modes are:
Production
...
Backup
...
Test
...
Development
These modes correspond to the server of the Workplace Management environment's servers (e.g., axpr, axbk, axts, etc. (Clusters and Servers)). If , based on clusters and servers).
For example, if the operation mode is set to Production, then the external app will not be accessible via through the backup or test server servers for the external system, for example. . The selected operation mode ensures that the app's accessibility aligns with the intended server environment.
| Note |
|---|
Important: If the operation mode is left empty, the external app |
...
will be accessible on all servers |
...
once it is synced (daily for the backup server and every |
...
6–8 weeks for the test server). However, this should be avoided at all costs, as it can lead to issues. For example, testing on a backup or test server could inadvertently send data to the external system's production server if the operation mode is not specified. |
1.4 Commission
The commission of the an 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 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 activeset to Active. If an external the app is no longer used, then the commission can in use, it should be set to Deactivated and the external app will to ensure it is 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 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 is created, the its category determines the external app app’s type. The external app type determines defines specific options and setting settings relevant for to the specific external system the external app is used forapp will interact with. By default, the following categories/types are available:
Workplace Experience
Analytics
Calendar integrationIntegration
It Additionally, it is also possible to create an external app in the default category (via by clicking the ‘New’ button in the external app overview shown above). This can be used option is useful for setting up an external app ( for authentication purposes ) for as part of a custom integration.
Next to Beyond the above mentioned general external app configurationconfigurations mentioned earlier, each of the 3 three standard types has additional specific configuration. In the next chapters, the different types and additional configuration and options are described for each type, 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 'Workplace Experience' is used 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 can to fetch the relevant data, including user datainformation, reservation data details, and reservable object dataobjects. Reservations and/ or visitors created via a Workplace Experience touchpoint touchpoints are created in synchronized with Workplace Management via through the external app. Reservations created Similarly, reservations made in Workplace Management , will also be are visible on the Workplace Experience touchpoints, ensuring seamless data exchange.
The By default, the Workplace Experience external app is set up by default created by Customer Support when setting up the during the initial configuration of a new Workplace Management environment for the customer.
...
The Workplace Experience external app consists of several includes , which are used to link all relevant master data objects applicable for the to Workplace Experience touchpoints. The Buildings, Areas, 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. Objects not linked to the external app, Unlinked objects will not be available/visible accessible in the Workplace Experience touchpoints.
...
Via the module activation settings or via ‘Module settings' → 'Workplace Experience’ tab it is possible to determine if new
You can configure whether new objects (e.g., Buildings, Areas, Reservable assetsAssets, Reservable catalog items and Cost centers Catalog Items, or Cost Centers) are automatically or manually added to the Workplace Experience external app or manually. So if the . 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 exposed for example, they can set to be automatically exposed in Workplace Experience, the corresponding setting to automatic and prevent the user from having it to do manuallycan be enabled to avoid manual linking.
...
| Info |
|---|
After adding the objects to the external app in Workplace Management, it takes may take up to 4 hours for the objects to be become available in Workplace Experience. |
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’:
...
| Info |
|---|
Ensure that the cache configuration is only enabled after the initial imports are completed. |
...
Enabling it prematurely will cause the cache to be invalidated and recomputed for every object during the import process. This can significantly impact performance (slowing down the imports) and is unnecessary if the customer is not yet live. |
2.1.3 Optimizing Availability Checks
In Workplace Management there are , several configuration options which are relevant when using influence the reservations module. These include:
Access to reservable object: Reservable Objects:
Custom access settings can restrict reservations to specific users or system groups. Only users from a particular system group are allowed to reserve the objectBlocked 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)
...
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 for example, the application will show the user displays all available and not available (unavailable reservable ) objects. Objects being not available can be due to several reasons:
...
may be unavailable for reasons such as:
The user lacks 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.
...
.
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 to reservable objects restrictions, or regimes with limited availability , each of can disable 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.
...
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.
...
| Info |
|---|
By default, these skip checks are enabled. Only disable them if the customer specifically requires a certain check. Be cautious when enabling these checks for tenants with large floorplans or a high number of reservable objects, as they can significantly impact performance when searching for reservable objects or loading floorplans via Workplace Experience touchpoints. Important: Skipping these checks only applies to Workplace Experience touchpoints and does not affect the use of Workplace Management for creating or managing reservations. |
2.1.3
...
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.
...
.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:
Open the tagged object.
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.
| Info |
|---|
By default, 'Disable access checking' is enabled for all reservable objects tagged to the Workplace Experience external app. Only disable this setting if the customer requires specific access checks. Be mindful when enabling access checks for many reservable resources, especially for tenants with large floorplans or numerous reservable objects, as these checks can significantly impact performance when searching for reservable objects or loading floorplans via Workplace Experience touchpoints. Important: Skipping access checks for specific reservable resources applies only to Workplace Experience touchpoints and does not affect the use of Workplace Management for creating or managing reservations. |
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.3 Calendar integration
The Calendar Integration external app type 'Calendar integration' is used to expose allows the Workplace Management environment to integrate with Exchange or Google Workspace. Room- This enables the synchronization of room and reservation data can be exchanged between Workplace Management and the calendar application in order to sync , ensuring meetings created in one of the two applications.The calendar integration in either system are automatically reflected in the other.
By default, the Calendar Integration external app is by default created and configuration to a certain extend via partially configured during the module activation process. Additional ( manual ) configuration is described belowconfiguration 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 partly partially pre-configured via during the calendar integration Calendar Integration module activation. The However, the client_id and client_secret must still need to be filled in. More information about obtaining manually entered.
For more information on how to obtain the client_id and client secret can be found in _secret, refer to 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 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.
...
Once the reservable objects are linked to the external app, the corresponding reservable resources need to must be mapped to the corresponding resource from their counterparts in Exchange or Google Workspace. Mapping the resources is described Instructions for mapping resources are detailed in the configuration guide..
Once After a mapping is successfully created between a Workplace Management reservable resource and a resource from an Exchange/Google Workspace resource, an observation is automatically created in generated within the external app. The This observation is used serves to bundle all notifications related to a the specific resource, ensuring streamlined communication and synchronization.
...
2.3.4 Workflow interaction
...