Manual start of a ruleset

Normally, ELOas executes the defined rulesets based on intervals. However, there are processes that are so complex in their execution that they cannot be run in short intervals. Still, they must become active as quickly as possible after a certain change has taken place. There is an option to manually execute a ruleset through a URL (or rather, via script).

If you execute rules via an "HTTP-GET" or "HTTP-RUN" command in ELOas 20, they need to be validated with a ticket. You need to attach a valid ticket to the corresponding ELOas URL, e.g:

http://localhost:9060/ELOas/actions?cmd=get&name=test&ticket=935666A2E27D8AB642C4C40AFAEAE2B9

You can turn off the internal ticket validation with the new ELOas configuration parameter checkTicket.

Fig.: config.xml

Important

Using ELOas in proxy mode with disabled ticket validation poses a security risk, especially if the ELO Indexserver is available on the Internet.

Example

The following example shows how to call a ruleset from a client script, which then changes specific objects.

Warning: As the call takes place via http access, any user can trigger this action from the browser or via a script command. For this reason, you need to ensure that the function cannot be misused (such as by verifying the user number or through a fixed internal preset of the object ID).

First, the ruleset in use must be considered. By entering an interval of 0 minutes (<interval>0H</interval>), this ruleset will be defined as triggered manually. Thus, it will not be called cyclically, but will rather wait until a specific URL is received.

<ruleset>
    <base>
        <name>Expand Name</name>
        <search>
            <name>"OBJIDS"</name>
            <value></value>
            <mask>2</mask>
            <max>200</max>
        </search>
        <interval>0H</interval>
    </base>
<rule>
    <name>Expand Name</name>
    <condition></condition>
    <script>
        log.debug("Param1: " + EM_PARAM1);
        log.debug("UserId: " + EM_USERID);
        NAME = "Approved: " + NAME;
        EM_WRITE_CHANGED = true;
    </script>
</rule>
<rule>
    <name>Global Error Rule</name>
    <condition>OnError</condition>
    <script></script>
</rule>
</ruleset>

The interesting part is found in the script area:

<script>
    log.debug("Param1: " + EM_PARAM1);
    log.debug("UserId: " + EM_USERID);

The call can provide up to three parameters. These can be queried from the ruleset using the variables EM_PARAM1, EM_PARAM2, and EM_PARAM3. In addition, the script can optionally provide the ticket of the current login for authentication. In this case, the number of the logged on user is entered to the variable EM_USERID. If no user has been authenticated, the number -1 is entered. In the first parameter, one or more object IDs can be transferred. These will then overwrite the search value from the ruleset definition. In this case, "OBJIDS" must be specified as the name for the metadata field.

NAME = "Approved: " + NAME;

In the example, the short name of the selected object is preceded with the text "Approved". Any other changes to the SORD object can be made here.

EM_WRITE_CHANGED = true;

As the object has been changed, it should also be saved.

</script>

Activating the ruleset

After starting ELOas, this ruleset is started, but not yet active. It waits for an external trigger (visible by the text "Trigger" in the Next run field).

Fig.: ELOas status page

The trigger is either initiated from a URL, or from the Windows Client by using a script command (starting with version 7.00.056 of the client):

SendELOasRequest( <server name>, <port number>, <service name>, <with ticket>, <ruleset name>, <parameter 1>, <parameter 2>, <parameter 3)

The SendELOasRequest command performs an asynchronous call with run. Such rulesets are shown in the ELO Administration Console under Rules, instead of Direct.

Server name	Name or IP address of the ELOas server.
Port number	Port number of the ELOas server. Normally 8080, standard http port.
Service name	Service name of the ELOas server. In a standard installation, it is created by combining the prefix "as-" and the repository name (e.g. as-ELO). However, make sure to use the correct capitalization, as otherwise the Tomcat server will return an error.
With ticket	0. Do not send logon information
	1: Send current ticket as logon information. In this case, ELOas checks the ticket and identifies the user number. This information is provided to the ruleset. The ruleset can then decide whether and to what extent the action will be run.
	The logon information for SSO cannot be evaluated at present. This will be changed in the next version of the ELO Indexserver.
Ruleset Name	Name of the ruleset to be run. Only triggered rulesets can be called in this way. The call is ignored for interval-controlled rulesets.
Parameter1	First parameter. If this parameter is not empty, it is used as a search term when the ruleset is run.
Parameter2, Parameter3	Additional optional parameters. These can be queried by the ruleset and control how it is run.

The complete sample script for such a call could therefore look like the following. It calls the Expand Name ruleset for the objects with ObjId 7944 and 7945.

Set Elo=CreateObject("Elo.Professional")
MsgBox Elo.SendELOasRequest("localhost", 8084, "/ELOmover/as" , 1, "Expand Name", "7944,7945", "TestParam2", "")

The ruleset can also be triggered from any other application by calling a URL:

http://localhost:8084/ELOmover/as?cmd=run&name=Expand%20Name&param1=7944,7945&param2=TestParam2

Please note

In this case, you cannot transfer any authentication information. Ensure in your ruleset that the action cannot be misused.

Other notes

Triggering rulesets asynchronously

When a ruleset is triggered by a URL or a script call, ELOas runs it asynchronously. Thus, if another ruleset is currently active, script execution will not be delayed for as long as it takes for ELOas to become available again. Instead, the activation command is placed in a queue and then run at the next opportunity.

This has two consequences: first, the client script cannot assume that the operation has actually been performed just because the command has been processed. If this is important for the further course of the script, it must be checked by the script itself and integrated into the queue. However, please note that a situation may occur where ELOas is also processing other very complex actions at the same time. Generally, a script should therefore not wait for the completion of an ELOas action.

It is also possible that an impatient user may initiate the trigger multiple times. In this case, the ruleset will also be run multiple times. For this reason, it is necessary to ensure that repeat triggering does not lead to errors, such as by checking the object in advance and then canceling any repeated runs.

Triggering rulesets asynchronously also leads to another problem: Errors that occurred while processing the ruleset cannot be reported using the script call.

Triggering rulesets synchronously

With synchronous triggering, the ruleset is initiated directly and can also return a result. Synchronous triggering is used primarily by ELO workflows (form editor). With the call, cmd=get is required instead of cmd=run. In addition, the rulesets for the synchronous call must not be placed in the Rules folder, but rather in the Direct folder. Synchronous rulesets are run independently from the asynchronous ruleset in their own thread.

Permissions check

When being called from the ELO Windows Client, the client authentication ticket can be optionally transmitted as well. In this case, ELOas can check the login and ascertain the current user. For critical actions, a test to determine whether it is being run by a user with sufficient rights must be performed. If no user is logged in or the user does not have sufficient rights, execution should be canceled.

However, in certain cases, anonymous triggering may be completely acceptable, such as when a specific predefined object is being edited. This is the case, for example, when a specific predefined object is being edited. In this case, care should be taken to ensure the ObjectId cannot be changed by the call. This can most easily take place in an onstart event by setting the value EM_SEARCHVALUE in the script. In this case, the preset value from the ruleset script is used for the search instead of the parameter.

Order of operations

A manually triggered ruleset inserts itself quite normally to the order of operations for the rulesets. If multiple triggers have been activated for a ruleset, all triggers are processed first before the next ruleset is processed.