Plug-in Development

The plug-in development process includes the following main tasks:

• Design a combination of steps for a new job type to execute on an external application.

• Define attributes for use in job properties, connection profiles, and runtime parameters.

• Create rules to control job output.

For each step, you need to define one of the following interfaces to communicate with the application and execute various operations:

• Command Line

• REST API

• Web Service

The following table describes the sequential order and purpose of each step type:

Step Type	Description	Usage
Pre-execution step	Defines an operation that needs to execute before the main execution, such as initialization or creation of a database table.	Optional One per plug-in Empty default provided
Execution step	Defines an operation that runs during the main execution flow.	Required At least one per plug-in Unnamed, empty default provided
Runtime information capture sub-step	Obtains information about plug-in job executions when they are running.	Optional One per execution step Added through parent step
Manual abort operation sub-step	Applies an additional operation when a job is manually terminated.	Optional One per execution step Added through parent step
Verify operation completion sub-step	Verifies that the job has completed.	Optional One per execution step Added through parent step
Retrieve output sub-step	Retrieves output of a REST API step while it is still executing and displays it in the job output.	Optional One per execution step Added through parent step
Post-execution step	Defines an operation that needs to run after completion, such as cleanup, logout, or adding completion data to the output.	Optional One per plug-in Empty default provided

Defining a Step

This procedure describes how to define a step in a plug-in. You can edit any of the steps created by default during creation of the plug-in (a pre-execution step, an execution step, and a post-execution step) or add additional execution steps and sub-steps.

For more information about the different types of steps, see Plug-in Development.

Begin

1. From the Home tab in Application Integrator, select the plug-in that you want to configure.

   The plug-in opens.

2. In the plug-in, do one of the following:

   • To edit the basic settings of an existing step, select the step under Execution Steps and click.

   • To add an execution step, click .

3. On the Edit or Add pane that appears on the right, define one or more of the following basic steps and then click Save or Add:

   • (Execution step only) Type a name for the step.

   • Type an optional step description.

   • In the Step interface field, select an interface to communicate with the application:

     • Command Line (default)

     • REST API

     • Web Service

   • (Execution step only) For additional sub-step actions, select one or more of the operations that appear under Additional actions:

     • Runtime information capture: Obtains information about plug-in job executions when they are running.

     • Manual abort operation: Applies an additional operation when a job is manually terminated.

     • Verify operation completion: Verifies that the job has completed.

     • Retrieve output: Retrieves output of a REST API step while it is still executing and displays it in the job output.

   The step is updated. If this is a new Execution step, it is added to the list of steps.

   To edit a sub-step, see Defining an Execution Sub-step.

4. Select the step and complete its technical details in the tabs on the right.

   • Command Line step:

     • Conditions: Defines the conditions required for the step to run.

     • Command Line: Defines the command line script to execute.

     • Return Code Handling: Controls how the job workflow behaves in response to return codes issued by the step.

     • Output Handling: Defines specific content to check for in the step output and controls how the job reacts to the output and whether to retain certain output content as parameters.

   • REST API step:

     • Conditions: Defines the conditions required for the step to run.

     • REST API: Defines the REST API request to submit.

     • Output Handling: Defines specific content to check for in the step output and controls how the job reacts to the output and whether to retain certain output content as parameters.

   • Web Service step:

     • Conditions: Defines the conditions required for the step to run.

     • Web Service: Enables you to load a WSDL file and define the Web Service to execute.

     • Output Handling: Defines specific content to check for in the step output and controls how the job reacts to the output and whether to retain certain output content as parameters.

5. Save the plug-in.

Defining an Execution Sub-step

This procedure describes how to define a sub-step under an Execution step in the plug-in, for several optional operations that you can apply during plug-in job execution. For descriptions of these operations, see Plug-in Development.

Before you begin

Ensure that the relevant sub-steps are listed under the Execution step. The sub-steps were created when you associated operations with the Execution step, as described in Defining a Step.

Begin

1. From the plug-in, select the Runtime information capture, Manual abort operation, or Verify operation completion sub-step and click.

   For a Retrieve output sub-step, go to step 5.

2. On the Edit pane, select one of the following interfaces to communicate with the application for execution of the sub-step:

   • Command line

   • REST API

   • Web service

   The default interface at the time of creation of the sub-step is the same as the interface associated with the parent Execution step.

