Web Services Jobs

The following topics describe job attributes that work with Web Services jobs:

Web Services JobLink copied to clipboard

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 create a Web Services job, see Creating a Job.

The following table describes the Web Services job attributes.

Attribute

Description

Connection Profile

Determines the authorization credentials that are used to connect Control-M to Web Services.

Rules:

  • Characters: 1−50

  • Valid Characters: Alphanumeric characters, _ (underscores), and - (hyphens).

  • Case: Uppercase only.

  • Invalid Characters: Blank spaces.

Special characters cannot be included with the name definition.

Variable Names:

  • %%WS-ACCOUNT

  • %%JAVA-PROFILE

  • %%MSG-ACCOUNT

For more information about creating a local connection profile for this job, see Creating a Local Connection Profile.

URL/WSDL

Defines a URL or fully qualified filename pointing to the WSDL, which is an XML-based notation that describes the web service.

Rules:

  • Characters: 1−214

  • Valid Characters: Alphanumeric characters.

  • Invalid Characters: 

    • Blank spaces.

    • Cannot begin with the numbers 0–9.

Variable Names

  • REST: %%WS-URL

  • Local File System and Web Service URL: %%WS-WSDL

Service

Defines a service provided by the company or business.

Rules:

  • Characters: 1−214

  • Case-Sensitive: Yes

Variable Name: %%WS-SERVICE

Method (REST)

Determines which of the following HTTP methods are used to execute the REST job:

  • GET

  • POST

  • PUT

  • DELETE

  • HEAD

  • OPTIONS

  • PATCH

Rules:

  • Characters: 1−214

  • Case-Sensitive: Yes

Variable Name: %%WS-SERVICE

Path

Defines a path available for the method specified in the Method (REST) field.

Rules:

  • Characters: 1−214

  • Case-Sensitive: Yes

Variable Name: %%WS-OPERATION

Operation

Defines an operation available for the service specified in the Service field.

Rules:

  • Characters: 1−214

  • Case-Sensitive: Yes

Variable Name: %%WS-OPERATION

Use Parameters from Input File

Defines an input file name and path, which enables you to invoke the target web service with a predefined SOAP message.

Rules:

  • Characters: 1−214

  • Any character string representing the file name including the file path.

Variable Name: %%WS-INPUTPUTFILE

Edit SOAP Request/Edit Body Request

Enables you to generate your own SOAP request for REST web services, in the following format:
WS-SOAPREQUEST-Pxxx-STR

Represents part of the SOAP request string. xxx in Pxxx represents the xxxth part of the SOAP request string divided in numerical order.

Add SOAP Header from File

Defines the filename and path of a predefined SOAP Header, which is added to the invocation of the target web service SOAP message.

Rules:

  • Characters: 1−212

  • Any character string representing the file name including the file path.

Variable Name: %%WS-SOAPHEADERFILE

Input Parameters

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

Rules:

  • Characters: 1−212

  • Case-Sensitive: Yes

Variable Name: %%WS-PARMS-P00n-NAME

n refers to the nth parameter of the corresponding method. For example, if there were two parameters for a particular method, the first parameter would use P001(%%WS-PARMS-P001-NAME) and the second parameter would use P002 (%%WS-PARMS-P002-NAME).

HTTP Code

Enables you to enter the different job output data based on the HTTP return status code.

Variable Name: %%WS-OUTPARMS-Pxxx-HTTPCODE

Array Size

Defines a number of items in an input parameter array applicable to the input parameters of the Web Services invocation when necessary.

Rules:

  • Characters: 1−2

  • Valid Characters: The numbers 0–9.

  • Invalid Characters: Blank spaces, letters, and special characters.

Variable Name: %%WS-ARRAYSIZE

Output Parameters

Defines the outcome of selected output parameters.

Rules:

  • Characters: 1−212

  • Case-Sensitive: Yes

Variable Name: %%WS-PARMS-P001-VALUE

P001 represents the number of the parameter for the chosen method. For example, if there were two parameters for a particular method, the second parameter would use P002 instead of P001 (%%WS-PARMS-P002-VALUE).

Exclude Job Output

Excludes information about job output from the output at the end of a job execution.

Variable Name: %%WS-SYSOUTSKIP

No Output Banner

Defines whether an output banner is written to the output at the end of a job execution.

Variable Name: %%WS-NOSYSOUTBANNER

