Job Archiving Configuration

The config archive service enables you to manage the setup of Job Archiving (provided by the Control-M Workload Archiving add-on), manage the rules in Workload Archiving policies, and delete accumulated data from the Workload Archiving server. This feature is offered in an environment with Control-M 9.0.20 or higher.

For information about searching and retrieving archived data after performing the setup, see Archive Service.

The following API commands enable you to configure Job Archiving:

• config archive:rules::get

• config archive:statistics::get

• config archive:rule::add

• config archive:rule::update

• config archive:rule::delete

• config archive::cleanup

config archive:rules::get

The config archive:rules::get command enables you to get the details of all defined Workload Archiving policy rules.

The output is returned in JSON format. You can use this output as a template for your own Archive Rule files when creating new rules or editing existing rules. For more information about the syntax of Workload Archiving policy rules, see Archive Rule File.

CLI Syntax

ctm config archive:rules::get

REST API Syntax

AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" $endpoint/config/archive/rules

config archive:statistics::get

The config archive:statistics::get command enables you to get statistics regarding job archiving for all defined Workload Archiving policy rules.

CLI Syntax

ctm config archive:statistics::get

REST API Syntax

AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" $endpoint/config/archive/statistics

Response

{
  "rulesStatisticList": {
    "ruleStatistics": [
      {
        "ruleName": "Collect all DS jobs",
        "retention": 1,
        "retentionType": "Year",
        "oldestItem": "2019-01-28 12:29:01 PM",
        "newestItem": "2019-02-08 07:00:11 AM",
        "totalJobs": 30,
        "dataSize": "1 MB"
      }
    ]
  },
  "summary": {
    "totalNumberOfJobs": 30,
    "totalDataSize": "1 MB",
    "actualDbSize": "9 MB",
    "diskUsage": "37%"
  }
}

config archive:rule::add

The config archive:rule::add command enables you to create a new Workload Archiving policy rule based on rule settings that you define through an Archive Rule file.

CLI Syntax

ctm config archive:rule::add -f <archiveRule>

Where archiveRule is the full path and name of a .json payload file that contains definitions for the rule, as described in Archive Rule File.

If annotation is enabled for the Configuration Management category in the CCM, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST -H "Content-Type: application/json"
-d @ruleDefinition.json "$endpoint/config/archive/rule"

config archive:rule::update

The config archive:rule::update command enables you to update the definitions of an existing Workload Archiving policy rule based on rule settings that you define through an Archive Rule file.

CLI Syntax

ctm config archive:rule::update <ruleName> [-f <archiveRule>]

The following table describes the config archive:rule::update command parameters.

If annotation is enabled for the Configuration Management category in the CCM, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

ruleName=rule5
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST -H "Content-Type: application/json"
-d @ruleDefinition.json "$endpoint/config/archive/rule/$ruleName"

config archive:rule::delete

The config archive:rule::delete command enables you to delete an existing Workload Archiving policy rule.

CLI Syntax

ctm config archive:rule::delete <ruleName> <deleteRuleDataFlag>

The following table describes the config archive:rule::delete command parameters.

If annotation is enabled for the Configuration Management category in the CCM, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

ruleName=rule5
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" 
-X DELETE "$endpoint/config/archive/rule/$ruleName?deleteRuleDataFlag=deleteRuleWithoutData"

config archive::cleanup

The config archive::cleanup command enables you to delete job data (including job output and job logs) that has accumulated in the Workload Archiving server, based on search criteria that you specify.

CLI Syntax

ctm config archive::cleanup -s <search query>

-s is used to run a search using the query string format "field1=criteria1&field2=criteria2&field3=criteria3".

The following table describes the fields that you can use in the search query.

If annotation is enabled for the Configuration Management category in the CCM, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE
"$endpoint/config/archive/cleanup?jobname=jobA*&jobnameExceptions=jobABC*&application=B*"

Archive Rule File

The Archive Rule File code sample shows the available properties and objects that you can include within payload JSON files that you can submit when you configure Job Archiving. Details about each of the properties and objects in this file are provided below.

{
    "name": "All DS jobs",
    "description": "Collect all DS jobs",
    "maxOutputSize": 20,
    "maxOutputSizeType": "MB",
    "trimType": "Omit",
    "retention": 1,
    "retentionType": "Months",
    "isActive": true,
    "archivedType": "Log",
    "ruleParameters": [
        {
          "field": "ctm",
          "criteria": "*",
          "exceptions": [
            "fds*"
          ]
        },
        {
          "field": "jobName",
          "criteria": "A*",
          "exceptions": [
            "Ac*",
            "Ad*"
          ]
        },
        {
          "field": "jobType",
          "criteria": "Job:FileTransfer"
        },
        {
          "field": "application",
          "criteria": "*",
          "exceptions": [
            "c*"
          ]
        },
        {
          "field": "subApplication",
          "criteria": "s*",
          "exceptions": [
            "s4*"
          ]
        },
        {
          "field": "folder",
          "criteria": "*",
          "exceptions": [
            "f*"
          ]
        },
        {
          "field": "library",
          "criteria": "bmc*",
          "exceptions": [
            "bmc6*",
            "bmc7*"
          ]
        },
        {
          "field": "jobStatus",
          "criteria": "Ended OK"
        }
    ]
}

General Rule Settings

The following table describes the General Rule Property settings, which you can use to start your Archive Rule file for the rule that you are defining.

Rule Parameters for Job Filtering

Under the ruleParameters object, you can define a group of rule parameters that filter jobs based on various job properties and determine which jobs to archive. These parameters are defined with the following properties:

• field: Job property by which to filter.

• criteria: Filter value.

• exceptions: Values to exclude from the filter.

All rule parameters are optional, and the default for all criteria is * (ALL jobs).

The following table summarizes the guidelines for including rule parameters in an Archive Rule file.