Display all invoices

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.

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:

• Click on the SAML2 addon button. On the Settings tab, fill out the following details and click the Save button:

{
  "nameIdentifierProbes": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
  ],
  "logout": {
    "callback": "[Exivity Single Logout Service endpoint]"
  },
  "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
}

• Click on the Usage tab.

In a separate browser tab, open the Exivity SAML configuration (see configuration) and copy over the following settings:

• As the last step, enable Single Sign-On in Exivity by navigating to Administration > Settings 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.

Setting up LDAP in Exivity

First, go to Administration - Settings - Single sign-on and choose the LDAP tab:

Fill the required Server and Attributes section parameters, and click on UPDATE.

Server section:

Attributes section:

Finally, go to the System tab, in the Core section, set the Single Sign-On parameter to Local and LDAP Authentication and click on UPDATE.

Now you can start login in Exivity using LDAP authentication.

Setting up your security certificate

If you don't have a certificate in .pem format you can convert your current certificate with the OpenSSL tool.

Once you have your pem certificate stored in the server hard drive, take a note of its path, and create a system environmental variable LDAPTLS_CACERT . The value of this environmental variable will be the certificate full path.

Finally, restart the Exivity Web Service.

REST-API

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 can be found at https://api.exivity.com.

GUI automation API

A simple JavaScript API is provided which enables programmatic access to some features normally controlled by a user in the GUI.

Single Sign-On

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.

SDKs

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.

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.

SAML configuration

The SAML configuration can be accessed by navigating to Administration > Settings 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.

Configuration

The configuration settings are listed below:

Advanced settings

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.

