This document covers the following topics:
When a rule is violated, you can have Optimize trigger a web service action. For example, suppose that you defined a rule to determine when a Natural Development Server goes offline. Also suppose that Natural can call a service that attempts to restart the Natural Development Server. You can define an action that, when the Natural Development Server rule is violated, invokes a web service that calls a Natural RPC server that executes a subroutine which restarts the Natural Development Server.
This chapter explains how you add a common action to your rules, including the built-in rules such as "EntireX Broker Connection Error", "EntireX Server Available Error", "Adabas Server Not Active" or "Natural Development Server Not Active". In addition to the action, you have to generate a web service using EntireX, and you have to create a Natural subprogram which is able to process the information from the web service. This is also explained in this chapter.
The above graphic shows a SOAP call that is sent from the Analytic Engine of Optimize to a Tomcat server in the case of a rule violation. The Tomcat server invokes a web service which sends information about the rule violation to the Natural subprogram.
So that Optimize can send rule violations to a web service, you have to
configure a web service action, and
add the web service action to the required rules.
This section briefly explains how to configure a web service action with the name "CommonAction". For more detailed information, see the following Optimize guides:
Administering webMethods Optimize, chapter Setting Up Web Service Actions.
Optimizing BPM and System Resources with BAM: webMethods Optimize User's Guide, chapter Defining Rules, section Specifying Alert Actions.
To define the action
Log on to My webMethods.
Go to Navigate > Applications > Administration > System-Wide > Environments > Define Environments.
Click the name of the environment for which you want to define the action.
Select the Configure Servers tab.
Expand Analytic Engine in the tree and click WSAction Settings.
Copy the following code and paste it into the text box for the WSAction Settings for your Analytic Engine.
<?xml version="1.0" encoding="UTF-8"?>
<properties>
<property name="action">
<string meta="name">CommonAction</string>
<string meta="url">http://localhost:8080/wsstack/services/CommonAction?wsdl</string>
<string meta="method">CommonAction</string>
<list>
<element><string>RuleName</string></element>
<element><string>RuleInstanceName</string></element>
<element><string>RuleDefinition</string></element>
<element><string>RuleEvaluation</string></element>
<element><string>RuleSla</string></element>
<element><string>RuleCustomer</string></element>
<element><string>RuleSeverity</string></element>
<element><string>RuleStatus</string></element>
<element><string>Attributes</string></element>
<element><string>Time</string></element>
</list>
</property>
</properties>
If your web service is not running on localhost:8080,
adapt the corresponding line in the above code.
Save your changes.
Click the button.
Deploy the updated environment.
Restart the Analytic Engine.
Add the action you have just defined to all required rules (for example, to the built-in rule "EntireX Broker Connection Error").
You will now generate and test a web service which receives a rule violation from Optimize and sends data to Natural. You can either do this with the Software AG Designer in which EntireX has been installed, or with EntireX. Use the description in the corresponding section below.
For more information on the EntireX functions mentioned below, see the following guides within the EntireX documentation:
EntireX XML/SOAP Wrapper, section XML/SOAP Runtime Environment.
EntireX Administration under Windows, section Configuring the EntireX XML/SOAP Listener.
The following topics are covered below:
When using the Software AG Designer, you can use the integrated Tomcat server.
To generate and test a web service with Software AG Designer
Install the Software AG Designer with EntireX.
Open the Project Explorer view.
Create a general project, for example, with the name "CommonAction".
In the new project, create a Software AG IDL file, for example, with the name "CommonAction.idl".
Copy the following code, paste it into the editor for the new IDL file (replace any existing code with the new code), and save your changes.
/* Interface for Optimize Common Action
library 'CommonAction' is
program 'ACTALLS':'CommonAction' is
define data parameter
1 RuleName (AV) In /* name of the base rule, an instance of which has fired
1 RuleInstanceName (AV) In /* name of the rule instance that fired
1 RuleDefinition (AV) In /* definition of the rule
1 RuleEvaluation (AV) In /* evaluation of the rule
1 RuleSla (AV) In /* Service Level Agreement (SLA) associated with the rule
1 RuleCustomer (AV) In /* customer associated with the rule
1 RuleSeverity (AV) In /* severity of the rule
1 RuleStatus (AV) In /* compliance status (Rule Violation or In Compliance) of the rule
1 Attributes (AV/V) In /* Array of strings containing key = value pairs of all attributes in the rule diagnosis
1 Time (AV) In /* time that the rule went out of compliance
end-define
ACTALLS in the above code is the sample Natural
program which is explained later in this chapter.
Select your IDL file in the Project Explorer view and then proceed as follows:
Invoke the context menu and choose .
Go to the EntireX Web Service Wrapper page, and then to the Mapping tab.
Adapt the settings in the Broker ID and Server Address text boxes to your requirements.
Select your IDL file in the Project Explorer view once more and then proceed as follows:
Invoke the context menu and choose .
In the resulting dialog box, select the Deploy service check box, and then deploy the EntireX web service.
The Console view should now inform you that your web service has successfully been deployed, and additional files should now be shown in the Project Explorer view.
Select your IDL file in the Project Explorer view once more and then proceed as follows:
Invoke the context menu and choose .
In the resulting dialog box, make sure that the settings in the Broker and Server text boxes are correct for your requirements, and that the specified server is active.
Tip:
Using the button, you can find out
whether the specified server is active.
In the RuleName (AV) text box, specify a name. This can be any name you like.
Choose the button.
When you later check the output on the specified server, you will see that name.
Double-click the generated XMM file in the Project Explorer view, and then go to the XML Samples tab.
Select the generated AAR file in the Project Explorer view and then proceed as follows:
Invoke the context menu and choose .
This displays the XML Tester view.
Copy the code that is shown on the XML Samples tab (make sure to use the code for the "Request Document" action), and paste it in the upper Text View tab of the XML Tester view.
Choose the green Play button which is provided in the local toolbar of the XML Tester view, and then check the result at the bottom of the XML Tester view.
When using EntireX (without the Software AG Designer), you have to install a web server. You can use, for example, Tomcat. In addition, you have to download the file CommonAction.aar from Empower (see below).
To add a web service with EntireX
Install EntireX.
In a later step, you will need to copy the following files from the EntireX installation: wsstack.war and entirex.jar. You can find them in the following directories:
<EntireXHome>\WS-Stack\webapp\wsstack.war
<EntireXHome>\EntireX\classes\entirex.jar
Install the web server and then start it.
The description below applies to Tomcat.
Copy the file wsstack.war into the <TomcatHome>\webapps directory.
Wait until the WAR file has been unpacked. You will find a <TomcatHome>\webapps\wsstack directory.
Copy the file entirex.jar into the <TomcatHome>\webapps\wsstack\WEB-INF\lib directory.
Log in to Empower (https://empower.softwareag.com/), go to Products > Download Components > Optimize for Infrastructure and look for the component "Rule Action". Download this component (CommonAction.zip) and then unpack the ZIP file to get the file CommonAction.aar.
Copy the file CommonAction.aar into the <TomcatHome>\webapps\wsstack\WEB-INF\services directory.
Edit the file <TomcatHome>\webapps\wsstack\WEB-INF\conf\axis.xml and add the following new parameter:
<parameter name="EntireX-XML-Listener"> <parameter name="services" location="./exx.xml" /> </parameter>
Add a new file <TomcatHome>\webapps\wsstack\WEB-INF\conf\exx.xml with the following content:
<?xml version="1.0" encoding="utf-8" ?>
<serviceGroup>
<service name="CommonAction">
<exx-brokerID>localhost:1971</exx-brokerID>
<exx-service>RPC/SRV1/CALLNAT</exx-service>
</service>
</serviceGroup>
Here you must enter your EntireX Broker and your Natural RPC server
on which the ACTALLS subprogram is located.
If the web service now receives an action from Optimize, it will
call the Natural subprogram ACTALLS.
You have to create a Natural subprogram which is able to process the information from the web service.
The following sample Natural subprograms are provided in the
SYSEDM library:
ACTALLACTALL can be used as common action for any rule. It
writes a message, including rule and instance details, to the output. If the
program runs on a mainframe and the rule severity is "1 -
Critical" or "2 - High", an
informational message concerning the rule violation is sent to the operator
console.
ACTALL1ACTALL1 is an enhanced version of ACTALL.
It does not only write informational messages to the output and console, it
also performs an action as a showcase. If the specified Adabas server or
Natural Development Server goes offline on the mainframe, it is restarted
automatically. The program uses Entire System Server (NPR) to restart the
service. On UNIX or Windows, a shell command is executed to restart an Adabas
server. A maintenance time window can be specified in which the action will not
be performed.
You can activate one of the above sample subprograms. To do so, you
have to save the sample program under the name ACTALLS, adjust it
to your needs and catalog it.
If you use ACTALL1 as the template for
ACTALLS, you must edit ACTALLS before cataloging it.
You have to adjust the maintenance time window, the instance name and the
console command to your needs. The corresponding lines are indicated by
"<== adjust".
Caution:
Do not modify the original ACTALL and
ACTALL1 programs which are delivered with Natural. These programs
might be overwritten when a Natural fix is loaded.
Note:
In Optimize, you can enable and disable a rule. Moreover, you can
edit the rule expression and specify a time window in which the rule should not
fire at all.
The following parameters are passed to ACTALLS when it is
called after a rule violation:
| Parameter | Format | Description |
|---|---|---|
RULENAME |
(A) DYNAMIC |
The name of the base rule, an instance of which has fired. The available rule names are listed in the section KPI Definitions for Infrastructure Monitoring with the built-in rules in the column Administration Name. |
RULEINSTNAME |
(A) DYNAMIC |
The name of the rule instance that fired and the reason why it fired according to the naming template in the Optimize rule definition. |
RULEDEFINITION |
(A) DYNAMIC |
The definition of the rule according to the rule expression in the Optimize rule definition. |
RULEEVALUATION |
(A) DYNAMIC |
The evaluation of the rule, how many intervals with critical values have been found. |
RULESLA |
(A) DYNAMIC |
The Service Level Agreement (SLA) associated with the rule. |
RULECUSTOMER |
(A) DYNAMIC |
The customer associated with the rule. |
RULESEVERITY |
(A) DYNAMIC |
The severity of the rule. The possible values are available in
the program array L_SEVERITY.
|
RULESTATUS |
(A) DYNAMIC |
The rule compliance status such as "Rule Violation". |
ATTRIBUTES |
(A/1:*) DYNAMIC |
An array of strings containing "key = value" pairs of all attributes in the rule diagnosis, such as "HostName = pcxyz03". |
EVENTTIME |
(A) DYNAMIC |
The time the rule went out of compliance. |
The samples in this section show the Natural output from the web
service action which has been defined for the built-in rules listed below. The
sample output for EntireX has been generated using the general template
ACTALL, whereas the sample output for the Adabas server and
Natural Development Server has been generated using the ACTALL1
template which has been adjusted to restart these instances. For the Natural
Development Server, a sample of a console message is shown as
well.
Optimize Rule Violated => EntireX Broker Connection Error Instance = slesvnat3.EntireX.1971 not available Severity = 2 - High Time = 2012-02-01 15:13:28.3 MEZ EntireXBrokerState = 0.0 Product = EntireX EntireXPort = 1971 HostName = slesvnat3
Optimize Rule Violated => EntireX Server Available Error Instance = slesvnat3.EntireX.1971.RPC/RAILWAY/JAVA not available Severity = 2 - High Time = 2012-02-01 14:08:07.970 MEZ EntireXServer = RPC/RAILWAY/JAVA Product = EntireX EntireXServerState = 0.0 EntireXPort = 1971 HostName = slesvnat3
Optimize Rule Violated => Adabas Server Not Active Instance = daeplex_daef.Adabas Server.65535 DB65535 not active Severity = 2 - High Time = 2012-02-02 13:43:08.153 MEZ Product = Adabas Server AdabasState = 0.0 AdabasServer = 65535 DB65535 HostName = daeplex_daef Optimize Rule Action => daeplex_daef.Adabas Server.65535 DB65535 started. Time: 2012-02-02 13:43:24
Optimize Rule Violated => Natural Development Server Not Active Instance = daeplex_daef.NDV Server.NDV42 (4762) - Local not active Severity = 2 - High Time = 2012-02-16 17:05:25.830 CET NdvServer = NDV42 (4762) - Local Product = NDV Server NdvState = 0.0 NdvHttpMonitorState = 1.0 HostName = daeplex_daef Optimize Rule Action => daeplex_daef.NDV Server.NDV42 (4762) started. Time: 2012-02-16 17:05:42
The following message is written to the operator console:
17.05.42 STC37644 +Optimize Rule Violated => daeplex_daef.NDV Server.NDV42 (4762) - 952 952 Local not active. Severity: 2 - High. Time: 2012-02-16 17:05:25.830 952 CET 17.05.42 STC37644 +Optimize Rule Action => daeplex_daef.NDV Server.NDV42 (4762) started. Time: 2012-02-16 17:05:42