Working with the Remote Trigger

  • Article
Caution
Test the script(s), processes and/or data file(s) thoroughly in a test environment, and customize them to meet the requirements of your organization before attempting to use it in a production capacity.  (See the legal notice here)

 

Note: The workflow sample mentioned in this article can be downloaded from the Opalis project on CodePlex:  https://opalis.codeplex.com

 

Overview

The Remote Trigger is designed to permit a workflow  in Opalis to be triggered from a location on a network remote to the Opalis installation.  It uses the Opalis Web Service (documented in the Users Guide) and hence the Opalis Operator Console service where this web service is hosted.

The AD User ID/Password used by the Remote Trigger would be no different from any other AD user with a need to access workflows via the Opalis Operator Console.  One must create/update the user ID such that the user has rights to log into the Operator Console, view the workflows one want the ID to be able to trigger, and has permissions to actually run the workflow.

The Remote Trigger uses the same connection requirements as a user would need to connect to the Opalis Operator Console including connection type (http/https) and port assignment.

The installation files for the Remote Trigger can be found on the Opalis installation CD.  Documentation on the install can be found in the Opalis Admin Guide.  Documentation on the Remote Trigger can be found in the “docs” directory (shown below) after the Remote Trigger has been installed.  Please note the setup requirements in the admin guide after running the setup.  They are important and the Remote Trigger won’t work unless these steps are followed.  Note that the Remote Trigger would typically be installed on a system remote to the Opalis install (the place where one wanted to remotely trigger a workflow from) and not on the Opalis server as shown here.

image

The Remote Trigger system has two main components. A Storage component that selectively stores notifications from external systems and a Forwarding component that forwards the stored notifications to Integration Server. The combination of the store and forward components provides a reliable notification delivery system.

Store Component

The Storage component of the Remote Trigger system is a Java based console application that can be invoked by external systems to trigger Policies. When some event occurs in an external system that should result in the triggering of a policy the external system can invoke that Store and pass along a notification that contains information about the event that occurred. How the store handles a notification is determined by a rules file that is included in the command line when the store is invoked. In particular the rules file contains rules for parsing data from the notification so that it can be passed to the policy as well as rules that can be used to filter notifications that should not be forwarded.

The Store can be invoked by calling the RemoteTrigger batch file which can be found in the RemoteTrigger\bin directory. Usage of this batch files is as follows:

Flag

Definition

Required

-rules

 Specifies the absolute or relative path to the rules file.

Yes

-file

 Specifies the absolute or relative path to a file containing the notification text.

No*

-text

 The notification text.

No*

* Either the one of the -file or -text parameter must be included.

Examples:

  • RemoteTrigger.bat -rules myrules.xml -file notification.txt
  • RemoteTrigger.bat -rules myrules.xml -text "This is a notification"

Rules File

The rules file is an XML formatted file that contains rules used to extract information from that notification so that should be forwarded to Integration Server as well as rules used to determine whether or not the notification should be forwarded.  Refer to the section entitled “Authoring a Rules File” later in this document for details.

Forwarding Service

The Forwarding Service is a java based daemon that continuously monitors the Store for pending notifications. Each stored notification is processed in sequence by the forwarding service and results in the triggering of a policy. In the event that the Forwarding Service is unable to trigger a policy it will simply return the notification to the Store so that it can be processed at a later date.

Starting the Forwarding Service from the command line

The Forwarding Service can be started from the command line by calling the Run-Service.bat batch file which can be found in the RemoteTrigger\bin directory.

C:\Program Files\Opalis Software\RemoteTrigger\bin\Run-Service.bat

Running the Forwarding Service as a Windows Service

Alternatively you can install and run the Forwarding Service as a Windows service.

You can install the Forward Service by running the Install-Service-NT.bat batch file as follows:

  1. Open a command prompt and go to the 'Opalis Software\RemoteTrigger\bin' directory.
  2. Type Install-Service-NT and press enter.
  3. Open the Services console by running services.msc.
  4. Select the Opalis Forwarding Service and click Start.

Remote Trigger Assistant

The Remote Trigger Assistant is a java based console applications that is used to manage the credentials used by the Remote Trigger system to trigger Integration Server policies. Using the assistant you can securely define one ore more connections to the Operator Console and then safely reference these connections by name in the rules files used to process a notification.

By default only local system administrators have access to the stored credentials.

Starting the Assistant

  1. Open a command prompt and go to the 'Opalis Softrware\RemoteTrigger\bin' directory
  2. Type Run-Assistant and press enter.
  3. Follow the on-screen instructions.

Authoring a Rules File

Lets say we would like to handle notifications that look something like the following sample:

 Ticket   : 123456 

Severity : High

From     : Smith, John

Received : 2009-01-10

Summary  : Require additional hard drive space on server srv-010

Pick your favorite XML editor and create a new file called "rules.xml". Nothing about that name is special. Now lets add the three lines of text that all rules file have:

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Rules>

</Rules>

Each rules file can handle multiple types of notifications, but in this example we are going define rules for handling a single type of notification. So we add the following lines to our rules file.

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Rules>

    <Rule>

    </Rule>

</Rules>

That forms the skeleton of our rules file. Now lets define some rules for extracting properties values from our notification. Start by adding the following text to your rules file.

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Rules>

