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. You must have Control-M/EM version 9.0.20 or higher installed to run the Archive service.

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

  • REST

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 example shows the REST API syntax for the archive search::get command in cURL.

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

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

where ? 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

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.

At the end of the response, a summary appears after the information about each job. The summary shows 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

  • REST

ctm archive log::get <jobId> -s runNo=<number_of_runs>

The following example shows the REST API syntax for the archive log::get command in cURL.

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

curl -H "$AuthHeader" "$endpoint/archive/$jobId/log?runNo=3"

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.

runNo

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

This is a query parameter.

archive output::get

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

  • CLI

  • REST

ctm archive output::get <jobId> -s runNo=<number_of_runs>

The following example shows the REST API syntax for the archive output::get command in cURL.

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

curl -H "$AuthHeader" "$endpoint/archive/$jobId/output?runNo=3"

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.

runNo

Determines the number of the most recent job executions to retrieve the output.

This is a query parameter.