Interfaces are web pages that provide users with a direct method of interaction with PlaceOS. They are suitable for any experiences that lend themselves to screen-based interaction. Common examples of interfaces are:

• A staff app

• Meeting room control interfaces

• A booking system

PlaceOS is a software platform which enriches interaction with physical space. It provides tools to design, build and iterate integrated digital experiences for physical environments. To do this, it merges any and all elements - from lighting and AV to entire BMS - without the legacy baggage.

Integration of disparate systems, devices and services forms a seamless experience for your space.

Automation boosts workplace efficiency and ease of use for any space.

Iteration lets your space constantly improve and grow with you and your needs.

Sections of this site

The documentation for PlaceOS is split into 4 categories.

See the overview for high-level coverage of topic areas.

Try a tutorial to learn in more detail about a process or feature.

Read a how-to guide for docs to help you with a specific task.

See the reference material for detailed technical docs.

Videos and Demonstration Apps

You can watch a short or in-depth video demonstrating the functions of PlaceOS Backoffice.

Take our Workplace or Concierge Demo Apps for a spin.

These steps will configure PlaceOS to use Microsoft Azure Active Directory as a federated authentication provider to allow users to sign in using their corporate credentials. The same Azure App Registration will be used to allow users logged in to PlaceOS Apps to book Exchange Online meeting rooms.

PlaceOS prefers to use OAuth2.

One advantage of using OAuth2 over SAML is that it is possible to require individuals to authorise access to certain resources. Thus users grant access to PlaceOS which can maintain a refresh token for offline access as needed.

Prerequisites

• Confirm the final UAT and PROD URLs of the web apps

• Ensure that the DNS entries for these URLs are active and forwarding to the server(s)

• Ensure that the SSL certificates for the above domains are signed and recognized as secure

Drivers are the core components of the PlaceOS platform. They combine to help different parts of the digital ecosystem interact with each other. PlaceOS has drivers that fall into one of two categories:

Integration Drivers

• Communicate with external systems and lets them talk to PlaceOS

• Represent hardware or software platforms (i.e. device or service)

• Control any functionality of the external systems and handle any incoming data

Logic Drivers

• Coordinate interactions between modules

• Don't map to specific physical objects

• Represent abstract or conceptual functions

• May use a variety of devices or software platforms

Drivers and Modules

Modules are instances of drivers, letting the rest of PlaceOS access their specific functions.

Driver Map

The driver map shows driver dependencies in PlaceOS.

Modules are instances of . Each module represents either:

• A specific physical device controlled by PlaceOS,

• A specific digital platform, or

• Logic that controls how a specific set of hardware and software should interact

Purpose

All modules have two broad functions on the system they control:

1. State: status information about the integration or higher level logic they control. Some examples of this kind of data could be:

   • Power status

   • Upcoming booking info

   • Current user

2. Behavior: actions which the device, service, or logic can do. Some examples of these actions could be:

   • Power on/off

   • Create/edit booking

   • Post a chat message

Starting and Stopping Modules

Each module can be individually started or stopped at any time. When started, the driver connects to the physical or digital integration and keeps track of its status. When stopped, the driver disconnects from its integration and will not send or receive any data or commands. For logic modules, this enables / disables its functionality.

Modules and Systems

Modules must be a part of at least one , but can be part of more than one system. Each system can use the same module instance everywhere it's required. Examples of modules used this way could be:

• A lighting gateway

• Centrally installed audio-visual equipment

• A common service such as a chatbot integration

Logic Modules

Logic modules are different to all other types of Modules (e.g. Device/Service modules) as they do not communicate to external devices/services. They only have access to the other Modules within the same System and co-ordinate actions across then.

As such, Logic Modules are strictly bound to the first System in which they are added, and should not be added to multiple Systems.

Settings Inheritance

