A Configuring Custom Process

This chapter describes custom process configuration in the OPMN opmn.xml file.

It features the following topics:

Custom Process Module Configuration
Custom Process Minimum Configuration
Custom Process Complete Configuration
Custom Process Attribute Descriptions

A.1 Custom Process Module Configuration

The following lines load and identify the custom process module. Management of custom processes by the process module are identified by the module id.

<module path="ORACLE_HOME/opmn/lib/libopmncustom.so">
   <module-id id="CUSTOM" />
</module>

A.2 Custom Process Minimum Configuration

The following lines represent the minimum configuration for a custom process. Default values are assigned to all other configuration elements and attributes for the custom process.

<ias-component id="Custom">
   <process-type id="Custom" module-id="CUSTOM">
   <process-set id="Custom" numprocs="1">
      <module-data>
         <category id="start-parameters">
            <data id="start-executable" value="Your start executable here" />
         </category>
      </module-data>
   </process-set>
   </process-type>
</ias-component>

A.3 Custom Process Complete Configuration

Example A-1 show a complete configuration for a custom process. It contains all possible configuration elements and attributes for a custom process.

A custom process can be part of any other system component. In such cases, the process-type element in Example A-1 must be part of the component configuration.

A.3.1 Ping

The custom module provides the framework for pinging a custom process in one of two ways:

HTTP ping
script ping

The type of ping can be configured by specifying the appropriate data in the ping-parameters category. The sample configuration example Example A-1 shows a custom process using HTTP ping. Example A-1 is an example of script ping that you can substitute into the component configuration.

Example A-1 Custom Process Complete Configuration

<ias-component id="Custom" status="enabled" id-matching="false">
   <environment>
      <variable id="TEST_ENV_VARIABLE" value="/your/test/value" 
      append="false"/>
   </environment>
   <process-type id="Custom" module-id="CUSTOM">
   <process-set id="Custom" restart-on-death="true" numprocs="1">
      <module-data>
         <category id="start-parameters">
            <data id="start-executable" value="Your start executable here" />
            <data id="start-args" value="Your start args here" />
            <data id="append-req-args" value="Arguments appended to the end of the
             start command"/>
            <data id="java-proc" value="true"/>
         </category>
         <category id="stop-parameters">
            <data id="stop-executable" value="Your stop executable here" />
            <data id="stop-args" value="Your stop args here" />
            <data id="append-req-args" value="Arguments appended to the end of the
             stop command"/>
         </category>
         <category id="restart-parameters">
            <data id="restart-executable" value="Your restart executable here"/>
            <data id="restart-args" value="Your restart args here" />
            <data id="append-req-args" value="Arguments appended to the end of the
             restart command"/>
         </category>
         <category id="ping-parameters">
            <data id="ping-type" value="http" />
            <data id="ping-url" value="/your/ping/url" />
            <data id="ping-host" value="abc.company.com" />
            <data id="ping-port" value="7777" />
            <data id="ping-limit" value="3" />
            <data id="ping-timeout" value="300" />
         </category>
         <category id="ready-parameters">
            <data id="use-ping-for-ready" value="false" />
         </category>
      </module-data>
   </process-set>
   </process-type>
</ias-component>

Pinging with a script can be configured as shown in Example A-2.

Example A-2 Ping Type Script

<category id="ping-parameters">
   <data id="ping-type" value="script" />
   <data id="script-executable" value="Ping executable here" />
   <data id="script-args" value="Ping arguments here " />
</category>

You can use pinging (when available) for determining the readiness of a process. This indicates that OPMN needs confirmation that a managed process has started successfully after creation. Processes can inform OPMN of their ready status in various ways. The custom module enables these processes to communicate readiness through pinging. If you configure pinging for a custom process, you can also use this mechanism to determine if the process is ready. You can choose not to configure any mechanism for determining readiness in which case the custom module just assumes that the process started successfully.

Note:

The ready ping, if configured, is created soon after the process is created. If the process takes a while to initialize and respond to pings, then using pinging for determining readiness is not appropriate. This is because if the process does not respond to the "ready ping", OPMN determines that the process did not start correctly and stop it.

A.4 Custom Process Attribute Descriptions

