DocumentationResourcesMarketplaceCommunity
Build your app

Board export job

📘

Discovery APIs are available as a Beta release to all customers who have Enterprise Guard and to a closed private beta cohort of customers on the Enterprise plan. If you are an Enterprise customer with a use case for the beta, please contact your Customer Success Manager to join the waitlist for early access.

Overview

Discovery APIs allow customers on the Enterprise Plan to export board data from Miro so the board data can be reviewed manually or ingested into purpose-built tools for legal, compliance, and security purposes. The first Discovery API, Board export API, is now in beta.

The Board export API provides a ZIP file that includes a PDF export of the board content , a JSON record of all open comments at the time when the job runs, and video recordings of TalkTrack webcam footage associated with the board, if applicable. For large boards, the export job produces multiple PDF files to depict the complete board.

The asynchronous API design includes endpoints for retrieving information about a board export job, such as the status.

📘

If you are an Enterprise Guard customer, you can run 5 board export jobs at the same time. However, if you are on the Enterprise private beta for Discovery APIs, you can have only one board export job running at once. The rate limit is set to level 4.

Use cases

Some of the common discovery use cases include:

  • eDiscovery (electronic discovery): the process of identifying, collecting, preserving, and reviewing digitally-stored information for use in a legal matter.
  • Information archive: a practice in which organizations maintain data outside the original system for long-term storage and record-keeping purposes. The content and metadata help customers index and search the archive and proactively monitor for compliance concerns.

Enabling eDiscovery in your Miro environment

Get the Discovery access token from the Enterprise integrations admin console:

  1. Log in to Miro as a Company Admin.
  2. Go to Settings > Enterprise Integrations.
  3. To enable eDiscovery, click the toggle.
  4. Copy the access token.
Settings image

Figure 1. Enable eDiscovery in the Enterprise Integrations Settings page.

Workflow

📘

The beta version of this API has limitations. The beta cohort will receive incremental data enrichment and API endpoints to solve their use cases as we work to productize a generally available offering.

  1. Creating an export job for boards

    1. Identify the set of Miro board IDs that meet your discovery criteria.

      📘

      • Identification of boards may come from custodians who share a URL, by querying the Get boards API or by analyzing Audit logs.
      • The board ID can be derived from the last part of a board url. For example, If the URL is https://miro.com/app/board/uXjVOD50NUI=/, then the board ID is uXjVOD50NUI=/.
    2. Make a request to create a board export job, where the boardIds body parameter is an array of the boards to export and the request_id parameter is a unique UUID created within your code.

      📘

      • A single board export job can have a maximum of 50 boards.
      • The UUID acts as an idempotency key. Subsequent requests using the same UUID will return the same jobId.
    3. Store the returned jobId for use in future steps.

      📘

      The UUID you provide is strictly for idempotency purposes and subsequent calls rely solely on the returned jobId from this step.

  2. Check the status of an export job

    📘

    We suggest you utilize an exponential back-off retry strategy.

    1. Make a request to get the board export job status, where the jobId parameter is the value returned from Step 1.
    2. If the jobStatus returns CREATED, the job has been created but not yet started. Retry the status call after some time.
    3. If the jobStatus returns IN_PROGRESS, the job is in progress, and the results are not ready yet. Retry the status call after some time.
    4. If the jobStatus returns FINISHED, the job is finished. You can now get results for the board export job.

  3. Retrieving the board export job results

    1. Make a request to get results for the board export job, where the jobId parameter is the value returned from Step 1.
    2. A successful call returns a results array for each board export requested.
    3. The exportLink parameter returns the URL of the S3 bucket that contains the exported files. Download the ZIP file from the S3 location.
    4. You can now utilize the downloaded board export results for manual review locally, or chain another job to ingest it into the compliance solution of choice.

Export content and structure

An individual zip file package is provided for each board.

  • The extracted zip file will use the boardKey as the naming standard.
    For example, if you request to export boardId uXjVPzN27sM=, the corresponding export zip file has the file name uXjVPzN27sM=.zip.
  • One or more PDF files with visual representations of the board canvas.
    Large boards are split into multiple PDF files.
  • Comments: JSON file with current comments on the board.
  • If applicable, one or more MP4 or webm video files with the webcam footage and a JSON metadata file containing information about the TalkTrack associated with the board, if applicable.