Logic modules inherit settings from both the Driver from which they are instantiated and the System in which they are added (including the settings that the System has inherited from it's Zones). System settings override Driver settings.

Driver settings > Zone Settings (in the hierarchical order specified by the System) > System Settings > Logic Module Settings

All other Module types only inherit Settings from the Driver from which they are instantiated.

Driver settings > Logic Module Settings

Settings are the configuration information that define how a deployment should behave. Any level can have defined settings, which are ultimately consumed by . , , or can have settings defined on them. Together, these create a system configuration that is easier to manage at scale.

Examples of some common uses for settings are:

• Available video inputs/outputs

• Source names

• DSP block IDs

• Lighting control IDs

• Device authorization information

• Desk / room auto-release timeouts

Within driver files are definitions for naming conventions and expected values for the settings. They will vary based on each deployment, but the general structure will always be similar.

JSON definitions

Settings are expressed as , that is, key-value pairs:

Settings inheritance

Different layers define settings which then combine to produce the final configuration. This simplifies large deployments, standardizes systems and reduces management overhead.

Systems inherit all the settings from each zone that they are in. Zones pass down their settings to all systems within them. Similarly, Modules inherit all the settings from the driver that they instantiate.

Only Systems and Modules inherit Settings

Systems

Systems inherit settings from their Zones, in the order specified on their Zones tab (highest priority at top).

Zone Settings (in the hierarchical order specified by the System) > System Settings

Modules

Logic modules inherit settings from both the Driver from which they are instantiated and the System in which they are added (including the settings that the System has inherited from it's Zones). System settings override Driver settings.

Driver settings > Zone Settings (in the hierarchical order specified by the System) > System Settings > Logic Module Settings

All other Module types (e.g. Device, Service) only inherit Settings from the Driver from which they are instantiated.

Driver settings > Logic Module Settings

Specific Overrules General

Settings inherited from a zone or driver combine with any settings defined directly on the system or module. If an inherited setting has the same key as one defined directly, the latter will override the inherited one. This lets you write general settings at a higher common level, with more specific ones on each lower tier.

Triggers provide a way to dynamically link state and behavior across different modules. They define actions that will occur based on certain criteria, such as:

• System state

• Time

• External input such as a webhook

Customization

Triggers permit modules to influence the behavior of other modules directly. In PlaceOS Backoffice, users can create, assign and manage triggers. This way, they can customize extensive event driven behavior. That accompanies more complex core system behavior written in the logic modules.

Overview

TypeScript is an open-source language which builds on JavaScript by adding static type definitions. Types provide a way to describe the shape of an object, provide better documentation, and allow TypeScript to validate your code.

TypeScript and Angular

Angular applications must be built with TypeScript. As PlaceOS frontend applications are mainly written in Angular, they need TypeScript.

Versioning

TypeScript version depends on your Angular version.

PlaceOS Frontends uses Angular 12 and TypeScript 4.2.4.

TypeScript References and Tooling

The TypeScript Handbook provides detailed documentation specifically related to TypeScript.

PlaceOS uses NX tools to assist with testing and building JavaScript Applications.

NX adds Jest for Unit Testing and Cypress for Integration and End-to-End Testing.

The Angular CLI lets you develop, scaffold and maintain Angular applications. It's used with PlaceOS frontend applications.

Automated Browser Testing

Automated browser testing can check application test cases. Any Selenium based automated test suite would be suitable for this purpose. One possible tool is Katalon Studio.

*[CLI]: Command-line Interface

Overview

Security Assertion Markup Language (SAML) is an open standard that allows Identity Providers (IdP) to pass authorization credentials to Service Providers (SP).

SAML is an umbrella standard that covers federation, identity management and SSO.

The SAML specification defines three roles:

• The principal (typically a human user)

• The Service Provider (SP)

• The Identity Provider (IdP)

In the primary use case addressed by SAML, the principal requests a service from the Service Provider. The Service Provider requests and obtains an authentication assertion from the Identity Provider.

SAML in PlaceOS

By default, PlaceOS uses a local authentication method. PlaceOS also supports Federated Authentication via SAML as the advised method of user authentication.

Under this configuration, by the SAML Standard, PlaceOS is the Service Provider (SP).

Authentication providers can be associated with Domains in PlaceOS.

• Configure SAML in PlaceOS

• Add Domains in PlaceOS

Resources

• Security Assertion Markup Language (SAML) V2.0 Technical Overview

These steps will help Azure Administrators make the necessary configurations for PlaceOS User Authentication via Microsoft Azure Active Directory (Federated Authentication) and PlaceOS Calendar Driver, for PlaceOS Room Booking.

If you only require User Authentication you do not need to complete the Calendar Access steps.

If your PlaceOS will have room booking enabled, you will need to complete the Calendar Access steps.

These steps will help Google Cloud & Google Workspace Administrators make the necessary configurations for PlaceOS User Authentication via Google Workspace (Federated Authentication) and Calendar Visualisation for PlaceOS Room Booking.

If you only require User Authentication you do not need to complete the Calendar Access steps.

If your PlaceOS will have room booking enabled, you will need to complete the Calendar Access steps.

Prerequisites

• Google Cloud Console Administrative Access or Permissions to Enable API's and create OAuth2 Client ID.

Procedure

Follow Google instructions to add a new client application to your Google account and obtain the client_id and secret.

The advantage of writing a script is that you can update multiple aspects of the system at once, ensure consistency and ideally allow running multiple times as data changes.

These are some example scripts: https://github.com/place-labs/scripted-imports

A simple way of providing data to your scripts that we recommend is by publishing google sheets https://www.youtube.com/watch?v=jxKmnhbrUWs

PlaceOS Supports a range of authentication providers, both SAML and OAuth2 can be used for authentication.

This section lists configuration for some common authentication providers using SAML.

To configure PlaceOS for Microsoft 365 or Google Authentication, it is best to use OAuth2 detailed in these articles:

• Configure PlaceOS for Microsoft Azure/365.

• Configure PlaceOS for Google Workspace.

This section also provides instructions to configure X-API Keys and bearer tokens which can be used for interacting with the PlaceOS API.

As Azure B2C does not explicitly provide us access to end user calendars, or a tenant for room resources you may optionally configure a 365 Tenant to be used for room booking/reservations.

To configure PlaceOS for integration with 365 Calendars, follow the existing instructions for integrating PlaceOS with 365.

Once Calendar Access has been configured, you will need to configure room resources to accept external meeting requests, this is done via PowerShell:

Set-CalendarProcessing -ProcessExternalMeetingMessages $true

For example:

PS> Set-CalendarProcessing -ProcessExternalMeetingMessages $true

cmdlet Set-CalendarProcessing at command pipeline position 1
Supply values for the following parameters:
Identity: room01_01l6yy.onmicrosoft.com

Use this page in tandem with Configuring PlaceOS for SAML2 if you are using AD FS. You can follow Microsoft's instructions for most cases. PlaceOS will use these four SAML2 claims:

• First name

• Last name

• Email Address

• User ID (such as a login name, e.g. UPN or Windows Account Name)

*[AD FS]: Active Directory Federation Services

PlaceOS uses a Custom SAML App to provide integrated SSO via Google User Authentication. For detailed steps, see Google's guide on setting up SAML

PlaceOS requires:

• Organization data

• Organization path

• Users full name

• Email address

• Unique identifier

You may need to map these as attribute claims.

Configuring PlaceOS

Parameters required from PlaceOS for Configuration:

ACS URL

Assertion Consumer Service. This is where google will send authentication responses with all the claim information.

Example: https://staffapp.placeos/auth/adfs/callback?id=adfs-XXXXX

Entity ID

The Entity ID is the Audience Restriction. It dictates the intended entity or audience for the SAML Assertion. This field is frequently referred to as the "Entity ID" or "Audience URI" by vendors. It can technically be any string of data up to 1024 characters long. Most commonly it's in the form of a URL that contains the Service Provider's name, and is often the same URL as the ACS.

Start URL

This the URL that will start the authentication flow.

Example: https://staffapp.placeos/auth/adfs?id=adfs-XXXXX

Metadata URL

You can provide this URL to Google to help with the setup process.

Example: https://staffapp.placeos/auth/adfs/metadata?id=adfs-XXXXX

NOTE:: this is a technical overview, there is a guide on configuring these services in backoffice.

Catering orders are linked bookings with a type of catering-order. Any driver that operates on bookings with a configurable booking_type can be used for catering bookings.

Examples

Booking Approver

The place/booking_approver driver can be used to auto approve catering orders with this configuration.

approve_booking_types:
	- catering-order

approve_zones:
	- building-zone-id

Booking Notifier

The place/booking_notifier driver can be configured to send notifications for catering orders to a specific email address like this.

booking_type: catering-order
unique_templates: true
notify:
	building-zone-id:
		name: Building Name
		email:
			- [email protected]
		notify_manager: false
		notify_booking_owner: false

Setting notify_booking_owner to true will send the notifications to the booking creator.

To send cancellation notifications a template must be created for the bookings.cancelled_catering-order trigger.

In this step, we will now apply the restriction to the PlaceOS Room Booking group, restricting it to only see the calendars required for the purposes of room booking.

Prerequisites

• Exchange Resource Group

• Exchange Administrator Access

• Azure App Registration App ID

Procedure

1. From Exchange Online, or any other service with PowerShell connected to Exchange, open a new PowerShell Terminal.

2. Run the following command, replacing the arguments for AppID, PolicyScopeGroupID and Description. We will use the AppID and PolicyScopeGroupID from previous steps:

New-ApplicationAccessPolicy -AppId e7e4dbfc-046f-4074-9b3b-2ae8f144f59b -PolicyScopeGroupId [email protected] -AccessRight RestrictAccess -Description "Restrict this app to members of distribution group PlaceOS Room Booking."

3. The application policy should now be applied, this can be tested using the `Test-ApplicationAccessPolicy` cmdlet:

Test-ApplicationAccessPolicy -Identity [email protected] -AppId e7e4dbfc-046-4074-9b3b-2ae8f144f59b

4. If we test using a regular user, the result should be denied:

5. If we test using a room resource address, the result should be granted:

A system is the main logical building blocks within PlaceOS. They contain three components:

• A collection of

• which will apply to the system and modules in it

• Basic metadata (name, description etc)

Purpose

Systems often represent physical spaces, such as meeting rooms. They can also represent connected items which run across physical spaces, such as a range of digital signage. Otherwise, they can represent a non-physical system with data inputs and outputs, such as a payment portal.

Systems and Zones

are groups of systems which can reflect their physical or conceptual groupings. Systems can belong to zero or more zones.

Settings Inheritance

Systems inherit settings from their Zones, in the order specified on their Zones tab (highest priority at top).

Zone Settings (in the hierarchical order specified by the System) > System Settings

Zones are collections of . A system can have tags marking it as a member of any number of zones.

Purpose

They serve two main purposes:

1. Logical groupings of systems with common traits, generally:

   • Those in the same physical space, but at a larger scale than systems. For example, if each system is a room then the building would be a zone

   • Systems of the same general concept. For example if you have customer-facing systems zoned separately to internal systems

2. A point to define that need to affect a set of systems in the same way

Settings Inheritance

Zones do not inherit settings from the Parent zones.

Guides

Crystal is a programming language with the following goals:

• Have a syntax like Ruby (but compatibility with Ruby is not a goal)

• Statically type-checked but without having to specify the type of variables or method arguments

• Be able to call C code by writing bindings to it in Crystal

• Have compile-time evaluation and generation of code, to avoid boilerplate code

• Compile to efficient native code

Why Crystal

Security: we can distribute a single static binary in a docker container, there is little chance of exploit.

Speed: the binaries are fast, see .

Developer happiness: all the benefits of Go Lang with the elegance of Ruby.

Resources

Installing Crystal

Crystal Documentation

Overview

MQTT is an standard messaging protocol for the Internet of Things (IoT). As a lightweight publish/subscribe messaging transport, it's ideal for connecting remote devices with a small code footprint and minimal network bandwidth.

Its versatility makes it suitable for a wide variety of industries. These include automotive, manufacturing, telecommunications, oil and gas, etc.

MQTT allows for messaging between device-to-cloud and cloud-to-device. This simplifies broadcasting messages to groups of receivers. Further information is available from the

MQTT in PlaceOS

PlaceOS supports publishing state information via MQTT. This provides environment information to external systems such as

MQTT messages consist of a header and a payload and typically have low bandwidth usage. The header declares the topic of the message, and the payload carries data as key-value pairs.

PlaceOS uses two types of message sent over MQTT: State Changes and Metadata. For further information on configuring MQTT for PlaceOS, see the guide on

Resources

Overview

OAuth is an open standard for access delegation, commonly used as a way for internet users to grant websites or applications access to their information on other websites but without giving them the passwords.

OAuth provides clients secure delegated access to server resources on behalf of the owner. It specifies a process for resource owners to allow third-party access to their server resources. Most importantly, it allows access without providing credentials.

OAuth works directly with HTTP. It issues access tokens to third-party clients through an authorization server. The resource owner approves which tokens get issued. The third party then uses the token to access the protected resources hosted by the resource server.

OAuth2 in PlaceOS

PlaceOS uses the OAuth Standard (OAuth2) to integrate to third-party services including:

• Microsoft Graph API

• Google API

• Cisco Meraki

OAuth provides PlaceOS access to read and write specific information needed for our application.

The Service Provider (SP) can impose extra permissions and scopes including read/write permissions.

PlaceOS also offers OAuth Access to our Staff and Booking API.

Resources

The PlaceOS Application requires access to read the booking state of room resources within the Microsoft 365 domain.

This is achieved by creating a with , configuration of an Exchange Group for Room Resources and applying an Application Restriction Policy to the Exchange Group.

Complete the following steps to correctly configure calendar access.

The steps should be completed in the following order:

1. Create the Azure App Registration PlaceOS will use to authenticate with the MS Graph API.

2. Create an exchange calendar group to provide PlaceOS Access with only the required room resource calendars.

3. Apply an application permission to the Exchange Calendar Group.

4. Apply the required configuration in PlaceOS to allow the platform to connect and read your calendar resources.

PlaceOS has made the decision to implement our resource calendar visualisation in this method to heavily restrict the application access to organisation calendars.

This method creates a strict separation of concerns between user authentication and access to PlaceOS and the PlaceOS Room Booking Functions, you can think of this as the PlaceOS Daemon.

Using the documented method will prevent the application from reading all calendars in your domain, such as the CEO's calendar and ensure scope is enforced to only provide access to those room resource calendars required for the correct function of PlaceOS.

Prerequisites

• PlaceOS Backoffice Administration Access

Procedure

1. In PlaceOS Backoffice navigate to the Domains tab.

2. Select the domain you would like to add Microsoft Authentication to.

3. Click the Authentication Tab.

4. Click New Auth Source.

5. Select OAuth as the auth source type.

6. Provide a name eg. 'Microsoft AD'.

7. Click Save.

8. Copy the Auth Source ID eg. oauth_strat-Dw9b-5_lO3

9. You will require the Auth Source ID to be used as the Azure App Registration Callback URI, for example: `https://placeos-dev.im/auth/oauth2/callback?id=oauth_strat-Dw9b-5_lO3`

Issue

An issue may arise where users receive an email from Microsoft when attempting to book a room via PlaceOS that states the email was undeliverable to the destination, noting the sender and receiver are both in the same domain.

The specific error:

Root Cause

This is caused by API Spam from the PlaceOS application to the Microsoft 365 via the Graph API Endpoint.

This condition is triggered where PlaceOS drivers are set to a running state against your tenant prior to correct configuration and API access been granted.

PlaceOS drivers related to Microsoft Graph API including the Microsoft Graph API, Staff API, Calendar Driver and Bookings Driver should not be put into an active state until configuration of Microsoft Graph API is complete.

Resolution

1. Navigate to the Exchange Admin Centre

2. Click Support

3. Raise a new Support Request

4. Advice you have received an error that email is undelivered due to spam blacklist.

5. A Microsoft agent will contact you and run a diagnostic tool that will resolve the issue typically within an hour.

To use google APIs you’ll need a server to server OAuth2 application configured. This involves creating a service account that will be used for authentication.

The service account can then “act as” staff in the organisation to perform action on their behalf, such as booking meeting rooms.

See:

There are some actions that regular staff do not have permission to perform, such as:

• Listing the users in the organisation

• Interacting directly with resource calendars.

For this functionality a user account should be created that is granted special permissions for these activities.

To perform actions on resource calendars, like reject meetings, the PlaceOS Service User account needs to have delegated access to these calendars.

Prerequisites

• Google Workspace Administrative Access

Procedure

1. Navigate to Calendars

2. Select the Resources

3. Select the Room Resource Calendar

4. Under Share with Specific People add the PlaceOS Service User

5. Ensure the Service User has 'Make changes to events' permission.

One advantage of using OAuth2 over SAML is that it is possible to require individuals to authorise access to certain resources. Thus users grant access to PlaceOS which can maintain a refresh token for offline access as needed.

Prerequisites

1. Confirm the final UAT and PROD URLs of the web apps

2. Ensure that the DNS entries for these URLs are active and forwarding to the server(s)

3. Ensure that the SSL certificates for the above domains are signed and recognized as secure

User Access Tokens

User tokens obtained from the OAuth2 flow are stored in the database and can be used for making requests on behalf of the users logging in.

You can obtain a token via POST /api/engine/v2/users/resource_token It will return a JSON payload

If the OAuth2 service returned a refresh token then this API will always return a valid token, refreshed as required (there is never direct access to the refresh token)

With multiple authentication sources you may have to specify which source to use for OAuth configuration:

Prerequisites

1. Confirm the final UAT and PROD URLs of the web apps

2. Ensure that the DNS entries for these URLs are active and forwarding to the server(s)

3. Ensure that the SSL certificates for the above domains are signed and recognized as secure

4. PlaceOS Backoffice Administration Access

Procedure

1. In PlaceOS Backoffice navigate to the Domains tab.

2. Select the domain you would like to add Google Authentication to.

3. Click the Authentication Tab.

4. Click New Auth Source.

5. Select OAuth as the auth source type.

6. Provide a name eg. 'Google Workspace'.

7. Click Save.

8. Copy the Auth Source ID eg. oauth_strat-Dw9b-5_lO3

9. You will require the Auth Source ID to be used as the Azure App Registration Callback URI, for example: `https://placeos-dev.im/auth/oauth2/callback?id=oauth_strat-Dw9b-5_lO3`

Once the Authentication Source is configured, we need to ensure PlaceOS Applications redirect the user to the authentication provider to login.

Prerequisites

• PlaceOS Backoffice Administrator Access

Procedure

1. Login to PlaceOS Backoffice

2. Navigate to the Domains tab.

3. Select the Domain for your organisation.

4. Click on the Edit icon.

5. Set the login URL to /auth/login?provider=adfs&id=[ADFS-ID-HERE]&continue={{url}}, replacing the [ADFS-ID-HERE] with the authentication source ID created in '' instructions, leaving the {{url}} as is.

6. Set the logout URL to /auth/logout?continue=https://sso.org.com/logout if they haven’t provided you a logout.

Debugging

The first step in this process should be to get the raw request.

Often you can see if a request attribute is not lining up to an attribute statement by inspecting the XML.

You can paste the resulting data into this

Then paste the XML into (so it’s readable)

There are two methods of getting SSO data, described below:

1. If you have an account you can use to test

2. If the client is logging in and you have access to logs

Self Check

1. Open the Chrome or Firefox inspection tool

2. Go to the network tab

3. Select: preserve log

4. Go through the login flow

The request coming back to the assertion URL is the one you want to inspect.

Assertion URL: /auth/adfs/callback?id=[ADFS-ID-HERE]

Copy and paste the SAML response into the SAML decoder.

is an authentication service provided by Microsoft designed to enable any users to register and authenticate against a web application.

Azure B2C may be used with PlaceOS where the organisation wish to provide external access to users not part of their organisation, this is commonly used for shared working or co-working spaces.

Under this configuration, Azure B2C is configured and added to PlaceOS as a OAuth2 Provider.

To use Azure B2C, you will require:

• An active Azure Tenant

• An Azure Subscription with valid payment method

• Administrator Access to an Azure B2C Tenant and/or sufficient access to create and deploy the Azure B2C Tenant from your existing tenant.

These instructions will assume you are able to configure an Azure B2C Tenant under your existing tenant and will only cover the specific requirements for PlaceOS Configuration.

There are two steps to this process:

1. Create Azure B2C Custom Policy Framework in your Azure B2C Tenant

2. Configure PlaceOS Authentication Source & Azure App Registration

Use this page in tandem with if you are using Auth0 domains for SSO. You should follow to a register a single-page-app for SAML SSO using Auth0.

Configuration

• The Name of the application can be the domain name of your instance of PlaceOS

• On the Addons tab, enable SAML2 Web App and use as a guide

• Set the Application Callback URL to match the Assertion URL in PlaceOS, e.g. https://auth/adfs/callback?id=adfs-XXXXXX

• Paste in the below for Settings:

Internal builds for all product service images are available on . These publish on every push to our service repos on GitHub and are tagged with the associated branch name.

Access is restricted to the outside world to help prevent accidental use. To authenticate:

1. with read:packages access only.

2. Run docker login ghcr.io on your machine. This will prompt you for your GitHub username, and a password. Use the PAT you created above.

Dev builds will now be available by prefixing the image name with ghcr.io. For example, if you would like to test branch foo from core, the image tag is ghcr.io/placeos/core:foo.

1. edit the .env file in your

2. replace ${PLACEOS_TAG} with the test branch, i.e. ghcr.io/placeos/core:foo

3. pull down the internal image docker-compose pull

4. run the new image docker-compose up -d

These must not be used on external infrastructure, but are suitable for internal testing and experimentation. For external development use, platform nightly builds are available on Docker Hub. Extending the example above, core can be accessed there via placeos/core:nightly. Similarly the latest stable build can be found simply as placeos/core.

To use Azure B2C with PlaceOS you will need to configure a Custom Policy Framework, using the existing User Flows provided by Azure B2C is not sufficient for use with OAuth2 as it does not provide a User Info endpoint.

Without a User Info endpoint, PlaceOS is unable to correctly create the user record in our users table.

Create Custom Policy

The first step in configuration is to create a custom policy framework and the supporting application registrations.

Microsoft have prepared extensive documentation to complete this process and we recommend following this documentation to complete this step: Microsoft Azure B2C - Create Custom Policy Framework

To complete this step, you will also require the Custom Policy Provider templates.

Download the Custom Policy Templates from Github or git clone https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack

Add User Info Endpoint

To allow PlaceOS to obtain your users information from Azure B2C via the Graph API, you will need to modify the custom policy to support a User Info endpoint.

Microsoft have prepared extensive documentation to complete this process and we recommend following this documentation to complete this step: Microsoft Azure B2C - Add User Info Endpoint to Custom Policies

Add Custom User Attributes

You may also opt to collect additional data from your users when they sign up to the application, these are referred to as Custom User Attributes.

Custom User Attributes may include additional information such as:

• Users phone number

• Address

• Company

• Department

This information will be stored against the user record in the Azure B2C Directory and can be claimed by PlaceOS where required.

Microsoft have prepared extensive documentation to add Custom User Attributes to your B2C Custom Policy, we recommend following this documentation to complete this step: Microsoft Azure B2C - Add Custom User Attributes

Password Reset Policy

By default, the self serve password reset user flow is not enabled.

You will need to add a custom user sub-journey to your policy to enable self serve password reset facilities, to do this you can follow this guide by Microsoft: Microsoft Azure B2C - Add Password Reset Journey

Examples

We have provided an example Custom User Policy that includes:

• Local user sign-up/sign-in i.e. using a email address and password.

• User Info endpoint enabled.

• Custom User Attributes added.

You can download our example policies from Github or git clone [email protected]:place-labs/azure-b2c-custom-policy-sample.git

Points of failure

etcd Failure

etcd is used by API and Core to determine the addresses of running Core services. As well as to determine where a module is executing in a cluster.

• Some drivers may not function as the API won't be able to reach them

• Core instances won't be able to join the cluster and won't launch drivers

• Most API requests will continue to work, execute and WebSocket requests will fail

• Triggers will fail

RethinkDB Failure

RethinkDB holds cluster configuration, primarily used by core during initialization.

• Most API requests will stop functioning, including authentication

• Existing WebSocket requests will continue to function

Redis Failure

Redis holds the runtime state of the cluster, such as module metadata and module status

• Status changes and signals will stop functioning

• Errors raised in modules may prevent some execute requests from functioning properly

• Execute APIs and cross driver communication will be effected as module metadata will be unavailable

Elasticsearch failure

• API index / listing / searching requests will fail - this will be mostly apparent when using Backoffice

• All other aspects of the system will continue functioning

Driver compilation issue / crash

• Executes directed at a module running on the driver will fail

Troubleshooting

In the event of a failure, being able to isolate which aspect of the system is not functioning is key to a quick recovery.

• Can you log-in? If not it's probably a RethinkDB Failure or load balancer issue (check if requests are hitting the services)

• Does Backoffice list the systems? If not it's probably an Elasticsearch failure

If you can login and see systems:

• Select a system you can safely use for testing

  • Does the list of modules and module functions load? If not it's probably a Redis Failure

  • Does executing a function work from Backoffice? View the response to see the error:

    • If the error says no core instances then core might be down or unable to connect to etcd

    • If the error says unable to connect to etcd then etcd might be down or the API can't connect to etcd

This should help you identify the cause of most issues.

Enable debug logs

All the services support being toggled to output more verbose logs which might help shed light on an issue.

To toggle log levels you send a signal to the service: kill -USR1 <process_pid>

As you typically cannot shell into the containers, you'll have to run this command from the host. You must be running as root and you can find the process pid by running: ps aux | grep <staff|api|triggers|etc>

Prerequisites

• Microsoft Azure Administrator Access or Permission to Create App Registrations

Procedure

In this step, we will create the application access PlaceOS will use to access the room resource calendars in your organisation via Microsoft Graph API.

After completion of this step, we will apply a policy restriction so the application can only access room resource calendars.

1. Login to Microsoft Azure Portal.

2. Navigate to App Registration blade.

3. Create a new App Registration called PlaceOS Bookings Visualiser

   • Supported account types should be ‘Accounts in this organisational directory only’

   • No redirect URI is required.

4. Note down the:

   • Application (client) ID as this will be required in the next step and also to be provided to PlaceOS.

   • Directory (tenant) ID this will not be required in the next step but will need to be provided to PlaceOS.

5. Once created, navigate to Certificates and Secrets.

6. Create a New Client Secret called ‘PlaceOS Booking Visualiser Secret’ and note down the secret value (you will need to supply this to PlaceOS).

7. Navigate to 'API Permissions'.

8. Click 'Add Permission'.

9. Click 'Microsoft Graph'.

10. Click 'Application Permissions'.

11. Add the following permissions: - Calendars.ReadWrite - Group.Read.All - User.Read.All

12. Click 'Add permissions'.

13. Click ‘Grant admin consent for xyz’.

14. Configuration of the Azure App is now complete.

15. Supply PlaceOS or your integration partner with (be aware that supplying these credentials to PlaceOS prior to configuring the application policy in exchange will allow PlaceOS to see ALL calendars in your organisation):

    • Application ID

    • Tenant ID

    • Secret

In this step, we will create a group that will contain the room resources you would like PlaceOS to access. Following this, we will create a restricted access policy applied to the group.

This prevents the PlaceOS Application from reading all calendars in your organisation and negates some security concerns around the applications access to sensitive information such as the CEO’s calendar.

Prerequisites

• Exchange Administrator Access

Procedure

1. Navigate to the Exchange Admin Centre.

2. Click Recipients.

3. Click Groups.

4. Click 'Add a group'.

5. Select 'Mail-enabled Security'.

6. Click Next.

7. Name the group 'PlaceOS Room Booking' and optionally enter a group description.

8. Click Next.

9. Assign an Exchange Admin or Service User as the group owner. The group owner has no impact on PlaceOS integration and is entirely at the organisation's discretion.

10. Click Next.

11. Under Add members you will need to add the room resource calendars you would like PlaceOS to have access to, this can optionally be done later via PowerShell if you have a large number of rooms.

12. Click Next.

13. Provide a group email address such as [email protected]

14. Click Next.

15. Click Finish.

16. Note down the group email address as this will be required in the next step.

Once the Authentication Source is configured, we need to ensure PlaceOS Applications redirect the user to the authentication provider to login.

Prerequisites

• PlaceOS Backoffice Administrator Access

Procedure

1. Login to PlaceOS Backoffice

2. Navigate to the Domains tab.

3. Select the Domain for your organisation.

4. Click on the Edit icon.

5. Set the login URL to /auth/login?provider=[AUTH-TYPE-HERE]&id=[AUTH-ID-HERE]&continue={{url}}, replacing the [AUTH-TYPE-HERE] with one of (adfs, oauth2, ldap) & the [AUTH-ID-HERE] with the authentication source ID created in 'Creating a PlaceOS Authentication Source' instructions, leaving the {{url}} as is.

6. Set the logout URL to /auth/logout?continue=https://sso.org.com/logout if they haven’t provided you a logout.

Debugging

ADFS:

The first step in this process should be to get the raw request.

Often you can see if a request attribute is not lining up to an attribute statement by inspecting the XML.

You can paste the resulting data into this SAML Decoder

Then paste the XML into Pretty Print (so it’s readable)

There are two methods of getting SSO data, described below:

1. If you have an account you can use to test

2. If the client is logging in and you have access to logs

Self Check

1. Open the Chrome or Firefox inspection tool

2. Go to the network tab

3. Select: preserve log

4. Go through the login flow

The request coming back to the assertion URL is the one you want to inspect.

Assertion URL: /auth/[AUTH-TYPE-HERE]/callback?id=[AUTH-ID-HERE]

ADFS: Copy and paste the SAML response into the SAML decoder.

PlaceOS recommends managing your Concierge users directly in 365 or Exchange Administration to allow Concierge users to be added and removed as required by the business.

Once changes are made on 365 or Exchange Admin the changes will be available to the user in real time via the PlaceOS Concierge App.

Prerequisites

• 365 or Exchange Administrator Access

  • Group Creation

  • Resource Management

Procedure

Group Creation

1. Navigate to 365 Admin Centre

2. In 365 Admin Centre select the Teams & Groups Blade -> Active teams & groups.

3. In Active teams & Groups select Add Group.

4. For Group Type select Mail-enabled Security.

5. Give your group a relevant name such as PlaceOS Concierge + Office

6. Nominate a user (typically a tenant administrator as the group owner).

7. In add members, select your Concierge users for that office location.

8. Nominate a email address for the group.

9. Click Finish followed by Create Group.

Delegate Room Resources

1. In 365 Admin Centre select the Resources Blade -> Rooms & Equipment.

2. Select the room you want to provide concierge access to.

3. Select Edit Exchange Settings.

4. Select mailbox delegation.

5. Under Full Access, add your Concierge Security Group.

6. Select Save.

7. Repeat these steps for other rooms as required.

You may also apply the Concierge group to a list of rooms via Powershell: https://learn.microsoft.com/en-us/exchange/recipients-in-exchange-online/manage-resource-mailboxes

Follow these steps to configure a Google Cloud Project and Enable API for PlaceOS.

Prerequisites

• Google Cloud Console Administrative Access or Permissions to:

  • Create Projects

  • Enable API's

  • Create OAuth2 Client ID.

Procedure

Configure GCP Project

1. Goto: https://console.cloud.google.com/

2. Click the Projects Dropdown

3. Click New Project in the Project Modal

4. Name your new project something descriptive eg. 'PlaceOS Integration'

5. Click Create

Enable API

1. If not directed, open your new project.

2. From the navigation menu select 'APIs & Services' then 'Dashboard'.

3. Select 'ENABLE APIS AND SERVICES'

4. Search for and enable the Following API:

   • Admin SDK (for staff directory)

   • Google Calendar API

   • Google Drive API (for attachments)

   • Marketplace SDK (not Marketplace API

Prerequisites

• Google Cloud Console Administrative Access or Permissions to:

  • Create OAuth2 Client ID.

Procedure

Create Service Account

1. From the Menu navigate to APIs & Services then Credentials.

2. Click Create Credentials

3. Select Service Account

4. Create the new service account with a descriptive name eg. PlaceOS Service Account.

5. Ignore the next steps in the Wizard and click return to return to the list of service accounts.

Create Keys

1. Click on the PlaceOS Service Account you just created.

2. Click Add Key

3. Select Create New Key

4. Create a JSON key

5. This will save a JSON file to your computer, this will be required to complete the PlaceOS Configuration Steps.

6. Once the key is saved, enable Domain Wide Delegation.

7. Click Save.

Prerequisites

• Google Workspace Administrator Access

• JSON Service Account File generated in Configure Google Service Account step

• The client_id from the JSON file

Procedure

1. Go to https://admin.google.com

2. Navigate to Security

3. Scroll down to Advanced Settings

4. Select 'Manage API Client Access'.

5. Add the following API Scopes to the client_id you extracted earlier.

   1. https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/drive.file

6. Click Authorise.

7. Navigate to the Security Tab and select API Controls.

8. Ensure Internal Applications are Trusted.

This only applies to organizations where a particular region or department will be using the application.

This step is not applicable to most organizations.

Prerequisites

• Google Cloud Console Administrative Access or Permissions to:

  • Create Marketplace Apps.

• Marketplace SDK Enabled

Procedure

1. Navigate to Google Cloud Console

2. From the navigation menu select API Services then Dashboard

3. Scroll down and click GSuite Marketplace SDK

4. Select Configuration

5. Enter an App Name and Description

6. Uncheck Individual Install

7. Upload Icons if required

8. Terms of Service URL is required, you can set this to your organisations homepage

9. Enter the Scope URL:

   • https://www.googleapis.com/auth/calendar

   • https://www.googleapis.com/auth/admin.directory.user.readonly

   • https://www.googleapis.com/auth/drive.file

10. Enable Drive Extension and click 'Configure drive SDK'

11. Fill in the details and icons for the drive application. This is required to have the application deployed without going through the public marketplace store and onboarding process.

12. Once done and you're back on the marketplace application form, ensure visibility is set to 'My Domain'

13. Click 'Save Changes'

14. You will now need to deploy the Marketplace App to the segment of the organisation that will be using the application, refer to these instructions: https://support.google.com/a/answer/172482?hl=en

There are some actions that regular staff do not have permission to perform, such as:

• listing the users in the organisation

• interacting directly with resource calendars

Prerequisites

• Google Workspace Administrative Access

Procedure

Create a New User

The new user may sit in a different OU to your regular users for security purposes.

To create a new user, if you are not already familiar you can follow these instructions from Google on Creating a Google Workspace User.

Assign Permissions

1. Select the newly created user from the user list.

2. Click the Roles and Privileges tab.

3. Click Edit.

4. Click create Custom Role.

5. On the privileges selection screen, under the 'Admin API Privileges' select the following permissions:

   1. Organization Units: Read

   2. Users: Read

   3. Groups: Read

6. When completed, the role summary should look like:

7. Assign the role to the account.

Where sensors are installed, the Sensor Management User Interface provides an interface to plot the sensors on the floor map.

This will enable custom zone capacity and enhanced capacity reporting via the zones.

The Sensor Management User Interface is able to plot the following types of sensors:

Prerequisites

• Administrator access to your PlaceOS Backoffice

• A Valid Org, Building and Zone Configuration

Enable the Sensor Extension

The first step is to enable the sensor extension.

1. In PlaceOS Backoffice Navigate to the Admin Tab

2. Under PlaceOS Admin select Extensions

3. Select a Domain and Click Add Extension

4. Configure the new extension as below:

• Type: zones

• Name: Sensors

• URL: https://editor.place.tech/sensor-map/#/editor/{{map_id}}

1. Click Add Condition and add the following condition:

• Condition Field: map_id

• Operation: truthy

1. Click Add

The Extension is now enabled.

Using The Sensor Manager

Once enabled, you can place sensors on the floor maps of Level Zones.

1. Navigate to Zones and select a zone with a tag of level

2. In the options bar you will now see the Sensors option

3. Select the Sensors tab.

You will now be able to select sensors from the list and place them according to their physical location on the map.

Webhooks are defined as a condition of a trigger. Add a new trigger that represents the webhook.

• Supported methods are the HTTP Verbs that should be accepted by the webhook URI

• The debounce period can be used to prevent multiple triggers occurring over a short period of time. (in seconds)

Once configured this trigger needs to be applied to a system before it's active.

Once you've added the trigger, you can obtain the webhook URL by clicking the link icon

The webhook URL

The webhook URL will look something like:

https://my.placeos.domain/api/engine/v2/webhook/trig-DHgkU1~p/notify?secret=kfwu5WYc3a1su

Webhooks that map to module functions

If this webhook is intended to provide data to modules in the system, not just as a condition to execute the trigger actions, then it needs a little more configuration.

1. in the System trigger list, click the edit button

2. ensure execute enabled is selected

3. click save

You will have to be aware of the methods that support Webhooks, which might involve looking at the driver code or driver documentation. Examples of webhook methods

• Meraki Dashboard

• Rhombus Interop

To build the execute URL you'll need the following information:

• Module name, i.e. Display

• Module index, i.e. 1, 2, 3 (Display_2 is index 2)

• Module method name: i.e. request

Then you can update the Webhook URL from above with this information

/api/engine/v2/webhook/trig-DHgkU1~p/notify?secret=kfwu5WYc3a1suZ&exec=true&mod=Display&index=2&method=request

An alternative form of this URL is (note that the secret is part of the route)

/api/engine/v2/webhook/trig-DHgkU1~p/notify/kfwu5WYc3a1suZ/Display/2/request

This URL can then be used to pass HTTP data to the module and should be provided to the service that uses websockets.

By default the root URL https://my.domain.com/ will redirect to https://my.domain.com/backoffice/

To override this behaviour:

1. Goto the domains tab in backoffice

2. select the domain you would like to configure

3. add the following config

{
  "default_app": "/concierge/"
}

Bearer tokens are tied to client applications. You can find the list of configured applications in Backoffice on the Domains -> Applications tab.

Password Flow

NOTE:: this flow is not recommended and only works for services accounts, it can be useful to obtain a token simply for testing.

POST /auth/oauth/token

This will return a new token

you can specify more than one scope - defaults to public the scopes selected here must be a subset of those configured on the client application

Making Requests

There are three ways to make an authenticated request with a bearer token:

1. A HTTP Header: Authorization: Bearer <token>

2. A URL Param: ?bearer_token=<token>

3. A HTTP Cookie: bearer_token=<token>

Inspect an existing token

GET /api/engine/v2/api_keys/inspect?bearer_token=yourtoken

GET /api/engine/v2/api_keys/inspect?api-key=yourkey

Authorisation Code Flow

This is the recommended flow for applications built on top of the PlaceOS platform. All PlaceOS templates additionally implement the PKCE extensions for additional security.

1. First a user session must be established, there are two methods to achieve this

   • Local login, POST /auth/[email protected]&password=developer

   • SSO login, GET /auth/oauth2?id=oauth2-id (generated as part of configuration)

2. Extract the user cookie (if performing programatically)

3. Perform the authorisation code flow to obtain a token, with the cookie header set

   • Authorise endpoint: /auth/oauth/authorize

   • Token endpoint: /auth/oauth/token

PlaceOS requires all interactions to be authenticated and associated with a specific identity. This includes fixed devices such as visitor sign-in kiosks or public information displays. Endpoint auto-login can provide persistent sessions for this style of shared device.

Prerequisites

1. Confirm the final UAT and PROD URLs of the web apps

2. Ensure that the DNS entries for these URLs are active and forwarding to the server(s)

3. Ensure that the SSL certificates for the above domains are signed and recognized as secure

Step 1: Create a local user account

1. Login as an admin to Backoffice

2. On the Users click Add new

3. Enter the required information, including a descriptive username (e.g. Touchpanel User)

4. Enter an email address (this does not need to be an active address)

5. No password required

Step 2: Create an X-API-Key for panel authentication

Follow the , specifying the service account created in the previous step

Step 3: Construct URL for Applications

Most PlaceOS applications can be passed a the API Key as a query parameter, so a destination URL such as:

/booking-panel/#/?panel=sys-F2u1l-oyxJ&x-api-key=be2aba8c8bd2be2a5c719339695b5a63.Edm7STXHDbacbsytz4RGvFc51PnBdQtcU9Yo7BSSVHw

Would be and configured as the continue param:

/auth/login?continue=%2Fbooking-panel%2F%23%2F%3Fpanel%2Fsys-F2u1l-oyxJ%3Fx-api-key%3Dbe2aba8c8bd2be2a5c719339695b5a63.Edm7STXHDbacbsytz4RGvFc51PnBdQtcU9Yo7BSSVHw

The application will use the API key for authentication and will display a bootstrap page for system selection, unless provided additional params that specify a system.

Prerequisites

• OAuth2 Callback URL from PlaceOS Authentication Source

• Microsoft Azure Administrator Access or App Registration Role

Procedure

1. Login to Microsoft Azure Portal.

2. Navigate to App Registration blade.

3. Create a new App Registration called PlaceOS User Authentication

   • Supported account types should be ‘Accounts in this organisational directory only’

   • See also:

4. Configure a Web Redirect URI with the PlaceOS Redirect URI created in the previous step eg. https://<YOUR-PLACEOS-DOMAIN>/auth/oauth2/callback?id=<OAUTH_STRAT-XXXX>
5. Note down the:

   • Application (client) ID as this will be required to be provided to PlaceOS.

   • Directory (tenant) ID as this will be required to be provided to PlaceOS.

6. Once created, navigate to Certificates and Secrets.

7. Create a New Client Secret called PlaceOS User Auth Secret and note down the secret value (you will need to supply this to PlaceOS).

8. Navigate to 'API Permissions'.

9. Click 'Add Permission'.

10. Click 'Microsoft Graph'.

11. Click 'Delegated Permissions'.

12. Add the following Permissions:

    • Calendars.ReadWrite

    • Calendars.ReadWrite.Shared

    • Group.Read.All

    • User.Read.All

    • offline_access

    • openid

    • profile

13. Click 'Grant admin consent'

14. This completes the App Registration.

The Workplace App is the primary user interface for end users to interact with the PlaceOS Platform and facilitates a range of functions, including:

• Room Booking

• Desk Booking

• Locker Booking

• Car Park Booking

• Building Floor Plans

• Real Time Location

• Room Status

• Your Bookings

Deployment

The Workplace app is typically configured at the base route of your PlaceOS Deployment i.e. https://yourdomain.placeos.run it may also be accessed via https://yourdomain.placeos.run/workplace

This is configured by the directory of the application configured for the relevant domain per the guide.

Some instances may also have a development interface, pulling from the development branch, this is typically configured as https://yourdomain.placeos.run/workplace-dev

Set The Base Route

If you would like the Workplace App to be the default base route of your deployment, you must configure a default app on the domain.

1. Navigate to PlaceOS Backoffice

2. Click on Domains

3. Select your Domain

4. Click into the Config Metadata

5. Add the default_app parameter

Configure the default_app parameter to the folder for the workplace app, typically /workplace/

This page will help you if you are using Azure Active Directory for SSO. You will need to configure a new or existing "App Registration" to be the SAML2 identity provider for PlaceOS.

Step 1 - New or Existing App Registration

1. Login to portal.azure.com and browse to Azure AD > App Registrations

2. Locate the existing app created for o365 Graph API access. If there isn't one yet, create a new app registration now. You can use this app for both SSO and o365 Graph API access

   • To create a new app registration:

     • Name it and select the appropriate "Support Account types" (typically "Single tenant")

     • Paste the PlaceOS Assertion URL (generated in Step 1 of Configuring PlaceOS for SAML2) into the Reply URL field. Leave the type as "Web". Click Register to finish

   • To configure an existing app registration:

     • Navigate to Overview -> Redirect URIs

     • Paste the PlaceOS Assertion URL (generated in Step 1 of Configuring PlaceOS for SAML2) into the Redirect URI field. Leave the type as "Web". Click Save to finish

3. Confirm that you have access to the SAML2 Federation Metadata URL for your Azure Tenant. You will need data from this XML file later in Step 3, OR if you configure advanced custom claims. The file URL is generally in the format: https://login.microsoftonline.com/<Tenant_ID_or_Domain_Name>/FederationMetadata/2007-06/FederationMetadata.xml

Step 2 - Edit the App Manifest

In the app Manifest, you need to edit groupMembershipClaims and optionalClaims.

1. Select the app from Step 1 from the list of App Registrations. Then select Manifest (near the bottom) from the menu on the left

2. In the editor, set groupMembershipClaims to either “All” or “SecurityGroup”. This page may help you decide which is most suitable for your organization. If unsure, select All. For each option the groups claim will contain:

   • “SecurityGroup” - identifiers of all security groups of which the user is a member

   • “All” - identifiers of all security groups and all distribution lists of which the user is a member

3. Set the value of the optionalClaims to include first name, last name, UPN, and email in the saml2Token. An example is below:

  "optionalClaims": {
      "idToken": [],
      "accessToken": [],
      "saml2Token": [
          {
              "name": "email",
              "essential": true
          },
          {
              "name": "upn",
              "essential": true
          },
          {
              "name": "family_name",
              "essential": true
          },
          {
              "name": "given_name",
              "essential": true
          }
      ]
  },

1. Click Save

Step 3 - Collect data required by Backoffice

The App Registration is now configured for PlaceOS. You now need to enter two pieces of information into Backoffice (Step 3 of Configuring PlaceOS for SAML2):

Issuer

You will need the "Application (client) ID" found on the Overview page of your App Registration. Adding spn: to the front will give the "Issuer", e.g. spn:00000000-0000-0000-0000-000000000000. The 0 digits are the "Application (client) ID" from Azure AD. Paste this value into the Issuer field of the SAML2 authentication object you created in PlaceOS.

IDP Target URL

Also known as SAML2 sign-on endpoint. This is the URL that PlaceOS redirects users to, so they can login with your SAML2 ID provider. For Azure AD, the URL is: https://login.microsoftonline.com/<TENANT-ID>/saml2. The "Directory (tenant) ID" can is in the Overview tab of your Azure App Registration. Paste this into the IDP Target URL field of the SAML2 authentication object you created in PlaceOS

Once the above steps are complete, we can add the required driver on PlaceOS and configure it with the Application ID, Tenant ID and Secret generated in previous steps.

Prerequisites

• PlaceOS Administrator Access

• Azure Application ID

• Azure Tenant ID

• Azure Application Secret

Add Calendar Driver

If you have already added the calendar driver, you can skip this step.

1. In PlaceOS Backoffice navigate to the Drivers tab.

2. Click New Driver.

3. Select the Drivers Repository.

4. Search for Microsoft Graph API

5. Select the most recent commit.

6. Click Save.

Configure Calendar Driver

1. In PlaceOS Backoffice navigate to Systems.

2. Select the Organisation System, typically this is *Org Name or similar.

3. Click Modules.

4. Click Add New Module.

5. Search for the Microsoft Graph API Driver.

6. Enter the domain your users will use to access PlaceOS eg. https://yourcompany.placeos.run

7. Click Save.

8. Click the Microsoft Graph API Module in the Module list to go to the module settings.

9. Click the Unencrypted tab.

10. Enter the following configuration, noting your application ID, tenant ID and secret.

calendar_config:
  tenant: your-tenant-id
  client_id: your-application-id
  client_secret: your-client-secret
  conference_type: teamsForBusiness

Testing Calendar Driver

In order to test the Calendar Driver with Delegated Access for Microsoft 365 you will require at least 1 system configured with a room resource and the Microsoft Graph API Calendar Module and Bookings Module added to the system.

1. Navigate to a system configured with the correct modules and a valid room resource address.

2. Under Modules, execute poll_events against the Bookings_1 module.

3. You should get a successful response.

4. If you enable Debug and open the Console and the room has valid bookings, you will see the module return the next meeting details.

Overview

This guide will step through the process of creating a domain and the associated application(s) that will exist on it.

You must create a domain before adding authentication sources (such as SAML) to it.

Prerequisites

1. PlaceOS has been deployed

2. You know the domain(s) required for the deployment and the applications on them

Step 1: Create the New Domain

1. Log in to Backoffice on the domain created during deployment and select the Domains tab

2. Select the + button to bring up the New Domain form

3. Add the following fields:

   • Name: Can be anything to identify the domain, like the domain itself i.e. placeos.domain.com

   • Domain: The actual domain, without a protocol i.e. placeos.domain.com

   • Login URL: The URL redirected to when a user logs in

     • You should usually set this to /login?continue={{url}}

   • Logout URL: The URL redirected to when a user logs out

     • You should usually set this to /auth/logout

Step 2: Add an Application to the Domain

1. Select the Applications tab

2. Choose New Application

3. Add the following fields:

   • Name: Can be anything to identify the applications

     • Usually the folder path where the application resides but capitalized i.e. Backoffice

   • Scopes: Leave this blank

   • Skip Authorizaiton: Check the box to set this to true

   • Login URL: The location that users are redirected to after completing authentication

     • This will generally be something like https://<domain>/<application path>/oauth-resp.html

Step 3: Add a User to the Domain

1. Select the Users tab

2. Select the New User button

3. Add or select the following fields:

   • Domain: Select the domain you created in Step 1

   • First Name: Add the first name of the user, this is required

   • Last Name: Add the last name of the user, this is required

   • Email: This will be the username and is required

   • System Admin: Denotes whether the user will be an admin (and thus can access and make changes in Backoffice)

     • This will usually be set to true when creating users in this interface

   • Password and Confirm Password: Enter the password which the user will use to login (when not using SSO)

You can now login with this new user on the domain created.

CI/CD

To work with PlaceOS frontend repositories must have build artifacts committed to a standalone repository or branch.

The user-interfaces repository already has CI/CD pipelines setup using GitHub Actions.

The user-interfaces repository follows these steps for the build pipeline:

1. Commit made with changes to libs or an application(apps/<project>)

2. Pipeline in GitHub Actions starts

3. Install dependencies and build application(s)

4. Commit build artifacts to associated branch. For example, a development build of workplace will be committed to build/workplace/dev

Backoffice Setup

Once a build has been created it can be added to Backoffice so that frontends service can pull down the interface.

Add Repository

1. Navigate to the repositories page

2. Add a new repository

• Name should describe the UI

• Folder name will be the path of the UI on the domain e.g. workplace would map to https://my.domain/workplace/

• Repository is the URL of your git repository with the UI builds

• Repository type must be Interface for the deployment of a UI

• Branch is the build branch of the User Interface

Configure Routing

1. You will need to register the new application on your domain.

   • Navigate to Domains

   • Select your application domain + Navigate to the applications tab + Press new Application

   • The login URL should be set to the location of your oauth-resp.html file from ts-client

After that you should be able to access your application at the URL https://my.domain/<folder>/.

Updating

Once the application is setup in Backoffice it should automatically pull any changes to the set branch every hour. If you to make a manual update there is a pull button in the about section of the repositories page.

Prerequisites

• PlaceOS BAckoffice Administrator Access

• client_id and secret obtained from Google.

Procedure

1. In PlaceOS Backoffice navigate to the Domains tab.

2. Select the domain you would like to add Microsoft Authentication to.

3. Click the Authentication Tab.

4. Identify the OAuth Source previously created.

5. Click the Edit Icon.

6. Update missing fields per the table below

Configuring fields

These fields are specific to the OAuth2 provider and tend to differ slightly between providers.

Details on how will be used to describe the following fields

• name: a friendly name for this authentication configuration

• client_id: the id provided by the OAuth2 provider when you added a new application

• client_secret: as above

• site: the URL of the application requesting access (https://poc.placeos.com in the screenshot above)

• scope: the scopes, space separated, for the APIs that are intended to be accessed

• token_method: POST or GET, Google uses a POST to obtain a token

• authentication_scheme: do we use request params or request body to obtain a token, Google uses the body

• token_url: the URL to obtain a token from, Googles is https://oauth2.googleapis.com/token

• authorize_url: this is the URL that initialises the OAuth2 request. .

• user_profile_url: the is is the URL we can use to test the OAuth2 token and obtain user details

• info_mappings: this maps PlaceOS fields to User Profile fields

• authorize_params: query params to pass along with the authorize URL

• ensure_matching: authorization response fields that should match

Google Example

An example configuration that works with Google

• scope: profile email

  • https://www.googleapis.com/auth/admin.directory.user.readonly

  • https://www.googleapis.com/auth/admin.directory.group.readonly

  • https://www.googleapis.com/auth/userinfo.email

• token method: POST

• Auth Scheme: Request Body

• Token URL:

• Authorize URL:

• User Profile URL:

• Info Mappings: (PlaceOS -> Google)

  • email -> email

  • first_name -> given_name

  • last_name -> family_name

  • uid -> sub

  • image -> picture

  • access_token -> token

  • refresh_token -> refresh_token

  • expires -> expires

  • expires_at -> expires_at

• Authorise Params

  • access_type -> offline (this will return a refresh token)

  • prompt -> consent (ensures we are always sent a new refresh token on login)

• Ensure Matching

  • hd -> my.google.apps.domain (typically the domain after the @ in your login name)

The above stores a refresh token against each user for scoped directory access. A simpler version if token based access isn't required could be:

Overview

This page assists with deploying PlaceOS on AWS using CloudFormation templates. The templates configure a PlaceOS Fargate deployment including an optional VPC configuration. The basic premise is:

1. Upload the nested templates to an S3 bucket

2. Orchestrate the deployment using a root stack template

You can use the upload-s3.sh script in the AWS command-line tool to upload the required files to a configurable S3 bucket.

A CloudFormation template specifies all the components. Each component is designed to deploy as its own CloudFormation stack.

The root stack requires the following files and directory structure:

• Security Groups: infra/sec_groups.yml

• Application Load Balancer: infra/load-balancer-https.yml

• Elastic File System: infra/EFS.yml

• Elasticsearch: managed/elasticsearch.yml

• ElastiCache: managed/elasticache-redis-cluster.yml

• Fargate Cluster: fargate/ecs-cluster.yml

• RethinkDB: fargate/rethinkdb/single/rethinkdb-primary.yml

• etcd: fargate/etcd-service.yml

• dispatch: fargate/dispatch-service.yml

• NGINX: fargate/nginx-service.yml

• Frontends: fargate/frontends-service.yml

• auth: fargate/auth-service.yml

• core: fargate/core-service.yml

• triggers: fargate/triggers-service.yml

• rubber-soul: fargate/rubber-soul-service.yml

• REST API: fargate/rest-api-service.yml

• init: fargate/init-service.yml

VPC Architecture infra/vpc.yml

The VPC root stack template infra/vpc.yml deploys two private and two public subnets. For each of these the user can configure:

• CIDR ranges

• An internet gateway

• Two NAT gateways

• Routes and route tables

The application load balancer is the only component that should deploy in public subnets.

Configuring the root stack template

Once you have uploaded the files to S3, use root-stack-templates/placeos/deploy.yml to deploy PlaceOS. The required parameters are:

• BucketName S3 Bucket name where nested templates live

• CertificateId Certificate Identifier from AWS ACM - required for TLS/SSL

• EnvironmentName An environment name that is a suffix for resource names

• PLACEEMAIL Email address to login initially to the application

• PLACEPASSWORD Password to login initially to Backoffice

• PLACEUSERNAME Users Name

• PrivateSubnet1 Select a private subnet

• PrivateSubnet2 Select another private subnet

• PublicSubnet1 Select a public subnet

• PublicSubnet2 Select another public subnet

• VPC Select the VPC containing the public and private subnets

• VpcCIDR IP range (CIDR notation) for the VPC

AWS EnvironmentName parameter and Stack naming

The EnvironmentName parameter's uses include:

• Tagging

• Service discovery

• Linking outputs of templates with inputs of later templates

PlaceOS is the default but each deployment in the same VPC should configure its own EnvironmentName. The Stack name you choose for each component has no effect on the function of the deployment.

init: fargate/init-service.yml

initializes the PlaceOS instance and is the final step in the deployment.

Accessing the deployed PlaceOS Backoffice application

You can expect the deployment to take 20-30 minutes, most of which is Elasticsearch. The Backoffice application will be available at:

https://{Application_Load_Balancer_DNS_NAME}/login?continue=/backoffice

The credentials are the email and password set by the init service. You can also find the application URL listed as an output for the init nested stack.

The PlaceOS Calendar Driver connects to Microsoft Graph API (365) or Google Workspace.

The Calendar Driver and the work together to get resource calendar events.

The Calendar Driver can also make ad-hoc bookings from kiosks or room booking panels.

Prerequisites

• Administrator access to your PlaceOS Backoffice

• PlaceOS Drivers Repository Configured in Backoffice

• Systems have a valid calendar resource address from Microsoft 365 or Google Workspace

Add Driver

Before we can use the PlaceOS Calendar Driver we must instantiate it as a driver.

1. Navigate to the Drivers tab

2. Click the + icon to add a new driver

3. Select PlaceOS Drivers Repository

4. Select the drivers > place > calendar.cr Driver Base

5. Select the latest commit

6. Click Save

Add to System

You need to instantiate a single instance of the PlaceOS Calendar Driver.

We recommend instantiating the driver in a generic system e.g. *Tracking.

That module is then added to each system that requires booking or calendar functionality.

Instantiate the Driver

1. Navigate to the system you will instantiate the driver in

2. Select the Modules tab

3. Click Add New

4. Search for the PlaceOS Calendar driver

5. Click Save

6. Enable the driver by clicking the black dot, it should turn green

Configure Driver

The driver is now instantiated as a module, we need to configure the API Credentials.

1. Navigate to the Drivers tab

2. Select the Calendar Driver

3. In the Settings view select unencrypted tab

4. Delete all the example configuration provided by the driver

5. If using Google Calendar API, paste this configuration into the encrypted tab:

6. If using Office 365, paste this configuration into the encrypted tab:

7. Enter your API information for Microsoft Azure or Google Workspace replacing placeholder text

Add Module to Systems

You can now add the module to other systems as required.

1. Navigate to an existing system

2. Select the Modules tab

3. From the drop down, select the Calendar Module

4. Click Add Existing

Test Module

You can test by creating a booking or inspecting the state of the Calendar Driver.

Inspecting State should return a valid response.

This should return:

You can also execute a function on the module and view the response.

As a test, executing the list_users function should return a list of users if connected properly.

PlaceOS can generate API Keys for authenticated access.

The API keys can be used for:

• Accessing the

• Using the

Prerequisites

• Administrator access to your PlaceOS Backoffice

Generate API Key

1. Login to PlaceOS Backoffice

2. Navigate to the Admin Tab

3. Select API Keys

4. Select the domain the API Key will belong to

5. Any existing API Keys will be shown in the list

6. Click Add API Key

7. Enter the required information:

   • Name: Suitable name for the API Key

   • Description: What the key will be used for (useful for other administrators)

   • Scopes: Select from available scopes (see available scopes below)

   • User: The user in which the API Key will emulate

   • Permissions: Permission level assigned to the API Key (see permission details below)

8. Click Save

9. The new API Key will be shown once after it is saved, you will not be able to view it again

Available Scopes

Available Scopes for API Keys are:

• public A special scope that can access all routes (supports read and write modifiers)

• api_keys

• ldap_authentication

• saml_authentication

• o_auth_authentication

• o_auth_applications

• brokers

• cluster

• domains

• drivers

• settings

• modules

• guests A special scope for guests that provides

• systems

• control .read: module class types, function list of a module, module state lookup .write: control websocket, API execute request

• edges

• metadata

• repositories

Available Permissions

• scope.read

• scope.write

Using the API Key

API Keys are typically passed in the header of the request, however can be used in the following ways

1. HTTP Header: X-API-Key: <token>

2. URL param: ?api-key=<token>

3. A HTTP Cookie: api-key=<token>

Removing an API Key

1. Navigate to the API Key Page in Backoffice located in the Admin Tab.

2. Click the trash icon to remove the key.

Scopes for Common Applications

X-API Keys can be used for unattended panel authentication, scopes are required for these applications to function. The table below outlines common applications that require API Keys and the associated scopes.

Location services

Location services are any driver that support the

The driver collects the responses of locatable modules in the same system and returns this as the result of a location search.

Response types

The frontend translates the search responses into a pin on a map. These are the supported formats:

X,Y Location

Such as a location calculated by a wireless network

Map Feature

Such as a desk

Desks highlight based on desk metadata stored against each level zone:

Where bookable is false, desks highlight based on sensor data

NOTE:: no metadata is required for area locations assuming there is a matching map_id, in which case the highlighting is based on the used capacity (low, medium or high)

Booking

Such as an event in a meeting room

Lockers

Any lockers that are in use on the floor

Configuring Cisco Meraki

See the guide.

Generate a Mist API token

You must record and save the API Token immediately after generating it, as the API Token cannot be re-displayed.

To generate a Mist API Token:

1. In your browser, access the . The Mist Sign In page opens.

2. Log in to your Mist account by entering your account credentials.

3. While logged in to your Mist account, open another browser tab and access the URL

4. Select POST The generated API Token displays in the following format:

   • "key": "<randomly generated character string>" where the character string is the API Token For example, "key": "34223XFE...e5"

   • also see the

5. Record and save the API Token, before closing the browser tab.

Note the following about Mist API Tokens:

• An API Token generated for a specific admin has the same privilege as the user

• API Tokens are automatically deleted, if not used within 90 days.

Obtain the Site ID

When you configure the PlaceOS connection to Mist, you'll need the site_id for the network you want to monitor. You can obtain these by:

1. logging into the

2. select the organisation and site (orange arrow below)

3. Record and save the UUID from the URL (highlighted in orange)

Configure Mist Websocket Driver

Add the Juniper Mist Websocket driver to the drivers list and configure the settings

Then add the driver to the location services system.

Obtain the list of map ids

We'll need to link Mist maps to PlaceOS maps. Use backoffice to execute the following command:

• MistWebsocket -> maps (execute)

This will return data like:

Configure Mist Location Services

Add the Juniper Mist Locations driver to the drivers list and configure the settings

Once the floor mappings are in place and the module has been added to your location services system, WIFI users will be searchable.

Microsoft Azure Active Directory/365

Google Workspace

Prerequisites

• PlaceOS Backoffice Administrator Access

• Microsoft Azure App Registration client_id and client_secret generated in the Microsoft Azure App Registration steps.

Procedure

1. In PlaceOS Backoffice navigate to the Domains tab.

2. Select the domain you would like to add Microsoft Authentication to.

3. Click the Authentication Tab.

4. Identify the OAuth Source previously created.

5. Click the Edit Icon.

6. Update missing fields per the table below.

These fields are specific to the OAuth2 provider and tend to differ slightly between providers.

Details on how Azure handles OAuth2 will be used to describe the following fields.

PlaceOS Staff API

Once you have completed the above steps, you will also need to create a StaffAPI Record for your domain.

To create the Staff API Record follow these instructions on configuring Staff API.

Overview

Backoffice supports uploading files to cloud storage for secure temporary access or public read. This is useful for device documentation, SVG Floor Maps or Room Photos.

Prerequisites

1. Configure your storage bucket on the cloud storage platform

2. Ensure CORS is enabled for the domain Backoffice will be uploading from

3. Note the storage bucket name

4. Generate access credentials for the storage bucket

Backoffice configuration

1. Go to the Manage instance tab and select Upload Storage

2. You can optionally configure a default storage solution or a per-domain one

3. Enter the bucket name and access keys, examples below:

Cloud configuration

S3 Configuration

You will find this under bucket permissions -> CORS configuration.

[
    {
        "AllowedHeaders": [
            "Authorization",
            "content-type"
        ],
        "AllowedMethods": [
            "GET"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": [],
        "MaxAgeSeconds": 3000
    },
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "PUT",
            "POST",
            "DELETE"
        ],
        "AllowedOrigins": [
            # add the domains that will be uploading files here
            "https://os.place.tech",
        ],
        "ExposeHeaders": []
    }
]

You will want to configure the access key with minimal permissions too:

1. In IAM, create a new user to act as the service account

2. Grant the user no permissions except S3 List, Read, Write, Object permissions management

3. Generate some access keys to use for signing upload requests

An example IAM user policy for file uploads:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "s3:ListBucket",
            "Resource": "arn:aws:s3:::os.place.tech"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": "s3:*Object",
            "Resource": "arn:aws:s3:::os.place.tech/*"
        },
        {
            "Sid": "VisualEditor2",
            "Effect": "Allow",
            "Action": [
                "s3:PutObjectVersionAcl",
                "s3:PutObjectAcl"
            ],
            "Resource": "*"
        }
    ]
}

