Report Export API

Table of Contents
- Introduction
- Configuring Exportable Reports
- Listing Exportable Reports
- Fetching Report Metadata
- Fetching Report Data
   - Real Time Pagination
   - Prepared Report View

---

Introduction

WorkSpan comes equipped with some advanced reporting capabilities that users can use to analyze and measure the success of their business goals in real-time, based on the data they have in the system. When they want to take this to the next level by building even more advanced analytics outside WorkSpan or they just want to loop some of the data back to their internal systems, WorkSpan provides them a Public RESTful API built on top of the robust reporting framework that enables them to do that with ease.

For OpenAPI documentation, visit: https://developer.workspan.com

Configuring Exportable Reports

Once a report is created in WorkSpan, to become available for export the user needs to explicitly mark it as exportable. To do this, under Report Options select “Enable Report for API” (see screenshot).

Additional feature to the report is to configure the column keys that will be used in the Export API data response. To do this, we can edit the report, under Report Columns - Export name we can configure the keys and click “Save & Exit” (see screenshot).

Listing Exportable Reports

This is a paginated endpoint that will return a list of all exportable reports that are accessible by the authenticated Application user.

For OpenAPI documentation and examples, visit: https://developer.workspan.com

Fetching Report Metadata

This endpoint will return metadata for a given report. Metadata consists of:

• Report’s id, name, description, status
• Created by/at, Updated by/at
• Report Category
• Report Columns - list of column keys and schema containing:
• Value Data Type
• Repeated Flag
• Report Filters - nested group of filters
• Report Sorting configuration

For OpenAPI documentation and examples, visit: https://developer.workspan.com

Fetching Report Data

WorkSpan Public API provides two ways of fetching report data:

1. Real-time Pagination
1. Returns real-time data (no preparation step required)
2. Good for small reports (< 10k rows)
3. Usable for bigger reports too with the risk of missing or ghost rows due to concurrent updates going in the same time
2. Prepared Report Data
1. Requires a separate prepare call and wait for a report view to be prepared before exporting the data
2. Good for reports of any size
3. Recommended way for data consistency

Real-time Pagination

This is a paginated endpoint that will return report data in real-time.
Note, while iterating through the pages there is a risk of missing or ghost rows due to concurrent updates going in at the same time.

For OpenAPI documentation and examples, visit: https://developer.workspan.com

Prepared Report View

Using a prepared report view is a safer and thus the recommended way for external applications to export report data. The view will be created in a single transaction and remain unchanged while iterating through the pages. This is the process for creating a prepared report view:

 Report View can be in one of the following states:

• PENDING - The background job has been submitted and waiting in the queue.
• RUNNING - The background job is running and preparing the view.
• SUCCESS - The background job successfully creates the view and the view is now available for export through the paginated data endpoint.
• FAILED - The background job failed to create the view. To check error messages, fetch report view metadata (status message).

Prepare Report View

This endpoint will trigger a background job that will create a new temporary report view. The expiry time for this view can be passed as a parameter, the maximum expiration time can be set to 24h. External applications that will export the data multiple times per day can create a new view for each run.

For OpenAPI documentation and examples, visit: https://developer.workspan.com

Fetch Report View Metadata

This endpoint will return the view metadata for an existing prepared report view. Metadata consists of:

• Report View ID and Report Version
• Created By/At
• Generated At, Expiry At
• Report View Status in (PENDING, RUNNING, SUCCESS, FAILED) and status message
• Report Metadata (see response from metadata endpoint)
• Additional filters and sorting applied

For OpenAPI documentation and examples, visit: https://developer.workspan.com

Fetch Report View Status

This endpoint will return the view status for an existing prepared report view.
Once the report view preparation is triggered, external applications will wait for the view to be ready (status: SUCCESS) by periodically checking the view status (polling). Depending on the size of the report, the view preparation can take from a few seconds to several minutes. It is recommended that external applications implement exponential backoff with an initial timeout.

For OpenAPI documentation and examples, visit: https://developer.workspan.com

Fetch Report View Data

This is a paginated endpoint that will return report view data. Report view data is guaranteed not to change after the view has been created.

For OpenAPI documentation and examples, visit: https://developer.workspan.com