Tasks API Guide

Introduction

This API allows you to add and manage tasks in the Tasks tab of Fourth Engage. It is intended for use by partners with a connected app in Fourth Engage, to complement and expand the user experience of the app.

Once added, your tasks show in Engage alongside those from the Fourth Platform. You can optionally include a push notification, sent to each task recipient, when you create or update a task.

The guide and reference covers everything you will need to know about integrating, such as how to make each request, how tasks are displayed in Fourth Engage, and how users interact with tasks.

Quick Facts

API type HTTP REST with JSON and XML
Authentication OAUTH (via client credentials)
Availability Available to partners with connected apps
Testing A test environment is available
More information See the Reference

Getting started

Follow these steps to integrate.

  1. Contact Fourth.
    Our implementation consultants will:
    • Provide you with an ID for your connected app.
    • Provide you with the URL for a test environment.
    • Help you with any questions.
  2. Request API credentials.
    API credentials are linked to customer accounts. Therefore, you must ask any mutual Fourth customers to request credentials for your use.
  3. Create your task templates and push notification templates.
    This API uses pre-defined templates to show task information. You will need to decide how many templates you need, and define the details that each type of task should include.
    Once you have decided on the template information, provide this to your Fourth implementation consultant. They will create the templates within Fourth and let you know when the templates are ready to test.
  4. Build and test your integrations.
    Connect to the test environments and begin creating and updating tasks. We recommend testing all of the tasks and outcomes you require. You will need to integrate with:
    • The Tasks API.
    • A Fourth workforce management API (to retrieve Fourth Account IDs for your recipients).
  5. Go live!

Tasks tab overview

The Tasks tab is found in Fourth Engage, which users can access via a mobile app or online. There are two screens that users interact with:

  • The Task List screen, which lists both upcoming and completed tasks.
  • The Task Detail screen for task.

The layout of the screen will depend on whether the end user is using a mobile device or a PC. However, the same elements will always be included in the screen. The details shown on these screens are controlled through two mechanisms: the task template, and the API request for an individual task.

Example Task List screen

Screenshot with page elements highlighted.

Example Task Detail screen

Screenshot with elements highlighted.

The example screenshots above share the same item numbers in the table below.

Number Description Controlled by
1 The Task List screen is split into two subtabs: My Tasks and Actioned Tasks. You control whether a task is in either column with the State value in your requests. API request > State
2 The title for your task. Task template > title
3

The recipients of this task. The icons onscreen (e.g. "GM") are automatically created for each recipient.

Note that a task can include comments added by end users, that all users with the task will see. If an end user adds a comment, then on the Task List screen a comment icon will appear beside the recipient icons.

API request > RecipientIds
4 Details about the task shown on the Task List screen. These details are taken from the table of details shown on the Task Detail screen.

Task template > detail table, with any related API request > TaskParameters values.

5

Icons that represent the status and weight of the task.

Fourth updates the icons based on the cut off date and status of a task.

Updated by Fourth.
6

The name of your connected app.

On the Task Detail page, the name can use a hyperlink or deeplink to your connected app.

On the Task List page, the name is unlinked.

API request > LinkUrl or Deeplinks

7

The due date for your task. This is calculated from the  CutOffDateTimeUtc provided in the task request. Fourth uses this date and time to update:

  • The value shown; e.g. "Overdue" or "Due in 25min"
  • How the expiry is displayed; e.g. in yellow, red, outlined, etc.
API request > CutOffDateTimeUtc
8 A summary of your task shown only on the Task Detail screen. Task template > detail paragraph
9 A table of details about your task, shown only on the Task Detail screen. Task template > detail table

Task templates

Before integrating with the API, you will need to provide Fourth with your task templates. They define what information is shown on the Task List and Task Detail screens.

You may need multiple task templates, depending on your needs. For example, an onboarding company may need separates templates; one for confirming a user has reviewed onboarding documents and another for requesting users to watch training videos.

The details we need for each task template are below.

Name Description
Connected app name  

The name of your connected app (shown as item 6 in the screenshots above). Ensure you provide the spelling and capitalization as exactly desired. On the Task Detail screen, this name is hyperlinked if you include LinkUrl or Deeplinks in your request.

Note that the same name is shared by all tasks, so you only need to provide this information once.

Type: Unicode string

Example: Acme Systems

Name

The name that identifies the task template in your API requests.

Type: Unicode string

Length: 1-255 characters

Example: Approve_Holiday

Title

The user-visible name for the task. This is shown on both the Task List and Task Detail screens.

This field can include a reference to a task parameters. Provide the value in curly brackets; for example: {task_type}.

Type: Unicode string

