Web Services Jobs

The following topics describe job types for web services:

Web Services Jobs
Job:Web Services REST
Job:Web Services SOAP

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 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 output 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 output 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