Role data for authorization configuration

This page provides information for creating role data files, that is, payload JSON files that you can submit when you configure role authorizations.

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.

{
    "Name": "AdminRole",
    "Description": "Administration role",   
    "AllowedJobs": {
        "Included": [
           [["FileName", "like", "a*"], ["JobType", "eq", "Job,Command"]],
           [["FileName", "like", "b*"], ["JobType", "eq", "Job,Command"]]
        ],
        "Excluded": [
           [["FileName", "like", "c*"], ["JobType", "eq", "Job,Command"]],
           [["FileName", "like", "d*"], ["JobType", "eq", "Job,Command"]]
        ]
    },
    "AllowedJobActions": {
        "ViewProperties": true,
        "SetToOk": true,
        "Documentation": true,
        "Confirm": true,
        "Log": true
    },
    "Privileges": {
        "ClientAccess": {
           "WorkloadChangeManagerAccess": "Full",
           "ApplicationIntegratorAccess": "None"
           },
        "ConfigurationManager": {
           "Authorization": "Browse",
           "ControlmSecurity": "Update"
           }   
    },
    "Folders": [{
        "Privilege": "Full",
        "ControlmServer":  "aaa*",
        "Library": "bbb*",
        "Folder": "ccc*",
        "Order": true,
        "Jobs": {
            "Privilege": "Full",
            "Application": "aaa*",
            "SubApplication": "bbb*"
        }
    }],
    "Calendars": [{
        "Privilege": "Full",
        "ControlmServer": "aaa*",
        "Name": "bbb*"
    }],
    "RunasUsers": [{
        "ControlmServer": "aaa*",
        "RunasUser": "aaa*",
        "Host": "bbb*"
    }],
    "WorkloadPolicies": [{
        "Privilege": "Full",
        "Name": "*"
    }],
    "SiteStandard": [{
        "Privilege": "Full",
        "Name": "*"
    }],
    "SiteCustomization": [{
        "Privilege": "Full",
        "Name": "*"
    }],
    "Services": [{
        "Privilege": "Full",
        "Name": "*",
        "AllowedActions":
            {"DrillDown": true,
            "Run": true,
            "Hold": true,
            "Resume": true,
            "ViewOrderableService": true}
    }],
    "Events": [{
        "Privilege": "Full",
        "ControlmServer": "aaa*",
        "Name": "*"
    }],
    "Mutexes": [{
        "Privilege": "Full",
        "ControlmServer": "aaa*",
        "Name": "*"
    }],
    "Semaphores": [{
        "Privilege": "Full",
        "ControlmServer": "aaa*",
        "Name": "*"
    }],
    "GlobalEvents": [{
        "Privilege": "Full",
        "Name": "*"
    }]
}

General role settings

The role file contains the following general properties for the role that you are defining:

PropertyDescription
NameA unique name for the role (required property)
DescriptionAn optional textual description of the role

For example:

    "Name": "AdminRole",
    "Description": "Administration role",

AllowedJobs

Grants the role browse access to the output of jobs that you specify using include/exclude filters.

    "AllowedJobs": {
        "Included": [
           [["FileName", "like", "a*"], ["JobType", "eq", "Job,Command"]],
           [["FileName", "like", "b*"], ["JobType", "eq", "job,command"}],
        ]
        "Excluded": [
           [["FileName", "like", "c*"], ["JobType", "eq", "Job,Command"]],
           [["FileName", "like", "d*"], ["JobType", "eq", "Job,Command"}],
        ]
    }

Under the AllowedJobs object, you define job authorizations:

  • The Included object lists filters for jobs that the role is authorized to access.
  • The Excluded object lists filters for jobs that the role is NOT authorized to access.

In each of these lists, you can include one or more filters. An implied OR logical operator connects between the various filters.

Each filter can include multiple conditions, with an implied AND logical operator connecting between the conditions. A condition is a pattern-matching expression that detects jobs according to a specific job property. A condition has the following format:

