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

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:

REST API Syntax

See REST API reference.

Example using curl:

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

{
    "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

{
    "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
            }
    ]
}