- 1. General
- 2. Types
Info
This article provides background information about the concept ‘API Connector’ 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 API Connector in Asset is an object used to configure and monitor the connection to an external system. It ensures that the external system can access the Asset environment to retrieve relevant data and, if applicable, provide input. Additionally, the API Connector facilitates access for the Asset environment to communicate with the external system.
The Integrations menu on the administrator startboard provides a central location for managing existing integrations. This landing page gives access to the most relevant integration-related configuration and management options.
The landing page provides access to additional information about integrations through a button that links to the knowledge base. It also includes the ‘Module activation’ option, which can be used to activate additional integrations alongside those that are already enabled.
The ‘Active integrations’ section displays a button for each activated integration, providing quick access to its configuration and management options.
Finally, the landing page also provides access to other integration-related settings and overviews, such as Custom web services, Access rules, and the Event log search.
By selecting one of the activated integration buttons, the integration-specific landing page is opened. This page provides access to the configuration and management options for the selected integration.
From the API Connectors overview, you can open the corresponding API Connector by selecting its button. If an integration contains multiple API Connectors, all available connectors are displayed, allowing you to select the appropriate one.
All configured API Connectors for a tenant can also be found via:
Client settings → Authentication → Page include ‘API Connectors’.
API Connectors 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 API Connector can be helpful for debugging purposes.
The following sections provide an in-depth explanation of the general settings and options applicable to all API Connectors, as well as specific details for the API Connectors used with native Spacewell products.
1.1 Trust relation
Each API Connector includes a trust relation, which is used to configure the authentication required for accessing the Asset environment through the API Connector. The authentication type is determined automatically based on the API Connector 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 API Connector. 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 API Connector. If the user is inactive or lacks the required permissions (e.g., to fetch specific master data), the integration will fail to function properly.
Note
The Trust Relation’s Access ID for the Workplace Experience API Connector is a unique generated reference and is not editable (anymore). This ensures that each Trust Relation is unique, even if a client uses multiple API Connectors over multiple servers (e.g. production and test).
1.2 Operation mode
The operation mode of an API Connector specifies which server the app is accessible from. The available operation modes are:
- Production
- Backup
- Test
- Development
These modes correspond to the Asset 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 API Connector 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.
Note
Important: If the operation mode is left empty, the API Connector 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.3 Commission
The commission of an API Connector defines its status (active or inactive) and the direction of its accessibility. The available commission options are:
- Active: The API Connector is fully functional and accessible.
- Deactivated: The API Connector is inactive and inaccessible, even if the secret key is still used by the external system.
- Incoming Allowed: The API Connector only allows incoming connections.
- Outgoing Allowed: The API Connector only allows outgoing connections.
By default, the API Connector 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 API Connector 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 API Connector depend on its type. Details about different app types will be covered in the next chapter.
2. Types
When creating an API Connector, 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
- GoCanvas
- SCIM
Additionally, it is possible to create an API Connector in the default category by clicking the ‘New’ button in the API Connector overview. This option is useful for setting up an API Connector for authentication purposes as part of a custom integration.
Beyond the general API Connector 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 API Connector type is designed to expose the Asset 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 Asset through the API Connector. Similarly, reservations made in Asset are visible on Workplace Experience touchpoints, ensuring seamless data exchange.
By default, the Workplace Experience API Connector is set up by Customer Support during the initial configuration of a new Asset environment for the customer.
2.1.1 Linking objects
The Workplace Experience API Connector 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 API Connector will be available and visible in Workplace Experience touchpoints. Unlinked objects will not be accessible in the Workplace Experience touchpoints.
Objects can be linked directly to the API Connector from the corresponding page include. It is also possible to link the object to an API Connector from the object itself. More information can be found here: Link object to application
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 API Connector. 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 Asset 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 API Connector in Asset, it may take up to 4 hours for the objects to become available in Workplace Experience.
2.1.2 Cache configuration
For detailed information on the cache configuration, please see: Cache configuration
2.1.3 Optimizing Availability Checks
In Asset, 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 reservable 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 API Connector 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 Asset for creating or managing reservations.
Info
The access check is performed on the reservable object. Setting access on the reservable, can prevent a user from reserving the object, but the object will be available to select when creating a request, for example. Setting access on the object itself (area, asset or catalog item), will result in the user not seeing the object in any module.
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 API Connector. 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 API Connector. 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 Asset for creating or managing reservations.
2.1.4 Check-in options
In the API Connector, 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 API Connector 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 API Connector 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.
Note
When linking the relevant service types to the WPE API Connector, make sure always to link any parent service types as well; otherwise, the service types will not be shown/selectable in Workplace Experience.
2.2 Analytics
By activating the Analytics integration via the module activation, the API Connector is automatically created and configured correctly. There are no additional configuration options in the API Connector for Analytics apart from the general settings described above.
2.3 Calendar integration
The Calendar Integration API Connector type allows the Asset environment to integrate with Exchange or Google Workspace. This enables the synchronization of room and reservation data between Asset and the calendar application, ensuring meetings created in either system are automatically reflected in the other.
By default, the Calendar Integration API Connector 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 Asset 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 Asset configuration guide.
2.3.2 Linking reservable rooms
The Calendar integration API Connector 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 API Connector, 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.
Reservable areas can be linked directly to the API Connector from the corresponding page include. It is also possible to link the reservable area to an API Connector from the area itself. More information can be found here: Link object to application
2.3.3 Observations
Once the reservable objects are linked to the API Connector, 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 Asset reservable resource and an Exchange/Google Workspace resource, an observation is automatically generated within the API Connector. This observation serves to bundle all notifications related to the specific resource, ensuring streamlined communication and synchronization.
2.3.4 Workflow interaction
In the API Connector 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 API Connector 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 API Connector is an overview of all events send and received from the calendar integration. This overview can be used for debugging purposes.
2.4 Asset App integration
The Asset App API Connector type allows the Asset environment to integrate with the Asset App. This enables the dispatching of corrective- and/or preventive maintenance work orders to the Asset App for the contractors to pick up straight from within the app.
The Asset App module activation creates and partially configures the API Connector. Additional manual configuration steps, as outlined below, are required to complete the setup.
2.3.1 Mappings
The mappings required to establish the integration between Asset and the Asset App are created and partially pre-configured during the Asset App integration module activation. However, the tenant_id, default_form, 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 Asset configuration guide
2.3.2 Linking system users
The Asset App API Connector consist of an include, which is used to link all relevant system users, who are going to use the Asset App to handle the work orders. System users not linked to the API Connector, can handle the work orders from within Asset.
System users can be linked directly to the API Connector from the corresponding page include. It is also possible to link the system user to an API Connector from the system user itself. More information can be found here: Link object to application
2.5 SCIM
The SCIM Integration API Connector type allows Azure to integrate with Asset for user provisioning. This enables the groups and users automatically provisioned to Asset, without the need to manage the users in Asset manually.
The SCIM integration module activation creates the API Connector. No additional configuration of the API Connector in necessary in Asset.