Generating and downloading a user admin report

Generating a user admin report

A User Admin Report is a special comma separated value (.csv) file that contains all ShareBase activity a specific user has performed on all folders and documents, as well as some key authentication information: logins, failed logins, and password resets. A User Admin Report may only be generated by a user who is a Site Admin.

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 the generation of a new User Admin Report, issue the following POST request:

POST /api/async/users/{userId}/admin-report?includeSyncs=<value>&fromDate=<value>&toDate=<value>&fileName=<value>

Where:

  • userId: the ID of the user to create a report on
  • 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
  • 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
  • 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.

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.

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 User Admin Report

Checking an asynchronous job

When ShareBase's asynchronous framework has been given a job to perform in the background, the consumer will be directed to a location to check the status of the job.

To check the status of an asynchronous job, issue the following GET request:

GET /api/async/{jobId}

Where:

  • jobId: the ID of the asynchronous job to check the status of

While the asynchronous job is still processing, an HTTP 200 OK response is returned with a response body like the following:

{
    "Links": {
        "Cancel": "https://app.sharebase.com/sharebaseapi/api/async/{jobId}"
    }
}

When the asynchronous job is complete, an HTTP 200 OK response is returned with a response body like the following:

{
    "IsComplete": true,
    "Links": {
        "SelfUri": "https://app.sharebase.com/sharebaseapi/api/async/{jobId}",
        "ResultUri": <resultUri>
    }
}

Where:

  • ResultUri: a URI string that will vary based on the type of job that was processed - in all cases, this uri can take an GET request and will return the processed job's data

If the response from this status endpoint is HTTP 410 Gone, the job has been deleted. This is most likely due to the asynchronous framework's automated cleanup. A new request will need to be generated.

Downloading the completed User Admin Report

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

https://app.sharebase.com/sharebaseapi/api/async/results/users/admin-report/{reportId}

Where:

  • reportId: the unique ID for this specific report.

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

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.

An example User Admin Report looks like the following:

Activity Date,Username,Activity Type,Content Name
2/28/2018 2:41:17 PM,Ziggy Stardust,DocumentDeleted,Perisid Shower and the Milky Way.jpg
2/28/2018 2:41:13 PM,Ziggy Stardust,DocumentViewed,Perisid Shower and the Milky Way.jpg
2/28/2018 2:41:08 PM,Ziggy Stardust,DocumentLinkCreated,Pillars of creation.jpg
2/28/2018 2:40:59 PM,Ziggy Stardust,DocumentComment,Pillars of creation.jpg
2/28/2018 2:40:40 PM,Ziggy Stardust,UserAuthenticated,
2/28/2018 2:40:35 PM,Ziggy Stardust,UserAuthenticated,
2/28/2018 2:40:35 PM,Ziggy Stardust,PasswordChanged,
2/28/2018 2:39:36 PM,Ziggy Stardust,InvalidUserOrPassword,
2/28/2018 2:39:27 PM,Ziggy Stardust,InvalidUserOrPassword,
2/28/2018 2:39:18 PM,Ziggy Stardust,InvalidUserOrPassword,
2/27/2018 2:38:39 PM,Ziggy Stardust,DocumentSharedWithGroup,Pillars of creation.jpg
2/27/2018 2:38:22 PM,Ziggy Stardust,DocumentViewed,Pillars of creation.jpg
2/27/2018 2:38:18 PM,Ziggy Stardust,DocumentCreated,Perisid Shower and the Milky Way.jpg
2/27/2018 2:38:18 PM,Ziggy Stardust,DocumentCreated,Pillars of creation.jpg
2/27/2018 2:38:03 PM,Ziggy Stardust,FolderCreated,Astrophotography
2/27/2018 2:37:39 PM,Ziggy Stardust,UserAuthenticated,

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.