Optimize for Infrastructure Version 9.8
 —  Guide for Enterprise Transaction Systems  —

Defining a Common Action for All Rules

This document covers the following topics:


General Information

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.

Overview

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.

Top of page

Configuring the Web Service Action in Optimize

So that Optimize can send rule violations to a web service, you have to

This section briefly explains how to configure a web service action with the name "CommonAction". For more detailed information, see the following Optimize guides:

Start of instruction setTo define the action

  1. Log on to My webMethods.

  2. Go to Navigate > Applications > Administration > System-Wide > Environments > Define Environments.

  3. Click the name of the environment for which you want to define the action.

  4. Select the Configure Servers tab.

  5. Expand Analytic Engine in the tree and click WSAction Settings.

  6. 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>
  7. If your web service is not running on localhost:8080, adapt the corresponding line in the above code.

  8. Save your changes.

  9. Click the Finish button.

  10. Deploy the updated environment.

  11. Restart the Analytic Engine.

  12. Add the action you have just defined to all required rules (for example, to the built-in rule "EntireX Broker Connection Error").

Top of page

Generating and Testing the Web Service with EntireX

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:

The following topics are covered below:

Using Software AG Designer

When using the Software AG Designer, you can use the integrated Tomcat server.

Start of instruction setTo generate and test a web service with Software AG Designer

  1. Install the Software AG Designer with EntireX.

  2. Open the Project Explorer view.

  3. Create a general project, for example, with the name "CommonAction".

  4. In the new project, create a Software AG IDL file, for example, with the name "CommonAction.idl".

  5. 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.

  6. Select your IDL file in the Project Explorer view and then proceed as follows:

    1. Invoke the context menu and choose Properties.

    2. Go to the EntireX Web Service Wrapper page, and then to the Mapping tab.

    3. Adapt the settings in the Broker ID and Server Address text boxes to your requirements.

  7. Select your IDL file in the Project Explorer view once more and then proceed as follows:

    1. Invoke the context menu and choose Generate Web Service from Software AG IDL.

    2. 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.

  8. Select your IDL file in the Project Explorer view once more and then proceed as follows:

    1. Invoke the context menu and choose Test Software AG IDL.

    2. 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 Ping button, you can find out whether the specified server is active.

    3. In the RuleName (AV) text box, specify a name. This can be any name you like.

    4. Choose the Call button.

      When you later check the output on the specified server, you will see that name.

  9. Double-click the generated XMM file in the Project Explorer view, and then go to the XML Samples tab.

  10. Select the generated AAR file in the Project Explorer view and then proceed as follows:

    1. Invoke the context menu and choose Test EntireX Web Service.

      This displays the XML Tester view.

    2. 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.

    3. 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.

Using EntireX

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).

Start of instruction setTo add a web service with EntireX

  1. 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

  2. Install the web server and then start it.

    The description below applies to Tomcat.

  3. 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.

  4. Copy the file entirex.jar into the <TomcatHome>\webapps\wsstack\WEB-INF\lib directory.

  5. 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.

  6. Copy the file CommonAction.aar into the <TomcatHome>\webapps\wsstack\WEB-INF\services directory.

  7. 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>
  8. 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.

Top of page

Creating a Natural Subprogram

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:

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.

Top of page

Sample Natural Output

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.

EntireX Broker Connection Error

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

EntireX Server Available Error

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

Adabas Server Not Active

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

Natural Development Server Not Active

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

Top of page