Configuring role authorizations

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",
   "OrganizationGroups": ["idp1", "idp2"],
   "OrganizationUsers": ["usr1", "usr2"],
   "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": {
          "ControlmWebClientAccess": "Full",
          "ApplicationIntegratorAccess": "None"
           },
       "ConfigurationManager": {
          "Authorization": "Browse",
          "ControlmSecurity": "Update"
           }
    },
   "Folders": [{
       "Privilege": "Full",
       "ControlmServer": "aaa*",
       "Library": "bbb*",
       "Folder": "ccc*",
       "Run": 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": "*"
    }],
   "Locks": [{
       "Privilege": "Full",
       "ControlmServer": "aaa*",
       "Name": "*"
    }],
   "Pools": [{
       "Privilege": "Full",
       "ControlmServer": "aaa*",
       "Name": "*"
    }],
   "GlobalEvents": [{
       "Privilege": "Full",
       "Name": "*"
    }],
   "AgentManagement": [
      {
       "ControlmServer": "ctm3",
       "Agent": "agent3",
       "Privilege": "Browse"
      },
      {
       "ControlmServer": "ctm4",
       "Agent": "agent4",
       "Privilege": "Update"
      }
    ],
   "PluginManagement": [
      {
       "ControlmServer": "ctm3",
       "Agent": "agent3",
       "PluginType": "SAP*",
       "Privilege": "Browse"
      },
      {
       "ControlmServer": "ctm4",
       "Agent": "agent4",
       "PluginType": "OEBS",
       "Privilege": "Update"
      }
    ],
   "ConnectionProfileManagement": [
      {
       "ControlmServer": "ctm3",
       "Agent": "agent3",
       "PluginType": "SAP*",
       "Name": "cpp3*",
       "Privilege": "Browse"
      },
      {
       "ControlmServer": "ctm4",
       "Agent": "agent4",
       "PluginType": "OEBS",
       "Name": "cpp4*",
       "Privilege": "Update"
      }
    ],
   "RunasDefinitionManagement": [
      {
       "ControlmServer": "br*",
       "Privilege": "Browse"
      },
      {
       "ControlmServer": "up*",
       "Privilege": "Update"
      }
    ]
}

General role settings

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

Property	Description
Name	A unique name for the role (required property)
Description	An optional textual description of the role
OrganizationGroups	A list of organization groups (such as LDAP groups or IdP groups) with which the role is associated
OrganizationUsers	A list of organization users (such as LDAP users or IdP users) with which the role is associated

For example:

    "Name": "AdminRole",
   "Description": "Administration role",
   "OrganizationGroups: ["idp1", "idp2"],
    "OrganizationUsers": ["usr1", "usr2"],

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 property	Operator	Value
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 actions	Control actions	Update 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": {
          "ControlmWebClientAccess": "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)	Description	Available authorizations
