Tasks

Overview

ShareBase Tasks enable you to have easy and simple decision-making on documents without the need for a custom workflow. Tasks can be assigned to individuals inside your organization with a ShareBase account (internal users) and individuals outside your organization (external users). Each task includes an instruction message for the assignee and a due date.

When a task is created, the assignee gains view access to the document and is sent an email notification message. In addition to an email message, users within your organization receive a web notification about the new task and can view all of their tasks on the My Tasks View webpage.

View access granted by tasks generally remains for 14 days after they have completed the task or 14 days after the task was due. Exceptions include when tasks are completed after they were due or when there is an Administrator setting restricting link expirations.

Assignees can approve or deny tasks, optionally with a comment. Task creators and all task update recipients for that task are sent an email message that the task was completed, which includes the decision and the assignee's comment.

The API exposes the ability to create new tasks, get information about a task, cancel tasks, and report on tasks.

Warning

Please note, ShareBase Tasks is currently in Beta.

Creating a task

Tasks can be created, by issuing the following POST request:

POST /api/tasks

With the following body:

{
    "Type": {Approval},
    "DueDate": <datetime>,
    "Assignee": "",
    "DocumentId": <long>,
    "Instructions": "",
    "Recipients": [""]
}

Type: this is the string indicating the type of task to create (e.g. "Approval")
DueDate: the date that the task is due
Assignee: the email address for the task assignee, either an internal user email address or an external email address
DocumentId: the Id of the document for the document task
Instructions: the instruction message for the task that is sent to the task assignee
Recipients: an optional list of task update recipient email addresses for task update notifications

Currently, only Approval type (Approve/Deny) tasks on documents are supported.

In order for the input to be valid:

The creator of the task cannot assign the task to themself
The task type must be specified and be a valid task type (currently just "Approval")
The due date must be specified and be in the future
The due date must be no more than 90 days in the future
The document must exist
The instructions message must have a length of 1000 characters or fewer
The assignee field must have a valid email address
Permissions must be grantable with the task
The creator must be a Site Admin if using a Recipients list
When using the recipients list, each entry should be a valid email address
When using the recipients list, each entry must be a distinct email address
The assignee must not already have been denied read permissions to the document

Upon successful creation, an HTTP 200 OK status code is returned with a response body like the following:

{
    "TaskId": 1,
    "TaskType": "Approval",
    "TaskStatus": "Open",
    "TaskResult": "",
    "Instructions": "Please review this document.",
    "DueDate": "2018-04-04T00:00:00Z",
    "DateAssigned": "2018-03-15T17:32:25.6024832Z",
    "DateEnded": null,
    "Creator": "creator@email.com",
    "Assignee": "assignee@email.com",
    "ItemType": "Document",
    "ItemName": "Sample Document",
    "Links": {
        "Self": "http://app.sharebase.com/sharebaseapi/api/tasks/1",
        "CancelTaskUri": "http://app.sharebase.com/sharebaseapi/api/tasks/1/cancel"
    }
}

Tasks can be assigned to internal or external users using an email address for the Assignee, detailed above. If the email address matches an email address for an internal user in the deployment, that user will be assigned the task and can view it on the My Tasks View webpage. External users will receive a secure access code to access the document and complete the task.

When a task is created, an email is sent to the task assignee that a task was created for them by the task creator and a web notification is sent if they are a user within your organization. In addition, task recipients that were specified in the request body also receive an email that a task was created for the assignee.

These tasks can be completed while viewing the document or while viewing open tasks on the My Tasks View (if the assignee is an internal user). They can be cancelled on the My Tasks View or with with an endpoint detailed below.

In addition to the task being created, Read permissions are granted to the assignee for access to the Document that the task was assigned on. These permissions automatically expire 15 days after a task DueDate, 15 days after a task is completed, or after the maximum amount of days a user can share a document externally for an external task, whichever date is first. Permissions granted by tasks get removed immediately when a task is cancelled.

An HTTP 400 Bad Request response is returned if the input is invalid, with requirements listed above. An HTTP 403 Forbidden response occurs if the user does not have rights to grant permission to the document, the assignee is denied access to the document, or the user sent update recipients without being a Site Admin. Also, an HTTP 404 Not Found response is sent if the document does not exist or was deleted.

Besides basic error responses, this endpoint returns detailed info when request properties are invalid, as shown in the example below:

{
    "Message": "The request is invalid.",
    "ModelState": {
        "createTask.Type": [
            "The only supported task type is \"Approval\"."
        ],
        "createTask.DueDate": [
            "Due date should be later than now."
        ],
        "createTask.Assignee": [
            "The email address provided is not valid."
        ],
        "createTask.Instructions": [
            "The Instructions field is required."
        ]
    }
}

Task Update Recipients

The API allows Site Admins to specify a Recipients list when tasks are created, who get email notifications when tasks are updated. Recipients receive notifications when tasks are created, completed - approved or denied, cancelled, deleted, and expired.

These individuals are not granted access to the document from the task creation and should be granted access through a separate share API request if this is desired.

Tip

