PingOne Advanced Identity Cloud

Reports API import and export

The reports API includes new import and export capabilities to automate and streamline the management of analytics reports. The reports API enables programmatic management of your report templates, and the accompanying Reports Postman collection simplifies the process of migrating them between different environments.

Importing and exporting report templates is only applicable to custom report templates. Administrators can export both draft and published templates.

Download Postman and import the reports collection

  1. Download and install the Postman application.

  2. Download the Reports Q3 Postman collection.

  3. Download the Reports Q3 Postman environment.

  4. In Postman:

    1. Go to File > Import... > Upload Files.

    2. Browse to the collection JSON file you downloaded in the previous step, and then click Open.

    3. Click Import to bring the collection and environment into your workspace. Make sure to change your environment variables to match your tenant.

Create a service account and download its private key

To use the Advanced Identity Cloud Postman collection, you must create a service account that the requests in the collection can use to connect to your Advanced Identity Cloud instance.

Follow the steps in Create a new service account.

  • In step 9, save the private key as a local file called key.jwk.

  • Make a note of the ID for the service account you created.

    An example of an ID is 449d7e27-7889-47af-a736-83b6bbf97ec5.

Export endpoint for report templates

The export endpoint allows you to retrieve the complete JSON configuration of a specific report template. Use this endpoint to back up your custom templates or to prepare them for migration to another environment.

General tips:

  • Reports UUID: To obtain a reports UUID for your export, first run a report. The response includes the UUID for the report.

  • Required Information: When using the import endpoint, specify the template name, target tenant and realm, and an owner responsible for reviewing the new template.

  • Local Download: The export action downloads the template as a file directly to your local machine. The filename matches the report’s name as it appears in the admin console.

  • Flexible and Editable: You can export both published and draft versions of a report. Once downloaded, you’re free to edit the file locally to change the report’s name or modify its JSON body.

  • Clean Assignments: For security and to ensure proper governance, the exported template doesn’t include any user or group assignments. After importing the report into a new environment, an administrator must explicitly assign it to the correct users or groups.

URI HTTP
method		 Description

/reports/templates/report-UUID?_action=export&templateType=draft

POST

Export a report template.

Parameters
Name Description

_action string (query)

Specify what action to take: export

templateType string (query)

Specify the type of template: draft, published
Responses
Code Description

200

Report template exported successfully

404

Template not found

500

Internal server error
Click for an example export request

Media type: application/json

curl \
--request POST \
'https://<tenant-env-fqdn>/reports/templates/A1C07D0B-49C9-48C6-B225-CE05F27A5DEE?templateType=draft&_action=export' \
--header 'Content-Type: application/json, text/plain, */\*' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Accept-Language: en-US,en;q=0.9' \
--header "Authorization: Bearer <access-token>" \
--data ''

Import endpoint for report templates

The API import endpoint lets you import a new report template using a previously exported JSON configuration. This simplifies the process of deploying tested and validated report templates from your staging environment.

General Tips:

  • Required Information: When using the import endpoint, you specify the template name, the target Advanced Identity Cloud tenant and realm, and an owner who is responsible for reviewing the new template.

  • Built-in Validation: The API performs two key checks before creating the report. First, it validates the structure of the uploaded file. Second, it checks if a report with the same name already exists in the target environment. If either of these checks fails, the API returns an error message.

  • Import as Draft: To ensure proper governance, the system always imports the new template as a draft. This allows the designated owner to test and verify the report before publishing it for wider use.

  • Immediate Availability: After a successful import, the new draft template immediately appears in the report list within the admin console, assigned to the specified owner.

URI HTTP
method		 Description

/reports/templates/import

POST

Imports a template draft.

Parameters

None

Responses
Code Description

200

Report template imported successfully

400

Bad Request: Invalid file format

500

Internal server error
Click for an example import request

Media type: application/json

curl \
--location \
https://<tenant-env-fqdn>/reports/templates/import' \
--header 'Content-Type: application/json, text/plain, */\*' \
--header 'Accept-API-version: resource=1.0' \
--header 'Accept-Language: en-US,en;q=0.9' \
--header "Authorization: Bearer <access-token>" \
--form 'file=@"/Users/test.admin/Downloads/New_draft"'