Web Services Jobs

The following topics describe job types for web services:

Job:Web Services REST

Web Services REST jobs enable you to design and execute single REST API calls.

To deploy and run a Web Services REST job, ensure that you have installed the Web Services REST plug-in with the provision image command or the provision agent::update command.

The following example shows how to define a Web Services REST job:

Copy
"Web Services REST_output_parameters"
{
   "Type": "Job:Web Services REST",
   "ConnectionProfile": "REST_OAUTH2",
   "Method": "POST",
   "Append Request": "checked",
   "Append Response": "checked",
   "Endpoint URL": "https://6943019930999707.net",
   "URL Request Path": "/api/2.1/jobs/run-now",
   "Variables": [
   {
      "UCM-BODY_REQ_TYPE": "text"
   },
   {
      "UCM-BODY_BODY_REQUEST": "{%4E  \"job_id\": 298,%4E   \"params\":{}%4E}"
   },
   {
      "UCM-HEADERS_KEY_001": "Authorization"
   } ],
   "OutputHandling": [
   {
      "HttpCode": "*",
      "Parameter": "$.run_id",
      "Variable": "file:/home/dbauser/temp.txt"
   },
   {
      "HttpCode": "*",
      "Parameter": "$.run_id",
      "Variable": "LOCAL_CTM_VAR"
   },
   {
      "HttpCode": "*",
      "Parameter": "$.run_id",
      "Variable": "\\GLOBAL_CTM_VAR"
   } ]
}

The following table describes the Web Services REST job parameters.

Parameter

Description

ConnectionProfile

Defines the ConnectionProfile:Web Services REST name that connects Control-M to Web Services REST.

Endpoint URL

Defines the endpoint base URL, which is the common resource prefix that the API uses to navigate.

Method

Determines one of the following HTTP methods that is used to execute the REST job:

  • GET: Reads or retrieves data from a resource.

  • POST: Adds a new resource.

  • DELETE: Deletes a resource.

  • PUT: Updates an existing resource by entirely replacing its content.

  • TRACE: Creates a loop-back test with the same request body that the user sent to the server. This is used for diagnostic purposes.

  • HEAD: Determines the size of the data and allows you to test if a server is available.

  • OPTIONS: Retrieves information about the possible communication options (HTTP methods) on the endpoint URL or the entire server.

  • PATCH: Partially updates an existing resource by replacing some of its content.

URL Request Path

Defines the URL request path.

/v1/submitjob

Request Definition

Determines one of the following requests to perform:

  • Edit Request Body

  • Specify Only URL Parameters and Headers

  • Use a Predefined Request Body from a Local File

Body

Defines the request body, which is the data in the resource that the API creates or edits, in JSON format.

For no body, type {}.

URL parameters

(Optional) Defines URL parameter key names and values.

Key: Filter

Value: Untitled Workflow

HTTP Headers

(Optional) Defines HTTP header key names and values.

Key: Content_Type

Value: application/json

OutputHandling

(Optional) Defines the following output parameters:

  • HttpCode: Defines the HTTP response or error code, in numbers or * (asterisk) for any code.

  • Parameter: Defines the parameter and its path in XPath or JsonPath format.

  • Variable: Defines the Control-M variable or file to save the parameter value to, in the following format:

    • Local Variable: <parameter_name>

    • Global Variable: \\<parameter_name>

    • Smart Folder Variable: \\\\<parameter_name>

    • Named Pool Variable: \\\\\\<parameter_name>

    • File: Defines the URI of the file in the following format:

      file:<full directory path and filename>

Rules:

  • Each parameter must have a value.

  • Maximum Rows: 999

Connection Timeout

Determines the number of seconds to wait after Control-M initiates a connection request to Web Services before a timeout occurs.

Default: 50

Append Request

Determines whether to append the API request to the outputClosed A tab in the job properties pane of the Monitoring domain where the job output appears that indicates whether a job ended OK, and is used, for example, with jobs that check file location..

Values:

  • checked

  • unchecked

Default: unchecked

Append Response

Determines whether to append the API response to the output.

Values:

  • checked

  • unchecked

Default: unchecked

Job:Web Services SOAP

Web Services SOAP jobs enable you to design and execute single SOAP API calls.