3. For a Verify operation completion sub-step, set values for one or more of the following parameters on the Edit pane:

   • Retry in case of failure > Retries: Defines the number of times to retry verification before failing the step. First select the option and then enter the number of retries.

   • Fail the job on timeout > Timeout: Defines the number of minutes to retry verification before failing the step. First select the option and then enter the number of minutes.

   To insert an attribute in any of these fields, click. For more information, see Defining Attributes.

4. Click Save.

5. In the list of steps, select the sub-step.

6. In the default tab on the right (Command Line, REST API, or Web Service), define the setting that is unique to the sub-step:

   • Abort Method: Determines what happens to the job after the Manual abort operation sub-step completes:

     • Terminate the job: The whole job is terminated. Default.

     • Continue execution: The current execution step is terminated, and the job proceeds to execute the next step.

   • Rerun Interval: Determines the number of seconds to wait before checking for the completion of the job (by a Verify operation completion sub-step) until the completion criteria is met. The default is 2 seconds.

     You can insert an attribute by clicking . For more information, see Defining Attributes.

7. Complete all other technical details on one or more of the following tabs (depending on sub-step type and the interface type):

   • Command Line: Defines the command line script to execute.

   • Return Code Handling: Controls how the job workflow behaves in response to return codes issued by the command line during verification of operation completion.

   • REST API: Defines the REST API request to submit.

     For a Retrieve output sub-step, the REST API details appear on a Request tab.

     An additional Pre-Request tab enables you to define REST API details if you need to invoke a preliminary REST call before running the main REST call. For example, the pre-request can retrieve a URL for use by the main request in the retrieval of output or it can retrieve an authentication token for use by the main request.

   • Web Service: Enables you to load a WSDL file and define the Web Service to execute.

   • Output Handling: Defines specific content to check for in the step output for Command Line, REST API, or Web Service and controls how the job reacts to the output and whether to retain certain output content as parameters.

8. Save the plug-in.

Condition Parameters

Conditions determine the requirements for a step to run and are based on the following:

• Values: Attribute or variable values, with the following syntax:

  If the <item type> <item name> <comparison operator> <value>

• Status: Previous steps status or previous job execution status, with the following syntax:

  If the <item type> <status>

The following table describes the types of items that you can specify in a condition:

Item	Description
Attribute	Enables you to run the step based on the value of an attribute that you select or create on the fly. Attributes are values derived from job properties or connection profile properties. For more information about attributes, see Defining Attributes.
Environment variable	Enables you to run the step based on the value of a user variable or system environment variable.
Control-M variable	Enables you to run the step based on the value of a Control-M variable.
Previous steps	Enables you to run an execution step or post-execution step based on one of the following statuses of previous steps: All succeeded Any failed Any You can include only one condition of this type in a step.
Previous job execution	Enables you to run the step based on one of the following statuses of the previous Control-M job execution: Succeeded Failed Any You can include only one condition of this type in a step.

Command Line Parameters

The following table describes parameters that enable you to execute a command line in a step:

Parameter	Description
Command Line Editor	Enables you to write a script to execute through the command line. You can add attributes into the command by clicking. For more information, see Defining Attributes.
Append command to job output	Determines whether to attach command line details to the job output. This option is selected by default.
Append command standard output to job output	Determines whether to attach the standard output from the command line to the job output. If you select this option, you can apply a filter to attach output based on a string, as described in the Append if parameter.
Append if...	Enables you to apply a filter when the standard output is attached to the job output (see the Append command standard output to job output parameter). The filter that you define contains the following syntax: Append if command standard output <comparison operator> <value> The comparison operator can be one of the following: Starts with Contains Ends with Matches regular expression Does not contain. The value can be any string. You can insert an attribute into the value by clicking. For more information, see Defining Attributes.

Return Code Handling Parameters

You can define rules that control how the job workflow behaves in response to return codes issued by the step, with the following syntax:

If the return code <comparison operator> <value> <action>

A rule contains the following parameters:

• Comparison operator: Enables you to select from multiple operators to compare the defined value, such as Not equals to (!=) or Less than (<). For a range of values, you can select the In range operator and set the minimum and maximum values of the range.

  Action: Defines the action to perform in response to the specified return code(s). The following actions are available in rules, depending on the step type:

  • Fail the job

  • Proceed to the next execution step

  • Complete Execution and Fail the job

  • Complete Execution and proceed

Command Line Output Handling Parameters

You can define rules that check for specific content in the step output from a command line and control how the job reacts to the output. For example, you can retain content from the output as parameter values.

Output handling rules have the following syntax:

If output <operator> <value> Do <actions>

A rule contains the following parameters:

• Operator: Enables you to select from multiple operators, such as Starts with, Contains, or Matches regular expression.

