Archive service

9.0.20.000 The Archive service enables you to search through job data archived in the Workload Archiving server by the Control-M Workload Archiving add-on, as well as to obtain job outputs and job logs for individual jobs. This feature is offered in an environment with Control-M 9.0.20 or later.

For information about the setup of Job Archiving, see Configuring Job Archiving.

archive search::get

Enables you to search through archived job data in the Workload Archiving server.

CLI Syntax

CLI
ctm archive search::get [limit] [-s <search query>]

Limit refers to the maximum number of jobs returned. The default is 500 jobs. Valid values for this limit depend on the ArchiveSearchRequestJobsLimit EM system parameter, as described in Control-M Workload Archiving parameters in the Control-M Online Help.

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

The following fields are available for use in the search query:

Field

Criteria guidelines

  • jobname
  • jobid
  • folder
  • folderLibrary
  • memName
  • memLibrary
  • server
  • application
  • subApplication
  • host
  • hostGroup
  • runAs
  • orderId
  • Supported wildcards are the asterisk and question mark (* and ?)
  • Wildcards are not supported for jobid
  • jobid is in the following format: <server>:<orderId>

Note: The server field was previously named ctm (deprecated name).

  • logContains
  • outputContains
  • These fields search the job logs or job output for specific strings.
  • A search query that contains one of these fields must also contain the jobname field or the application field. Furthermore, in such a case, the jobname and application fields do not support the "*" value.
  • orderDateFrom
  • orderDateTo
  • fromTime
  • toTime

Format: YYYY-MM-DD

statusThe following job statuses are relevant:
  • Ended OK
  • Ended Not OK
  • All

REST API Syntax

See REST API reference.

Example using curl:

curl -H "Authorization: Bearer $token" "$endpoint/archive/search?jobname=jobA*&status=Ended%20OK&application=B*"

Response

The response to the archive search includes extensive information about each of the jobs that matched the search criteria (similar to the response to the run jobs:status::get command). Many of the job parameters provided in this response were also available as search query fields. The following example shows the parameters that are included in the response for one of the returned jobs. Such a block of job parameters is repeated in the response for each of the returned jobs:

{
      "jobId": "srv-arc:0001c",
      "numberOfRuns": 1,
      "name": "Job15",
      "folder": "EndOkJobs",
      "type": "Command",
      "status": "Ended OK",
      "startTime": "2019-09-01 07:00:06",
      "endTime": "2019-09-01 07:00:09",
      "orderDate": "20190901",
      "ctm": "srv-arc",
      "description": "",
      "host": "srv-arc",
      "application": "OsApp",
      "subApplication": "SampleJobs",
      "outputURI": "https://localhost:8446/automation-api/archive/srv-arc:0001c/output?runNo=1",
      "logURI": "https://localhost:8446/automation-api/archive/srv-arc:0001c/log?runNo=1",
      "duration": 3,
      "runAs": "controlm",
      "archiveRule": "Collect all DS jobs"
    }

At the end of the response, after the information for each of the individual jobs, a summary appears, including the following information:

  • returned — the total number of jobs returned in the response
  • additionalJobsMatchSearchCriteria — whether additional jobs that match the search criteria exist, but were left out of the response because the defined limit was reached (true|false)

archive log::get

Retrieves the log of a specific job from the Workload Archiving server.

CLI Syntax

CLI
ctm archive log::get <jobId> <numberOfRuns>

Where:

Parameter

Description

<jobId>

The unique identifier for the job, in the format <server>:<orderid>

You can obtain the jobId from the response to the archive search::get command.

<numberOfRuns>The number of most recent job runs for which to retrieve log messages.

REST API Syntax

See REST API reference.

Example using  curl:

jobId="srv-arc:0001c"
runs=3
curl -H "Authorization: Bearer $token" "$endpoint/archive/log/$jobId/$runs"

archive output::get

Retrieves the output of a specific job from the Workload Archiving server.

CLI Syntax

CLI
ctm archive output::get <jobId> <numberOfRuns>

Where:

Parameter

Description

<jobId>

The unique identifier for the job, in the format <server>:<orderid>

You can obtain the jobId from the response to the archive search::get command.

<numberOfRuns>The number of most recent job runs for which to retrieve the output.

REST API Syntax

See REST API reference.

Example using  curl:

jobId="srv-arc:0001c"
runs=3
curl -H "Authorization: Bearer $token" "$endpoint/archive/output/$jobId/$runs"
Was this page helpful? Yes No Submitting... Thank you

Comments