Length: Up to 25 characters is allowed

Example: Approve Holiday Request

Detail Paragraph

A descriptive paragraph for the task. This is displayed to the end user on the Task Detail page after the list of recipients.

This field can include a reference to one or more task parameters. Provide the value in curly brackets.
Type: Unicode string

Length: The maximum length is 280 characters; however this is not enforced by the platform. Paragraphs longer than 280 characters may become truncated.

Example: Please approve or reject the holiday requested by {firstname}.

Detail Table

A table of details about the task. This is displayed to the end user on the Task Detail screen after the detail paragraph. The font weight is bold for the lefthand column and normal for the righthand column.

The fields in the table can include a reference to one or more task parameters. Provide the value in curly brackets.

Type: Unicode string

Length: For each cell, the maximum length is 280 characters; however this is not enforced by the platform. Cells longer than 280 characters may become truncated.

Example:

Staff member: {firstname} {lastname}

Start time: {StartDateTime}

End time: {EndDateTime}

Total requested days: {TotalDays}

Push notification template name

The name that identifies the template for the related push notification.

Type: Unicode string

Length: 1-255 characters

Example: Approve_Holiday_Push_Not

Task parameters

Task parameters enable you to set specific values in each request. For example, you may want your task to show a user's name, the value of a purchase order, or the type of fruit on order. The parameters the API expects are defined by you, which allows you to display any data that is relevant to your tasks. Fourth will validate this data against your own definitions.

Task parameters can also be referenced in your push notifications.

In your API request, the values are set in the TaskParameters array. For example:

"TaskParameters": {
   "Supplier": "Banger's Spuds and Mash",
   "Subtotal": "100.12"
   },

For each task parameter, you need to tell Fourth the following details.

Name Description
Key

The key used in your requests to identify the parameter.

Type: Unicode string

Length: 1-255

Example: Supplier

Value type

The type of value sent for the key. Options are:

  • Boolean (0)
  • String (1)
  • Integer (2)
  • Double (3)
  • DateTime (4)
  • Format options are:
    • DD/MM/YYYY
      For example: 13/01/2019
    • YYYY-MM-DDThh:mm:ss.sTZD
      For example: 2018-12-19T07:05:14.604Z
Is mandatory

Whether the parameter must be included in your API request. Only parameters in the detail table should be optional. Options are:

  • Yes — Specifying this parameter is mandatory. Requests missing this value are rejected.
  • No — Specifying this parameter is optional.
    • If the parameter is the value of a cell in the Detail Table, then the value is set to "None".
    • If the parameter is in any other field, then the parameter key is shown in curly braces instead. For example: “Hello {username}".

For example:

Key Value type Is mandatory
Supplier String (1) Yes
Subtotal Double (3) Yes

Validation of task parameters

We provide validation for your task parameters, to check that:

  • All mandatory fields have a value.
  • The correct data type is sent.

If your request doesn't pass this check, then the API will return an HTTP 400 Bad request error.

Example task template with task parameters

This example shows an onboarding task.

Connected app name: Acme Onboarding

Name: Onboarding_Videos

Title: Training video {Sequence_Number}

Detail Paragraph: As part of the onboarding process, please watch this video on {Video_Short_Description}.

Detail Table:

Number

{Sequence_Number} of {Total_Videos}

Assigned date {Assigned_Date}
IMDB rating

{Rating}

Push notification template name: Onboarding_Videos_Notification

Task Parameters:

Key Value type Is mandatory
Sequence_Number Integer (2) Yes
Video_Short_Description String (1) Yes
Total_Videos Integer (2) Yes
Assigned_Date DateTime (4) Yes
Rating String (1) No
Video_Name
(used in push notifications for this task)
String (1) Yes

Example Task List screen

Screenshot showing the example values.

Example Task Detail screen

Screenshot showing the example values.

Push notification templates

If you wish to send push notifications with your task requests, then you will need to define at least one push notification template.

Push notifications are sent immediately after a Tasks request is processed. They are not tied to the StartDateTimeUtc so, if you set this to a future date, you should be aware that any specified push notification is immediately sent regardless.

Users who click on the push notification are taken to the Task Detail screen for the task.

Screenshot showing an example push notification

The push notification templates are referenced by your task templates. If desired, you can share push notification templates between task templates.

Note that a push notification is only sent if the API request has SendNotification set to true. The notification is sent to all task recipients.

For each push notification template, you need to tell Fourth:

Name Description
Name

A name that identifies the push notification template. This is referenced by the task template.

Type: Unicode string

Length: 1-255 characters

Example: Onboarding_Videos_Notification

Title

