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. After a report is generated, it is stored on the server for 10 days until it is deleted.

To generate a report with Control-M Automation API, the user that runs the command must be the same as the user who creates the report in Control-M Reports.

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

reporting report::get (Synchronous)
reporting report (Asynchronous)
reporting status::get
reporting reportUrl::get
reporting download (Deprecated)
reporting reportFilters::get

reporting report::get (Synchronous)

The reporting report::get command enables you to generate a report synchronously. You must specify in the command the name of the report as predefined in Control-M Reports. The report format options include a CSV file, a PDF file, or an Excel (.xlsx) file. After you generate a report, the system downloads it to a specified file.

CLI Syntax

The following shows the CLI syntax for the reporting report::get command:

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

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

Parameter	Description
report_name	Defines the 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) Determines one of the following report formats: csv pdf excel Default: csv
file_path	Defines the full path to the file that you want to create and download.
configuration file	(Optional) Defines a JSON file that contains additional customized parameters, such as date and time formats and new filter values. For more information about the configuration file and settings that you can include, see Reporting Configuration.

The following example shows the reporting report::get command and response:

Copy

>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'

Synchronous report generation is supported only with the CLI. REST API commands, such as cURL commands, for synchronous report generation are deprecated. Run the REST API commands for asynchronous report generation instead of reporting/report and then reporting/status and reporting/download.

reporting report (Asynchronous)

The reporting report command enables you to send a request to generate a report asynchronously. You must specify in the command the name of the report as predefined in Control-M Reports. The report format options include 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 to check the status of asynchronous report generation with the reporting status::get command.

CLI Syntax

The following shows the CLI syntax for the reporting report command:

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

The following table describes the reporting report command parameters.

Parameter

Description

report_name

Defines the 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) Determines one of the following report formats:

csv
pdf
excel

Default: csv

configuration file

(Optional) Defines a JSON file that contains additional customized parameters, such as date and time formats and new filter values.

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

The following example shows the reporting report command and response:

Copy

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

REST API Syntax

The following example shows the REST API syntax for the reporting report command in cURL:

Copy

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

reporting status::get

The reporting status::get command enables you to check the report generation status for a previously generated report. You can identify the report with its report ID.

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

CLI Syntax

The following shows the CLI syntax for the reporting status::get command:

ctm reporting status::get <reportID>

where <reportID> is the report ID you receive after you request to generate a report with the reporting report command or the reporting report::get command. A report is available for 10 days from the time it is generated.

The following example shows the reporting status::get command and response:

Copy

>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

The following example shows the REST API syntax for the reporting status::get command in cURL:

Copy

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

reporting reportUrl::get

The reporting reportUrl::get command enables you to obtain a report URL for download of a report that you previously generated. You can identify the report with its report ID.

The command returns a presigned S3 URL that is valid for 15 minutes. You can use this URL to download the report with a web browser or you can include it in a cURL or wget command in a command line.

If you run this command with the CLI, you can use the -o option to download the report to a file that you specify (in addition to returning the download URL).

CLI Syntax

The following shows the CLI syntax for the reporting reportUrl::get command:

ctm reporting reportUrl::get <reportID> [-o <output_report_path>]

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

Parameter	Description
reportID	Defines the report ID you receive after you send a request to generate the report with the reporting report command or the reporting report::get command. A report is available for 10 days from the time it is generated.
output_report_path	(Optional) Defines the name and path of an output report file to download the report into from the generated URL.

The following example shows the reporting reportUrl::get command and response:

Copy

>ctm reporting reportUrl::get 52ddeded-7234-4ec3-8588-945db0f961c0 -o Alerts1.csv
{
  "reportURL": https://ctm...
}
Downloading 'https://ctm...'  into 'Alerts1.csv'

REST API Syntax

The following example shows the REST API syntax for the reporting reportUrl::get command in cURL:

Copy

curl -H "x-api-key: $token" -X GET \
"$endpoint/reporting/reportUrl?reportId=$reportID"

reporting download (Deprecated)

The reporting download command enables you to download a previously generated report. You can identify the report with its report ID.

This command is deprecated and replaced by reporting reportUrl::get.

CLI Syntax

The following shows the CLI syntax for the reporting download command:

ctm reporting download <reportID> -o <output_report_path>

The following table describes the reporting download command parameters.

Parameter	Description
reportID	Defines the report ID you receive after you send a request to generate the report with the reporting report command or the reporting report::get command. A report is available for 10 days from the time it is generated.
output_report_path	Defines the name and path of an output report file to download the report.

The following example shows the reporting download command and response:

Copy

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

REST API Syntax

The following example shows the REST API syntax for the reporting download command with an API token in cURL:

Copy

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

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 to update filter values, edit filter values, and then submit your list with the API command to generate a report.

For more information, see Filter Values in Reporting Configuration.

CLI Syntax

The following shows the CLI syntax for the reporting reportFilters::get command:

ctm reporting reportFilters::get <report_name>

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

REST API Syntax

The following example shows the REST API syntax for the reporting reportFilters::get command in cURL:

Copy

report_name="Alerts_1"
curl -H "x-api-key: $token" -H "Content-Type: application/json" \
-X GET "$endpoint/reporting/reportFilters/$report_name"