How to use the Pulse Delinquent User API to Block Internet Access

Pulse provides several tools to enforce timesheet compliance, ranging from ‘Pop-Up Reminders‘ to blocking a user’s internet access to all sites except Pulse – until they have completed their Timesheets as required.

The Pulse Delinquent User API provides a list of Users who are Overdue in their Timesheet Submissions.

This article is for IT Departments, to explain how you can use the Pulse “Delinquent User API” to receive an up-to-date list of Users who are Overdue with their Timesheets so that the IT Department can Block these Users from Internet Access.

How Blocking Internet Access Works

To Block Internet Access for these Users, your IT Department needs to load this list of Users from the API and use the User Details to create a ‘Restriction Group‘ in your Office’s Active Directory which will then restrict their access to the internet.

In order for this to work, you will need:

• Internet access in your Office Location or VPN is controlled via IT Department using SSO and Active Directory
• Users in your Office must log in and Authenticate (Via SSO) to use their PC/Laptop/Mac and Network.
• IT Department will have to create a ‘Script‘ to access the Pulse Delinquent User API, to retrieve an up-to-date list of Users who are overdue with their Timesheets.
• IT Department will use this list of Users to create an ‘Internet Restricted‘ Group in their Active Directory configuration – to ‘Block’ users from Internet Access.
• IT Department will need to ‘Poll‘ to check the Delinquent User API every 5 minutes to update this list of blocked users.

Office Settings

You must also update the Office Settings to enable the Timesheet ‘Delinquent User API‘ as follows:

1. Timesheets must be enabled
2. Timesheet Reminder must be enabled
3. Compliance Rules must be configured
4. Grace Period must be configured
5. Lockout Rule must be set to API only

Location: Address Book > Office Settings > Timesheets tab

1. Enable Timesheets in the User’s Office

Timesheets must be enabled for the Office by setting ‘Enable Timesheets’ to ‘YES’

2. Timesheet Reminder must be enabled

Timesheet Reminders must be enabled by setting ‘Enable Timesheet Reminder’ to either “Yes” or “API Only”.

Setting: ‘Enable Timesheet Reminder’ = ‘YES’

Use this setting if you want the ‘Pop up Reminder’ in the Pulse UI and the API listing users who should be ‘Blocked’ from internet access.

Use the additional settings to control how long the TImesheet reminder pop up is displayed and whether it appears on login with every page view.

Setting: ‘Enable Timesheet Reminder’ = ‘API Only’

Use this setting if you only want the API listing users who should be ‘Blocked’ from internet access.

Users will not receive the pop-up reminder and the settings for Notification will be disabled.

3. Configure the Compliance Rules required for your Office

Location: Address Book > Office Settings > ‘Timesheets Tab’

1. Select whether the Timesheet Reminder notification should appear if a user has failed to Submit or Supply their Timesheets
2. Set the time period that is considered when calculating whether a user is compliant

4. Set the ‘Grace Period’ before notifications begin to show

If this setting is “Enabled for Lockout Only” then users will appear in the Delinquent API but will not be redirected to the Timesheets page when they use Pulse.

Please Note: when this option is selected, the User option “Timesheet Reminder Lockout” will be disabled for all Users in that Office (see below).

User settings

Each individual User also has multiple settings that control how they will be affected by the Internet Block. The settings for each user are found in the Address Book > User Details > Timesheets tab.

Minimum Weekly Timesheet Hours

User must have a value in Minimum Weekly Timesheet Hours. The calculation of timesheet compliance is based on the minimum number of hours a User must submit per week. Without this setting, the system cannot evaluate whether a particular user is compliant.

User settings for “Timesheet Reminder Lockout”

User settings for “Timesheet Reminder Lockout” do not affect whether a user will appear in the Delinquent API. It only controls whether the user will see the Pulse Front end “Lockout”.

If a User belongs to an Office that is configured Lockout = “Enabled” then they will have the option to enable/disable the Pulse Redirection for individual Users.

If a User belongs to an Office that is configured so Lockout = “Enabled for API only” then the option to enable/disable the Pulse Redirection is disabled.

API Connection and Authentication

To access the Pulse Delinquent User API you use a Secure Pulse API Access Token.

A Pulse API Access Token is generated at the ‘User’ level in the Address Book, so you should create your Secure API Access Token for a User that has Permission to Access the Office (or Offices) you wish to include in your API Query.

How to Generate an Access Token using the Pulse API