["jobProperty", "operator", "value"]

The following table provides guidelines for specifying the various elements within the filter condition:

Job propertyOperatorValue

The following properties are available:

  • Application
  • ApplicationType
  • Command
  • ControlmServer
  • Critical
  • Cyclic
  • Description
  • EmbeddedScript
  • FileName
  • FilePath
  • Folder
  • Host
  • Jobname
  • JobType
  • NjeNode
  • OrderDate
  • Rba
  • Runas
  • SubApplication

Choose one of the following:

  • eq (equals)
  • ne (does not equal)
  • ge (greater than or equals)
  • le (less than or equals)
  • like

Specify a value appropriate for the property:

  • For most properties, provide any string.
    For multiple values, you can use commas (,).
    If using the like operator, you can also use wildcards (* or ?).
  • The following properties call for a Boolean value, either true or false. The default is false.
    • Critical
    • Cyclic
    • EmbeddedScript
  • For the JobType property, specify one or more of the following values:
    • Job
    • Task
    • SmartFolder
    • Detached
    • Command
    • Dummy

AllowedJobActions

Authorizes the role to perform specific actions (browse actions, control actions, or update actions) on the jobs filtered through the AllowedJobs object and the folders specified through the Folders object.

    "AllowedJobActions": {
        "ViewProperties": true,
        "SetToOk": true, 
        "Documentation": true, 
        "Confirm": true,
        "Log": true 
    }

Under the AllowedJobsActions object, you define which job actions the role is authorized to perform. Each action is set to either true (allowed) or false (not allowed). The default is false.

The following table lists all available job actions. For your convenience, the actions in this table are divided into three categories — Browse actions, Control actions, and Update actions.

Browse actionsControl actionsUpdate actions
  • Documentation
  • Log
  • ViewProperties
  • Statistics
  • ViewJcl
  • ViewOutputList
  • Why
  • Bypass
  • Confirm
  • Free
  • Hold
  • Kill
  • React
  • Rerun
  • Restart
  • Delete
  • EditJcl
  • EditProperties
  • SetToOk
  • Undelete

Privileges

Grants the role access to various Control-M components, utilities, and tools, and authorizes the role to perform actions through these tools based on the defined access levels.

    "Privileges": {
        "ClientAccess" {
           "ConfigurationManagerAccess": "Full",
           "ApplicationIntegratorAccess": "None",
	       },
        "ConfigurationManager" {
		   "Authorization": "Browse",
		   "ControlmSecurity": "Update",
           } 	
    }

Under the Privileges object, various Control-M features and capabilities are categorized and grouped together under the following next-level objects:

  • ClientAccess
  • ConfigurationManager
  • Monitoring
  • Planning
  • Tools
  • ViewpointManager

The following table lists all the Control-M features and capabilities in these categories, and provides details of the authorization levels that are available for each feature. The default authorization for all features is None.

