Reporting service

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

NOTE: To generate a report through the API, the user running the command must be the same as the user who created the report in Control-M Reports.

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

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

Where:

Parameter

Description

<report_name>

Name of the Control-M report

If the name contains spaces, enclose it in double quotes. It must not contain other special characters.

If the report is shared, add shared: before the name.

[format]

(Optional) The format of the report, one of the following:

  • csv
  • pdf
  • excel

Default value: csv

<file_path>The full path to the file that you want to create and download
[configuration file]

(Optional) JSON file that contains additional, customized parameters (for example, date and time formats and new filter values).

For more information about the configuration file and the settings that you can include within it, see Reporting configuration.

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'


Note

Synchronous generation of reports is supported only through the CLI. The use of REST API command (such as cURL commands) for synchronous generation of reports is deprecated. Use the REST API commands for asynchronous generation of reports instead (reporting/report and then reporting/status and reporting/download).

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

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

Where:

Parameter

Description

<report_name>

Name of the Control-M report

If the name contains spaces, enclose it in double quotes. It must not contain other special characters.

If the report is shared, add shared: before the name.

[format]

(Optional) The format of the report, one of the following:

  • csv
  • pdf
  • excel

Default value: csv

[configuration file]

(Optional) JSON file that contains additional, customized parameters (for example, date and time formats and new filter values).

For more information about the configuration file and the settings that you can include within it, see Reporting configuration.

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

See REST API reference.

Example using curl:

REST API
curl -H "x-api-key: $token" \
-H "Content-Type: application/json" \
-X POST -d "{"name": "Alerts_1", "format": "pdf"}" \
"$endpoint/reporting/report"

Retrieving 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

CLI
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

See REST API reference.

Example using curl:

REST API
reportID="52ddeded-7234-4ec3-8588-945db0f961c0"
curl -H "x-api-key: $token" -H "Content-Type: application/json" \
-X GET "$endpoint/reporting/status/$reportID"

Downloading 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

CLI
ctm reporting download <reportID> -o <output_report_path>

Where:

Parameter

Description

<reportID>

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).

<output_report_path>The name and path of an output report file to download the report into.

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

See REST API reference.

Example using curl:

REST API
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
Was this page helpful? Yes No Submitting... Thank you

Comments