System Settings reference

This page provides information for creating or reviewing payload JSON files that are involved in the configuration of system settings.

The following code sample shows the system settings that you can include within such a file. The rest of this page provides details about each of these system settings.

{
    "saml2IdentityProvider": // SAML Parameters
    {
        "serviceProviderInformation": // SAML Configuration parameters for your environment (e.g. Okta)
        {
            "singleSignOnUrl": "https://tenant_name.auth.us-west-2.amazoncognito.com/Saml2/idpresponse",  // Signin URL                                       
            "entityID": "urn:amazon:cognito:sp:us-west-2_XqOgd0twY"                                       // Cognito ID
        },                           
       "metadataUrl":"metadata" OR "http://jj.okta.com/.../metadata",   // SAML metadata file/url set to Cognito
       "enabled": "true/false", // is the identity provider enabled
    },
    "historyRetentionDays": {
       "value": "4"
    },
    "newDayTime": {
       "value": "+0600"
    },
    "firstDayOfTheWeek": {
       "value": "wednesday"
    },
    "environmentBannerColor": {
       "value": "blue"
    },
    "environmentTitle": {
       "value": "test title"
    },
    "environmentDescription": {
       "value": "test desc"
    },
	"siteInterfaceLanguage": {
       "value": "english"
 	},     
	"enforceSiteStandards": {
       "value": "true"
    },
    "strictnesslevel": {
       "value": "non-strict"
    },
    "annotations": [
       "Authentication",
       "Account management"
    ],
	"privacyNoticeURL": {
       "value": "myURL"
    },
    "enableExternalAlerts": {
       "value": "true"
    },
	"allowDuplicateJobNames":{
	   "value": "true"
	}
}

SAML2 Identity Provider settings

The first element in the JSON list of system settings, Saml2IdentityProvider, focuses on settings for integration of a SAML2 identity provider (IdP) with Control-M. The following properties are included:

Property	Description
serviceProviderInformation	Attributes generated by Control-M for enabling integration with a SAML2 IdP.
singleSignOnUrl	URL for single sign-on, where SAML2 assertions are sent by the internal IdP in Helix Control-M You obtain this property value by running the config systemsettings::get API command.
entityID	An ID that dictates the entity or audience for SAML2 assertions for the internal IdP in Helix Control-M You obtain this property value by running the config systemsettings::get API command.
metadataUrl	Points to the location of SAML2 metadata that you obtained from your identity provider. You can choose from the following options: A URL that points to the metadata The constant value metadata enables you to provide metadata as an XML payload file through the config systemsettings::set API command.
enabled	Whether the SAML2 IdP is enabled in your environment, either true or false Note: After you enable the SAML2 IdP, certain user authorization management actions are no longer relevant and cannot be performed. These include adding, updating, or deleting a user, as well as getting user details.

Steps for enabling a SAML2 IdP

A typical end-to-end process for enabling a SAML2 IdP consists of the following steps:

Obtain values for the two properties that pertain to the internal IdP in Helix Control-M — singleSignOnUrl and entityID — by running the config systemsettings::get API command.
Obtain SAML2 metadata from your SAML2 IdP, either as a URL or as an XML file.
Use the output from step 1 as a template for creation of a System Settings .json file.
In the same file, set the metadataUrl property to the relevant value (from step 2) and the enabled property to true.
Run the config systemsettings::set API command and provide the System Settings .json file (that you prepared in step 3) as a payload file for this API command.
If you set the metadataUrl property in the .json file to metadata, you must also provide a SAML2 Metadata file in XML format.

After completing this setup, if at any point you want to review the SAML2 metadata from your SAML2 IdP, you can run the config systemsettings:identityprovidermetadata::get API command.

General system settings

A variety of general system settings are included in the JSON list. The following table summarizes and describes the available properties:

Property	Description
historyRetentionDays	Number of days to save historical job processing data. Range of values: 1–14 days Default: 4 days
newDayTime	Start-of-day time when the date changes and a new day begins in Control-M for the purposes of job processing. Values are expressed as the number of hours before or after midnight: -hhmm — number of hours before midnight +hhmm — number of hours after midnight Note that only the number of hours (hh) is taken into account. The number of minutes (mm) is ignored. The default is 0000 (midnight). Examples: If you use +0600, the hours between midnight and 6:00 AM are considered part of the previous date’s work day. Thus, system date February 10, 5:59 AM is considered part of the February 9 work day. If you use -2200, the hours between 10 P.M. and midnight are considered part of the next date’s work day. Thus, at 10:00 P.M. on system date February 10, the Control‑M date changes to February 11.
firstDayOfTheWeek	Day on which the work week starts at your site, expressed using the full name of the day. The default is Monday.
environmentBannerColor	The background color of the on-screen title banner for your environments, which helps differentiate between development and production environments.. Choose one of the following options: none (default) blue gray green orange pink purple red teal yellow
environmentTitle	The name of the environment to be displayed on-screen in the title banner, up to 255 characters. The default is the environment's host name.
environmentDescription	A textual description for the environment, up to 255 characters.
siteInterfaceLanguage	An administrator setting that defines the user interface language for new users. Valid values: English German Spanish French The default is English. The following appears in English only: Login and logout pages Control-M Application Integrator Control-M Reports Job logs Messages sent by the Server
enforceSiteStandards	Whether to enforce validation of folders based on Site Standards, either true or false. Default: false
strictnesslevel	The level of strictness for folder validation, either non-strict or strict. Default: non-strict
annotations	Categories of user actions for which to demand annotations (that is, a note that justifies the action). You can specify any number of the following categories: Authentication Scheduling definitions Active Job Operations Active Job Information Active Job Prerequisites Alerts handling Account management Component operations Configuration management Security By default, annotations are not required for any category of actions.
privacyNoticeURL	Sets a URL address that contains your company Privacy Notice. Typically used to meet GDPR requirements. By default, no URL is set.
enableExternalAlerts	Whether to enable listening for alerts from Helix Control-M and sending them to external tools. For more information, see Setting Up External Alerts. Default: false
allowDuplicateJobNames	Whether to allow more than one job to bear the same name. When you have multiple jobs with the same name, job definitions in the JSON code are structured as an array. For examples of the job array structure, see the examples in Folders and Flows. Default: false

System Settings reference

SAML2 Identity Provider settings

Steps for enabling a SAML2 IdP

General system settings

Comments