Archive Service

The Archive service enables you to search through job data archived in the Workload Archiving server. The service also enables you to obtain job outputs and job logs for individual jobs. This feature is for environments with Control-M/EM version 9.0.20 or higher.

For information about job archiving setup, see Config Service.

The following list contains the Archive service API commands:

archive search::get

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

CLI Syntax

The following shows the CLI syntax for the archive search::get command:

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

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

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

Parameter

Description

limit

Determines the maximum number of jobs returned. Valid values for this limit depend on the ArchiveSearchRequestJobsLimit system parameter, as described in Control-M Workload Archiving parameters.

Default: 500 jobs

The following table shows the fields for the search query:

Field

Criteria guidelines

  • jobname

  • jobid

  • folder

  • folderLibrary

  • memName

  • memLibrary

  • server

  • application

  • subApplication

  • host

  • hostGroup

  • runAs

  • orderId

  • numberOfRuns

  • Supported wildcards are * 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 log 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. In this scenario, the jobname and application fields do not support the "*" value.

  • orderDateFrom

  • orderDateTo

  • fromTime

  • toTime

Format: YYYY-MM-DD

status

The following list shows the relevant job statuses:

  • Ended Not OK

  • All

REST API Syntax

The following example shows the REST API syntax for the archive search::get command in 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 job that matches the search criteria, similar to the response to the run jobs:status::get command. Many of the job parameters in this response are also available as search query fields.

The following example shows the parameters included in the response for one 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"
}

A block of job parameters that is similar to this one is repeated in the response for each returned job.

After information about each job in the end of the response, a summary appears with the following:

  • returned: Defines the total number of jobs returned in the response.

  • additionalJobsMatchSearchCriteria: Determines whether additional jobs that match the search criteria exist but were left out of the response because the results reached the defined limit (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

The following shows the CLI syntax for the archive log::get command:

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

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

Parameter

Description

jobId

Defines the unique identifier for the job in the following format:

<server>:<orderid>

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

numberOfRuns

Determines the number of the most recent job executions to retrieve the log messages.

REST API Syntax

The following example shows the REST API syntax for the archive log::get command in 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

The following shows the CLI syntax for the archive output::get command:

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

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

Parameter

Description

jobId

Defines the unique identifier for the job in the following format:

<server>:<orderid>

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

numberOfRuns

Determines the number of the most recent job runs to retrieve their output.

REST API Syntax

The following example shows the REST API syntax for the archive output::get command in 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"