Archive Service

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/EM or later.

For information about the setup of Job Archiving, see Config Service.

The following API commands enable you to use the archive service:

archive search::get

The archive search::get command enables you to search through archived job data in the Workload Archiving server.

CLI Syntax

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

-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

  • numberOfRuns

  • Supported wildcards are the asterisk and question mark (* and ?).

  • Wildcards are not supported for jobid.

  • jobid is in the following format: <server>:<orderId>.

  • 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

status

The following job statuses are relevant:

  • Ended OK.

  • Ended Not OK.

  • All

REST API Syntax

Example using cURL:

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

curl -H "$AuthHeader" "$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:

Copy 
{
    "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

The archive log::get command enables you to retrieve the log of a specific job from the Workload Archiving server.

CLI Syntax

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

The following table describes the archive log::get command parameters.

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

Example using cURL:

Copy 
jobId="srv-arc:0001c"
runs=3
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/archive/log/$jobId/$runs"

archive output::get

The archive output::get command enables you to retrieve the output of a specific job from the Workload Archiving server.

CLI Syntax

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

The following table describes the archive output::get command parameters.

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

Example using cURL:

Copy 
jobId="srv-arc:0001c"
runs=3
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/archive/output/$jobId/$runs"