Control-M feature
(divided by category)
DescriptionAvailable authorizations
FullUpdateBrowseNone
ClientAccess
SelfServiceAccessAccess Control-M Self Service(tick)(error)(error)(tick)
WorkloadChangeManagerAccessAccess Control-M Workload Change Manager(tick)(error)(error)(tick)
UtilitiesAccessAccess Control-M/Server utilities, Control-M/EM API, and the Control-M Batch Impact Manager Web UI(tick)(error)(error)(tick)
ApplicationIntegratorAccessAccess to Control-M Application Integrator(tick)(error)(error)(tick)
ConfigurationManager
AuthorizationManage authorizations(tick)(tick)(tick)(tick)
ConfigurationManagerAccessAccess Control-M Configuration Manager(tick)(error)(error)(tick)
ConfigurationManage configurations(tick)(tick)(tick)(tick)
OperationManage operations(tick)(tick)(error)(tick)
DatabasePerform database maintenance(tick)(error)(tick)(tick)
ControlmSecurityManage Control-M security(tick)(tick)(tick)(tick)
Monitoring
AlertManage alerts(tick)(tick)(tick)(tick)
ViewpointArchiveManage archived Viewpoints(tick)(error)(error)(tick)
Planning
PeriodicalStatisticsManage periodical statistics(tick)(error)(tick)(tick)
ForecastOrBatchImpactManagerConfigConfigure Control-M/Forecast and Control-M Batch Impact Manager(tick)(tick)(tick)(tick)
PromotionRulesManage promotion rules(tick)(error)(error)(tick)
PromoteActionManage promotion actions(tick)(tick)(error)(tick)
Tools
CliAccess command line tools(tick)(error)(error)(tick)
BatchImpactManagerReportGenerate and view Control-M Batch Impact Manager reports(tick)(error)(error)(tick)
ForecastReportGenerate and view Control-M/Forecast reports(tick)(error)(error)(tick)
ViewpointManager
CollectionsManage Viewpoint collections(tick)(tick)(tick)(tick)
HierarchiesManage Viewpoint hierarchies(tick)(tick)(tick)(tick)
FiltersManage Viewpoint filters(tick)(tick)(tick)(tick)
ViewpointsManage Viewpoints(tick)(tick)(tick)(tick)

Folders

Grants the role access to specific folders, along with an authorization level for each folder. Also enables you to grant different authorizations per job within a specific folder based on Application or Sub Application criteria.

    "Folders": [{
        "Privilege": "Full", 
        "ControlmServer":  "aaa*",
        "Library": "bbb*",
        "Folder": "ccc*",
        "Order": true,
        "Jobs": {
            "Privilege": "Full",
            "Application": "aaa*",
            "SubApplication": "bbb*"
        },
    }]

The Folders object has the following properties:

PropertyDescription
Privilege

Level of authorization to assign for the specified folder (or folders) — Full, Update, or Browse

This property is required.

ControlmServer

Name of (one or more) Control-M/Server that processes jobs

Note: This property is optional if you specify a value for Library and/or Folder (the next two properties).

Library

Name of the library that contains the job folder

Note: This property is optional if you specify a value for ControlmServer and/or Folder (the previous and next properties).

Folder

Name of folder or folders

Note: This property is optional if you specify a value for ControlmServer and/or Library (the previous two properties).

Order

Whether the role is allowed to order the folder(s) and the jobs within it, either true or false

This setting is not dependent on the Privilege that you set for the role.

Jobs

Level of authorization to assign to specific jobs within a folder based on the jobs' Application or SubApplication criteria.

To specify authorizations on the job level, you must have Control-M Workload Change Manager installed.

       Privilege

Level of authorization to assign to the specified job(s) in the folder — Full, Update, or Browse

This property is required when you specify authorizations on the job level.

       Application

Name of an Application (logical grouping of jobs) that the job is associated with

Note: If this property is not defined, privileges are granted to jobs associated with the specified Sub-Application(s) (next property) within all Applications.

       SubApplication

Name of a Sub-Application (logical sub-grouping of jobs within an Application) that the job is associated with

Note: If this property is not defined, privileges are granted to jobs associated with all Sub-Applications within the specified Application(s) (previous property).

For properties that support multiple values (ControlmServer, Library, Folder, Application, and SubApplication), you can use commas (,) or wildcards (such as * or ?). For more information, see Pattern matching strings in the Control-M Online Help.

Calendars

Associates specific calendars in Control-M with the role, along with an authorization level for each calendar.

    "Calendars": [{
        "Privilege": "Full",
        "ControlmServer": "aaa*", 
        "Name": "bbb*"
    }]

The Calendars object has the following properties:

PropertyDescription
Privilege

Level of authorization to assign for the specified calendar (or calendars) — Full, Update, or Browse

This property is required.

ControlmServer

Name of (one or more) Control-M/Server that processes jobs

Note: If this property is not defined, privileges are granted for the specified calendar (next property) on all Control-M/Servers in the environment.

Name

