System Settings Configuration

The following API commands enable you to configure system parameters and system settings:

config systemsettings::get

The config systemsettings::get command enables you to get details of general system settings.

The output is returned in JSON format. You can use this output as a template when you use the config systemsettings::set command to set new values for general system settings.

For more information about the available settings and their JSON syntax, see System Settings File.

CLI Syntax

Copy 
ctm config systemsettings::get [-s "server=<serverName>"]

The optional -s swtich can be used to filter by name of server.

REST API Syntax

cURL:

Copy 
server=IN01
curl -H "x-api-key: $token" "$endpoint/config/systemsettings"?server=$serverName

config systemsettings::set

The config systemsettings::set command enables you too modify general system settings based on definitions that you provide through a JSON file.

You can optionally use this API command to integrate your SAML2 identity provider (IdP) with Control-M to support Single Sign On (SSO) authentication.

In the .json file, you can choose to include only those system settings that you want to update. Any system settings that are not included in the .json file are not updated and remain untouched.

For full details about the available system settings and their JSON syntax, as returned by the config systemsettings::get command, see System Settings File.

CLI Syntax

Copy 
ctm config systemsettings::set <systemsetting.json> [saml2metadatafile] [server]

The following table describes the config systemsettings::set command parameters.

Parameter

Description

systemsetting.json

Full path and name of a .json payload file that contains details of system settings, as described in System Settings File.

saml2metadatafile

Full path and name of a SAML2 Metadata file, an .xml payload file that contains SAML2 IdP metadata.

To provide the SAML2 IdP metadata through an .xml payload file, ensure that you have set the MetadataUrl property in the .json payload file to metadata.

For information about the steps involved in integrating your SAML2 IdP with Control-M to support Single Sign On (SSO) authentication, see System Settings File.

server

Name of Server

REST API Syntax

cURL:

Copy 
serverName=IN01
curl -H "x-api-key: $token" -X POST "$endpoint/config/systemsettings?server=$serverName

config systemsettings:identityprovidermetadata::get

The config systemsettings:identityprovidermetadata::get command enables you to get metadata from the SAML2 IdP that you integrated with Control-M. The output is SAML2 metadata in XML format.

For information about the steps involved in integrating your SAML2 IdP with Control-M to support Single Sign On (SSO) authentication (prior to running this API command), see Steps for Enabling a SAML2 IdP.

CLI Syntax

Copy 
ctm config systemsetting:identityprovidermetadata::get

REST API Syntax

cURL:

Copy 
server=IN01
curl -H "x-api-key: $token" "$endpoint/config/systemsettings/identityprovidermetadata"

System Settings File

The following code sample shows the system settings that you can include within payload JSON files that are involved in the configuration of system settings. Details about each of these system settings are provided below.

Copy 
{
    "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": "false"
    }
}

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 table describes the Saml2IdentityProvider property parameters.

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

After you enable the SAML2 IdP, certain user authorization management actions (discussed in User Configuration) 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:

  1. Obtain values for the two properties that pertain to the internal IdP in Control-M — singleSignOnUrland entityID — by running the config systemsettings::get API command.

  2. Obtain SAML2 metadata from your SAML2 IdP, either as a URL or as an XML file.

  3. 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.

  4. 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 describes the available parameters:

Property

Description

historyRetentionDays

Number of days to save historical job processing data.

Valid Values: 1–14 days.

Default: 4

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.

Default: 0000 (midnight)

  • 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 10 February, 5:59 AM is considered part of the 9 February work day.

  • If you use -2200, the hours between 10 PM and midnight are considered part of the next date’s work day. Thus, at 10:00 PM on system date 10 February, the Control‑M date changes to 11 February.

firstDayOfTheWeek

Day on which the work week starts at your site, expressed using the full name of the day.

Default: Monday

environmentBannerColor

The background color of the on-screen title banner for your environments, which helps differentiate between development and production environments.

Valid Values:

  • none

  • blue

  • gray

  • green

  • orange

  • pink

  • purple

  • red

  • teal

  • yellow

Default: none

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

Default: 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.

Valid Values: true | false

Default: false

strictnesslevel

The level of strictness for folder validation.

Valid Values:

  • non-strict

  • 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.

Valid Values: true | false

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.

Valid Values: true | false

Default: false