<Rule>

        <Properties>

        </Properties> 

    </Rule>

</Rules>

Property values can be extracted from a notification by specifying the line(s) to be extracted or with regular expressions and these rules are define using the SelectLine and SelectGroup elements respectively. In this example we will be using the SelectGroup element to define rules for extracting property values using regular expressions.

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Rules>

    <Rule>

        <Properties>

            <SelectGroup name="Ticket">Ticket\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Severity">Severity\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="From">From\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Received">Received\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Summary">Summary\s+:\s(\w+)</SelectGroup>

        </Properties> 

    </Rule>

</Rules>

Now that we have added some rules for extracting properties from our notification lets add add some more rules to determine whether or not a notification should be handled. We start by adding the Filters element to our rules file.

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Rules>

    <Rule>

        <Properties>

            <SelectGroup name="Ticket">Ticket\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Severity">Severity\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="From">From\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Received">Received\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Summary">Summary\s+:\s(\w+)</SelectGroup>

        </Properties> 

        <Filters>

        </Filters>

    </Rule>

</Rules>

Each filter file that we add to our rules file will evaluate a specific property against some specified criteria. Also, note that each filter is given a name which allows and this name can be used to build a filter expression which can be used to combine multiple filter rules together using boolean logic rules. Suppose we would like to only handle notifications that have a severity of "High" or "Critical". This could be accomplished by by adding the following filtering rules to our rules file.

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Rules>

    <Rule>

        <Properties>

            <SelectGroup name="Ticket">Ticket\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Severity">Severity\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="From">From\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Received">Received\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Summary">Summary\s+:\s(\w+)</SelectGroup>

        </Properties> 

        <Filters filter="Critical OR High">

            <Filter name="Critical" property="Severity" relation="equalTo">Critical</Filter>

            <Filter name="High" property="Severity" relation="equalTo">High</Filter>

        </Filters>

    </Rule>

</Rules>

Now that we have defined rules for extracting properties and filtering, lets add another rule to trigger a policy. When adding a trigger policy rule we need to specify the fully qualified path to the policy that we would like to trigger which includes the folders in which the policy is contained as well as the name of the policy. We also need to specify the name of the connection that we would like to use and this connection refers to a connection that we added to the Connection Store using the Remote Trigger Assistant.

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Rules>

    <Rule>

        <Properties>

            <SelectGroup name="Ticket">Ticket\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Severity">Severity\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="From">From\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Received">Received\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Summary">Summary\s+:\s(\w+)</SelectGroup>

        </Properties> 

        <Filters filter="Critical OR High">

            <Filter name="Critical" property="Severity" relation="equalTo">Critical</Filter>

            <Filter name="High" property="Severity" relation="equalTo">High</Filter>

        </Filters>

<Actions>

            <TriggerPolicy name="New Incident" connection="Main"> 

            </TriggerPolicy>

</Actions>

    </Rule>

</Rules>

Now lets say that the policy that we want to trigger starts with a "Custom Start" that has one or more parameters. We can expand the trigger policy rule with parameter rules which handle assigning property values to each parameter of the Custom Start object. In the following example we will use the VariableParameter element which is used to assign parameter values from properties that have been extracted from the body of the notification.

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Rules>

    <Rule>

        <Properties>

            <SelectGroup name="Ticket">Ticket\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Severity">Severity\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="From">From\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Received">Received\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Summary">Summary\s+:\s(\w+)</SelectGroup>

        </Properties> 

        <Filters filter="Critical OR High">

            <Filter name="Critical" property="Severity" relation="equalTo">Critical</Filter>

            <Filter name="High" property="Severity" relation="equalTo">High</Filter>

        </Filters>

        <Actions>

            <TriggerPolicy policy="New Incident" connection="Main"> 

                <VariableParameter name="ID" property="Ticket"/>

                <VariableParameter name="Severity" property="Severity"/>

                <VariableParameter name="From" property="From"/>

                <VariableParameter name="Received" property="Received"/>

                <VariableParameter name="Summary" property="Summary"/> 

            </TriggerPolicy>

        </Actions>

    </Rule>

</Rules>

Finally we are going to add a default notification handling rule to cleanup incoming notification files once they have been handled by the store.

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Rules>

    <Rule>

        <Properties>

            <SelectGroup name="Ticket">Ticket\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Severity">Severity\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="From">From\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Received">Received\s+:\s(\w+)</SelectGroup>

            <SelectGroup name="Summary">Summary\s+:\s(\w+)</SelectGroup>

        </Properties> 

        <Filters filter="Critical OR High">

            <Filter name="Critical" property="Severity" relation="equalTo">Critical</Filter>

            <Filter name="High" property="Severity" relation="equalTo">High</Filter>

        </Filters>

        <Actions>

            <TriggerPolicy policy="New Incident" connection="Main"> 

                <VariableParameter name="ID" property="Ticket"/>

                <VariableParameter name="Severity" property="Severity"/>

                <VariableParameter name="From" property="From"/>

                <VariableParameter name="Received" property="Received"/>

                <VariableParameter name="Summary" property="Summary"/> 

            </TriggerPolicy>

        </Actions>

    </Rule>

    <Rule name="Cleanup">

        <Actions>

            <DeleteNotification/>

        </Actions>

    </Rule>

</Rules>

 

Share this post :