Reporting Configuration

This page provides information for creating a configuration file for use during report generation. This configuration file is a payload JSON file that can contain various report settings.

The following code sample shows the available objects that you can include within such a file. The rest of this page provides details about each of these objects and their properties. All objects are optional.

Copy 
{
    "format": "csv",
    "dateTimeSettings": {
       "dateFormat": "DB_date_format",
       "timeFormat": "h:mm tt",
       "dateTimeFormat": "yyyy-MM-dd H:mm:ss"
    },
    "filters": [
        {
            "name": "Application",
            "value": "myApp"
        },
        {
            "name": "Folder",
            "value": "myFolder"
        }
    ]
}

Report Format

You can specify the report format in the configuration file instead of specifying it in the API command for report generation.

You can set the format to one of the following values:

  • csv (default)

  • pdf

  • excel (.xslx file)

"format": "pdf"

Date and Time Formats

The dateTimeSettings object enables you to set the format of dates and times in reports, overriding the default formats inherited from your browser.

The following table describes the dateTimeSettings object properties.

Property

Description
dateFormat

Format of dates in the report.

Valid values:

  • Formats available in a Windows operating system:

    • M/d/yyyy

    • M/d/yy

    • MM/dd/yy

    • MM/dd/yyyy

    • yy/MM/dd

    • yyyy-MM-dd

    • dd-MMM-yy

    • dddd, MMMM d, yyyy

    • MMMM d, yyyy

    • dddd, d MMMM, yyyy

    • d MMMM, yyyy

  • As set in the Control-M/EM database:  DB_date_format.
timeFormat

Format of times in the report.

Valid values:

  • Formats available in a Windows operating system:

    • h:mm tt

    • hh:mm tt

    • H:mm

    • HH:mm

    • h:mm:ss tt

    • hh:mm:ss tt

    • H:mm:ss

    • HH:mm:ss

  • As set in the Control-M/EM database:  DB_time_format.
dateTimeFormat

Format of timestamps that include both the date and the time.

Valid values:

  • A combination of the other two formats, first the date format and then the time format, separated by a space character. For example: "M/d/yyyy h:mm tt".

  • As set in the Control-M/EM database:  DB_datetime_format.

For example:

Copy 
"dateTimeSettings": {
    "dateFormat": "DB_date_format",
    "timeFormat": "h:mm tt",
    "dateTimeFormat": "yyyy-MM-dd H:mm:ss"
}

The date and time settings that you specify in the configuration file are validated during report generation. If you want to set some other format that is not listed above but is valid in your environment, you can turn off the validation process. To do so, define a new system parameter of type rf (Report parameter) named SkipDateTimeSettingValidation in the CCM. For more information, see Defining Control-M/EM system parameters.

Filter Values

The filters object enables you to set new values for filters that were defined in the report in Control-M Reports, overriding the original filter values in the report definitions.

For each filter value that you want to override, you include a pair of name and value properties. For example:

Copy 
"filters": [
    {
        "name": "Application",
        "value": "myApp"
    },
    {
        "name": "Folder",
        "value": "myFolder"
    }
]

Note the following additional guidelines:

  • To simplify the process, you can generate a list of all filters defined in the report (in JSON format) and use that list as the starting point for an edited list (with different filter values). You can then submit your edited list using the API command for generating a report. To obtain the list of filters, you have the following options:

  • Ensure that any filter that you want to override has a unique name in the report (that is, in Control-M Reports, the value in the left-hand-side field is used in only one filter in the report definitions).

If you want to dynamically populate the filter values (for example, based on a job variable), you can schedule a command-type or script-type job to run together with the reporting command, as in the following example:

Copy 
echo '{"filters": [
{"name":"Alert ID","value":"%%AlertID"}
]}' > filter.json |  ctm reporting report::get Alerts_1 csv -f filter.json

In this example, the first command creates the filter.json file, to be used by the reporting command as the configuration file, and the second command runs the reporting command.

The Alert ID is the filter whose value you want to override and %%AlertID is the predefined job variable.