Control-M feature (divided by category)	Description	Full	Update	Browse	None
ClientAccess
ControlmWebClientAccess	Access Control-M Web Client	✅️	❌️	❌️	✅️
SelfServiceAccess	Access Control-M Self Service **(Deprecated; replaced by ControlmWebClientAccess)**	✅️	❌️	❌️	✅️
WorkloadChangeManagerAccess	Access Control-M Workload Change Manager **(Deprecated; replaced by ControlmWebClientAccess)**	✅️	❌️	❌️	✅️
UtilitiesAccess	Access Control-M/Server utilities, Control-M/EM API, and the Control-M Batch Impact Manager Web UI	✅️	❌️	❌️	✅️
ApplicationIntegratorAccess	Access to Control-M Application Integrator	✅️	❌️	❌️	✅️
AutomationAPIAccess	Access to Control-M Automation API	✅️	❌️	❌️	✅️
ConfigurationManager
Authorization	Manage authorizations	✅️	✅️	✅️	✅️
ConfigurationManagerAccess	Access Control-M Configuration Manager	✅️	❌️	❌️	✅️
Configuration	Manage configurations	✅️	✅️	✅️	✅️
Operation	Manage operations	✅️	✅️	❌️	✅️
Database	Perform database maintenance	✅️	❌️	✅️	✅️
ControlmSecurity	Manage Control-M security	✅️	✅️	✅️	✅️
Monitoring
Alert	Manage alerts	✅️	✅️	✅️	✅️
ViewpointArchive	Manage archived Viewpoints	✅️	❌️	❌️	✅️
Planning
PeriodicalStatistics	Manage periodical statistics	✅️	❌️	✅️	✅️
ForecastOrBatchImpactManagerConfig	Configure Control-M/Forecast and Control-M Batch Impact Manager	✅️	✅️	✅️	✅️
PromotionRules	Manage promotion rules	✅️	❌️	❌️	✅️
PromoteAction	Manage promotion actions	✅️	✅️	❌️	✅️
Tools
Cli	Access command line tools	✅️	❌️	❌️	✅️
BatchImpactManagerReport	Generate and view Control-M Batch Impact Manager reports	✅️	❌️	❌️	✅️
ControlMReports	Generate and view Control-M Reports	✅️	❌️	❌️	✅️
ForecastReport	Generate and view Control-M/Forecast reports *(Deprecated; replaced by* *ControlMReports* )	✅️	✅️	✅️	✅️
ViewpointManager
Collections	Manage Viewpoint collections	✅️	✅️	✅️	✅️
Hierarchies	Manage Viewpoint hierarchies	✅️	✅️	✅️	✅️
Filters	Manage Viewpoint filters	✅️	✅️	✅️	✅️
Viewpoints	Manage Viewpoints	✅️	✅️	✅️	✅️

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*",
       "Run": true,
       "Jobs": {
           "Privilege": "Full",
           "Application": "aaa*",
           "SubApplication": "bbb*"
        }
    }]

The Folders object has the following properties:

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:

Property	Description
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:

Property	Description
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
Host	Name 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.

Property	Description
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.

Property	Description
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.

Property	Description
Privilege	Level 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:

Property	Description
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:

Property	Description
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).

Locks

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

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

The Locks object has the following properties:

Property	Description
Privilege	Level of authorization to assign for the specified lock (or locks) — 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 lock (next property) on all Control-M/Servers in the environment.
Name	Name of lock or locks Note: If this property is not defined, privileges are granted for all locks on the specified Control-M/Server (previous property).

Pools

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

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

The Pools object has the following properties:

