Deploying OnSite in a Non-SaaS Environment

Managing Version Compatibility

Your version of Apollo must be in sync with the OnSite release. For example, OnSite V6 requires Apollo V6. Given this requirement, Eptura provides two options for deploying OnSite and managing version compatibility.

Option 1: Use MDM (mobile device management) to manage version compatibility.

This option is recommended for non-SaaS deployments, particularly for organizations with limited IT resources, and organizations that take time to allocate their IT resources.

Option 2: Business Partners maintain version compatibility for their customers.

If you do not use MDM, follow this procedure for each new OnSite release.

A month ahead of a release, Eptura notifies you of the upcoming release so that you can prepare IT resources. Eptura reminds you again a few days before the OnSite release.
A few days before the OnSite release, Eptura sends you a zip file of the new Apollo files.
You upgrade the OnSite Apollo server to the new compatible version before the OnSite release. You can also do this once OnSite is released.

Components

Non-SaaS deployments require the following:

The OnSite mobile app, downloaded from the Apple or Google Play app stores.
At least one of the following applications:
- Corrective Maintenance application
- Preventive Maintenance application
An Apollo GraphQL server to connect the OnSite mobile app with the Archibus Web Central API. For OnSite V6, you must have Apollo V6.
An OIDC-compliant cloud identity provider (IdP) to authenticate app users. OnSite currently supports the Okta and Microsoft Azure identity providers.
If your site uses SSO (single sign-on) for Web Central, you will create a dedicated Web Central server for OnSite REST API calls.

Step 1: Configure an Identity Provider

The OnSite app authenticates users with a cloud identity provider (IdP) that is OpenID Connect (OIDC)-compliant. Customers will need to provide the cloud IdP. The app currently supports the following providers: Okta or Microsoft Azure.

See:

Step 2: Deploy an Apollo GraphQL Server

The OnSite mobile app connects to the Archibus API using the Apollo GraphQL platform as shown in the diagram below:

OnSite mobile app <> OnSite Apollo GraphQL <> Archibus Web Central

You will need to deploy an Apollo GraphQL server with the OnSite software. This could be the same server hosting Archibus Non-SaaS.

Procedure

Following is an outline of the key requirements for setting up an Apollo GraphQL server for OnSite. Please consult with your IT department for steps specific to your environment.

Select a server for the OnSite Apollo setup, running on either Windows, Linux, or macOS. The server will be hosting the Node.js software and the Apollo GraphQL platform configured for OnSite.
Download the LTS version of Node.js from Download | Node.js (nodejs.org) , and install the software on the selected server.

To ensure that Node.js is properly installed, open the server’s Command or Terminal prompt and type the below code to test the node and npm commands:

Command	Output
`node -v`	something like v16.3.1
`npm -v`	something like 7.15.1

Download the OnSite Apollo setup contained in onsite-apollo-release-v3.0.0.zip .
- This is available to download from Eptura Allbound at: https://eptura.allbound.com/my-dashboard/ .
Unzip the setup files in the onsite-apollo-release-v3.0.0 folder.
Open the server’s Command or Terminal prompt, go to the /onsite-apollo-release-v3.0.0 folder, and run the following commands to install the OnSite Apollo GraphQL files and to start the server:

npm install npm start

The Apollo server will now be running on a URL with your local IP address, such as http://USERS_LOCAL_IP_ADDRESS:4000 .

Step 3: Configure Web Central

Configure Archibus Web Central to reflect the selected identity provider (IdP) and the Apollo GraphQL server by updating the settings in the following files:

WEB-INF\config\context\applications\configservice.properties
WEB-INF\config\oidc.properties

When through editing these files, restart the Archibus Web Central server. It is best to delete and install the OnSite app again when switching between OIDC providers.

For details, see:

Step 4: Configure REST API Traffic Configuration (If using SAML SSO Authentication for Web Central)

Note : You can use your same license for all instances. You will be fine with license counts since the OnSite API server consumes only the OnSite license.

You need to take this step because the Archibus OnSite App server can get confused when the Archibus OnSite App server is configured with SSO Authentication and also OIDC is configured for OnSite

You need to not forward through your reverse proxy server (or however else you are doing SAML authorization) items for which the following paths apply:

/archibus/cxf/configs/version
/archibus/cxf/configs/onsite
/archibus/api/*

This requires setting up a load balancer with traffic routing rules for each server. For example, set up traffic routing rules such as the following. (This image is for a SaaS deployment, but the same principles apply for a non-SaaS deployment.)

It is important to list the rules in the proper order. In the above example, the request goes to the API server first and then is forwarded as needed.

Step 5: Allow Sentry.io through your Firewall (Optional)

If you run OnSite on your employees' phones through a company firewall, it is suggested that you enable calls to Sentry.io domain. OnSite uses Sentry to log errors that might occur during app use, which enables us to resolve potential issues more quickly. Data logged in Sentry is obfuscated and no sensitive data is stored.

Step 6: Configure the Push Notifications

To enable push notification, configure push-notification.properties and configservice.properties , as outlined below.

push-notification.properties

Edit WEB-INF\config\push-notification.properties to provide settings for:

Property	Description	Value
pushNotification.endpoint	AWS notification endpoint URL	This is always `https://onsite.prod.archibus/notification`
pushNotification.endpointApiKey	AWS push notification endpoint API key	Archibus staff manages this for each customer.
pushNotification.workspaceId	OnSite workspace ID	This is the same value that you enter when signing into OnSite at your site. Eptura supplies this to your company.
pushNotification.bundleId	OnSite client bundle ID	For production, this is always `com.archibus.onsite` For staging, this is always `com.archibus.onsite.staging`

Example:

# # Site-configurable properties for OnSite push notification. # The AWS push notification endpoint url pushNotification.endpoint=https://onsite.prod.archibus/notification # The AWS push notification endpoint API Key pushNotification.endpointApiKey=TpTmBvlAnN1gp5vP69KAA2opoG7wNUXr6d8PRBW6 # The OnSite workspace id, for example 'onsite-release-afmusers.dev.archibus.cloud' pushNotification.workspaceId=onsite-release-afmusers.dev.archibus.cloud # The OnSite client bundle id, 'com.archibus.onsite' is for production, 'com.archibus.onsite.staging' is for staging test pushNotification.bundleId=com.archibus.onsite

configservice.properties

Edit \WEB-INF\config\context\applications\configservice.properties to provide push notification-related settings for OnSite client side for:

Property	Description	Value
configService.onsite.notificationServiceUrl	Notification Service URL for mobile apps	This is always `https://onsite.prod.archibus.cloud`
configService.onsite.notificationServiceApiKey	Notification Service API key for mobile apps	Archibus staff manages this for each customer.

Example:

# Notification Service URL for mobile apps configService.onsite.notificationServiceUrl=https://onsite.prod.archibus.cloud # Notification Service API key for mobile apps configService.onsite.notificationServiceApiKey=TpTmBvlAnN1gp5vP69KAA2opoG7wNUXr6d8PRBW6

Step 7: Set up OnSite Users and Log In

For details, see Set Up OnSite Users .