If you don't want the user to have object permission management then you also override the bucket level policy, where all objects are public

{
    "Version": "2008-10-17",
    "Id": "Policy1397632521960",
    "Statement": [
        {
            "Sid": "Stmt1397633323327",
            "Effect": "Allow",
            "Principal": {
                "AWS": "*"
            },
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::os.place.tech/*"
        }
    ]
}

Upload Files

Once the above configuration steps are completed, you should be able to upload files to PlaceOS.

To upload a file, drag and drop it into Backoffice in your browser.

The file upload status will be displayed.

Once the upload is complete, you can copy the file URL and use this as required.

:::tip The uploaded file will be given a discrete URL on the storage bucket, for example: https://s3-ap-southeast-2.amazonaws.com/bucket.name/directory.name/16221818379492128.svg. Characters will be automatically encoded, if present. :::

*[CORS]: Cross-Origin Resource Sharing *[IAM]: Identity & Access Management

The PlaceOS Native Booking Panel App may be deployed stand-alone from the public Apple App Store and Google Play Store or deployed to a fleet of devices via a Mobile Device Management platform.

The Mobile Device Management platform will provide some added benefits of passing additional pre-configuration to each device to make the set up process easier. End users would need to refer to documentation specific to their MDM for these instructions.

Configuring The App

Configuring the App requires three key pieces of information:

• PlaceOS API Key: Click here to learn how to generate an API Key.

• Your PlaceOS URL.

• A Room Booking System configured.

1. On first launch, the app will provide some brief instructions detailing the required information as above.

2. On the second screen, enter your PlaceOS Domain/URL. This is the URL your users use to access existing PlaceOS Apps eg. https://yourcompany.placeos.run

3. Next, enter the API Key you have generated or was provided to you by PlaceOS Support.

4. Finally select the room you wish the panel to display. If you have multiple systems a drop down will be shown, or you can search for the system by name or ID.

5. The app will launch and display the room booking panel interface.

Configuring Device to Remain On

When using an Android Tablet or Apple iPad as a Kiosk Device, you will need to ensure the device will remain unlocked.

If you are using a Mobile Device Management platform you can configure this as part of your room booking profile.

For Apple devices, this is referred to as Guided Access and can be configured with these instructions.

Screen Pinning is one technique on Android devices, although depending on the make and model of the tablet you may require a third party app to configure Kiosk Mode. You can read more about pinning apps here.

Deploying via MDM

The booking panel app is designed to support custom configuration that can be deployed along with the app via a MDM Platform such as SimpleMDM or Google Device Manager.

For this to work, you must use the correct keys in your configuration schema and submit the required information.

Once the data is received by the device, they will display the custom configuration and ask for the data to be validated. Once this is complete, you can set the appropriate Room System on the device.

Dictionary

The following dictionary is required for generating custom configuration:

<?xml version="1.0"?>
<managedAppConfiguration>
  <version>1</version>
  <bundleId>place.technology.bookingPanel</bundleId>
  <dict>
    <string apiKey="2246a9570b1e821a337c47353c.cUm33sGOmjHlSCbf5M07v8y8vRa4_GBmCW7hFkU"></string>
    <string domainName="https://placeos-dev.aca.im"></string>
    <string systemId="sys-223fn20n"></string>
  </dict>
</managedAppConfiguration>

It's possible to create a custom LLM chat bot per system, providing the LLM with the ability to execute functions within the system.

For a system to work as a ChatGPT chat bot it requires the PlaceOS LLM Interface driver. This driver is used to define the system prompt and the initial message to display to the user.

Drivers implementing the ChatFunctions interface expose the available functionality to the LLM.

Building a capability

Each driver should encapsulate related functions that can easily be summarised. This summary is used by the LLM to discover the driver with the function it needs.

The key to building effective functions is to make them as human friendly as possible. If the parameters are hard to understand and not constructed for a human the LLM will produce more errors. An example would be to use parsable date strings over Unix timestamps.

Descriptions should explain how to use any non-obvious parameters and be firm when describing any order of operations:

# Capability example
getter capabilities : String do
  String.build do |str|
    str << "provides details of my daily schedule, meeting room bookings and events I'm attending.\n"
    str << "lookup or search for the email and phone numbers of other staff members if you haven't been provided their details. Do not guess.\n"
    str << "check schedules before booking or moving meetings to ensure no one is busy at that time\n"
  end
end

# Parameter usage example, only functions with descriptions are provided to the LLM
@[Description("search for a staff members phone and email addresses using odata filter queries, don't include `$filter=`, for example: `givenName eq 'mary' or startswith(surname,'smith')`, confrim with the user when there are multiple results, search for both givenName and surname using `or` if there is ambiguity")]
def search_staff_member(filter : String)
  # ...
end

See the example TODO driver and spec as a template.

Configuring access to OpenAI or Azure APIs

Either OpenAI or Azure APIs can be used to provide LLM model functionality. API keys can be defined for each domain in the internal settings.

Settings