Skip to main content
Skip table of contents

1. Analytics Dashboard Reports

Analytics Dashboard Reports

This scenario demonstrates how to generate analytics dashboard reports that provide aggregated insights into your Circularo environment. These reports offer high-level view of system activity, document status distribution, and usage patterns to help you understand organizational trends and make data-driven decisions.

Key features:

  • Generate analytics dashboards for monitoring system usage and document status

  • Access predefined reports designed for common business intelligence needs

  • Retrieve aggregated metrics that summarize organizational activity

Available Dashboard Reports

Due to security considerations and the complexity of analytics processing, Circularo provides a predefined set of dashboard reports. The currently available reports are:

[trans_status, trans_success_per_date, trans_per_date, docs_per_user, trans_consumption, trans_per_user, docs_consumption, docs_per_state, trans_per_avg]

Report Types and Use Cases

Different dashboard reports serve various business intelligence needs:

  • Transaction Status Reports: Monitor transaction success rates and status distribution

  • User Activity Reports: Analyze user engagement and document/transaction distribution by user

  • Document Status Reports: Track document lifecycle stages and identify bottlenecks

The list of available reports may be updated over time as new analytics capabilities are added to the system.

Read more about the reports in the Circularo documentation - Reports

Step 1 - Authenticate user and obtain session token

Before generating reports, you need to authenticate and retrieve the list of available dashboard reports. The login response includes the `allowedDashboards` array in the settings object, which lists all reports your account can access.

Endpoint

CODE 
POST /login

Request

JSON 
POST /login

Content-Type: application/json

{
  "name": "mary.griffin@circularo.com",
  "password": "#32Password1!",
  "returnToken": true
}

Response

JSON 
{
  "token": "UvBZ8wjW8pM0GNOD1DQdWqXUEHrs1CzWdDI5J403hNV1RY1LIhC2ZvLoifxqzYlH",
  "user": {
    "name": "mary.griffin@circularo.com",
    ...
  },
  "settings": {
    "data": {
      "allowedDashboards": [  //List of dashboard reports available to your account
        "trans_status",
        "trans_success_per_date",
        "trans_per_date",
        "docs_per_user",
        "trans_consumption",
        "trans_per_user",
        "docs_consumption",
        "docs_per_state",
        "trans_per_avg"
      ],
      ...
    }
  },
  ...
}

The response contains the following important properties:

  • token - Located at token in the response.

    • The authentication token that should be included in subsequent API requests. This token identifies your session and provides access to authorized resources.

    • Example value: UvBZ8wjW8pM0GNOD1DQdWqXUEHrs1CzWdDI5J403hNV1RY1LIhC2ZvLoifxqzYlH

  • allowedDashboards - Located at settings.data.allowedDashboards in the response.

    • Array of dashboard report identifiers that your account can generate.

    • Example value:

      JSON 
      [
  "trans_status",
  "trans_success_per_date",
  "trans_per_date",
  "docs_per_user",
  "trans_consumption",
  "trans_per_user",
  "docs_consumption",
  "docs_per_state",
  "trans_per_avg"
]

Step 2 - Generate Analytics Dashboard Reports

This endpoint allows you to generate one or multiple analytics dashboard reports in a single request. Each report provides aggregated data view for specific aspects of your Circularo environment.

  • Each report returns structured data suitable for visualization in charts or graphs

  • Reports include both raw values and corresponding labels for easy integration

  • Data is aggregated in real-time based on your current system state

Endpoint

CODE 
POST /search/dashboards

Request

JSON 
POST /search/dashboards?token=UvBZ8wjW8pM0GNOD1DQdWqXUEHrs1CzWdDI5J403hNV1RY1LIhC2ZvLoifxqzYlH

Content-Type: application/json

{
  "dashboards": [  //Array of dashboard reports to generate
    {
      "name": "docs_per_state"  //Report identifier from the allowedDashboards list
    }
  ]
}

Response

