2. Transaction Detail Reports

Transaction Detail Reports

This scenario demonstrates how to generate detailed transaction reports that provide comprehensive information about document activities and workflow states in your Circularo environment. Unlike the analytics dashboard reports that offer aggregated visualizations, transaction detail reports provide granular, record-level data for in-depth analysis and auditing.

Key features:

Generate detailed reports with comprehensive transaction data for each document
Filter reports based on specific criteria such as user, document state, or transaction type
Access document-level details including creation, sharing, and signing information

Understanding Transaction Detail Reports

Transaction detail reports provide comprehensive information about document activities:

Document Metadata: Title, ID, type, creation date, and owner information
Workflow States: Current status of documents (completed, in progress, rejected, etc.)
Transaction History: Record of actions performed on documents

Due to security reasons, only users with the use_all_documents_export permission can generate transaction detail reports. This restriction helps protect sensitive document information.

For more information about transaction reports and their contents, see the Circularo documentation - Transaction Detail Report

Step 1 - Generate Report Filtered by Creator

This endpoint demonstrates how to generate a transaction detail report filtered by document creator. This is useful when you need to analyze or audit the activities of a specific user within your organization.

Filters transactions based on the user who created the document
Includes pagination parameters to control the number of results returned
Returns detailed information about each matching document and its transactions
Useful for user activity auditing and performance analysis

Endpoint

CODE

POST /search/reports

Request

JSON

POST /search/reports?token=B5hA4lnb7bzkWP351KtnE7U2HOL3EouhLH5YXGQQd0YgGONavKfNoknfvrgduhS2

Content-Type: application/json

{
  "query": {
    "esFilters": {  //Elasticsearch filter query structure
      "bool": {
        "filter": [
          {
            "nested": {  //Nested query to filter by document creator
              "path": "createName",
              "query": {
                "term": {
                  "createName.name": "mary.griffin@circularo.com"
                }
              }
            }
          }
        ]
      }
    },
    "from": 0,  //Starting position for pagination (0-based)
    "size": 20  //Maximum number of results to return
  }
}

Response

JSON

{
  "from": 0,  //Starting position of this result set
  "total": 451,  //Total number of matching documents
  "results": [  //Array of document transaction records
    {
      "documentTitle": "Project Proposal",  //Document title and identifier
      "documentId": "e94b10db-994a-4476-8e8e-b1825860e46d",
      "createName": "mary.griffin@circularo.com",  //User who created the document
      ...
    },
    ...
  ]
}

The response contains detailed transaction information for up to 20 documents created by the specified user.

Each result includes comprehensive document metadata and transaction details
The total field indicates the total number of matching documents across all pages
The from field shows the starting position of this result set
For large result sets, use pagination parameters to retrieve subsequent pages

Step 2 - Generate Report Filtered by Workflow State

This endpoint demonstrates how to generate a transaction detail report filtered by workflow state. This allows you to focus on documents that have reached a specific stage in their lifecycle, such as completed signatures.

Filters transactions based on the current workflow state of documents
Focuses on successfully completed documents in this example
Returns detailed information about each matching document and its transactions
Useful for completion rate analysis and successful transaction reporting

The "completed" state filter is particularly useful for generating success reports or analyzing fully executed documents for compliance purposes.

Endpoint

CODE

POST /search/reports

Request

JSON

POST /search/reports?token=B5hA4lnb7bzkWP351KtnE7U2HOL3EouhLH5YXGQQd0YgGONavKfNoknfvrgduhS2

Content-Type: application/json

{
  "query": {
    "esFilters": {
      "bool": {
        "filter": [
          {
            "nested": {  //Nested query to filter by workflow state
              "path": "workflow",
              "query": {
                "term": {
                  "workflow.shareStateName": "completed"
                }
              }
            }
          }
        ]
      }
    }
  }
}

Response

JSON

{
  "from": 0,
  "total": 1227,
  "results": [
    {
      "documentTitle": "Contract Agreement",
      "documentId": "a9becc2b-76af-410e-bfd4-8312c7aed8b7",
      "shareStateName": "completed",  //Workflow state of the document
      ...
    },
    ...
  ]
}

The response contains detailed transaction information for documents that have been successfully completed.

Each result includes comprehensive document metadata and transaction details
All returned documents have a shareStateName value of "completed"
The total field indicates the total number of completed documents
This data is valuable for success rate analysis and compliance reporting

Other common workflow states you can filter by include "inprogress", "rejected", "expired", and "cancelled". Each provides insight into different aspects of your document processes.

Step 3 - Generate Report for Documents with Transactions

This endpoint demonstrates how to generate a transaction detail report that includes only documents with actual transaction activity. This filter excludes documents that have been created but haven't undergone any significant workflow actions.