The user-visible title in the push notification, similar to a subject line or heading.

This field can include a reference to task parameters. Provide the value in curly brackets; for example: {Sequence_Number}.

Type: Unicode string

Length: 40 characters; titles longer than this may be truncated by the mobile phone.

Example: Training video {Sequence_Number}

Body

The user-visible description.

This field can include a reference to task parameters. Provide the value in curly brackets; for example: {Video_Name}.

Type: Unicode string

Length: Different mobile phones have different supported lengths, after which a message may be truncated. For maximum compatibility, we recommend limiting the body text to 280 characters.

Example: Tap to watch a video on {Video_Name}.

Linking to your connected app

The Task Detail screen can include a hyperlink or deep link to your connected app. The link shows in the top left of the screen:

Screenshot showing an example link.

To add a hyperlink, include LinkUrl in your API request.

A deep link allows you to direct the end user directly to the task in your connected app. To add a deep link, include the Deeplinks array in your API request. This takes precendent over any value for LinkUrl you might supply. The information you need to include for the deep link is:

  • Destination: This is provided by Fourth. It identifies your connected app in our systems.
  • Command: A command name for the action that the deep link triggers.
  • Args: A collection of key/value pairs that includes any values you want passed to your connected app.

Our integration team will help you develop your deep links.

Retrieving recipientIds

Every end user of Fourth products, such as Fourth Engage, is given a unique Fourth Account ID. You will need to supply this ID in the recipientId array in your requests.

There are two APIs available for retrieving the Fourth Account IDs of users. Which one you use will depend on where the shared customer is in business. 

  • UK Employee API - use if your customer is using Fourth HR & Payroll in the UK

  • Labor Productivity API - use if your customer is using Fourth Labor Productivity in the US

Before we can provide you with API credentials, your customer will need to provide authorization by contacting their Fourth customer success manager.

Validation of Fourth Account IDs

On submission, we check that the IDs match the format of our Fourth Account IDs. If they do, then Fourth responds with an HTTP 200 OK response. The request is then added to a Tasks API queue, after which it is validated again before creating the tasks and push notifications.

On submission, we do not check that the IDs are for active accounts, or that the IDs are for people in the mutual customer's employment. Tasks are only created for recipients who are active employees of the mutual customer. Any non-valid recipients included in the request will cause the request to fail AFTER submission. Depending on your integration, it is vital that your system regularly checks that the Fourth Account IDs are valid, particularly if your requests include multiple recipients.

Using the API

Full details about the API are provided in the Reference.

Connecting

The URL for reaching the endpoints will depend on your use. The taskID is your unique identifier for the task. The structure is:

{ROOT}/Tasks/{taskID}

Where:

  • ROOT: Your Fourth implementation consultant can provide you with the root url to use for testing and live.
  • taskID: This is a unique identifier that you supply. If this identifier already exists, the task is updated.

Methods

There are two available methods: PUT and DELETE.

The PUT requests can both create and update a task, based on whether the taskID is unique. For updates, the request updates all of the resource entry. Any non-mandatory values that are left out of the update are either use the value's default, or if it does not have a default, are set to null.

Authenticating

This API uses OAUTH to authenticate; however there is no need to request a token or include authentication in the header. This is because the connected app is already authenticated when the user (who creates the task) logs into Fourth Engage. 

Error messages and troubleshooting

See Troubleshooting below.

Example workflow

This example uses the values from the example task template to ask a recipient to watch a training video as part of the onboarding process.

1. The task is created.

The task is created by sending a PUT request to the Tasks endpoint. The request specifies:

  • To use the task template named Onboarding_Videos.
  • The task parameters required for the task template.
  • To send a push notification for the task. Which push notification template is used is defined in the task template.
  • An immediate start time for this task.

The state is Active, and so it appears in the recipient's My Tasks subtab of the Tasks tab.

PUT /Tasks/123456 HTTP/1.1
Host: example.fourth.com
Accept: text/json

{
  "State": "Active",
  "TaskTemplateName": "Onboarding_Videos",
  "TaskParameters": {
      "Sequence_Number": 2,
      "Video_Name": "Serving Customers",
      "Video_Short_Description": "how to provide the quality of service our customers deserve",
      "Total_Videos": 4,
      "Assigned_Date": "09/03/2019",
      "Rating": "87%"
  },
  "StartDateTimeUtc": " 2019-03-09T09:41:04.000Z",
  "CutOffDateTimeUtc": "2019-03-14T17:30:00.000Z",
  "ExpiryDateTimeUtc": "2019-04-04T04:00:00.000Z",
  "RecipientIds": [
    "0058E00000207pP"
  ], 
  "Deeplinks": [
    {
      "destination": "Acme_Onboarding_Fourth_id",
      "command": "OPEN_APP_VIDEO_2",
      "args": {
          "campaign": "fourth1",
          "count": 12345
      }
    }
  ],
  "SendNotification": true
}