Jobs only end Not OK when an exception occurs from the Java method. If this happens, the job end status is set to Not OK and the exception is printed into the output. If a system.exit() command is executed, Control-M for Java converts the call into an exception. This means that the job ends Not OK, and the detailed exception is displayed in the output. In all other cases, jobs end OK.

Override URL Endpoint

Defines the URL endpoint at the job definition level. Upon job submission, Control-M for Web Services uses the job definition endpoint URL rather than the URL.

Rule: Case-sensitive.

Variable Name: %%WS-URLENDPOINT

Preemptive Authentication

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

This information must match the the information in HTTP Basic Authentication field in the Control-M for Web Services Connection Profile Management (CCM).

Variable Name: %%BPI-PREAUTH

Override CONTENT-TYPE

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

Rule: Case-sensitive.

Variable Name: %%WS-CONTENTTYPE

Override Connection Timeout (sec)

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

Variable Name: %%WS-CONNECTIONTIMEOUT

Web Services REST JobLink copied to clipboard

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

To create a Web Services REST job, see Creating a Job. For more information about this plug-in, see Control-M for Web Services REST.

The following table describes the Web Services REST job attributes.

Attribute

Description

Connection Profile

Determines the authorization credentials that are used to connect Control-M to Web Services REST, as described in Web Services REST Connection Profile Parameters.

Rules

  • Characters: 1−30

  • Case Sensitive: Yes

  • Invalid Characters: Blank spaces.

Endpoint URL

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

https://batch.eu-west-2.amazonaws.com

URL Request Path

Defines the URL request path.

/v1/submitjob

Method

Determines one of the following HTTP methods to run 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.

Rules:

  • Characters: 1−214

  • Case-Sensitive: Yes

Variable Name: %%WS-SERVICE

URL Parameters

Defines optional URL parameters, as Key:Value pairs.

Key: Filter

Value: Untitled Workflow

HTTP Headers

Defines optional HTTP headers, as Key:Value pairs.

  • Key: Content-Type

  • Value: application/json

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:

  • Key: Authorization

  • Value: bearer

Request Definition

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

  • Edit request body: Textual input of the body

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

  • Use a predefined request body from a local file

Body

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.

/home/jobdefs/request-body.txt

Output Parameters

(Optional) Defines output handling that extracts values from the service response in either JSON or XML.

The attribute consists of the following:

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

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

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

    • Local 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 file name>

  • HTTP Code: *

  • Parameter/Path

    • Xpath Format: //AddIntegerResult

    • JsonPath Format: $.run_id

  • CTM Variable/URI: 

    • CTM Variable: CTM_LOCAL_VAR

    • File:

      • Windows: file:C:\output\temp.txt

      • Linux: file:/home/dbauser/temp.txt

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 before a timeout occurs.

Default: 50

Append Request

Determines whether to append the API request to the outputClosed.

Append Response

Determines whether to append the API response to the output.

Web Services SOAP JobLink copied to clipboard

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

To create a Web Services SOAP job, see Creating a Job. For more information about this plug-in, see Control-M for Web Services SOAP.

The following table describes the Web Services SOAP job attributes.

Attribute

Description

Connection Profile

Determines the authorization credentials that are used to connect Control-M to Web Services SOAP, as described in Web Services SOAP Connection Profile Parameters.

Rules

  • Characters: 1−30

  • Case Sensitive: Yes

  • Invalid Characters: Blank spaces.

Endpoint URL

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

https://batch.eu-west-2.amazonaws.com

SOAP Action

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

In the WSDL file, copy the SOAP action http://tempuri.org/SOAP.Demo.AddInteger from the body of the following operation and paste it in the SOAP Request field:

CopyCopied to clipboard 
<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.

CopyCopied to clipboard 
<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

Output Parameters

(Optional) Defines the following output parameters:

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

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

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

    • Local 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 file name>

  • HTTP Code: *

  • Parameter/Path

    • Xpath Format: //AddIntegerResult

    • JsonPath Format: $.run_id

  • CTM Variable/URI: 

    • CTM Variable: CTM_LOCAL_VAR

    • File:

      • Windows: file:C:\output\temp.txt

      • Linux: file:/home/dbauser/temp.txt

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 before a timeout occurs.

Default: 50

Append Request

Determines whether to append the API request to the outputClosed.

Append Response

Determines whether to append the API response to the output.