• Value: Defines the string to search for.
  To insert an attribute, click . For more information, see Defining Attributes.

• Actions: Define the actions to perform in response to detected output content. The following actions are available in rules, depending on the step type:

  • Fail the job

  • Extract and handle data

  • Keep value in Runtime Parameter

  • Complete and fail

  • Complete & Proceed

  The following table describes additional parameters that are available to define actions:

  Action Type	Parameter	Description
  Extract and handle data	Extract <scope>	Determines the quantity of data to extract, as follows: Whole line: Extracts data from the whole line. Match regular expression: Enables you to match an expression that you define in the Expression field. Part of the line: Enables you to extract part of a line based on the outer boundaries of a string in the line: Start position: Enables you to select a starting point based on a specific number of characters or words from the beginning or end of the line, or relative to an exact text in the line (after the text or including it). End position: Enables you to select an endpoint based on the number of characters or words from the start position, or relative to an exact text in the line (up to the text or including it). Columnar data: Enables you to extract columnar data when the output is column-based, such as CSV format or SQL output format. You need to define the separation identifier between the columns and the column number that you want to extract.
  	Trim preceding/trailing whitespace from extracted data	Determines whether to remove blank spaces that appear at the beginning or at the end of the extracted data, for extraction of part of a line or extraction of columnar data.
  	Preview	Enables you to view the effect of your settings on a sample text. Based on your settings, the text that is extracted is highlighted in yellow. You can replace or edit the sample text by clicking .
  	Encrypt extracted data	Replaces the extracted data with asterisks (****** ) in the logs, customer log, or output, to keep sensitive data secure.
  	Keep extracted data in a runtime parameter	Stores the extracted data as the value of a runtime parameter that you define. In addition, you can choose to fail the job based on the value of this runtime parameter, using a rule with the following syntax: Fail the job if extracted data <comparison operator> <value|range>
  Keep value in Runtime Parameter	Parameter name	Defines the name of the runtime parameter where the extracted value is stored for future use
  	Encrypt the runtime parameter value	Replaces the value of the runtime parameter with asterisks (****** ) in the logs, customer log, or output, to keep sensitive data secure.
  	Fail|Succeed the job if...	(For Verify operation completion sub-step only) Enables you to set the status of the job to failed or succeeded based on the value of the runtime parameter using a rule with the following syntax: [Fail|Succeed] the job if extracted data <comparison operator> <value|range>

REST API Parameters

The following categories of parameters enable you to define the REST API to execute in the step:

• URL Settings

• Authentication Settings

• URL Parameters, Headers, and Body Definitions

• Advanced Settings

• Output Handling Settings

URL Settings

The following table describes the URL settings that you define in a REST API step:

Parameter	Description
Load from presets	Populates the URL settings with a preset of URL settings that you saved previously (see Add to Presets).
REST API URL	Defines the base URL location of the REST services, excluding the specific resource context path. For example, https://www.googleapis.com. You can insert an attribute into the URL by clicking . For more information, see Defining Attributes.
URL request path	Defines the required path (recourse). For example, /language/translate/v2. You can insert an attribute by clicking . For more information, see Defining Attributes. If the path requires values for input parameters, type them separately, as described in URL Parameters, Headers, and Body Definitions.
Method	Defines the method to invoke, such as GET or POST.
Authentication required	Determines whether authentication is required by the target server for the REST API URL. After selecting this option, authentication settings appear. See Authentication Settings.
Add to Presets	Saves the URL settings as a preset for future use in other steps in the plug-in.

Authentication Settings

The following table describes the authentication settings that you define if the target server for the REST API URL requires authentication.

