User Synchronization API

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.

User Synchronization API

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:

• SyncGuid. The unique identifier of the user in your user directory. This can be alphanumeric and is the only mandatory element. Max length = 100.
• Name. The preferred name of the user, which if present is displayed on the recognition screen. Max length = 100.
• FirstName. The first name of the user. Max length = 40.
• LastName. The last name of the user. Max length = 40.
• UserNumber. The business-defined number for the user, such as an employee number or membership number. This element can be alphanumeric, but must be numeric if it is to be used for user identification. Max length = 40.
• UserType. The business-defined type of user (eg: Manufacturing, Service, Management, Cleaning, etc). This can be used to drive conditional data entry in the Clock In/Out screen.
• Language. The preferred language of the user (eg: English, Spanish, French).
• Country. The country code for the user's phone number (eg: 1 = USA, 44 = UK, 61 = Australia).
• Mobile. The mobile phone number of the user. This can be used to send passcode notifications.
• Email. The email address of the user. This can be used to send passcode notifications. Max length = 100.
• CardNumber. The access card number of the user, which is used in secure access control applications. Max length = 20.
• Site. The name of the primary site the user belongs to, which is used for categorisation.
• ShiftStart. The start time for the user's shift today (or next shift if they have multiple shifts today). Format = HH:MM.
• ShiftEnd. The end time for the user's shift today (or next shift if they have multiple shifts today). Format = HH:MM.
• Team. The primary team or group that the user belongs to, which can be used to restrict access through access rules. The synchronization process will automatically add users to a group if it exists (it will not automatically create groups). Max length for each group name = 40.‍
• Groups. A list of secondary teams or groups that the user belongs to.‍
• Details. A dictionary of custom attributes for the user, which can be used to drive the list of tasks in the Task Tracking screen or a selectable list of projects or work types in the Clock In/Out screen. Max length = 1024.‍
• Expiry. The expiry date of the user, after which they will not be permitted to use NoahFace. Format = YYYY-MM-DD.‍
• Role. The role the user has within the organization (ie: Administrator, Manager, Viewer). You should omit this attribute, or leave it blank, for regular users.‍
• Scope. If a user has a role within the organization (eg: Manager), then you can optionally restrict their access to a named site.

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.

Example JSON

The following is an example of the JSON that your API should return:

{ 
    "Users" : [           
        {  
            "SyncGuid"   : "12345",
            "FirstName"  : "Samara",  
            "LastName"   : "Smith", 
            "UserNumber" : "1001" 
        },
        {
            "SyncGuid"   : "55555", 
            "Name"       : "Jimmy", 
            "FirstName"  : "James",  
            "LastName"   : "Smith", 
            "UserNumber" : "1002",
            "UserType"   : "Contractor", 
            "Country"    : "61", 
            "Mobile"     : "0414736887",  
            "Email"      : "james@gmail.com", 
            "Site"       : "Sydney",
            "Team"       : "Manufacturing",
            "Groups"     : ["Finance", "Management"],
            "CardNumber" : "",
            "Expiry"     : "2020-12-31",
            "Role"       : "Manager"
        }
    ]
}

Global Lists

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:

• List. The number of the global list that the list entry belongs to.
• Name. The display name for the list entry.
• Value. The unique (within the list) identifier for the list entry.
• Code. A short code associated with the list entry (eg: a project code or job number).
• Parent. For hierarchical lists, the unique identifier of the entry's parent.

The first three elements (ie: List, Name, and Value) are mandatory for each list entry, and the remaining elements are optional.

Example JSON

The following is an example of the JSON that your API should return:

{ 
    "Users" : [           
        ....
    ],
    "Lists" : [
            {"List" : 1, "Value" : "100", "Name" : "Airport"}, 
            {"List" : 1, "Value" : "101", "Name" : "Tower One"}, 
            {"List" : 1, "Value" : "102", "Name" : "Wharf"}, 
            {"List" : 2, "Value" : "200", "Name" : "Design"}, 
            {"List" : 2, "Value" : "201", "Name" : "Construction"}, 
            {"List" : 2, "Value" : "202", "Name" : "Maintenance"} 
    ]
}

Configuration

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).

‍

Individual User Synchronization

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. For example:

{ 
    "Users" : [           
        {  
            "SyncGuid"   : "12345",
            "FirstName"  : "Samara",  
            "LastName"   : "Smith", 
            "Expiry" : "2020-12-31" 
        }
    ]
}

‍

Supporting individual user synchronization is entirely optional; if you don't need this feature, you do not need to support this query parameter.

Performance and Error Handling

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).

Security

Your implementation of the User Synchronization APIs should enforce one of the following authentication methods:

• Basic Security. You provide a username and password which is passed in the Authorization header of each HTTP request.‍
• Token Security. You provide a bearer token which is passed in the Authorization header of each HTTP request.‍
• OAuth 2.0 Security. You provide client credentials which are used to obtain an access token which is passed in the Authorization header of each HTTP request.

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 (TLS 1.2 and later is supported).

‍