We recommend using a dedicated "service account" with contact information in the instructions message when using update recipients. Assignees will get a non-replyable email message when tasks are created with update recipients.

Getting a task

Tasks can be retrieved by issuing the following GET request:

GET /api/tasks/{taskId}

Where:

taskId: the ID of the task to retrieve

In order to retrieve a task, the current user must be the creator or assignee of a task.

Upon successful retrieval, an HTTP 200 OK status code is returned with a response body like the following:

{
    "TaskId": 1,
    "TaskType": "Approval",
    "TaskStatus": "Completed",
    "TaskResult": "Positive",
    "Instructions": "Please review this document.",
    "DueDate": "2018-04-04T00:00:00Z",
    "DateAssigned": "2018-03-15T17:32:25.6024832Z",
    "DateEnded": "2018-03-20T17:33:34.5401625Z",
    "Creator": "creator@email.com",
    "Assignee": "assignee@email.com",
    "ItemType": "Document",
    "ItemName": "Sample Document",
    "Links": {
        "Self": "http://app.sharebase.com/sharebaseapi/api/tasks/1",
        "CancelTaskUri": "http://app.sharebase.com/sharebaseapi/api/tasks/1/cancel"
    }
}

The DateEnded property contains the date that a task was ended or resolved. Tasks are considered resolved after they are completed (approved or denied), are cancelled, or have expired without a decision.

If an internal task creator or assignee was deleted from the deployment, their email addresses will have .inactive1, .inactive2, etc. appended to the end of it (e.g. "assignee@email.com.inactive1").

Note, that if a user does not have access to a task, an HTTP 403 Forbidden will be returned. If a task Id was not specified, an HTTP 400 Bad Request will be returned, and if a task was not found for a given Id, an HTTP 404 Not Found response will be returned.

Cancelling a task

Open tasks can be cancelled by issuing the following PATCH request:

PATCH /api/tasks/{taskId}/cancel

Where:

taskId: the ID of the task to retrieve

In order for the input to be valid:

The user must the creator of the task
The task must be an open task
The document must exist
The user must not have been denied read permissions to the document

Upon successful retrieval, an HTTP 200 OK status code is returned with a response body like the following:

{
    "TaskId": 1,
    "TaskType": "Approval",
    "TaskStatus": "Cancelled",
    "TaskResult": "Positive",
    "Instructions": "Please review this document.",
    "DueDate": "2018-04-04T00:00:00Z",
    "DateAssigned": "2018-03-15T17:32:25.6024832Z",
    "DateEnded": "2018-03-20T17:33:34.5401625Z",
    "Creator": "creator@email.com",
    "Assignee": "assignee@email.com",
    "ItemType": "Document",
    "ItemName": "Sample Document",
    "Links": {
        "Self": "http://app.sharebase.com/sharebaseapi/api/tasks/1",
        "CancelTaskUri": "http://app.sharebase.com/sharebaseapi/api/tasks/1/cancel"
    }
}

The DateEnded property contains the date that the task was cancelled.

Cancelling a task sets the task's status to Cancelled, updates the DateEnded property, logs the cancellation, and removes permissions that were granted by the task. Assignees can no longer access the shared document or complete the task.

In addition, internal task assignees are sent a web notification of the cancellation and all task update recipients receive an email update message regarding the cancellation.

Note, that if a user is not the task creator, an HTTP 403 Forbidden will be returned. An HTTP 400 Bad Request will be returned if a task Id was not specified or the task had a status which wasn't 'Open'. Also, an HTTP 404 Not Found response will be returned if a task was not found for the given Id.

Generating and downloading a task admin report

Similar to User Admin Reports, a Task Admin Report is a special comma separated value (.csv) file that contains all tasks that a have occurred within a time period, with parameters for the creator, assignee, and task status. In addition to comma separated responses, a JSON response is also provided using the header: Accept: "application/json". A task report contains information about all tasks within a 90 day period that meet the given parameters.

Information included in the report consists of the Task Id, Type, Instructions, Item Type (e.g. Document), Item Name (i.e. Document Name), Creator, Assignee, Due Date, Date Assigned, Status/Result (e.g. Approved, Denied, Expired, Open), and Date Resolved (DateEnded). Like the other task requests detailed above, Date Resolved or DateEnded contains the date that a task was completed or cancelled, or the date that it expired.

A Task Admin Report may only be generated and retrieved by a user who is a Site Admin.

Generating a task report

Because these reports can contain a large amount of data, they are generated asynchronously. Consumers will first make a request to begin the report generation and will then be given a link in the response header to check the status of the report. When the report is ready, that status endpoint will send a ResultUri that points to a location where the report can be downloaded.

To start generating a new Task Admin Report, issue the following POST request:

POST /api/async/tasks/task-report?fromDate=<value>&toDate=<value>&status=<value>&assignee=<value>&creator=<value>&fileName=<value>

Where:

fromDate: a DateTime string, an optional query string parameter to only include results on and after the given date. The recommended format is YYYY-MM-DD
toDate: a DateTime string, an optional query string parameter to only include results up to and including the given date. The recommended format is YYYY-MM-DD
status: a string array, an optional query parameter of status representations to to only include results that have specific Task statuses
assignee: a string, an optional query string parameter to filter tasks by assignee, using an internal or external user email address
creator: a string, an optional query string parameter to filter tasks by creator, using the task creator's email address
fileName: a string, an optional query string parameter to set a custom filename, returned in the Content-Disposition response header of the final result

To specify a date range, use both the fromDate and toDate query string parameters. With this date range, tasks are retrieved if they were assigned or ended within the date range. The date range cannot be greater than 90 days.

Tip

Task dates are stored in UTC time. If you are retrieving tasks starting or ending on a specific date, be sure to specify start and end date times in UTC.

When using the creator parameter, it must match an email address for a user in the deployment.

For task status filtering, the status parameter can be used, which allows filtering of tasks by their status. For instance, it can filter tasks to just open tasks, just completed tasks, just cancelled tasks, just expired tasks, and all tasks.

To use this filtering, you need to specify each desired status with separate query parameters, in the form ?status=<status1>&status=<status2>, where each status parameter value is a string representation for the status. The following list contains the values for each possible status:

Open Tasks: "open"
Completed Tasks: "completed"
Cancelled Tasks: "cancelled"
Expired Tasks: "expired"
All Tasks: "all"

Two examples of retrieving tasks filtered to multiple statuses are as follows:

Open and Completed Tasks: ?status=open&status=completed
Cancelled and Expired Tasks: ?status=cancelled&status=expired

If the status filtering contains invalid status representation values, an HTTP 400 Bad Request will be returned.

In addition to using a value of "all" for the status parameter, you can also retrieve all tasks by omitting the status parameter in the request.

To generate a report that contains open and completed tasks, the following request could be used:

POST /api/async/tasks/task-report?fromDate=<value>&toDate=<value>&status=open&status=completed

And for a report that contains all tasks within a date range, either of the following requests could be used:

POST /api/async/tasks/task-report?fromDate=<value>&toDate=<value>&status=all

POST /api/async/tasks/task-report?fromDate=<value>&toDate=<value>

Upon receiving a successful request, an HTTP 202 Accepted response is returned with a special location header in the response:

Location: https://app.sharebase.com/sharebaseapi/api/async/{jobId}

Where:

jobId: the ID of the asynchronous job that represents the Task Admin Report

If the user is not a Site Admin, an HTTP 403 Forbidden response is returned.

An HTTP 400 Bad Request is sent if the parameters are invalid, e.g. if a date range was 100 days or if the searchFlags value is less than -1.

Checking an asynchronous job

As detailed on the Admin Report page, job status can be checked by issuing a GET request:

GET /api/async/{jobId}

For more details, refer to the Admin Report page.

Downloading a task report

The ResultUri for a Task Admin Report has the following shape:

https://app.sharebase.com/sharebaseapi/api/async/results/tasks/task-report/1

Where:

reportId: the unique ID for this specific report.

By issuing a GET request to the provided resultUri, the completed Task Admin Report can be retrieved. This report respects the constraint parameters chosen in its initial POST request, such as toDate and fromDate.

The report response format supports both JSON and CSV, corresponding to the Accept header in the request. The value application/json can be used for a JSON response and the value text/csv can be used for a CSV response. Without the header, it defaults to CSV.

Like the other endpoints, if an internal task creator or assignee was deleted from the deployment, their email addresses will have .inactive1, .inactive2, etc. appended to the end of it (e.g. "assignee@email.com.inactive1").

After retrieving the report, it will be continue to be available for 10 minutes. Afterwards, it will be gone, with an HTTP 410 GONE response returned. An HTTP 303 See Other is returned when the report is not complete yet. Meanwhile, an HTTP 403 Forbidden response is returned if the user requesting the report is not a Site Admin.

Examples of the Task Admin Report are included below:

Task Admin Report CSV Response

Task Id,Type,Instructions,Item Type,Item Name,Creator,Assignee,Due Date,Date Assigned,Status,Date Resolved
1,Approval,Please review this document.,Document,Sample Document,creator@email.com,assignee@email.com,3/1/2019 12:00:00 AM,2/13/2019 8:12:27 AM,2/13/2019 8:45:37

Task Admin Report JSON Response

[
    {
        "TaskId": 1,
        "TaskType": "Approval",
        "TaskStatus": "Approved",
        "Instructions": "Please review this document.",
        "DueDate": "2019-03-01T00:00:00",
        "DateAssigned": "2019-02-13T8:12:27.4672279",
        "DateEnded": "2019-02-13T8:45:37.7726553",
        "Creator": "creator@email.com",
        "Assignee": "assignee@email.com",
        "ItemType": "Document",
        "ItemName": "Sample Document"
    }
]

Deleting an asynchronous job

If an asynchronous job needs to be cancelled or deleted sooner than the automated cleanup occurs, issue the following DELETE request:

DELETE /api/async/{jobId}

Where:

jobId: the ID of the asynchronous job to delete

Upon a successful deletion, an HTTP 204 response is returned.

An HTTP 403 Forbidden response will occur when trying to cancel an operation started by another user.