Web Services Jobs

The following topics describe job types for web services:

Job:WebServices

9.0.20.220 Control-M for Web Services enables you to schedule standard web services, servlets, and RESTful web services.

A web service is XML-based software that enables electronic devices to communicate via intranet or the internet. Servlets are small, Java-based programs that run on web servers, can access databases in response to user input, and add dynamic content to web sites. RESTful web services conform to the Representational State Transfer (REST) software architectural model and are used to create APIs for web-based applications.

To deploy and run a Web Services job, ensure that you have done the following:

The following examples show how to define a Web Services job.

  • This JSON defines a Web Services job that receives input for a calculator service and outputs the result of a simple calculation:

    Copy 
    "WebServices_Job": 
    {
       "Type": "Job:WebServices",
       "Location": "http://www.dneonline.com/calculator.asmx?WSDL",
       "SoapHeaderFile": "c:\\myheader.txt",
       "Service": "Calculator(Port:CalculatorSoap)",
       "Operation": "Add",
       "RequestType": "Parameter",
       "OverrideUrlEndpoint": "http://myoverridehost.com",
       "OverrideContentType": "*/*",
       "HttpConnectionTimeout": "2345",
       "PreemptiveHttpAuthentication": "abc@bmc.com",
       "IncludeTitleInOutput": true,
       "ExcludeJobOutput": false,
       "ConnectionProfile": "CALCULATOR",
       "Host": "host1",
       "OutputParameters": [
       {
          "Element": "AddResponse.AddResult",
          "HttpCode": "*",
          "Destination": "testResultAdd",
          "Type": "string"
       } ],
       "InputParameters": [
       {
          "Name": "Add.intA",
          "Value": "97",
          "Type": "string"
       },
       {
          "Name": "Add.intB",
          "Value": "345",
          "Type": "string"
       } ],
    }

  • This JSON defines a Web Services job that receives all input through a SOAP request to a calculator service and outputs the result of a simple calculation:

    Copy 
    "WSSoapRequest": 
    {
       "Type": "Job:WebServices",
       "SoapHeaderFile": "c:\\myheader.txt",
       "Location": "http://www.dneonline.com/calculator.asmx?WSDL",
       "Service": "Calculator(Port:CalculatorSoap)",
       "Operation": "Add",
       "RequestType": "FreeText",
       "OverrideUrlEndpoint": "http://myoverridehost.com",
       "OverrideContentType": "*/*",
       "HttpConnectionTimeout": "2345",
       "PreemptiveHttpAuthentication": "abc@bmc.com",
       "IncludeTitleInOutput": true,
       "ExcludeJobOutput": false,
       "ConnectionProfile": "CALCULATOR",
       "Host": "host1",
       "OutputParameters": [
       {
          "Element": "AddResponse.AddResult",
          "HttpCode": "*",
          "Destination": "testResultAdd",
          "Type": "string"
       } ],
       "Request": [
          "<soapenv:Envelope xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/ xmlns:tem=http://tempuri.org/>
             <soapenv:Header/>
             <soapenv:Body>
                <tem:Add>
                   <tem:intA>98978</tem:intA>
                   <tem:intB>75675</tem:intB>
                </tem:Add>
             </soapenv:Body>
          </soapenv:Envelope>" ],
    }

  • This JSON defines a Web Services job that receives a SOAP request through an input file. It then uses the input file to submit a SOAP request to a calculator service, and outputs the result of a simple calculation:

    Copy 
    "WSSoapRequest_InputFile": 
    {
       "Type": "Job:WebServices",
       "SoapHeaderFile": "c:\\myheader.txt",
       "Location": "http://www.dneonline.com/calculator.asmx?WSDL",
       "Service": "Calculator(Port:CalculatorSoap)",
       "Operation": "Add",
       "RequestType": "InputFile",
       "OverrideUrlEndpoint": "http://myoverridehost.com",
       "OverrideContentType": "*/*",
       "HttpConnectionTimeout": "2345",
       "PreemptiveHttpAuthentication": "abc@bmc.com",
       "IncludeTitleInOutput": true,
       "ExcludeJobOutput": false,
       "ConnectionProfile": "CALCULATOR",
       "Host": "host1",
       "OutputParameters": [
       {
          "Element": "AddResponse.AddResult",
          "HttpCode": "*",
          "Destination": "testResultAdd",
          "Type": "string"
       } ],
       "InputFile": "/home/usr/soap.xml"
    }

  • This JSON defines a Web Services job that receives input for a calculator REST service and outputs the result of a simple calculation:

    Copy 
    "REST_Service_Job": 
    {
       "Type": "Job:WebServices",
       "Location": "http://www.dneonline.com",
       "Service": "/restAPI/calculator.asmx",
       "Operation": "PUT",
       "RequestType": "Parameter",
       "OverrideContentType": "*/*",
       "HttpConnectionTimeout": "2345",
       "PreemptiveHttpAuthentication": "abc@bmc.com",
       "IncludeTitleInOutput": true,
       "ExcludeJobOutput": false,
       "ConnectionProfile": "CALCULATOR_REST",
       "Host": "host1",
       "OutputParameters": [
       {
          "Element": "$AddResponse.AddResult",
          "HttpCode": "*",
          "Destination": "testResultAdd",
          "Type": "string"
       } ],
       "InputParameters": [
       {
          "Name": "intA",
          "Value": "97",
          "Type": "string"
       },
       {
          "Name": "intB",
          "Value": "345",
          "Type": "string"
       },
       {
          "Name": "accept-encoding",
          "Value": "*/*",
          "Type": "header"
       } ],
    }

The following table describes the Web Services job parameters.

Parameter

Description

ConnectionProfile

Defines the ConnectionProfile:WebServices name that connects Control-M to the web service.

SoapHeaderFile

(Web service only): Defines the path to a file that contains a predefined SOAP Header to add to the invocation of the target web service SOAP message.

Location

(Either web service or REST service): Defines a URL, or

(Web service) Defines a fully qualified filename that points to the WSDL of the web service.

Service

Defines the service provided by the company or business.

  • For a Local File System, this means any service specified in the WSDL file.

  • For a Web Service URL, this means any service specified in the WSDL URL.

  • For a REST service, this means the path to the specific REST API.

Operation

(Web service): Defines an operation available for the specified service.

(REST service): Defines the HTTP method for REST job execution (GET, POST, PUT, DELETE, HEAD, or OPTIONS).

RequestType

Determines one of the following sources of the payload request to submit. The payload can be either a SOAP request (in the case of a web service) or a JSON/XML string (in the case of a REST service).

  • FreeText: Complete request entered in free text. See the Request parameter below.

  • Parameter: Request parameters for a web service or query parameters for a REST service, provided through the InputParameters parameter.

  • InputFile: Complete request provided through a local file. See the InputFile parameter below.

OverrideUrlEndpoint

(Web service only): Defines the URL endpoint at the job definition level.

Upon job submission Control-M for Web Services uses the job definition's Endpoint URL, rather than the address location in the WSDL.

OverrideContentType

Defines a preferred HTTP header Content-Type to be used to execute the job.

HttpConnectionTimeout

Determines the maximum number of seconds to wait for the web service to respond before disconnecting.

PreemptiveHttpAuthentication

Defines HTTP Basic Authentication information in the format of <user>@<realm>.

This information must match the HTTP Basic Authentication information defined through the connection profile (not including the password).

IncludeTitleInOutput

Determines whether an Output banner is written to the Output at the end of job execution.

Values:

  • checked

  • unchecked

Default: true

ExcludeJobOutput

Determines whether to exclude information about job output from the Output at the end of job execution.

Values:

  • checked

  • unchecked

Default: false

OutputParameters

Defines details of the outcome of selected output parameters.

For each output parameter, define the following subparameters:

  • Element: An element in the job output response, specified by its name or using an XPath or JSONPath expression.

  • HttpCode: HTTP code of the job response. Capture of the element to the destination is performed only for the specified HTTP code.

  • Destination: A fully qualified path in URI format or an AutoEdit variable to be assigned to the element.

  • Type: Format type of the element value (for example, string or integer).

InputParameters

Defines details of the input parameters required by the web service.

For each input parameter, define the following subparameters:

  • Name

  • Value

  • Type: Format type of the parameter value. For an HTTP header, enter header. For any other type, enter the type name that you defined (such as string or integer).

Request

Free-text request to submit to the service, one of the following:

  • ( Web Service): Full SOAP request.

  • (RESTful web service): JSON or XML string.

This parameter is relevant only if RequestType is set to FreeText.

InputFile

The fully qualified path to an input file that contains a complete request to submit to the service — either a full SOAP request (for a web service), or a JSON or XML string (for a RESTful service).

This parameter is relevant only if RequestType is set to InputFile.

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 done the following:

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

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",
   "URL parameters" : [
      {
         "FilterValue" : "Untitled Workflow"
      }
   ],
   "Spec Request Headers" : [ 
      {
         "Content-Type" : "application/json"
      } 
   ],
   "WsRestBody" : 
      {
         "RequestDefinition" : "text",
         "BodyRequest" : "{%4E\"Job Identifier\": \"some-unique-id-000x\"%4E}"
      },
   "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 example shows the same Web Services REST job as above, but the request body is obtained from a local file:

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",
   "URL parameters" : [
      {
         "FilterValue" : "Untitled Workflow"
      }
   ],
   "Spec Request Headers" : [ 
      {
         "Content-Type" : "application/json"
      } 
   ],
   "WsRestBody" : 
      {
         "RequestDefinition" : "filename",
         "FileName" : "/home/jobdefs/request-body.txt"
      },
   "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.

URL Request Path

Defines the URL request path.

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 parameters

Defines optional URL parameters, as an array of Key:Value pairs.

HTTP Headers

Defines optional HTTP headers, as an array of Key:Value pairs.

If you created a connection profile that authenticates with OAuth2, as described in Web Services REST Connection Profile Parameters, you must define the following HTTP header key name and value:

"Authorization" : ""

WsRestBody

Defines the REST request body, using the following parameters on the next level:

  • RequestDefinition: Determines whether to define a REST request body, and how to do so:

    • text: Textual input of the body

    • none: No request body (only URL parameters and headers)

    • filename: Use a predefined request body in a local file

  • BodyRequest: Defines the request body as textual input, in JSON format.

  • FileName: Defines the full path to a local file that contains a predefined request body.

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 done the following:

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