1. Using a tool such as “PostMan”, set query type to POST
2. Add URL/v2/api/v2/delinquent_userIn the body for your request, add the email and password values for the user you wish to create the secure API Token
   email:jeanne.dupont@example.ms
password:XXXXXX
3. Click send
4. This will create an Access Token for the selected user, and the response will include the token. This Access Token can be used as your ‘Bearer Token’ for subsequent API Requests.

Access API using ‘Bearer Token’ technology to Authenticate

The Pulse API uses Open API technology, which requires the use of ‘Bearer Token‘ to authenticate.

Thus, you can use any technology that supports ‘Bearer Tokens‘ to access the Pulse Delinquent User API, such as:

• PostMan
• CURL
• PHP Curl
• .Net API Connector

Configuration for your API Request

1. Set Authorisation:
   You will need to set the Authorisation to “Bearer Token”.
   Copy the access token you have retrieved and paste it into the token field.
2. Set Request type to ‘GET’
3. Set HOST to your environment, pointing at the following API Endpoint
   {{your-host-pulse-domain}}/v2/api/v2/delinquent_user?timesheet_required=y
4. Set Additional Parameters if required
   See the notes below for the available API Parameters.

Available API Parameters for ‘Delinquent Users API’:

The Delinquent User API supports the following parameters:

API Result – JSON Format

An array of Users is returned as a JSON object, as follows:

[
    {
        "office_client_id": 555888,
        "email": "jane.doe@example.com",
        "timesheet_lockout_flag": 0,
        "agresso_resource_id": "CW-00448",
        "agresso_default_branch": 3710,
        "upn": "jane.doe@example.com",
        "resource_type": 5,
        "agresso_instance": "US",
        "timesheet_required": "y",
        "is_valid_agresso_user": "Y",
        "last_submitted": null
    },
{
        "office_client_id": 555888,
        "email": "john.doe@example.com",
        "timesheet_lockout_flag": 1,
        "agresso_resource_id": "CW-00449",
        "agresso_default_branch": 3710,
        "upn": "john.doe@example.com",
        "resource_type": 5,
        "agresso_instance": "US",
        "timesheet_required": "y",
        "is_valid_agresso_user": "Y",
        "last_submitted": null
    }
]

The fields returned for each User Object include:

• office_client_id
• email
• timesheet_lockout_flag
• agresso_resource_id
• agresso_default_branch
• upn
• resource_type
• agresso_instance
• timesheet_required
• is_valid_agresso_user
• last_submitted

If there are no matching results, there are no Users returned in the JSON.

Implementing Internet Access Block

To implement an Internet Access Block for Users who have not completed their timesheets, your IT Department will have to create a script that can access the Pulse Delinquent Users API (as above) and add the returned Users to an ‘Internet Restricted’ Group in your Office Active Directory configuration.

The Returned list of Users can be processed with any technology. Your IT Department should consider the following:

• You can use PowerShell ConvertFrom-JSON to turn the list into whatever format you require to maintain an Internet Access block via your Active Directory Configuration.
• The ‘Internet Restricted’ Group in Active Directory should have the capability to disable access to the internet for ALL Websites EXCEPT your Pulse Host Domain. Users will require access to the Pulse Host Domain so they can access and complete their timesheets.
• The API can be polled on a recurring basis, we recommend every 5 minutes.
• Users are cleared from the ‘Timesheet Lockout’ (eg: “Blocked Users”) as soon as they update their Timesheets. The lag between internet access being returned will be determined by how often the API endpoint is queried.
• It is possible to query users directly via their user ID – presenting the possibility that blocks could be cleared on-demand

Example API Queries

1) Blocking by Office

To get a list of all users of a single Office that are required to submit timesheets and are delinquent your query would look like this (Where the ‘ID’ of 460 is the ‘Pulse Office ID’ which is accessible from the Address Book inside Pulse).

{{your-host-pulse-domain}}/v2/api/v2/delinquent_user?timesheet_required=Y&office_client_ids[]=460

To block users from multiple Offices:

{{your-host-pulse-domain}}/v2/api/v2/delinquent_user?timesheet_required=Y&office_client_ids[]=460,462,463

2) Blocking by Agresso Instance

To get a list of all users within a particular Agresso instance that are required to submit timesheets and are delinquent your query would look like this:

{{your-host-pulse-domain}}/v2/api/v2/delinquent_user?timesheet_required=Y&agresso_instance[]=US

You can include several Agresso instances via a comma-separated list:

{{your-host-pulse-domain}}/v2/api/v2/delinquent_user?timesheet_required=Y&agresso_instance[]=US,UK