| 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 in Workplace Management 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.
...
1.1 Data
The data in Workplace Management which needs to be exposed to the external system can be linked to the external app. This makes sure that only the relevant data is exposed to the external system and irrelevant or personal data is not exposed or accessible via the external app.
1.2 Trust relation
Next to the objects, the external app also 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 as 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 key needs to be shared with the external system to be able to access the external appAll configured external apps for a tenant can be found under:
Client settings → Authentication → Page include ‘External apps’.
...
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
| Info |
|---|
Via the different applicable module activations, a dedicated ‘Spacewell Integration’ user is automatically created and/or linked to the trust relations as the default authorized system user. |
| Note |
|---|
Important: Ensure that the authorized system user linked to the trust relation is an active user with administrator access. This user is automatically utilized to perform administrator actions via the external application. If the user is inactive or lacks the required permissions (e.g., to fetch specific master data), the integration will fail 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, for example. servers for the external system. 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 a creating an external app is created, the its category determines the external app app’s type. The external app type determines which type defines specific options and settings relevant to the external system the external app is exposed toapp 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.
Next to Beyond the above general external app configurationconfigurations mentioned earlier, each type has addition specific configuration. In the next chapters, the different types and additional configuration is described for each typeof 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 '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 are created in Workplace Management via the external apptouchpoints 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 also consist consists of several includes , which are used to link all relevant masterdata objects applicable for the Workplace Experience touchpoints. The 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, Catering itemsReservable Catalog Items, 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.
...
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 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.
...
| Info |
|---|
After adding objects to the external app in Workplace Management, it may take up to 4 hours for the objects to 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, 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 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 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.
...
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.
...
| 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 used by the external system to fetch data. For each filter or report it is determined, if the fetched 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 needs to always 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. Determine whether More information about the check-in is required, check-in can be done via scan, when the option to check-in becomes available before the start of the meeting and until what time after the start of the reservation, the user can check-insettings can be found in the module activation additional settings.
...
2.1.5 Workflow interaction
...
It is possible to create a ticket via the Workplace App. In the external app, the default request category and the default problem type can be specified. Requests created from the Workplace App will automatically get the applicable category and the problem type is automatically assigned resulting in the request ready to be picked up by the relevant service teamMore 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 for in the external app for Analytics apart from the general settings described above.
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 calendar integration 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 needs 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. The observation is used to 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
...
Configuration by module activation
Created by CS or via module activation
4. Configuration of the External App
An External App is used to configure and monitor the connection to an external system. An External App can concern multiple objects (such as buildings, areas, system users, assets, catalog items and cost centers), and can define which objects are exposed to the external system.
The External App used for the Workplace Experience integration can be found via the Workplace Experience buttonbar on the administrator startboard (or via Client settings → Aiuthentication tab).
When configuring the External App, you actually determining what Workplace Management objects becoce available in Workplace Experience.
Check cache configuration (only needed once)
The cache configuration is used to periodically cache certain data for Workplace Experience. But this cache configuration needs to be enabled. If the cache configuration is not enabled, the data needs to be fetched every time a touch point does a request. This will result in performance issues.
Press the ‘External App’ button on the administrator startboard
Open the External App configuration by clicking on the reference
Cache configuration tab: check if the most recent cache configuration is enabled (Active = Yes, (green light))
If ‘Active = No (red light)’ > open the cache configuration > click 'Enable'
Manage what objects are exported to Workplace Experience
...
Press the ‘External App’ button on the administrator startboard
Open the External App configuration by clicking on the reference
Buildings include: check if all buildings, that should be visible in Workplace Experience, are shown here. If not, use the ‘assign’ button to manually add (additional) buildings.
Areas tab: check if all areas , that should be visible in Workplace Experience, are shown here. If not, use the ‘assign’ button to manually add (additional) areas
If Services and Equipment (assets and catalog items in Workplace Management) should be reservable via Workplace Experience, make sure to also add these to the External App via the designated includes as well.
If cost centers should be set in (Service) reservations in Workplace Experience, make sure to add these to the External App via the designated include as well
| Info |
|---|
After adding the objects to the External App in Workplace Mamagement, it takes 1-4 hours to be available in Workplace Experience. |
Automatically add new objects to the External App
Via the module activation (see chapter 4) or via the module settings → 'Workplace Experience' tab, it is possible to indicate that (per type of object) any newly created object is added to the Workplace Experience External App by default:
...
...
Linking floor plans to areas and workplaces
...
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.
...