Name of calendar or calendars

Note: If this property is not defined, privileges are granted for all calendars on the specified Control-M/Server (previous property).

For properties that support multiple values (ControlmServer and Name), you can use commas (,) or wildcards (such as * or ?). For more information, see Pattern matching strings in the Control-M Online Help.

RunasUsers

Associates "run as" users with the role, for running jobs on a Control-M/Agent.

Note: For a role's RunasUser definitions to take effect on jobs in a folder, the same role must be granted sufficient folder privileges — either Full or Update privileges must be granted to the relevant folders.

    "RunasUsers": [{
        "ControlmServer": "aaa*",
        "RunasUser": "aaa*",
        "Host": "bbb*"
    }]

The RunasUsers object has the following properties:

PropertyDescription
ControlmServer

Name of (one or more) Control-M/Server that processes jobs

RunasUser

Name of "run as" user(s) to be granted authorization to execute jobs

HostName of a Control-M/Agent computer, remote host computer, or host group where jobs are submitted

You must define at least one of these properties. Once one property is defined, the implied value for any other undefined property is "*".

For multiple values in any of these properties, you can use commas (,) or wildcards (such as * or ?).

You might also want to specify values to be excluded. For example, to exclude user names root or Oracle, you can specify the following string:
"RunasUser": "!(root|Oracle)"

For more information, see Pattern matching strings in the Control-M Online Help.

WorkloadPolicies

Associates specific Workload Policies in Control-M with the role, along with an authorization level for each Workload Policy.

Workload policies are groups of jobs that you define for the purpose of balancing the workload and limiting resources used by jobs.

    "WorkloadPolicies": [{
        "Privilege": "Full",
        "Name": "*"
    }]

The WorkloadPolicies object has the following properties. All parameters are required.

PropertyDescription
Privilege

Level of authorization to assign for the specified Workload Policy or Policies — Full, Update, or Browse

Name

Name of Workload Policy (or Workload Policies)

For multiple values, you can use commas (,) or wildcards (such as * or ?). See Pattern matching strings in the Control-M Online Help.

Note: If the Privilege property is set to Full, the Name property must be set to "*" (all Workload Policies).

SiteStandard

Associates specific Site Standards with the role, along with an authorization level for each one.

Site Standards are collections of settings that are applied to folders and jobs to ensure that web users follow organization standards.

    "SiteStandard": [{
        "Privilege": "Full",
        "Name": "*"
    }]

The SiteStandard object has the following properties. All parameters are required.

PropertyDescription
Privilege

Level of authorization to assign for the specified site standard(s) — Full, Update, or Browse

Name

Name of site standard(s)

For multiple values, you can use commas (,) or wildcards (such as * or ?). See Pattern matching strings in the Control-M Online Help.

SiteCustomization

Associates specific Site Customizations with the role, along with an authorization level for each one.

Site Customizations are collections of settings that are applied to jobs to limit web users' access to job properties or to restrict the types of jobs that web users can create.

    "SiteCustomization": [{
        "Privilege": "Full",
        "Name": "*"
    }]

The SiteCustomization object has the following properties. All parameters are required.

PropertyDescription
PrivilegeLevel of authorization to assign for the specified site customization(s) — Full, Update, or Browse
Name

Name of site customization(s)

For multiple values, you can use commas (,) or wildcards (such as * or ?). See Pattern matching strings in the Control-M Online Help.

Services

Grants the role authorization to view services and to perform job actions, order, hold, and release services.

A service is a group of jobs that are aggregated based on various job filtering criteria.

    "Services": [{
        "Privilege": "Full",
        "Name": "*",
        "AllowedActions":
            {"DrillDown": true, 
            "Run": true, 
            "Hold": true, 
            "Resume": true, 
            "ViewOrderableService": true}
    }]

The Services object has the following properties:

PropertyDescription
Privilege

Level of authorization to assign for the specified service(s) — Full, Update, Browse, or None

This property is required.

Name