This section describes the attributes that are specific for a custom process. This section also provides attribute descriptions of the attributes.

The custom process attributes are described with the following format:

Title: This is the attribute name and value being defined. For example, id="Custom".
Required: This field defines whether or not the attribute is required in the component definition.
Default: This defines the default value assigned to the attribute. The default value appears in the installed version of the opmn.xml file or is assigned internally if the attribute is not present.
Valid values: If applicable, this field defines the valid values for the attribute. For example, custom.
Path: This field defines in which elements the attribute can appear. For example, ias-component.

id="Custom"

Required: true
Default: none
Valid values: Any id of your choice
Path: ias-component
Path: ias-component/process-type
Path: ias-component/process-type/process-set

This id is required and can be any name you choose. The id cannot be a duplicate of existing names.

module-id="CUSTOM"

Required: true
Default: none
Valid values: The same as the module-id specified in Appendix A for configuring a custom process.
Path: ias-component/process-type

The module-id associates the process with a module. For Custom processes, this id has to match the module-id specified in Process Module Configuration for the Custom module.

id="start-parameters"

Required: true
Default: none
Path: ias-component/process-type/process-set/module-data/
category

The start-parameters category contains child elements specifying the start executable and start arguments.

id="java-proc"

Required: false
Default: false
Valid values: true or false
Path: ias-component/process-type/process-set/module-data/category/
data

This data element specifies if the process is a Java process. If set to true, OPMN adds the default managed process system properties to the start-args.

id="start-executable"

Required: true
Default: none
Valid values: a valid executable to run
Path: ias-component/process-type/process-set/module-data/category/
data

This data element specifies the name of the executable to be started.

id="start-args"

Required: false
Default: none
Valid values: Valid arguments to the executable specified by start-executable data element.
Path: ias-component/process-type/process-set/module-data/category/
data

The value of this data element should be a string containing all the arguments for the start executable. Multiple data elements with this id should not be specified.

id="append-req-args"

Required: false
Default: none
Path: ias-component/process-type/process-set/module-data/
category

The value of append-req-args is appended to the end of the constructed start command.

id="stop-parameters"

Required: false
Default: none
Path: ias-component/process-type/process-set/module-data/
category

The stop-parameters category contains child elements specifying the stop executable and stop arguments. If this category is not configured, OPMN stops the process with the kill command.

id="stop-executable"

Required: false
Default: none
Path: ias-component/process-type/process-set/module-data/category/
data

This data element specifies the name of the executable to be used for stopping the process.

id="stop-args"

Required: false
Default: none
Path: ias-component/process-type/process-set/module-data/category/
data

The value of this data element should be a string containing all the arguments to the stop executable. Multiple data elements with this id should not be specified.

id="restart-parameters"

Required: false
Default: none
Path: ias-component/process-type/process-set/module-data/
category

The restart-parameters category contains child elements specifying the restart executable and restart arguments. This category needs to be configured if the process has an explicit restart command. In the absence of a restart command, a stop followed by the start command executes whenever the process needs to be restarted.

When restart data is specified, OPMN assumes that the process ID of the process remains the same after a restart. If there is no explicit restart command available for the process, a stop followed by a start is issued. In this scenario, a process ID change is acceptable.

id="restart-executable"

Required: false
Default: none
Valid values: A valid restart executable name
Path: ias-component/process-type/process-set/module-data/category/
data

This data element specifies the name of the executable to be used for restarting the process.

id="restart-args"

Required: false
Default: none
Valid values: valid arguments to the restart executable
Path: ias-component/process-type/process-set/module-data/category/
data

The value of this data element should be a string containing all the arguments to the restart executable. Multiple data elements with this id should not be specified.

id="append-req-args"

Required: false
Default: none
Path: ias-component/process-type/process-set/module-data/category

The value of append-req-args is appended to the end of the constructed restart command.

id="ping-parameters"

Required: false
Default: none
Path: ias-component/process-type/process-set/module-data/
category

Custom processes that are pinged through the HTTP protocol must specify this category. This module data category consists of all the data required to perform such a ping.

id="ping-type"

Required: false
Default: none
Valid values: http, script, integrator
Path: ias-component/process-type/process-set/module-data/category/
data

Custom processes that wish to be pinged have to specify this module data.