Property	Description
Privilege	Level of authorization to assign for the specified pool (or pools — 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 pool (next property) on all Control-M/Servers in the environment.
Name	Name of pool or pools Note: If this property is not defined, privileges are granted for all pools on the specified Control-M/Server (previous property).

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.

Property	Description
Privilege	Level 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.

AgentManagement

9.0.20.000 Grants the role authorization to manage agents and perform administrative tasks on agents (such as connect a Control-M/Agent to a Control-M/Server or configure agent parameters).

This object is used in Role-Based Administration (RBA), enabling an administrator to grant non-administrator roles permission to perform certain administrative tasks. This feature is offered in an environment with Control-M 9.0.20 or later.

    "AgentManagement": [
      {
       "ControlmServer": "ctm3",
       "Agent": "agent3",
       "Privilege": "Browse"
      },
      {
       "ControlmServer": "ctm4",
       "Agent": "agent4",
       "Privilege": "Update"
      }
    ]

Under the AgentManagement object, each specified Control-M/Agent has the following properties:

Property	Description
ControlmServer	Name of a Control-M/Server that is associated with the Control-M/Agent
Agent	The tag associated with the Control-M/Agent to which this role is granted access
Privilege	Level of authorization to assign for the specified Control-M/Agent — Full, Update, or Browse

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

PluginManagement

9.0.20.000 Grants the role authorization to manage Control-M plugins and perform administrative tasks on plugins (such as plugin configuration).

    "PluginManagement": [
      {
       "ControlmServer": "ctm3",
       "Agent": "agent3",
       "PluginType": "SAP*",
       "Privilege": "Browse"
      },
      {
       "ControlmServer": "ctm4",
       "Agent": "agent4",
       "PluginType": "OEBS",
       "Privilege": "Update"
      }
    ]

Under the PluginManagement object, each specified plugin has the following properties:

Property

Description

ControlmServer

Name of a Control-M/Server that is associated with a Control-M/Agent

Agent

The tag associated with the Control-M/Agent to which this role is granted access

PluginType

The type of Control-M plugin that you have installed in your Control-M environment and to which this role is granted access

Click here for the list of PluginType values...

Plugin full name	PluginType value
Control-M Managed File Transfer	FILE_TRANS
Control-M for Databases	DATABASE
Control-M for Oracle E-Business Suite	OEBS
Control-M for PeopleSoft	PS8
Control-M for SAP	SAP
Control-M for SAP Business Objects	SAP_BO
Control-M for IBM Cognos	Cognos
Control-M for Informatica	ETL_INFA
Control-M for Hadoop	HADOOP
Control-M for Cloud
Control-M for VMware	VMware
Control-M for BladeLogic	BladeLogic
Control-M for Amazon EC2	AmazonEC2
Control-M for Java	JAVA
Control-M for Web Services	WS
Control-M for Messaging	MSG
Control-M for IBM InfoSphere DataStage	DataStage
Control-M for Backup	BACKUP
Control-M for SAP Process Integration	SAP_PI
Control-M Application Integrator	dynamic, dependent on user definitions
Control-M for AWS	AmazonEC2
Control-M for Azure	AZURE

For more information, see the list of available plugins in the Control-M documentation.

Privilege

Level of authorization to assign for the specified plugin — Full, Update, or Browse

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

ConnectionProfileManagement

9.0.20.000 Grants the role authorization to manage connection profiles and perform administrative tasks on connection profiles (such as create, update, or delete a connection profile).

    "ConnectionProfileManagement": [
      {
       "ControlmServer": "ctm3",
       "Agent": "agent3",
       "PluginType": "SAP*",
       "Name": "cpp3*",
       "Privilege": "Browse"
      },
      {
       "ControlmServer": "ctm4",
       "Agent": "agent4",
       "PluginType": "OEBS",
       "Name": "cpp4*",
       "Privilege": "Update"
      }
    ]

Under the ConnectionProfileManagement object, each specified connection profile has the following properties:

Property	Description
ControlmServer	Name of a Control-M/Server that is associated with a Control-M/Agent For a centralized connection profile, specify a value of "" (all* Control-M/Servers).
Agent	The tag associated with the Control-M/Agent to which this role is granted access For a centralized connection profile, specify a value of "" (all* agents).
PluginType	The type of Control-M plugin that you have installed in your Control-M environment and to which this role is granted access For a list of values, see the corresponding property under PluginManagement. For more information, see the list of available plugins in the Control-M documentation.
Name	Name or name pattern of the connection profile
Privilege	Level of authorization to assign for the specified connection profile — Full, Update, or Browse

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

RunasDefinitionManagement

9.0.20.000 Grants the role authorization to manage the configuration of "run as" users (that is, to perform administrative tasks such as create, update, or delete a "run as" user).

    "RunasDefinitionManagement": [
      {
       "ControlmServer": "br*",
       "Privilege": "Browse"
      },
      {
       "ControlmServer": "up*",
       "Privilege": "Update"
      }
    ]

Under the RunasDefinitionManagement object, each authorization has the following properties:

Property	Description
ControlmServer	Name of a Control-M/Server To specify a pattern, use an asterisk wildcard or any other supported character. See Pattern matching strings http://documents.bmc.com/supportu/9.0.21/help/Main_help/en-US/index.htm#14822.htmin the Control-M Online Help.
Privilege	Level of authorization to assign for configuration of "run as" users on this Control-M/Server — Full, Update, or Browse