.png)
Our Open APIs allow you to integrate NoahFace with your existing IT systems and applications. For example, you could:
The opportunities are endless.
There are three primary interfaces as follows:
Each of these interfaces are explained in detail in the following sections.
NoahFace can automatically retrieve your list of users from an existing IT system so you don't need to import/export users or manually maintain them in two places. To do this, you simply implement our User Synchronization API (a REST Web Hook), and configure NoahFace to call it.
Your implementation of the User Synchronization API should return JSON data. The JSON data should contain a top level element called Users, which is an array of all of your users. Each user can contain any of the following elements:
Only the SyncGuid and at least one of the Name and FirstName elements are mandatory for each user. However, the more attributes you return the more functionality you will have available to you within NoahFace.
The following is an example of the JSON that your API should return.
Your JSON data can optionally contain a second top level element called Lists, which is an array of global lookup list entries. For example, you might return a list of projects and a list of work types. These lists can then be presented in the NoahFace App to allow users to select the project they are working on or the type of work they are performing. Each list entry can contain the following elements:
The first three elements (ie: List, Name, and Value) are mandatory for each list entry, and the remaining elements are optional.
The following is an example of the JSON that your API should return.
To enable user synchronization, simply add a synchronization instance, select 'Custom' as the type of synchronization, and specifying your API endpoint details (see example below).
NoahFace can synchronously update an individual user while they are recording an event (eg: while they are attempting to clock in for work). This is used, for example, to ensure that a user's expiry date is up to date before denying them access based on their currently recorded expiry date.
To support individual user synchronization, your user list url should accept an optional query parameter of syncguid, and when this query parameter is present, it should only return the user with that guid.
Supporting individual user synchronization is entirely optional; if you don't need this feature, you do not need to support this query parameter.
It is critical that you return your list of users quickly (ie: ideally sub-second, and a maximum of 10 seconds in all circumstances). If you need to make many API calls to a 3rd party system to collect your user data, you should prefetch this data in the background (storing it locally), and your API should simply return the prefetched data to NoahFace.
Your API should return an HTTP response code of 200 on success, and an appropriate response code on failure (eg: 404 if the specified User list url is incorrect, 401 if access was unauthorised, etc).
Your implementation of the User Synchronization APIs should enforce one of the following authentication methods:
If your implementation of the NoahFace APIs is being designed to service multiple organizations, you should use different credentials for each organization so you can access the appropriate data in your IT system or application.
Regardless of which authentication method you choose, all API calls are over HTTPS so your data and credentials are encrypted. We strongly recommend you configure your end points to use TLS 1.2 or higher.
NoahFace can forward user events to your applications or IT systems. To do this, you simply implement our Event Notification API (a REST Web Hook), and configure NoahFace to call it when a user records an event.
Your implementation of the Event Notification API should expect to receive the following elements:
Your API can be designed to be called using an HTTP GET, PUT, or POST method. If you use GET, the event data will be sent in query parameters. If you specify PUT or POST, the event data will be sent in JSON format (see example below).
The following is an example of the JSON that your API should expect.
Each event includes an event type attribute. The full list of possible event type values is as follows:
Different event types are generated by different screen types. For example, if your are using the Clock In/Out screen, the only event types you will receive are: register, clockin, clockout, startbreak, endbreak, and accessdenied, and if you are using the Task Tracking screen, the only event types you will receive are: register, starttask, clockout, and accessdenied. You can generally ignore register and accessdenied type events.
Each event contains an event detail attribute. This is populated with any data that is collected with the event. For example:
Processing the detail attribute can therefore help you automate cost allocation.
You can forward user events either from the Cloud or locally from the NoahFace App. Forwarding user events from the Cloud is usually used for integration with payroll systems.
To forward user events from the Cloud, simply add a notification, select 'Custom' as the type, and specifying your API endpoint details (see example below). Once you have done this, associate this notification with an access point type, and create your access point.
It is critical that you process Cloud notifications quickly (ie: ideally sub-second, and a maximum of 10 seconds in all circumstances). If you have processing work to do, you must store the notification data, return success, and then perform your processing in the background.
Your API should return an HTTP response code of 200 on success (ie: you have received the data, validated security, and do not need it sent again), and an appropriate response code on failure (eg: 404 if the specified url is incorrect, 403 if access was unauthorised, etc). If you return anything other than 200 (or your API cannot be reached), then NoahFace will attempt to re-send the event the following number of hours in the future:
2 ^ (number of failed attempts - 1)
So, the first retry will be after 1 hour, the second retry will be after an additional 2 hours, the third retry will be after an additional 4 hours, etc. This will continue until your API returns success, or until 90 days has passed.
You can forward user events either from the Cloud or locally from the NoahFace App. Forwarding user events locally from the NoahFace App is usually used for integration with local hardware (eg: unlocking a door or printing labels). You can also use local event forwarding to retrieve and display real time messages to users.
To forward user events locally from the NoahFace App, select your access point type, select 'Web Server' as the Receiver type, and specifying your API endpoint details (see example below). Once you have done this, create your access point.
It is critical that you process local notifications quickly (ie: less than a second) in all circumstances, as local event forwarding is synchronous (ie: users are waiting for the response).
Your API should return an HTTP response code of 200 on success, and an appropriate response code on failure (eg: 404 if the specified url is incorrect, 403 if access was unauthorised, etc). You can optionally return a custom HTTP response header of X-NOAHFACE-MESSAGE to display a message to the user. There is no retry mechanism for local notifications.
Your implementation of the Notification APIs should enforce one of the following authentication methods:
If your implementation of the NoahFace APIs is being designed to service multiple organizations, you should use different credentials for each organization so you can access the appropriate data in your IT system or application.
Regardless of which authentication method you choose, all API calls are over HTTPS so your data and credentials are encrypted. We strongly recommend you configure your end points to use TLS 1.2 or higher.
NoahFace can display a custom screen whenever a user is identified, which gives you complete flexibility in the user experience you deliver to your users. Custom screens also allow you to integrate tightly with other systems, displaying information sourced from them, and even update them. For example, you might want to support complex searching on a project database, or display detailed information about an employee's current shift.
To implement a custom screen, you simply design it using HTML, host it on your Web server, and configure NoahFace to call it.
Configure your Access Point Type to use a Screen Type of Custom, and then specify any of the following Screen Details options:
For example, you might specify the following Screen Details options:
url=https://acme.com/noahface/myscreen.html, cache=always
NoahFace passes data to your Web page via a custom JSON object called NoahFace. This object contains the following elements:
You can access these elements from Javascript using standard dot notation (eg: NoahFace.firstname) as needed.
NoahFace can also pass data to your Web page via query parameters. This is useful if you want to perform integration at the server rather than in the client. To enable server-side data access, specify the query=true configuration option in your access point type.
Note that if you implement server-side data access, your custom screen will not be able to be used offline, so it is important you have an extremely reliable network connection.
Your custom screen can call back to NoahFace to perform the following functions:
To make a call back to NoahFace, simply post a message to the NoahFace interface, passing it a JSON object containing the appropriate action element. For example:
window.webkit.messageHandlers.NoahFace.postMessage({"action":"success"});
Note that you would generally only call back to NoahFace if you are using mode=manual, because in the default mode=auto, events are automatically logged.
The following HTML illustrates how to access data from NoahFace as well as how to call back to NoahFace to log events:
This will result in the following screen being displayed, and when a user presses one of the icons, an event will be logged to NoahFace recording the corresponding mood:
