The GUI automation API consist of a set of JavaScript functions which enables programmatic access to some features normally controlled by a user in the GUI. These functions are grouped in a global window.Exivity
object.
session
Control the current user session.
.login
function(string username, string password): void
Attempts to login given the username and password.
.logout
function(): void
Logs out the current user, and cleans up local storage used by the current session.
.refreshToken
function(string token): void
Attempts to use the given token to login (always refreshes the given token).
.apiRoot
function(string root): void
Set the domain (e.g. https://example.com:8002
) for the Exivity API.
navigate
Navigate the GUI.
.home
function(): void
Navigate to the root URL of the Exivity instance, which is the Dashboard if a user is currently logged in, or the login page otherwise.
.to
function(string path): void
Navigates to the given URL fragment.
report
Control the report filters and more.
.byId
function(int id): void
Select a report definition.
.depth
function(int depth): void
Select a reporting depth.
.daterangeStart
function(string start): void
Select a the reporting start date, in YYYYMMDD format.
.daterangeEnd
function(string end): void
Select a the reporting end date, in YYYYMMDD format.
.filterAccount
function(int id): void
Filter the report by showing only this account.
.showSingleAccount
function(bool show = true): void
On the summary report, show only the single account set with filterAccount
.
.showAllSummaries
function(bool show = true): void
Show all summaries if on the /reports/summary
page.
.showConsolidatedSummaries
function(bool show = true): void
Show consolidated summary on the /reports/summary
page.
.showSummaryAccounts
function(bool show = true): void
Show accounts on summary report.
.showSummaryServices
function(bool show = true): void
Show services on summary report.
.showSummaryInstances
function(bool show = true): void
Show instances on summary report.
.summaryGroupInstanceBy
function(string key): void
Group the instances on the summary report by this key. The key
argument should be one of: instances
, services
.
wait
Functions returning a Promise to make it easier to determine the state of the GUI.
.ms
function(int|float ms): Promise
Wait for ms and then resolve the returned promise.
.networkIdle
function(int waitBefore = 100, int waitAfter = 100, int timeout = 60000): Promise
Wait for the network stack to become idle, optionally specifying:
A timeout before starting to detect network traffic
A timeout after detecting that the network became idle
A timeout after which the promise will reject. Set to 0
to disable.
.syncComplete
function(): Promise
Wait for data synchronisation to complete.
Exivity provides a full REST-API which acts as a programmatic interface to each operation supported through the Graphical User Interface (GUI). On top of that, some operations can be exclusively executed through the API (such as file uploads).
A reference guide on all API endpoints and further details about implementation and authentication is publicly available online.
A simple JavaScript API is provided which enables programmatic access to some features normally controlled by a user in the GUI.
With Exivity it's possible to connect your existing AD/ADFS/AAD user directory so your end-users can benefit from an easy SSO experience.
Currently, Exivity supports the Security Assertion Markup Language (SAML) v2 protocol, supported by a large number of identity providers.
We're currently in the planning stages of developing Exivity SDKs in various languages which would make interfacing with the REST-API very straight-forward and easy to implement.
If you want to learn more, please let us know at dev@exivity.com.
Exivity can act as a SAML Service Provider (SP) which can be connected to a SAML Identity Provider (IdP). Some configuration is required to setup a secure connection.
The SAML configuration can be accessed by navigating to Administration > System info and then clicking on the SAML tab. On this page, you'll find two sub-tabs:
Configuration: Your IdP endpoints can be entered here, along with details about the certificate used by the IdP.
Endpoints: When registering Exivity with your IdP, you need to provide these Exivity endpoints.
The configuration settings are listed below:
Using the advanced settings editor, even more options are exposed for configurating the integration. Please note that settings should be entered using a valid JSON format. Please consult with your implementation partner first before editing the advanced settings.
To view the full SAML endpoints for your Exivity instance, navigate to Administration > System and then click on the SAML tab and then the Endpoints sub-tab.
Setting up Azure Active Directory is pretty straight-forward, but it helps to know the exact steps to follow, as configuraing SAML can be a bit daunting.
To add Exivity to your Azure AD applications, follow these steps:
In your Azure portal, go to the Azure Active Directory service:
In the sidebar, click Enterprise applications:
Click the New application button:
Click the Non-gallery application button:
Enter a name for the new application (i.e. My Exivity instance) and click the Add button.
Click the Configure single sign-on (required) button:
From the Single Sign-On Mode dropdown list, select SAML-based Sign-on:
Now enter the following details on this page:
The resulting page could look something like this:
Click the Configure [your application name] button:
A new pane will open with instructions. Navigate to the Exivity SAML configuration (see configuration) and copy the following options from the pane in your Azure portal:
The Exivity configuration page could look something like this:
In Exivity, click the Update button.
In your Azure Portal, click the Save button:
As the last step, enable Single Sign-On in Exivity by navigating to Administration > Configuration and then clicking on the System tab. Make sure the Single Sign-On option is set to Enabled, and click the Update button:
SSO is now configured and enabled, and you can now use Azure AD to login to your Exivity instance. The login screen will look something like this:
And by clicking on the Login button, you'll be taken to the Azure AD login screen. Exivity will receive the Azure AD e-mail address and create a new user with a minimal set of permissions if no existing user is found.
First, we need to add Exivity to your Auth0 applications. Follow these steps:
On the Auth0 dashboard, click the Applications menu item, and then the Create application button:
Choose a descriptive name for your application, click the Single Page Web App button, and finally the Create button:
On the application overview page, click the Settings tab:
On this page, fill out the following details and click on the Save changes button:
Now click on the Addons tab, and enable the SAML2 addon:
Click on the SAML2 addon button. On the Settings tab, fill out the following details and click the Save button:
Replace the text[Exivity Single Logout Service endpoint]
with the Single Logout Service endpoint of your Exivity instance (see endpoints)
Click on the Usage tab. In a separate browser tab, open the Exivity SAML configuration (see configuration) and copy over the following settings:
In Exivity, click the Show advanced button. In the Advanced settings field, enter the following and click the Update button:
As the last step, enable Single Sign-On in Exivity by navigating to Administration > Configuration and then clicking on the System tab. Make sure the Single Sign-On option is set to Enabled, and click the Update button:
SSO is now configured and enabled, and you can now use Auth0 to login to your Exivity instance. The login screen will look something like this:
And by clicking on the Login button, you'll be taken to the Auth0 login screen. Exivity will receive the Auth0 e-mail address and create a new user in the configured user group (see configuration) if no existing user is found.
Option
Description
Entity ID
Sometimes called the Issuer or Metadata URL.
SSO URL
The URL of the Single Sign On service endpoint. Sometimes called the SAML 2.0 Endpoint.
SLO URL
The URL of the Single Logout service endpoint.
X-509 certificate
Base-64 encoded (DER) certificate:
- on a single line
- without -----BEGIN CERTIFICATE-----
and -----END CERTIFICATE-----
Default user group
When a new user logs in using SSO, a user will be created in this user group.
Endpoint
Description
/v1/auth/saml/login
Login URL. Initiate SAML login request. Redirects to SAML Identity Provider SSO URL set in the SAML configuration. After a successful authentication (possibly interactive), it will redirect back to this APIs ACS endpoint.
/v1/auth/saml/logout
Logout URL. Initiate SAML login request. Redirects to SAML Identity Provider SLO URL set in the SAML configuration. After the user has been logged out, it will redirect back to this APIs SLS endpoint.
/v1/auth/saml/metadata
Entity ID / Metadata URL. Metadata about the SAML Service Provider instance will be published at this URL.
/v1/auth/saml/acs
Assertion Consumer Service. If the received response from the SAML Identity Provider is valid, redirects to the Exivity dashboard.
/v1/auth/saml/sls
Single Logout Service. If the received response from the SAML Identity Provider is valid, redirects back to the login screen of Exivity.
Azure AD setting
Use value
Identifier
Exivity Entity ID / Metadata URL endpoint (see endpoints)
Reply URL
Exivity Assertion Consumer Service endpoint (see endpoints)
Show advanced URL settings
Checked
Sign on URL
Optional, you can enter the URL for the Exivity interface here.
Relay State
Leave empty
User Identifier
Select user.mail
Exivity SAML setting
Use value
Entity ID
SAML Entity ID
SSO URL
SAML Single Sign-On Service URL
SLO URL
Sign-Out URL
X-509 certificate
Download the certificate by clicking the SAML Signing Certificate - Base64 encoded link. Open the .cer
file with a text editor and remove the text -----BEGIN CERTIFICATE-----
, -----END CERTIFICATE-----
and all line breaks so you end up with a single-line base64 encoded string.
Field
Value
Allowed Callback URLs
Allowed Logout URLs
Exivity Single Logout Service endpoint (see endpoints)
Field
Value
Application callback URL
Exivity Entity ID / Metadata URL endpoint (see endpoints)
Settings
See below
Exivity SAML setting
Use value
Entity ID
Issuer
SSO URL
Identity Provider Login URL
SLO URL
Identity Provider Login URL, suffix with /logout
X-509 certificate
Download the certificate by clicking the Download Auth0 certificate link.
Open the .pem
file with a text editor and remove
the text-----BEGIN CERTIFICATE-----
, -----END CERTIFICATE-----
and all line breaks so you end up with a single-line base64 encoded string.