JSON 
{
  "dashboards": [
    {
      "name": "docs_per_state",  //Report identifier as specified in the request
      "results": [
        {
          "values": [  //Array of data points for this report
            {
              "value": 12,
              ...
            },
            {
              "value": 152,
              ...
            },
            {
              "value": 1048,
              ...
            },
            {
              "value": 85,
              ...
            },
            {
              "value": 7,
              ...
            },
            {
              "value": 12,
              ...
            }
          ]
        }
      ],
      "properties": {
        "datasetLabels": [  //Metadata for interpreting the report data
          {
            "value": "dynamic:dashboards.inactive",
            ...
          },
          {
            "value": "dynamic:dashboards.inprogress",
            ...
          },
          {
            "value": "dynamic:dashboards.completed",
            ...
          },
          {
            "value": "dynamic:dashboards.rejected",
            ...
          },
          {
            "value": "dynamic:dashboards.expired",
            ...
          },
          {
            "value": "dynamic:dashboards.cancelled",
            ...
          }
        ],
        ...
      }
    }
  ]
}

The response contains the generated data for each requested dashboard report. Each report includes both the raw values and corresponding labels needed for visualization.

  • The `dashboards` array contains one object for each requested report

  • Each report includes `results` with the actual data values and `properties` with metadata

  • The values in `results.values` correspond to the labels in `properties.datasetLabels`

Analytics Dashboard Reports Summary

You have successfully learned how to generate analytics dashboard reports from the Circularo system. These reports provide valuable insights into your organization's document workflows, user activity, and system usage patterns.

Key Concepts

  • Dashboard Reports: Predefined analytics visualizations that aggregate system data

  • Multi-Report Requests: Ability to request multiple reports in a single API call

  • Data Visualization: Structured data format designed for easy integration with charting libraries

Common Use Cases

  • Executive Dashboards: Create high-level overviews of system usage and document processing

  • Operational Monitoring: Track document workflows and identify bottlenecks or delays

  • Compliance Reporting: Generate reports for audit purposes and regulatory compliance

  • User Adoption Tracking: Monitor system usage patterns and user engagement metrics

Next Steps

With your understanding of analytics dashboard reports, you can now:

  • Integrate Circularo analytics into your organization's business intelligence systems

  • Create custom visualizations using the structured data returned by the reports

  • Set up automated reporting schedules for regular business reviews

  • Combine multiple reports to create comprehensive dashboards

Example Implementation

See our OpenAPI documentation to learn about the full set of API endpoints and parameters.

Please use proper exception handling and function decomposition in your own code. The code is provided for illustrative purposes only and is not intended for production use.

JAVASCRIPT 
// Analytics dashboard reports example
const URL = "https://sandbox.circularo.com";
const API_PATH = "/api/v1";
const TOKEN = "YOUR_AUTH_TOKEN"; // Obtained from login or API key

try {
    // Step 1: Retrieve available dashboard reports (optional if you already know the report names)
    // The "allowedDashboards" property is included in both "POST login" and "GET login" endpoints
    const userInfoResponse = await fetch(`${URL}${API_PATH}/login?token=${TOKEN}`);
    if (!userInfoResponse.ok) {
        throw new Error(`Failed to get user info: ${userInfoResponse.status} ${userInfoResponse.statusText}`);
    }

    const userData = await userInfoResponse.json();
    const availableReports = userData.settings.data.allowedDashboards;
    console.log("Available dashboard reports:", availableReports);

    // Step 2: Generate multiple dashboard reports in a single request
    const reportsResponse = await fetch(`${URL}${API_PATH}/search/dashboards?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            dashboards: [
                { name: "docs_per_state" },
                { name: "trans_per_user" }
            ]
        })
    });
    if (!reportsResponse.ok) {
        throw new Error(`Failed to generate reports: ${reportsResponse.status} ${reportsResponse.statusText}`);
    }

    const reportsData = await reportsResponse.json();

    // Step 3: Process the report data
    reportsData.dashboards.forEach((dashboard) => {
        console.log(`Processing dashboard: ${dashboard.name}`);

        // Extract labels and values
        const labels = dashboard.properties.datasetLabels.map((label) => label.parsed ?? label.value);
        const values = dashboard.results[0].values.map((item) => item.value);

        console.log("Labels:", labels);
        console.log("Values:", values);

        // Your code to process the report data
    });

} catch (error) {
    console.error('Error generating analytics reports:', error.message);
}
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close