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 and General System Settings.

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 and General System Settings.

CLI Syntax

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

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

Parameter

Description

systemsetting

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 -F '[email protected]' "$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"
    },
    "externalAlertTypes": {
       "value": "Alert"
    },
    "allowDuplicateJobNames": {
       "value": "false"
    },
    "allowDuplicateResourceNames": {
       "value": "false"
    },
    "additionalParameters": [
       {
          "name": "addOrphanEvents",
          "value": "2"
       },
       {
          "name": "loadOldEventsDays",
          "value": "7"
       }
    [
}

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:

  • Several parameters are defined at the highest level in the JSON. Many of the parameters in this group can also be configured through the Helix Control-M user interface, as described in Defining System Settings.

  • Many additional parameters are defined under the additionalParameters object. These system parameters are configurable only through Control-M Automation API.

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

(Deprecated) 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

(Deprecated) 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

externalAlertTypes

Sets the type of alerts to send to external tools:

  • Alert: Alerts that relate to job processing.

  • XAlert: System alerts (also known as exception alerts or xAlerts) for system failures in Control-M components and the Control-M communication network. This option is especially useful if you have self-hosted Control-M/Servers connected to Helix Control-M.

  • Alert|XAlert: Both types of alerts.

Default: Alerts

allowDuplicateJobNames

Determines 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

allowDuplicateResourceNames

Determines whether to allow a resource pool and lock resource to have the same name in a job. For such duplicate names, resources are structured as an array in the JSON code (see Resources).

Valid Values: true | false

Default: false

additionalParameters

Lists many additional system parameters in an array structure. Each system parameter is identified by its API parameter name, along with the parameter value.

These system parameters are configurable only through Control-M Automation API.

For more information about these additional parameters, see Additional System Parameters.

Additional System Parameters

The following table describes the additional system parameters that are configurable only through Control-M Automation API. These parameters are defined under the additionalParameters object.

Parameter

Description

handleAlertsOnRerun

Determines how to handle alerts when a job is rerun.

Valid Values:

  • 0: Alerts for this job that are in the Alerts window before the job is rerun are not automatically changed to HANDLED. If the rerun fails, a new alert is displayed in the Alerts window.

  • 1: Alerts for this job that are in the Alerts window before the job is rerun are automatically changed to HANDLED.

Default: 0

numberHandledAlarms

Defines the maximum number of handled alerts saved in the database (in addition to not-yet-handled alerts).

Valid Values: 0 (no maximum)-9999

Default: 2000

userAuditContext

Determines which activities are audited and recorded.

Valid Values:

  • ALL: All values listed below

  • NONE: None of the values listed below

  • AUTH: Authentication

  • SCHED: Scheduling definitions

  • J_CONT: Active network

  • J_INFO: Active job information

  • RES: Resources

  • ALERT: Alerts

  • ACCOUNT: Account management

  • HIGH_AVAIL: High Availability

Default: All values

userAudit

Determines whether activities specified by userAuditContext are recorded in the database.

Valid Values:

  • 0: Not recorded

  • 1: Recorded

Default: 1

userAuditAnnotation

Determines whether the user is required to enter details about the type of operation being performed and the reason for the operation.

Valid Values:

  • 0: Annotation not required

  • 1: Annotation required

Default: 1

annotationDefaultCategory

Determines the default value when an annotation description is missing.

Default: Utility

annotationDefaultNote

Determines the default value when an annotation note is missing.

Default: Command line utility invocation

auditAllDefinitionChanges

Determines whether to audit all changes to the job definition when it is updated.

Valid Values:

  • 0

  • 1

Default: 1 (Audits all changes when a job definition is updated)

auditCleanup

Determines whether cleanup of audit information from the database occurs automatically.

Valid Values:

  • 0: Cleanup is performed manually by the user as necessary.

  • 1: Cleanup is automatic.

Default: 1

auditHistoryDays

Determines the number of days that audit information is retained before being cleaned from the database (if cleanup is automatic).

Valid Values: 0 or more

Default: 90

alertOnJobFail

Determines whether alerts are sent for jobs that end Not OK.

Valid Values:

  • 0: Alerts are not created.

  • 1: Alerts are created.

Default: 1

alertOnJobFailUrgency

Determines the urgency level for Gateway alerts for jobs that end with the status Ended Not OK.

Valid Values:

  • Regular

  • Urgent

  • Very Urgent

Default: Very Urgent

alertOnSmartFolderFail

Determines whether to create an alert for a SMART folder that ended Not OK.

Valid Values:

  • N: Alerts are not created.

  • Y: Alerts are created.

Default: N

alertOnDownloadJobFail

Determines whether to send alerts for downloaded jobs that end Not OK when they are run.

Note: This parameter is relevant only when alertOnJobFail is set to 1.

Valid Values:

  • 0: Alerts are not sent.

  • 1: Alerts are sent.

Default: 1

historyRetentionMax

Determines the number of downloads that can be stored in the database. If this number is exceeded, the oldest download is deleted.

Valid Values: 1–40

Default: 4

viewpointSmartFolderPolicy

Determines which SMART Folders are passed to the ViewPoint.

Valid Values:

  • SELECT_JOBS: Filtering criteria are applied only to the jobs. Only jobs satisfying the filtering criteria, and only SMART Folders containing at least one such job, are passed and displayed. (No empty folders are passed.)

  • SELECT_JOBS_AND_SG: Filtering criteria are applied both to jobs and SMART Folders. In addition to passing the same jobs and SMART Folders that are passed for the SELECT_JOBS value, the Server also passes any SMART Folders that match the filtering criteria (and pass the security criteria) even if they are empty.

Default: SELECT_JOBS_AND_SG

DefaultAverageTimeJobWithoutStatistics

Determines the default average run time for jobs with no statistics.

Valid Values: Any valid time in the MM:SS format.

Default: 00:05

useDoCondition

Determines whether to add conditions created by On Do Actions.

Valid Values:

  • 0: Do not add conditions

  • 1: Add only added conditions

  • 2: Add added and deleted conditions

Default: 1

dateFormat

Determines the format for dates displayed in SLA Management alert messages.

Valid Values: DD/MM and MM/DD.

Default: DD/MM

loadOldEventsDays

Defines the number of days of active conditions that SLA Management loads for service calculations.

Valid Values: Any integer, 1 or greater

Default: 7 days

addOrphanEvents

Determines whether to add external or orphan events.

Such events are events that are specified as Wait For events for jobs but will not exist at the time that Control‑M/Forecast generates its forecast. This may be because:

  • The job relies on an event from a previous day. (Forecasts are only generated for a specific day.)

  • The job relies on an event that has to be manually added or removed.

Valid Values:

  • 0: Do not add events.

  • 1: Add events at New Day.

  • 2: Events are added at the average start time of the first job waiting for the event.

Default: 2

executeConfirmedJobs

Enables you to execute jobs that are waiting for confirmation.

Valid Values:

  • 0: Do not execute jobs.

  • 1: Execute at New Day.

  • 2: Execute at the job’s average start time.

Default: 2

userInactivityTimeoutMinutes

Determines the maximum number minutes of inactivity before the user is automatically logged out of Helix Control-M.

Valid Values: 1–24

outputAutomaticLoadLimitBytes

Determines the size of the output (in bytes) that determines whether to send an output download confirmation message to the user.

This occurs when the user attempts to download an output.

Valid Values: 1–15728639 (15 MB)

Default: 1000000

jobPrimaryFieldInMonitoring

Determines the title of the job (primary field) in monitoring.

Valid Values:

  • JobNameMemName: JobName for Distributed jobs, MemName for Control-M for z/OS jobs)

  • JobName

  • MemName