Parameter	Description
Authentication Type	Determines the method to use to authenticate REST API requests: Basic: Sends an encrypted request with user name and password to the server. OAuth2: Sends a secured request to the server using the OAuth 2.0 protocol. AWS: Sends a secured request to the server using AWS. Google: Sends a secured request to the server using Google services.
Basic Authentication settings
Use preemptive authentication	Sends a basic authentication response before the server returns an unauthorized response.
User name attribute	Defines an attribute that contains the username to connect to the HTTP server.
Password attribute	Defines an attribute that contains the password to connect to the HTTP server.
OAuth2 settings
Use basic authentication	Adds basic authentication to the OAuth2 request. If you select this option, you must define the User name attribute and Password attribute.
OAuth2 API URL	Defines the REST API authorization endpoint.
Token parameter	Defines the access token required by the REST API. You can use this token in the URL request header for authentication. For example, Authorization=Bearer{{TOKEN_NAME}}
Grant type	Determines ones of the following options to access the token: Resource owner password credentials: Enables the application to request an access token by sending its credentials, its client ID, and the client secret to the authorization server. Password: Enables the user to provide service credentials directly to the application. The password is only used if trusted by the user. For this grant type, you must define a User name and Password parameter.
Apply client ID	Defines the public identifier for applications.
Use client secret	Defines the secret known to the application and the authorization server. This option is relevant when Grant type is set to Resource owner password credentials.
Specify content type	Defines the media type of the resource.
Apply headers	Defines any additional HTTP headers as key-value pairs. You can type <key>=<value> lines in an Editor View or you can define keys and values in a Table View.
Apply body	Defines any text that is required in the request body as key-value pairs. You can type <key>=<value> lines in an Editor View or you can define keys and values in a Table View.
AWS Authentication settings
Region	Defines the AWS regional endpoint.
Custom service name	Defines the AWS Service Name. Default: execute-api
Authentication method	Determines the authentication method required to run the AWS Service: IAM role: Enables you to specify the IAM Role name that is used to acquire a temporary security token. This is the default method. Access & Secret keys: Enables you to specify a unique Access Key for the service API to identify the application and a Secret Access Key to authenticate the identity of the application when access is requested to a user account.
Google Authentication settings
Token type	Determines one of the following types of tokens to use to access data in Google APIs: Access token Identity token Default: Access token
Service account key	Defines the authorization key to access data in Google APIs.

URL Parameters, Headers, and Body Definitions

The following table describes the settings that you can define for additional elements in the REST API URL and the REST API job step.

Parameter	Description
URL Parameters	Defines URL parameters that are added to the URL address. These parameters are added to the URL as key-value pairs after a ? character. You can type <key>=<value> lines in an Editor View or you can define keys and values in a Table View.
Headers	Defines any additional HTTP headers, as key-value pairs. You can type <key>=<value> lines in an Editor View or you can define keys and values in a Table View.
Body	Defines data required in the request body in one of the following formats: ASCII data: Data in text format, expressed as key-value pairs. You can type <key>=<value> lines in an Editor View or you can define keys and values in a Table View. form-data: Data of the multipart/form-data content type, which supports file uploads. In the table, use the following fields to define the various data parts: Key Value Type: Either Text or File (to upload a file up to 250MB) Value: A text value or file path File path examples: /path/to/file C:\Path\To\File https://hostname.com/file.json Content Type: You can select one of the available types (such as application/yaml, text/csv, or image/jpeg), or specify any other type. Form-data content is supported by most step types, but not by the Retrieve output sub-step.
Append REST API request to job output	Determines whether to attach the REST API request to the job output. This option is selected by default in most step types, but not in the Retrieve output sub-step.
Append REST API response to job output	Determines whether to attach the REST API response to the job output. This option is selected by default in the main request of a Retrieve output sub-step, but not in a pre-request.

Advanced Settings

The following table describes the advanced settings that you can define for a REST API step.

Parameter	Description
Apply Cookie	Enables you to specify a cookie for the REST API to apply.
Override connection timeout	Determines the number of seconds to wait for the REST service to respond before disconnecting.
Override Content-Type	Enables you to define a preferred HTTP content type for the request body to use to execute the job (to override the default text/javascript). This parameter is relevant when the request body contains ASCII data. It is not available for a request with form-data content.

Output Handling Settings

The following table describes the Output Handling settings that you define in a pre-request of a Retrieve Output sub-step:

Parameter	Description
Output Handling	Determines whether to extract a value from the response of the pre-request.
Response Type	Determines one of the following response types for extraction of a value from the response: JSON XML
URL Parameter Name	Enables you to specify a JsonPath or XPath expression for selection of JSON or XML data and extraction of a value from the response. You can insert an attribute by clicking . For more information, see Defining Attributes.
Parameter Name	Defines the name of a parameter where the value is stored.

REST API Output Handling Parameters

You can define rules that check for specific content in the step output from a REST API request and control how the job reacts to the output. For example, you can retain content from the output as parameter values.

The following table describes the lines in output handling rules and the parameters in these lines:

Rule Parameters	Description
When the response is <response status>	Enables you to select from the following statuses that determine when to handle output: Any Response Successful Failure Specify Http Code, along with a specified value. In the specified value, you can insert an attribute by clicking . For more information, see Defining Attributes.
Extract from <request part>	Determines the part of the REST request from which to extract data, either the HEADER or the BODY.
Content type <format>	Determines one of the following content formats for the REST body: JSON XML Other
If output <element> <operator> <value>	(For data from the header) Defines a condition for data extraction, with the following parameters: Element: Enables you to specify an element in the header. You can insert an attribute by clicking. For more information, see Defining Attributes. Operator: Enables you to select from multiple operators to compare with the specified value, such as Equals to (=) or Greater than (>). For a range of values, you can select the In range operator and set the minimum and maximum values of the range.
If output <path expression> <operator> <value>	(For JSON or XML data from the body) Defines a condition for data extraction, with the following parameters: Path expression: Enables you to specify a JsonPath or XPath expression for selection of JSON or XML data. You can insert an attribute by clicking. For more information, see Defining Attributes. Operator: Enables you to select from multiple operators to compare with the specified value, such as Greater than (>) or Contains. For a range of values, you can select the In range operator and set the minimum and maximum values of the range.
If output <operator> <value>	(For data of other formats, not JSON or XML, from the body) Defines a condition for data extraction, with the following parameters: Operator: Enables you to select from multiple operators, such as Starts with, Contains or Matches regular expression. Value: Defines the string to search for. You can insert an attribute by clicking . For more information, see Defining Attributes. You can define only one condition of this type.
Do <actions>	Defines the actions to perform in response to detected output content. The following actions are available in rules, depending on the step type: Fail the job Extract and handle data Keep value in Runtime Parameter Keep value of related element Save content to file Ignore failure Complete and fail Complete & Proceed For information about action parameters, see the next table.

The following table describes additional parameters that are available to define actions:

Action Type	Parameter	Description
Extract and handle data	Extract <scope>	Determines the quantity of data to extract, as follows: Whole line: Extracts data from the whole line. Match regular expression: Enables you to match an expression that you define in the Expression field. Part of the line: Enables you to extract part of a line based on the outer boundaries of a string in the line: Start position: Enables you to select a starting point based on a specific number of characters or words from the beginning or end of the line, or relative to an exact text in the line (after the text or including it). End position: Enables you to select an endpoint based on the number of characters or words from the start position, or relative to an exact text in the line (up to the text or including it). Columnar data: Enables you to extract columnar data when the output is column-based, such as CSV format or SQL output format. You need to define the separation identifier between the columns and the column number that you want to extract.
	Trim preceding/trailing whitespace from extracted data	Determines whether to remove blank spaces that appear at the beginning or at the end of the extracted data, for extraction of part of a line or extraction of columnar data.
	Preview	Enables you to view the effect of your settings on a sample text. Based on your settings, the text that is extracted is highlighted in yellow. You can replace or edit the sample text by clicking .
	Encrypt extracted data	Replaces the extracted data with asterisks (****** ) in the logs, customer log, or output, to keep sensitive data secure.
	Keep extracted data in a runtime parameter	Stores the extracted data as the value of a runtime parameter that you define. In addition, you can choose to fail the job based on the value of this runtime parameter, using a rule with the following syntax: Fail the job if extracted data <comparison operator> <value|range>
Keep value in Runtime Parameter	Parameter name	Defines the name of the runtime parameter where the extracted value is stored for future use
	Encrypt the runtime parameter value	Replaces the value of the runtime parameter with asterisks (****** ) in the logs, customer log, or output, to keep sensitive data secure.
	Fail|Succeed the job if...	(For Verify operation completion sub-step only) Enables you to set the status of the job to failed or succeeded based on the value of the runtime parameter using a rule with the following syntax: [Fail|Succeed] the job if extracted data <comparison operator> <value|range>
Keep value of related element	Element name	Defines the name of the element with the value that you want to keep. This element is on the same level or a child element in the XML response or JSON response.
	Parameter name	Defines the name of the parameter in which to save the element value.
	Encrypt the runtime parameter value	Replaces the value of the runtime parameter with asterisks (****** ) in the logs, customer log, or output, to keep sensitive data secure.
Save content to file	File name	Defines the name of the file to save the output. You can also specify the file extension.
	Append date and time to file name	Appends the date and time to the file name, to avoid overwriting the same file every execution.
	Store the full path to the output file in a runtime parameter	Stores the full path to the output file as the value of a runtime parameter that you define.

Web Service Parameters

The following table describes the parameters available for defining the Web Service to execute.

