Generating and downloading an item activity report

In addition to User Admin Reports, the API provides the ability to generate activity reports for individual documents and libraries in ShareBase.

A Document Activity Report is a special comma separated value (.csv) file that contains all ShareBase activity that has occurred on a specific document.

Meanwhile, a Library Activity Report is a special comma separated value (.csv) file that contains all ShareBase activity that has occurred in a specific library.

For both reports, a JSON response is also available using the header: Accept: "application/json".

Information included in these reports consists of the activity date, the user name for the user who performed the activity, the type of activity, the name of the content in the activity, and the Id of the user. Note, the user name of users who received link shares to documents or folders (who are also known as "external users" or "share by link users") will be either the email address of the user or "Share By Link User". The email address will be given if the share uses access code security. In all other cases, it will be "Share By Link User". The User Id for all share by link users is the same.

A Document Activity Report can be generated by Site Admins or users who have read access to the document (excluding external share by link users). Likewise, a Library Activity Report can be generated by Site Admins or users who have read access to the library.

Generating an activity 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 Document Activity Report, issue the following POST request:

POST /api/async/documents/{documentId}/activity-report?fromDate=<value>&toDate=<value>&includeSyncs=<value>&fileName=<value>

To start generating a new Library Activity Report, issue the following POST request:

POST /api/async/libraries/{libraryId}/activity-report?fromDate=<value>&toDate=<value>&includeSyncs=<value>&fileName=<value>

Where, in both cases:

  • 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
  • includeSyncs: a boolean, an optional query string parameter to show the download activity specifically from the ShareBase Desktop client ('syncing') in the report - defaults to false
  • 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.

On maximum date ranges, the document activity report does not have a maximum date range. If the values are not specified, all of the document activity is retrieved.

Conversely, the library activity report has a maximum date range of 30 days.

Tip

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

To generate a report for document with Id 42 that includes Desktop syncs for all document activity, the following request could be used:

POST /api/async/documents/42/activity-report?includeSyncs=true

To generate a report for document with Id 42 over a specific date time range, the following request could be used:

POST /api/async/documents/42/activity-report?fromDate=2019-01-01+10%3A20&toDate=2019-01-03+12%3A40

To generate a report for library with Id 100, the following request could be used:

POST /api/async/libraries/100/activity-report

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 activity report

If the user is a share by link user or if they are not a Site Admin nor do they have read access to the content, an HTTP 403 Forbidden response is returned.

If the content does not exist, an HTTP 404 Not Found response is returned.

An HTTP 400 Bad Request is sent if the parameters are invalid, e.g. if the from date was after the to date.

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 an activity report

The ResultUri for the reports have the following shapes:

Document Activity Report:

https://app.sharebase.com/sharebaseapi/api/async/results/documents/document-activity-report/{reportId}

Library Activity Report:

https://app.sharebase.com/sharebaseapi/api/async/results/libraries/library-activity-report/{reportId}

Where, in both cases:

  • reportId: the unique ID for this specific report

By issuing a GET request to the provided resultUri, the completed 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.

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 does not have access to get the report. An HTTP 404 Not Found response is returned if a report for the specific activity type and the given Id was not found.

Examples of a retrieved report are included below:

Example Activity Report CSV Response

Activity Date,Username,Activity Type,Content Name,User Id
1/29/2020 2:27:02 PM,Share By Link User,Viewed Document,Promotional Document.docx,2
6/7/2019 10:31:18 AM,Document Creator,Created Link to Document,Promotional Document.docx,16
6/6/2019 7:51:39 AM,Document Creator,Viewed Document,Promotional Document.docx,16
6/6/2019 7:51:25 AM,Document Creator,Created Document,Promotional Document.docx,16

Example Activity Report JSON Response

[
    {
        "ActivityDate": "2019-06-08T19:27:02.1234288",
        "UserName": "Share By Link User",
        "ActivityItemType": "Viewed Document",
        "ContentName": "Promotional Document.docx",
        "UserId": 2
    },
    {
        "ActivityDate": "2019-06-07T14:31:18.4514114",
        "UserName": "Document Creator",
        "ActivityItemType": "Created Link to Document",
        "ContentName": "Promotional Document.docx",
        "UserId": 16
    },
    {
        "ActivityDate": "2019-06-06T12:51:39.2659261",
        "UserName": "Document Creator",
        "ActivityItemType": "Viewed Document",
        "ContentName": "Promotional Document.docx",
        "UserId": 16
    },
    {
        "ActivityDate": "2019-06-06T12:51:25.477829",
        "UserName": "Document Creator",
        "ActivityItemType": "Created Document",
        "ContentName": "Promotional Document.docx",
        "UserId": 16
    }
]

Note, document and library activity reports have the same format.

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.