Default: JobNameMemName

numberJobVersionsToKeep

Determines the number of versions of the job to keep, including the current version.

Valid Values: 1–100

Default: 2

defaultRunMethod

Determines the default run (order) method that is set when you create a new folder in a job flow.

Valid Values

  • Automatic: Ordered automatically.

  • None: Ordered manually.

  • Specific: Ordered according to a specific date and time.

Default: Automatic

approvedRequestsRetentionTimeDays

Determines the number of days to keep approved requests data in the Server database.

Valid Values: 1-28 days

Default: 14 days

enforceSiteStandardAdminOnly

Determines whether only a Control-M Administrator can enforce validations for a Site Standard in Folders.

Valid Values: true | false

Default: false

maxJobsInViewpoint

Determines the maximum number of jobs that can appear in the Jobs view.

When the number of jobs exceed its limitation, a warning message appears and you are prompted to select Simple Tile view.

Valid Values: 1-40,000

Default: 20,000

numberOfDaysToKeepMftRecords

Determines the number of days to keep records in MFT tables.

Valid Values: Any integer, 1 or greater

Default: 30

longFileTransfersMinimumMinutes

Determines the minimum number of minutes to wait for a file transfer before it is declared a long-running file transfer and added to the Long Running Transfers section in the MFT Dashboard.

Valid Values: 5–2880

Default: 15

slowFileTransfersThresholdInKbps

Determines a minimum file transfer speed, in kilobytes per second, under which a file transfer is declared a slow-running file transfer and added to the Slow Running Transfers section in the MFT Dashboard.

Valid Values: 5–131072

Default: 500

slowFileTransfersMinimumDurationSeconds

Determines the minimum file transfer duration, in seconds, for a file transfer to be included in the count of slow transfers in the MFT Dashboard (provided that the measured bitrate is also too low).

Valid Values: 5–172,800 (2 days)

Default: 10

enabledVaultProviders

Determines which Vault Providers are enabled.

Default: all

allowReferencePath

Determines whether to allow or prevent users from creating and modifying reference sub-folders.

Valid Values:

  • true: Allow creation or modification of reference sub-folders.

  • false: Do not allow creation or modification of reference sub-folders.

Default: true

checkDoForceJobAuthorizations

Determines whether to apply an order authorizations check on Do Force job statements when creating or modifying a job definition.

Valid Values: true|false

Default: true