Parameter	Description
Load WSDL File / Change WSDL File	Enables you to upload a WSDL file that describes your Web Service, either from a URL or from file. If you update and load a WSDL file that is already defined in a job type, that job type is updated only after the you open the job type in Application Integrator.
WSDL Display name	(Read-only) Presents the name of the Web Service, as derived from the WSDL file.
Web Service endpoint	Defines the endpoint where the Web Service is sent.
Authentication required	Determines whether authentication is required by the target server for the Web Service. If you select this option, you need to specify the following credentials: User name attribute: Defines an attribute that contains the username to connect to the HTTP server. Password attribute: Defines an attribute that contains the password to connect to the HTTP server.
Service	Enables you to select a specific service (from a list of detected services) to request from the application.
Operation	Enables you to select a specific operation (from a list of detected operations) to request from the application.
Edit mode	Enables you to define values for schema parameters in the SOAP request. You can choose from the following methods: In a List display, all schema parameters are hierarchically listed. For each parameter, you can enter a value and set whether to send the parameter in the request. In an XML editor, you can edit the SOAP request directly.
Advanced Settings > Headers	(List mode only) Defines any additional HTTP headers, as key-value pairs. You can type <key>=<value> lines in an Editor View or you can define keys and values in a Table View.
Advanced Settings > Override connection timeout	(List mode only) Determines the number of seconds to wait for the Web Service to respond before disconnecting.
Advanced Settings > Override Content-Type	(List mode only) Enables you to define a preferred HTTP header content type to use to execute the job (to override the default text/xml; charset=utf-8).
Append web service request to job output	Determines whether to attach the Web Service request to the job output
Append web service response to job output	Determines whether to attach the Web Service response to the job output

Web Service Output Handling Parameters

You can define rules that check for specific content in the step output from a Web Service and control how the job reacts to the output. For example, you can retain content from the output as parameter values.

Output handling rules have the following syntax:

If output <operator> <value> Do <actions>

A rule contains the following parameters:

• Operator: Enables you to select from multiple operators, such as Greater than or Contains. The CDATA Value operator enables you to enter an XPath expression as your value. For a range of values, you can select the In range operator and set the minimum and maximum values of the range.

• Value: Defines the string to search for.
  To insert an attribute in an XPath expression, click . For more information, see Defining Attributes.

• Actions: Define the actions to perform in response to detected output content.

  The following actions are available in rules, depending on the step type:

  • Fail the job

  • Keep value in Runtime Parameter

  • Keep value of related element

  • Ignore failure

  • Complete & Proceed

  The following table describes additional parameters that are available to define actions:

  Action Type	Parameter	Description
  Keep value in Runtime Parameter	Value to keep	Determines the element value to keep: Same element value Save value of inner CDATA element: Enables you to save the value of an inner cdata element from the response, expressed as a cdata XPath expression. You can insert an attribute into the XPath expression by clicking. For more information, see Defining Attributes.
  	Parameter name	Defines the name of the runtime parameter where the extracted value is stored for future use
  	Encrypt the runtime parameter value	Replaces the value of the runtime parameter with asterisks (****** ) in the logs, customer log, or output, to keep sensitive data secure.
  	Fail|Succeed the job if...	(For Verify operation completion sub-step only) Enables you to set the status of the job to failed or succeeded based on the value of the runtime parameter using a rule with the following syntax: [Fail|Succeed] the job if extracted data <comparison operator> <value|range>
  Keep value of related element	Element name	Defines the name of the element with the value that you want to keep. This element is on the same level or a child element in the XML response.
  	Value to keep	Determines the element value to keep: Same element value Save value of inner CDATA element: Enables you to save the value of an inner cdata element from the response, expressed as a cdata XPath expression. You can insert an attribute into the XPath expression by clicking. For more information, see Defining Attributes.
  	Parameter name	Defines the name of the parameter in which to save the element value.
  	Encrypt the runtime parameter value	Replaces the value of the runtime parameter with asterisks (****** ) in the logs, customer log, or output, to keep sensitive data secure.
  	Fail|Succeed the job if...	(For Verify operation completion sub-step only) Enables you to set the status of the job to failed or succeeded based on the value of the runtime parameter using a rule with the following syntax: [Fail|Succeed] the job if extracted data <comparison operator> <value|range>

Defining Attributes

This procedure describes how to define attributes in a plug-in through the Attribute Management pane. You can use the attributes as variables in various fields and parameters in plug-in steps. In addition, you can use the attributes when you define the plug-in job in the Planning domain.

Before You Begin

To define a runtime parameter attribute, ensure that you have defined Output Handling rules that include Do actions with defined runtime parameters.

Begin

1. From the Home tab in Application Integrator, select the relevant plug-in.

   The plug-in opens.

