Reporting Service

The Reporting service enables you to generate reports and obtain information about reports that were set up through Control-M Reports. You can generate reports either synchronously or asynchronously.

The following API commands enable you to generate reports and obtain information about reports:

• Synchronous Report Generation (reporting report::get)

• Asynchronous Report Generation (reporting report)

• Retrieve Report Status (reporting status::get)

• Download the Report (reporting download)

• Retrieve Report Filter Definitions (reporting reportFilters::get)

Synchronous Report Generation (reporting report::get)

The reporting report::get command enables you to generate a report synchronously. In the command, you specify the name of the report, as set up in Control-M Reports. For the report format, you can choose between a CSV file, a PDF file, or an Excel (.xlsx) file. The report is then downloaded to a file that you specify.

CLI Syntax

ctm reporting report::get <report_name> [format] -o <file_path> [-f <configuration file>]

The following table describes the reporting report::get command parameters.

The following example shows a typical CLI command and response:

>ctm reporting report::get "Active Jobs_1" csv -o Active.csv
{
  "reportId": "f6ef006a-75ef-4db1-9c3b-17cb2d145f87",
  "name": "Active Jobs_1",
  "format": "csv",
  "status": "SUCCEEDED"
}
Downloading 'f6ef006a-75ef-4db1-9c3b-17cb2d145f87' into 'Active.csv'

curl -H "Authorization: Bearer $token" $endpoint/reporting/report/$report_name?format=pdf

Asynchronous Report Generation (reporting report)

The reporting report command enables you to send a request to generate a report asynchronously. In the command, you specify the name of the report, as set up in Control-M Reports. For the report format, you can choose between a CSV file, a PDF file, or an Excel (.xlsx) file.

The command response provides a summary of basic report details and generation status, including a report ID that you can use to check the status of asynchronous report generation (using the reporting status::get command).

CLI Syntax

ctm reporting report <report_name> [format] [-f <configuration file>]

The following table describes the reporting report command parameters.

The following example shows a typical CLI command and response:

>ctm reporting report Alerts_1 pdf
{
    "reportId": "52ddeded-7234-4ec3-8588-945db0f961c0",
    "name": "Alerts_1",
    "format": "pdf",
    "status": "PROCESSING"
}

REST API Syntax

Example using cURL:

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json" \
-X POST -d "{"name": "Alerts_1", "format": "pdf"}" \
"$endpoint/reporting/report"

Retrieve Report Status (reporting status::get)

The reporting status::get command enables you to check the status of report generation for a report that you previously generated. You identify the report by specifying its report ID.

The command response provides a summary of basic report details and generation status.

CLI Syntax

ctm reporting status::get <reportID>

Where <reportID> is the report ID that you received when you requested generation of the report using the reporting report command (or even the reporting report::get command).

The following example shows a typical CLI command and response:

>ctm reporting status::get 52ddeded-7234-4ec3-8588-945db0f961c0
{
    "reportId": "52ddeded-7234-4ec3-8588-945db0f961c0",
    "name": "Alerts_1",
    "format": "pdf",
    "status": "SUCCEEDED"
}

REST API Syntax

Example using cURL:

reportID="52ddeded-7234-4ec3-8588-945db0f961c0"
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json" \
-X GET "$endpoint/reporting/status/$reportID"

Download the Report (reporting download)

The reporting download command enables you to download a report that you previously generated. You identify the report by specifying its report ID.

CLI Syntax

ctm reporting download <reportID> -o <output_report_path>

The following table describes the reporting download command parameters.

The following example shows a typical CLI command and response:

>ctm reporting download 52ddeded-7234-4ec3-8588-945db0f961c0 -o Alerts1.pdf
Downloading '52ddeded-7234-4ec3-8588-945db0f961c0' into 'Alerts1.pdf'

REST API Syntax

Example using cURL with an API token:

reportID="52ddeded-7234-4ec3-8588-945db0f961c0"
output_report_path="C:\Reports\Alerts1.pdf"
curl -H "x-api-key: $token" -H "Authorization: x-api-key $token" \
-X GET "$endpoint/reporting/download?reportId=$reportID" -o $output_report_path

Example using cURL with a session token:

reportID="52ddeded-7234-4ec3-8588-945db0f961c0"
output_report_path="C:\Reports\Alerts1.pdf"
curl -H "Authorization: Bearer $token" \
-X GET "$endpoint/reporting/download?reportId=$reportID" -o $output_report_path

Retrieve Report Filter Definitions (reporting reportFilters::get)

The reporting reportFilters::get command enables you to obtain a list of all filters defined in a report, in JSON format.

You can use the output of this command as the starting point for updating filter values — edit filter values and then submit your list using the API command for generating a report.

For more information, see Filter Values in Reporting Configuration.

CLI Syntax

ctm reporting reportFilters::get <report_name>

where <report_name> is the name of the Control-M report.

REST API Syntax

Example using cURL:

report_name="Alerts_1"
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json" \
-X GET "$endpoint/reporting/reportFilters/$report_name"