{
    // Service Provider Data that we are deploying
    "sp": {
        // Identifier of the SP entity  (must be a URI)
        "entityId": "",

        // Specifies info about where and how the <AuthnResponse> message MUST be
        // returned to the requester, in this case our SP.
        "assertionConsumerService": {

            // URL Location where the <Response> from the IdP will be returned
            "url": "",

            // SAML protocol binding to be used when returning the <Response>
            // message.  Onelogin Toolkit supports for this endpoint the
            // HTTP-Redirect binding only
            "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
        },

        // If you need to specify requested attributes, set a
        // attributeConsumingService. nameFormat, attributeValue and
        // friendlyName can be omitted. Otherwise remove this section.
        "attributeConsumingService": {
            "ServiceName": "SP test",
            "serviceDescription": "Test Service",
            "requestedAttributes": [
                {
                    "name": "",
                    "isRequired": false,
                    "nameFormat": "",
                    "friendlyName": "",
                    "attributeValue": ""
                }
            ]
        },

        // Specifies info about where and how the <Logout Response> message MUST be
        // returned to the requester, in this case our SP.
        "singleLogoutService": {

            // URL Location where the <Response> from the IdP will be returned
            "url": "",

            // SAML protocol binding to be used when returning the <Response>
            // message.  Onelogin Toolkit supports for this endpoint the
            // HTTP-Redirect binding only
            "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
        },

        // Specifies constraints on the name identifier to be used to
        // represent the requested subject.
        // Take a look on lib/Saml2/Constants.php to see the NameIdFormat supported
        "NameIDFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",

        // Usually x509cert and privateKey of the SP are provided by files placed at
        // the certs folder. But we can also provide them with the following parameters
        "x509cert": "",
        "privateKey": "",

        // Key rollover
        // If you plan to update the SP x509cert and privateKey
        // you can define here the new x509cert and it will be 
        // published on the SP metadata so Identity Providers can
        // read them and get ready for rollover.
        "x509certNew": ""
    },

    // Compression settings 
    // Handle if the getRequest/getResponse methods will return the Request/Response deflated.
    // But if we provide a $deflate boolean parameter to the getRequest or getResponse
    // method it will have priority over the compression settings.
    "compress": {
        "requests": true,
        "responses": true
    },

    // Security settings
    "security": {
        /** signatures and encryptions offered */
        // Indicates that the nameID of the <samlp:logoutRequest> sent by this SP
        // will be encrypted.
        "nameIdEncrypted": false,

        // Indicates whether the <samlp:AuthnRequest> messages sent by this SP
        // will be signed.              [The Metadata of the SP will offer this info]
        "authnRequestsSigned": false,

        // Indicates whether the <samlp:logoutRequest> messages sent by this SP
        // will be signed.
        "logoutRequestSigned": false,

        // Indicates whether the <samlp:logoutResponse> messages sent by this SP
        // will be signed.
        "logoutResponseSigned": false,

        // Sign the Metadata: False || True (use sp certs)
        "signMetadata": false,

        /** signatures and encryptions required **/
        // Indicates a requirement for the <samlp:Response>, <samlp:LogoutRequest> and
        // <samlp:LogoutResponse> elements received by this SP to be signed.
        "wantMessagesSigned": false,

        // Indicates a requirement for the <saml:Assertion> elements received by
        // this SP to be encrypted.
        "wantAssertionsEncrypted": false,

        // Indicates a requirement for the <saml:Assertion> elements received by
        // this SP to be signed.        [The Metadata of the SP will offer this info]
        "wantAssertionsSigned": false,

        // Indicates a requirement for the NameID element on the SAMLResponse received
        // by this SP to be present.
        "wantNameId": true,

        // Indicates a requirement for the NameID received by
        // this SP to be encrypted.
        "wantNameIdEncrypted": false,

        // Authentication context.
        // Set to false and no AuthContext will be sent in the AuthNRequest,
        // Set true or don't present this parameter and you will get an AuthContext 'exact' 'urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport'
        // Set an array with the possible auth context values: {'urn:oasis:names:tc:SAML:2.0:ac:classes:Password', 'urn:oasis:names:tc:SAML:2.0:ac:classes:X509'),
        "requestedAuthnContext": false,

        // Allows the authn comparison parameter to be set, defaults to 'exact' if
        // the setting is not present.
        "requestedAuthnContextComparison": "exact",

        // Indicates if the SP will validate all received xmls.
        // (In order to validate the xml, 'strict' and 'wantXMLValidation' must be true).
        "wantXMLValidation": true,

        // If true, SAMLResponses with an empty value at its Destination
        // attribute will not be rejected for this fact.
        "relaxDestinationValidation": false,

        // Algorithm that the toolkit will use on signing process. Options:
        //    'http://www.w3.org/2000/09/xmldsig#rsa-sha1'
        //    'http://www.w3.org/2000/09/xmldsig#dsa-sha1'
        //    'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256'
        //    'http://www.w3.org/2001/04/xmldsig-more#rsa-sha384'
        //    'http://www.w3.org/2001/04/xmldsig-more#rsa-sha512'
        // Notice that sha1 is a deprecated algorithm and should not be used
        "signatureAlgorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",

        // Algorithm that the toolkit will use on digest process. Options:
        //    'http://www.w3.org/2000/09/xmldsig#sha1'
        //    'http://www.w3.org/2001/04/xmlenc#sha256'
        //    'http://www.w3.org/2001/04/xmldsig-more#sha384'
        //    'http://www.w3.org/2001/04/xmlenc#sha512'
        // Notice that sha1 is a deprecated algorithm and should not be used
        "digestAlgorithm": "http://www.w3.org/2001/04/xmlenc#sha256",

        // ADFS URL-Encodes SAML data as lowercase, and the toolkit by default uses
        // uppercase. Turn it True for ADFS compatibility on signature verification
        "lowercaseUrlencoding": false
    },

    // Contact information template, it is recommended to suply a technical and support contacts
    "contactPerson": {
        "technical": {
            "givenName": "",
            "emailAddress": ""
        },
        "support": {
            "givenName": "",
            "emailAddress": ""
        }
    },

    // Organization information template, the info in en_US lang is recomended, add more if required
    "organization": {
        "en-US": {
            "name": "",
            "displayname": "",
            "url": ""
        }
    }
}

Endpoints

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.

Integration tutorials

External resources

• Setup SSO with Azure AD

• Setup SSO with G Suite

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:

The Exivity configuration page could look something like this:

• Now unfold the Advanced menu at the bottom of the screen, and paste the following JSON data:

• Then in Exivity, click the Update button

• And 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.