Basic process

The process to perform an audit using the UCentric protocols is as follows:-

• Obtain a JWT token

• Upload the PABX backup (and any ancillary files, such as Active Directory export)

• Verify that the PABX audit file is of an expected type (and retrieve vendor type codes etc)

• Create a new site (or use an existing one)

• Schedule an ‘immeadiate’ Audit using the vendor type code

• Poll the server to await completion

• Request HLD (Word Merge) document

• Request LLD (Excel Bulk Loader) document

Getting the JWT token

In order to obtain a JWT token, there must already be a valid user configured within the UCentric suite with appropriate privaledges. Note: On a ‘new’ install, you can use ucadmin / 12345 as the default credentials.

This is accessible via a standard HTTP(s) request

http://127.0.0.1:8809/checklogin?f=ucadmin&p=12345

This will return a JWT token that looks something like this

You will need this token for all future requests, but for further validation of access rights etc, you can use a JWT tool like https://jwt.io/ to view the token contents.

For all future requests, the Authorisation should be set to:-

(replacing xxxxxxxxx with the entire JWT token)

Uploading files

All files needed for the Audit should be uploaded prior to scheduling the audit event. These are all sent as POST ‘file upload' to http://127.0.0.1:8809/tempfile , setting the Authorization token as above

The returned data will provide the temporary filenames that you will need to schedule the audit

You should upload any additional files at this point (e.g. Active Directory) - there is no need to specify their usage at this point.

Verify the PABX audit file

With the “temporary” filename (in this case vxogr_alcatel2.txt) to a simple GET request as follows (adding the Authorization token)

This will return a JSON array of ‘detected’ types:

Note: There are rare circumstances where a backup can contain multiple audits (e.g. A Mitel MSL backup could contain a MiCC and MiCollab), which is why an Array is returned. If there is more than one entry, it is up to you to decide which decoder to use for the import.

The ALC is the “Vendor type” that we will need to schedule the import.

Create a new site

We now need a SiteId to tag this audit against. You can use an existing SiteId if you wish (the system supports multiple audits against a single system/customer) or simply add a new site.

This call returns a list of sites (set the nodes parameter to filter based on the node (tree branch) - this can be comma-delimited for multiple branches.

The returned value looks like this

This dataset is designed to assist with a ‘tree’ view, but the key data you need is siteidand vendorwhich are the actual systems.

If you want to add a new site, instead use this GET endpoint

The parameters are:

This will return details of the site added

The key information you need here is the siteId

Scheduling an ‘immeadiate’ Audit

To schedule an audit, use the following GET endpoint

The parameters are as follows

The XXXX parameter details how the UCentric Server should perform the audit and also has some embedded parameters, these should be URLEncoded

This is the same as

Where ALC is the detected vendor type and 2619 is the siteId we either created or located

This will return the following result

Within this response you will need to note the following key parameters for future calls:-

scheduleId is the Scheduled event (the actual Audit activity)

timestamp is the time the activity starts

scandate is the Timestamp that will be attached to all data that is audited

Polling the server

At this point you can repeatedly call the following URL to get a status of what is happening (live audit process view)

The parameters are

This will return a data set that looks like this

As the polling continues, you’ll get a status of where the audit is, the the newest entry at the top of the rows:[] array

Eventually you will see the following event as the 1st entry in the array

You are looking for eventMsg to show "eventMsg": "Audit has completed successfully."

Once that has been received, you can then request the reports.

Requesting a HLD (Word Merge) document

This is simply a case of providing the audit details as follows:

The parameters are

The following standard templates are available, but you can create your own - please refer to this guide

UCentric HLD/Word Merge Creation Guide

Open

Requesting LLD (Excel Bulk Loader) document

The LLD or Bulk-loader document can accept a number of additional parameters to blend alternative data sources and set various conditions

The parameters are

The JSON (which MUST be URL encoded) is as follows:

The key parameters you should change are:-

outputFormat is one of UCentric’s standard output formats, which are Excelor JSON