Filters for documents that have transaction data (signing, sharing, etc.)
Excludes documents that have only been created or viewed
Returns detailed information about each document with transaction history
Useful for focusing on documents with meaningful workflow activity

This filter is particularly valuable when you want to analyze active documents and exclude documents that haven't entered a workflow process yet.

Endpoint

CODE

POST /search/reports

Request

JSON

POST /search/reports?token=B5hA4lnb7bzkWP351KtnE7U2HOL3EouhLH5YXGQQd0YgGONavKfNoknfvrgduhS2

Content-Type: application/json

{
  "query": {
    "esFilters": {
      "bool": {
        "filter": [
          {
            "nested": {  //Nested query to filter for documents with transaction data
              "path": "workflow",
              "query": {
                "bool": {
                  "must": {
                    "exists": {
                      "field": "workflow.shareStateName"
                    }
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}

Response

JSON

{
  "from": 0,
  "total": 1227,
  "results": [
    {
      "documentTitle": "Confidentiality Agreement",
      "documentId": "03149c14-aeeb-43f1-bc28-c9f88fbae878",
      "shareStateName": "rejected",  //Example of a non-completed workflow state
      ...
    },
    ...
  ]
}

The response contains detailed transaction information for documents that have undergone workflow actions such as sharing or signing.

Each result includes comprehensive document metadata and transaction details
All returned documents have transaction history (sharing, signing, etc.)
Documents that were only created or viewed without further actions are excluded
This focused data set is ideal for analyzing active document workflows

Combining this filter with other criteria, such as date ranges or specific users, can help you create highly targeted transaction reports for specific business needs.

Transaction Detail Reports Summary

You have successfully learned how to generate and filter transaction detail reports in the Circularo system. These reports provide comprehensive, record-level information about document activities and workflow states.

Key Concepts

Transaction Detail Reports: Granular, record-level data about document activities and states
Filtering Capabilities: Various criteria to focus reports on specific users, states, or activities
Elasticsearch Queries: Powerful query structures for precise data filtering
Pagination: Techniques for handling large result sets in manageable chunks

Common Use Cases

Compliance Reporting: Generate detailed audit trails for regulatory requirements
User Activity Analysis: Track document creation and processing by specific users
Success Rate Monitoring: Analyze completion rates for document workflows
Process Optimization: Identify bottlenecks or issues in document processing

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

// Transaction detail reports example
const URL = "https://sandbox.circularo.com";
const API_PATH = "/api/v1";
const TOKEN = "YOUR_TOKEN"; // Must have "use_all_documents_export" permission

try {
    // Example 1: Generate report for documents created by a specific user
    const userReportResponse = await fetch(`${URL}${API_PATH}/search/reports?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            query: {
                esFilters: {
                    bool: {
                        filter: [{
                            nested: {
                                path: "createName",
                                query: {
                                    term: {
                                        'createName.name': "john.smith@example.com"
                                    }
                                }
                            }
                        }]
                    }
                },
                from: 0,
                size: 50
            }
        })
    });
    if (!userReportResponse.ok) {
        throw new Error(`User report generation failed: ${userReportResponse.status} ${userReportResponse.statusText}`);
    }

    const userReportData = await userReportResponse.json();
    console.log(`Found ${userReportData.total} documents created by john.smith@example.com`);

    // Example 2: Generate report for successfully completed documents
    const completedReportResponse = await fetch(`${URL}${API_PATH}/search/reports?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            query: {
                esFilters: {
                    bool: {
                        filter: [{
                            nested: {
                                path: "workflow",
                                query: {
                                    term: {
                                        'workflow.shareStateName': "completed"
                                    }
                                }
                            }
                        }]
                    }
                },
                from: 0,
                size: 50
            }
        })
    });
    if (!completedReportResponse.ok) {
        throw new Error(`Completed report generation failed: ${completedReportResponse.status} ${completedReportResponse.statusText}`);
    }

    const completedReportData = await completedReportResponse.json();
    console.log(`Found ${completedReportData.total} successfully completed documents`);

    // Example 3: Generate report with existing transactions
    const transactionReportResponse = await fetch(`${URL}${API_PATH}/search/reports?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            query: {
                esFilters: {
                    bool: {
                        filter: [
                            {
                                nested: {
                                    path: "workflow",
                                    query: {
                                        bool: {
                                            must: {
                                                exists: {
                                                    field: "workflow.shareStateName"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        ]
                    }
                },
                from: 0,
                size: 50
            }
        })
    });
    if (!transactionReportResponse.ok) {
        throw new Error(`Transaction report generation failed: ${transactionReportResponse.status} ${transactionReportResponse.statusText}`);
    }

    const transactionReportData = await transactionReportResponse.json();
    console.log(`Found ${transactionReportData.total} documents with transactions`);

} catch (error) {
    console.error('Error generating transaction reports:', error.message);
}