2. Click Attribute Management.

3. In the Attribute Management pane, select one of the following:

   • Connection Profile Attributes: Enables you to manage attributes that are used to connect with applications or application servers.

   • Job Properties Attributes: Enables you to manage attributes that are used during job execution.

   • Job Properties Dependencies: Enables you to create dependency events between job properties.

   • Runtime Properties: Enables you to control the display of runtime information from the job output in the Monitoring domain.

4. Click or .

5. Depending on the type of item that you want to define, do one of the following:
   • For a connection profile attribute or job attribute, complete the settings in the Add Attribute pane. For descriptions of these settings, see Job Attribute and Connection Profile Attribute Definitions.
   • For a job property dependency rule, complete the rule settings, as described in Job Property Dependency Rules.
   • For a runtime parameter attribute, select one of the runtime parameters that were defined in Output Handling rules in the plug-in steps and type a label to associate with this attribute.

6. Click Add.

Job Attribute and Connection Profile Attribute Definitions

The following categories of parameters enable you to define job attributes and connection profile attributes:

• General Settings

• Format Settings

• Validation Settings

• Load Button and Text Extraction Settings

General Settings

The following table describes the attribute settings in the General tab:

Parameter	Description
Field type	Determines one of the following field types assigned to the attribute for input of a value during job execution: Text box Text area Dropdown list Toggle button Label Password (connection profile attribute only) List (job attribute only) Text box with load button (job attribute only) Load text file (job attribute only) Load text file is available for jobs in Control-M Web but not in the Control-M client. To support the inclusion of variables, see Variables in a Loaded Text File.
Label	Defines the text that describes the field in the connection profile or job properties.
Attribute name	Defines the internal name of the attribute. No blanks allowed. The attribute name appears in lists of available attributes when you define a step. The following strings are reserved for internal use and cannot be used as the attribute name. All strings are case insensitive. app_name string object procid orderid runnumber
Description	Enables you to add a description of the attribute.
Default value	Defines a default value for the attribute. Relevant only for Text box and Text area field types.
Default field state	Determines the default state for visibility of the field: Visible: The field is visible to users. Hidden: The field does not appear in the job properties or the connection profile. Read only: The field is visible to users but cannot be changed.
Resolve Control-M variable on job's rerun	Enables you to resolve Control-M variables when the job reruns. By default, Control-M variables are resolved only in the first execution. Relevant only for Text box and Text area field types.
Use as environment variable	Enables you to set the connection profile attribute value specified by the end user as an environment variable. Relevant only for Text box, Text area, and Password field types.
Add to path	Enables you to append the connection profile attribute value specified by the end user to the PATH environment variable. Relevant only for Text box, Text area, and Password field types.

Variables in a Loaded Text File

To support the inclusion of variables in a file that is loaded through a Load text file field, you must provide another Text area field where the user can specify parameters to use as variables in the text file.

The following table describes how these elements are used in the job:

Element	User Input	Example
Text area field	List of parameter:value pairs in JSON format	{ "param_a":"value_x", "param_b":"value_y", "param_c":"value_z" }
Load text file field	A Load button enables selection of a text file.
Text file	Within the text in the loaded file, variables refer to the parameters in the Text area field, in the following format: {{<TextAreaFieldName>:<parameter_name>}}	{{additional_params:param_a}}

Format Settings

The following table describes the attribute settings in the Format tab for each field type:

Field Type	Parameter	Description
Text box Text box with load button Password (for connection profile)	When value is empty	Defines a default value to use when the user does not specify a value in the field.
	When value is not empty	Enables you to append an optional prefix and an optional suffix to the attribute value during execution.
Dropdown list	Enable users to manually input values	Enables you to select between the following types of lists: If not selected: A dropdown list is visible to the user and the user must select from a closed list of items. If selected: The user must enter a value from a closed list, but the closed list is not visible to the user. Default: If not selected
	Dropdown items	Lists definitions of at least two items in a closed list and enables you to add items and select the default item. For each item, you must define a value. If the list is visible to the user, you must also define a display name, which can be different from the internal value.
Toggle button	Checked by default	Determines whether the toggle button appears (by default) as selected or unselected.
	When checked	Defines the value of the field when the toggle button is selected.
	When unchecked	Defines the value of the field when the toggle button is not selected.
List (for job properties)	Command line format	Enables you to select the list format for multiple values: Separator: Defines a list that contains multiple items separated by space characters or some other character(s) that you specify. Pattern: Defines a list that contains multiple items that are appended with a required prefix and optional suffix and separated by space characters.