Name of service(s)

For multiple values, you can use commas (,) or wildcards (such as * or ?). See Pattern matching strings in the Control-M Online Help.

This property is required.

AllowedActions

Actions that the role is authorized to perform on the service(s)

Specify each action as a next-level property, and set it to a Boolean value — either true or false.

Note: If this property is not defined, all actions are set to a default of false.

You can specify any of the following actions:

  • DrillDown – Drill down to view jobs
  • Run – Order a service and run its jobs
  • Hold – Hold a service, that is, stop jobs from running
  • Resume – Release the service and resume job running
  • ViewOrderableService – View orderable services that were started by other users

Events

Grants the role authorization to manage events, by associating specific events with the role and assigning an authorization level to each one.

    "Events": [{
        "Privilege": "Full",
        "ControlmServer": "aaa*",
        "Name": "*"
    }]

The Events object has the following properties:

PropertyDescription
Privilege

Level of authorization to assign for the specified event(s) — Full, Update, or Browse

This property is required.

ControlmServer

Name of (one or more) Control-M/Server that processes jobs

Note: If this property is not defined, privileges are granted for the specified event (next property) on all Control-M/Servers in the environment.

Name

Name of event(s)

Note: If this property is not defined, privileges are granted for all events on the specified Control-M/Server (previous property).

For properties that support multiple values (ControlmServer and Name), you can use commas (,) or wildcards (such as * or ?). For more information, see Pattern matching strings in the Control-M Online Help.

Mutexes

Grants the role authorization to manage mutexes (also known as control resources), by associating specific mutexes with the role and assigning an authorization level to each one.

    "Mutexes": [{
        "Privilege": "Full",
        "ControlmServer": "aaa*",
        "Name": "*"
    }]

The Mutexes object has the following properties:

PropertyDescription
Privilege

Level of authorization to assign for the specified mutex (or mutexes) — Full, Update, or Browse

This property is required.

ControlmServer

Name of (one or more) Control-M/Server that processes jobs

Note: If this property is not defined, privileges are granted for the specified mutex (next property) on all Control-M/Servers in the environment.

Name

Name of mutex or mutexes

Note: If this property is not defined, privileges are granted for all mutexes on the specified Control-M/Server (previous property).

For properties that support multiple values (ControlmServer and Name), you can use commas (,) or wildcards (such as * or ?). For more information, see Pattern matching strings in the Control-M Online Help.

Semaphores

Grants the role authorization to manage semaphores (also known as quantitative resources), by associating specific semaphores with the role and assigning an authorization level to each one.

    "Semaphores": [{
        "Privilege": "Full",
        "ControlmServer": "aaa*",
        "Name": "*"
    }]

The Semaphores object has the following properties:

PropertyDescription
Privilege

Level of authorization to assign for the specified semaphore (or semaphores) — Full, Update, or Browse

This property is required.

ControlmServer

Name of (one or more) Control-M/Server that processes jobs

Note: If this property is not defined, privileges are granted for the specified semaphore (next property) on all Control-M/Servers in the environment.

Name

Name of semaphore or semaphores

Note: If this property is not defined, privileges are granted for all semaphores on the specified Control-M/Server (previous property).

For properties that support multiple values (ControlmServer and Name), you can use commas (,) or wildcards (such as * or ?). For more information, see Pattern matching strings in the Control-M Online Help.

GlobalEvents

Grant the role authorization to manage global events, by associating specific global events with the role and assigning an authorization level to each one.

    "GlobalEvents": [{
        "Privilege": "Full",
        "Name": "*",
    }]

The GlobalEvents object has the following properties. All parameters are required.

PropertyDescription
PrivilegeLevel of authorization to assign for the specified global event(s) — Full, Update, or Browse
Name

Name of global event(s)

For multiple values, you can use commas (,) or wildcards (such as * or ?). See Pattern matching strings in the Control-M Online Help.

Was this page helpful? Yes No Submitting... Thank you

Comments