The following example shows how to define a Web Services SOAP job, which enables you to design and execute a single SOAP API call.

To deploy and run a Web Services SOAP job, ensure that you have installed the Web Services SOAP plug-in with the provision image command or the provision agent::update command.

The following example shows how to define a Web Services SOAP job:

Copy
"Web Services SOAP_Job_2"
{
   "Type": "Job:Web Services SOAP",
   "ConnectionProfile": "SOAP_BASIC_AUTH",
   "Endpoint URL": "http://vw-usr1:8091/ws/register",
   "Append Request": "unchecked",
   "Append Response": "unchecked",
   "SOAP Action": "http://www.bmc.com/ctmem/#register",
   "Variables": [
   {
      "UCM-SOAP_REQUEST_REQ_TYPE": "xml"
   },
   {
      "UCM-SOAP_REQUEST_SOAP_REQUEST": "<soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\" xmlns:sch=\"http://www.bmc.com/ctmem\">%4E   <soapenv:Header/>%4E   <soapenv:Body>%4E      <sch:request_register>%4E         <!--Optional:-->%4E         <sch:component>?</sch:component>%4E         <sch:user_name>?</sch:user_name>%4E         <sch:password>?</sch:password>%4E         <sch:timeout>?</sch:timeout>%4E         <!--Optional:-->%4E         <sch:hostname>?</sch:hostname>%4E      </sch:request_register>%4E   </soapenv:Body>%4E</soapenv:Envelope>"
   } ],
   "OutputHandling": [
   {
      "HttpCode": "200",
      "Parameter": "//sch:error_message",
      "Variable": "CTM_VAR_RESULT"
   },
   {
      "HttpCode": "200",
      "Parameter": "//sch:error_message",
      "Variable": "file:/home/dbauser/soap_result.txt"
   } ],
}

The following table describes the Web Services SOAP job parameters.

Parameter

Description

ConnectionProfile

Defines the ConnectionProfile:Web Services SOAP name that connects Control-M to Web Services SOAP.

Endpoint URL

Defines the endpoint base URL, which is the common resource prefix that the API uses to navigate.

SOAP Action

Defines a single SOAP action (operation), which you must take from the WSDL file.

In this example, in the WSDL file, copy the SOAP action http://tempuri.org/SOAP.Demo.AddInteger from the body of the following operation:

Copy
<operation name="AddInteger">
<soap:operation soapAction="http://tempuri.org/SOAP.Demo.AddInteger"
 style="document"/>

Request Definition

Determines one of the following requests to perform:

  • Edit SOAP Request

  • Use a Predefined SOAP Request from a Local File

SOAP Request

Defines the SOAP request.

Copy
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:tem="http://tempuri.org">
<soapenv:Header/>
<soapenv:Body>
<tem:AddInteger>
<!-Optional:->
<tem:Arg1>1</tem:Arg1>
<!-Optional:->
<tem:Arg2>2</tem:Arg2>
</tem:AddInteger>
</soapenv:Body>
</soapenv:Envelope>

HTTP Headers

(Optional) Defines HTTP header key names and values.

Key: Content-Type

Value: application/json

OutputHandling

(Optional) Defines the following output parameters:

  • HttpCode: Defines the HTTP response or error code, in numbers or * (asterisk) for any code.

  • Parameter: Defines the parameter and its path in XPath or JsonPath format.

  • Variable: Defines the Control-M variable or file to save the parameter value to, in the following format:

    • Local Variable: <parameter_name>

    • Global Variable: \\<parameter_name>

    • Smart Folder Variable: \\\\<parameter_name>

    • Named Pool Variable: \\\\\\<parameter_name>

    • File: Defines the URI of the file in the following format:

      file:<full directory path and filename>

Rules:

  • Each parameter must have a value.

  • Maximum Rows: 999

Connection Timeout

Determines the number of seconds to wait after Control-M initiates a connection request to Web Services before a timeout occurs.

Default: 50

Append Request

Determines whether to append the API request to the outputClosed A tab in the job properties pane of the Monitoring domain where the job output appears that indicates whether a job ended OK, and is used, for example, with jobs that check file location..

Values:

  • checked

  • unchecked

Default: unchecked

Append Response

Determines whether to append the API response to the output.

Values:

  • checked

  • unchecked

Default: unchecked