Validation Settings

The following table describes the attribute settings in the Validation tab:

Parameter	Description
Valid values	Defines the type of characters that are allowed as input in the attribute field: All Alphanumeric Numbers only Letters only
Mandatory field (non empty)	Determines whether the user must specify a value in the attribute field or can leave the field empty. For a field of type Load text file, this is the only Validation setting.
Exclude characters	Defines characters that the user cannot use in the field value.

Load Button and Text Extraction Settings

The Load Button and Text Extraction settings enable you to define the load operation and data extraction for a job property attribute with a Text box with load button field type.

The following table describes the attribute settings in the Load Operation tab:

Parameter	Description
Perform the Pre-Execute step before load operation	Enables you to execute the pre-execution step that was defined for the plug-in prior to the load operation. For more information about the pre-execution step, see Plug-in Development.
Perform the Post-Execute step after load operation	Enables you to execute the post-execution step that was defined for the plug-in after the load operation. For more information about the post-execution step, see Plug-in Development.
Interface	Enables you to select an interface to communicate with the external application for the load operation and to retrieve values from the external application: Command line REST API Web service
Interface-specific parameters	The following additional parameters enable you to execute the load operation through the selected interface: Command Line Parameters REST API Parameters Web Service Parameters The Load Operation parameters are almost identical to the corresponding parameters for plug-in steps with the following exceptions: Load operations do not support Append options for appending content to the job output. Fields that support inserting attributes enable you to select from previously defined attributes but do not enable ad-hoc creation of a new attribute. The REST API body supports only ASCII data, and not form-data.

The following table describes the attribute settings in the Extract values list tab for each interface type selected in the Load Operation tab:

Interface	Parameter	Description
Command Line	Extract data from lines	Defines a filter for data extraction from lines in the output of the load operation, based on a comparison operator and value. The comparison operator can be one of the following: Any (no value required) Starts with Contains Ends with Matches regular expression
	Extract	Determines the quantity of data to extract, as follows: Whole line: Extracts data from the whole line. Match regular expression: Enables you to match an expression that you define in the Expression field. Part of the line: Enables you to extract part of a line based on the outer boundaries of a string in the line: Start position: Enables you to select a starting point based on a specific number of characters or words from the beginning or end of the line, or relative to an exact text in the line (after the text or including it). End position: Enables you to select an endpoint based on the number of characters or words from the start position, or relative to an exact text in the line (up to the text or including it). Columnar data: Enables you to extract columnar data when the output is column-based, such as CSV format or SQL output format. You need to define the separation identifier between the columns and the column number that you want to extract.
	Trim preceding/trailing whitespace from extracted data	Determines whether to remove blank spaces that appear at the beginning or at the end of the extracted data, for extraction of part of a line.
	Preview	Enables you to view the effect of your settings on a sample text. Based on your settings, the text that is extracted is highlighted in yellow. You can replace or edit the sample text by clicking .
REST API	Content type	Determines one of the following content formats for the REST body: JSON: Extracts content from JSON data, based on a JSONPath that you specify. XML: Extracts content from XML data, based on an XPath that you specify. Other: Extracts content from data of another type (not JSON or XML). The remaining parameters are the same as the parameters described for the Command Line interface.
Web Service	Extract value of element	Defines the name of the element with the value that you want to keep. This element is on the same level or a child element in the XML response.
	Value to keep	Determines the element value to keep: Same element value Save value of inner CDATA element: Enables you to save the value of an inner cdata element from the response, expressed as a cdata XPath expression.

Job Property Dependency Rules

You can define rules that create dependencies between job property attributes. These rules control the display status of one or more attributes based on the value of another attribute.

Each rule contains the following parts:

• A condition based on the value of one attribute:

  If attribute <attribute name> <comparison operator> <value>
  

• One or more actions to set the display status of another attribute:

  Do <other attribute name> <display status>

The rule contains the following parameters:

• Attribute name: Defines the name of the attribute with the valueyou want to check. This must be an attribute with a closed set of values (an array) in a Dropdown list or Toggle button field.

• Comparison operator: Defines the operator for the comparison with the specified value, as follows:
  • Equals to (=)
  • Not equal to (!=)
• Value: Enables you to select a value from the array defined for the attribute.

• Other attribute name: Defines the name of another attribute with a display status that is set based on the value of the first attribute. Each defined attribute can be used in only one Do line.

• Display status: Determines one of the following display statuses of the attribute:

  • Visible

  • Hidden

  • Read only