Fourth responds with an HTTP 200 OK response to successful requests.

2. Fourth creates the task and sends the push notification.

The task now appears in the task list.

Screenshot showing the example request in the Task List.

3. The recipient receives a push notification on their mobile phone.

If the user taps the push notification, they are taken to the Task Detail screen for the task. If the user ignores the push notification, they can find the task later in the Task List screen.

Screenshot showing an example push notification

4. The recipient accesses the Task Detail screen for the task.

Screenshot showing the example values.

5. The recipient completes the task.

The recipient clicks on the connected app name, which has a deep link to the task, and completes the task. The connected app then determines when the user has completed the task.

6. The task is updated with a new PUT request.

Once the task is completed, it is updated by sending a PUT request to the Tasks endpoint for the same taskID. The request specifes the same details as previously, with these changes:

  • The state is set to Completed. This moves the task from the My Tasks subtab to the Actioned Tasks
  • It does not specify to send a push notification.

The request also specifies any additional updates to the task, such as the template used or the value of any task parameters. Any value that is not included in the PUT is set to null or to the default value. In this example update, there is no Deeplinks array or LinkUrl specified, which means that there is no longer a link on the connected app's name on the Task Detail screen.

PUT /Tasks/123456 HTTP/1.1
Host: example.fourth.com
Accept: text/json
Authorization:

{
  "State": "COMPLETED",
  "TaskTemplateName": "Onboarding_Videos",
  "TaskParameters": {
      "Sequence_Number": 2,
      "Video_Name": "Serving Customers",
      "Video_Short_Description": "how to provide the quality of service our customers deserve",
      "Total_Videos": 4,
      "Assigned_Date": "09/03/2019",
      "Rating": "87%"
  },
  "StartDateTimeUtc": "2019-03-07T07:05:14.604Z",
  "ExpiryDateTimeUtc": "2019-03-14T17:30:00.000Z",
  "RecipientIds": [
    "0058E00000207pP"
  ],
  "SendNotification": false
}

Fourth responds with an HTTP 200 OK response to successful requests.

7. The task appears in the Actioned Tasks subtab.

The task is removed from the My Tasks subtab and added to the Actioned Tasks subtab.

8. The task is removed from the Tasks list

The task is set to expire on the 4th of April. On this date, it is removed from the Tasks tab.

Alternatively, you can also delete a task before its expiry date, using a DELETE request.

DELETE {ROOT}/Tasks/12345

This immediately deletes the task from the Tasks tab.

Fourth responds with an HTTP 200 OK response. If the task has previously been deleted, Fourth responds with an HTTP 404 Not found response.

Troubleshooting

Fourth responds to successful requests with an HTTP 200 OK response with an empty response body. This indicates that the request was successfully recieved and passed validation. After validation, the request is added to a queue of task requests—this ensures that we can accept and process requests during periods of high load.

    What should I do if I don't receive a response from Fourth?

    If you do not receive a response, you should retry your request using a truncated backoff strategy. Please retry requests no more than once a minute. Get in contact with Fourth if you continue to not receive responses.

    Retries with push notifications: When considering your retry strategies, it's important to note that if you receive an HTTP transaction timeout, it is still possible that we received the request. Therefore, you should decide whether you'd prefer the end user to potentially receive the push notification multiple times, or to not receive the message at all.

    How do I determine whether messages are received?

    While we do everything to ensure that your requests are successfully processed, there may be instances where an issue occurs between Fourth receiving the request and any task update or push notification delivery. To check that your requests are being processed successfully, we recommend:

    • Always testing each template and variant with test handsets.
    • Including a test handset as a recipient for any bulk tasks requests.

    Error messages

    This API uses standard HTTP response codes.

    • All 400-499 responses mean that there is an issue with your request. Review the error message included in the response body for more information. Do not retry the request until the error is resolved.
    • 500 responses mean that Fourth experienced an issue receiving your request. You may retry your requests using a truncated backoff strategy. Please retry requests no more than once per minute. Get in contact with Fourth if you continue to receive these error messages.

    Each error response includes a description in the response body explaining the error. For example:

    {
        "StatusCode": 400,
        "ErrorCode": 6,
        "Message": "Failed to save the Task: Error: ERROR: Recipient/Recipients is not a valid",
        "Details": [
            "Error: ERROR: Recipient/Recipients is not a valid"
        ]
    }