Usage Report Service

The Usage Report service enables you to generate reports regarding the number of jobs that your organization has run during the year, per day or per month. These reports can be used for license auditing and compliance purposes. The reports are returned in JSON format.

You can choose between two types of reports:

  • Daily report — total number of jobs executed per day on each Helix Control-M tenant

  • Monthly report — total number of jobs executed per month and the daily average during the month, for each Helix Control-M tenant

The report includes all job runs that were submitted to an agent. For a cyclic job, all job executions are counted.

Jobs that are not submitted to an agent are not counted. The following are not counted as job executions in Helix Control-M:

  • Folder processing

  • Sub Folder processing

  • SLA Management (BIM) jobs

  • Dummy jobs or jobs set to “Run as dummy” (RunAsDummy=true)

The data for this report is updated once a day at 1:00 AM, Pacific Time.

CLI Syntax

Copy 
ctm usage report -s "<query string>"

-s is used to run a search using the query string format "field1=criteria1&field2=criteria2", with the following supported fields:

Field

Description

server

Defines the name of one server to limit results from.

reportBy

Determines the type of time period by which to aggregate the measurements.

Values:

  • day

  • month

Default: month

year

Defines the year to limit results from, in YYYY (four-digit) format.

Default: Current year

REST API Syntax

Example using curl:

Copy 
curl -H "x-api-key: $token" -X GET "$endpoint/usage/report?reportBy=day&year=2023"

Response

The following example shows a report based on monthly aggregation (that is, reportBy=month) from two Helix Control-M tenants. Besides the monthly total, the report also provides a daily average during each month.

This report was returned in response to the following API command: ctm usage report -s reportBy=month&year=2020

Copy 
{
    "organization": "acme",
    "year": "2020",
    "reportBy": "month",
    "usage": [
            {
                "tenantId": "acme-4800",
                        . . .
 
                "jun": {
                        "jobExecutions": {
                            "total": 56,
                            "dailyAverage": 10
                        }
                },
                "jul" :
                        "jobExecutions": {
                            "total": 25,
                            "dailyAverage": 12
                        }
                        . . .
 
                "totalExecutions": 1041
                     
            },
            {
                "tenantId": "acme-5519",
                        . . .
 
                "mar" :
                    {
                        "jobExecutions":
                            "total" : 600
                            "dailyAverage"  : 20
                    },
                "apr" :
                    {
                        "jobExecutions":
                            "total" : 600
                            "dailyAverage"  : 20
                    },
                        . . .
 
                "totalExecutions": 2071
            }
    ]
}

The following example shows a report based on daily aggregation (that is, reportBy=day) from two Helix Control-M tenants.

This report was returned in response to the following API command: ctm usage report -s reportBy=day&year=2020

Copy 
{
    "organization": "acme",
    "year": "2020",
    "reportBy": "daily",
    "usage": [
            {
                "tenantId": "acme-4812",
                        . . .
 
                "2020-06-14" : {
                    "jobExecutions" : 600
                 },
                        . . .
 
                "2020-03-12" : {
                    "jobExecutions" : 600
                 }
                        . . .
 
                "2020-11-02" : {
                    "jobExecutions" : 600
                 }
 
                . . .
 
                "totalExecutions": 10410
            },
            {
                "tenantId": "acme-2212",
                        . . .
 
                "2020-03-21" : {
                    "jobExecutions" : 200
                 },
 
                . . .
 
                "2020-07-12" : {
                    "jobExecutions" : 600
                 }
 
                        . . .
 
                "2020-12-31" : {
                    "jobExecutions" : 6020
                 }
                        . . .
 
                "totalExecutions": 12041
            }
    ]
}