Category: Event Hub, Event Analytics

Call M3 API from Event Analytics rules

Here is how to call M3 API from a Drools rule in Infor Event Analytics; this is a common requirement.

Sample scenario

Here is my sample business case.

When a user changes the status of an approval line in OIS115 (OOAPRO), I have to find the order type (ORTP) of the order to determine which approval flow to trigger in Infor Process Automation (IPA), but ORTP is not part of the table OOAPRO, for that reason I must previously make a call to OIS100MI.GetHead.

I could call M3 in the approval flow, but false positives would generate noise in the WorkUnits.

Is it possible?

I asked Nichlas Karlsson, Senior Architect – Business Integration at Infor, if it was possible to call M3 API directly in the Drools rule. He is one of the original developers of Event Hub and Event Analytics and very helpful with my projects (thank you) although he does not work with these products any longer. He responded that Event Analytics is a generic software with no specific connection to M3, so unfortunately this is not possible out of the box, however it is a common requirement. He said I could solve it using MvxSockJ to call M3 APIs in my own Java class, included in a jar that I put in the lib folder. He added to not forget that the execution time for all rules within a session must be less than the proxy timeout, i.e. 30s. And I would also need to manage host, port, user, password and other properties in some way.

Instead of MvxSockJ I will use the MI-WS proxy of the Grid as illustrated in my previous post.

Sample Drools rule

Here is my sample Drools rule that works:

package com.lawson.eventhub.analytics.drools;

import java.util.List;
import com.lawson.eventhub.analytics.drools.model.Event;
import com.lawson.eventhub.analytics.drools.model.HubEvent;
import com.lawson.eventhub.EventOperation;
import com.lawson.grid.node.Node;
import com.lawson.grid.proxy.access.SessionId;
import com.lawson.grid.proxy.access.SessionProvider;
import com.lawson.grid.proxy.access.SessionUtils;
import com.lawson.grid.proxy.ProxyClient;
import com.lawson.grid.registry.Registry;
import com.lawson.miws.api.data.MIParameters;
import com.lawson.miws.api.data.MIRecord;
import com.lawson.miws.api.data.MIResult;
import com.lawson.miws.api.data.NameValue;
import com.lawson.miws.proxy.MIAccessProxy;

declare HubEvent
	@typesafe(false)
end

rule "TestSubscription"
	@subscription(M3:OOAPRO:U)
	then
end

rule "TestRule"
	no-loop
	when
		event: HubEvent(publisher == "M3", documentName == "OOAPRO", operation == EventOperation.UPDATE, elementOldValues["STAT"] == 10, elementValues["STAT"] == "20")
	then
		// connect to MI-WS
		Registry registry = Node.getRegistry();
		SessionUtils su = SessionUtils.getInstance(registry);
		SessionProvider sp = su.getProvider(SessionProvider.TYPE_USER_PASSWORD);
		SessionId sid = sp.logon("Thibaud", "******".toCharArray());
		MIAccessProxy proxy = (MIAccessProxy)registry.getProxy(MIAccessProxy.class);
		ProxyClient.setSessionId(proxy, sid);

		// prepare input parameters
		MIParameters p = new MIParameters();
		p.setProgram("OIS100MI");
		p.setTransaction("GetHead");
		MIRecord r = new MIRecord();
		r.add("CONO", event.getElementValue("CONO"));
		r.add("ORNO", event.getElementValue("ORNO"));
		p.setParameters(r);

		// execute and get output
		MIResult s = proxy.execute(p);
		List<MIRecord> records = s.getResult(); // all records
		if (records.isEmpty()) return;
		MIRecord record = records.get(0); // zeroth record
		List<NameValue> nameValues = record.getValues(); // all output parameters
		String ORTP = nameValues.get(4).getValue(); // PROBLEM: somehow nameValues.indexOf("X") returns -1

		// make decision
		if (ORTP.equals("100")) event.postEvent("ApprovalFlowA");
		if (ORTP.equals("200")) event.postEvent("ApprovalFlowB");
		if (ORTP.equals("300")) event.postEvent("ApprovalFlowC");
end

Note: You will need to drop foundation-client-10.1.1.3.0.jar in the lib folder of Event Analytics, and restart the application

Limitations

There are some limitations with this code:

  • The execution time must be less than the 30s proxy timeout
  • Limit the number of return columns; there is currently a bug with Serializable in ColumnList, see Infor Xtreme incident 8629267
  • If the M3 API returns an error message it will throw the bug with Serializable in MITransactionException, see Infor Xtreme incident 8629267
  • Somehow NameValue.indexOf(name) always returned -1 during my tests, it is probably a bug in the class, so I had to hard-code the index value of the output field (yikes)
  • I do not know how to avoid the logon to M3 with user and password to get a SessionId; I wish there was a generic SYSTEM account that Event Analytics could use
  • For simplicity of illustration I did not verify all the null pointers; you should do the proper verifications
  • The code may throw MITransactionException, ProxyException and IndexOutOfBoundsException
  • You can move the Java code to a separate class in the lib folder; for that refer to my previous post

Related articles

That’s it. Let me know what you think in the comments below.

Subscribe to Event Hub in Java

To programmatically subscribe to Event Hub or Event Analytics with your own Java class:

Write the Java code, get the libraries from the Event Hub and Event Analytics applications in the Infor Grid, download the simple SLF4J logger, compile, and run. I used this code for my demo of picking lists in Google Glass; I would not use this in a production environment.

DISCLAIMER: INFOR DOES NOT SUPPORT USAGE OF CUSTOM SUBSCRIBER OR PUBLISHER CLIENTS IN EXTERNAL APPLICATIONS. ONLY INFOR PROCESS AUTOMATION (IPA) AND M3 ENTERPRISE COLLABORATOR (MEC) ARE ALLOWED TO CONNECT TO THE EVENT HUB. USE AT YOUR OWN RISK. MAY VOID YOUR WARRANTY.

/*
javac -cp eventhub-common-2.0.20.jar;eventhub-subscriber-2.0.20.jar;slf4j-api-1.6.2.jar TestEventSubscriber.java
java -cp eventhub-common-2.0.20.jar;eventhub-subscriber-2.0.20.jar;slf4j-api-1.6.2.jar;hornetq-core-client-2.3.0.CR1.jar;hornetq-commons-2.3.0.CR1.jar;slf4j-simple-1.7.12.jar;jboss-logging-3.1.0.GA.jar;jboss-logmanager-1.2.2.GA.jar;netty-3.6.2.Final.jar;. TestEventSubscriber
*/

import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.lawson.eventhub.ElementData;
import com.lawson.eventhub.EventData;
import com.lawson.eventhub.Subscription;
import com.lawson.eventhub.Subscription.Builder;
import com.lawson.eventhub.subscriber.EventReceiver;
import com.lawson.eventhub.subscriber.Subscriber;
import com.lawson.eventhub.subscriber.SubscriberException;

public class TestEventSubscriber {

    static String name = "MyTest";
    static String hostName = "host";
    static int portNumber = 22110;
    static String subscription = "M3:OCUSMA:U"; // or EventAnalytics:something
    static Subscriber subscriber;
    static Logger log = LoggerFactory.getLogger(TestEventSubscriber.class);

    public static void main(String[] args) throws Exception {
        register();
        Runtime.getRuntime().addShutdownHook(new Thread() {
            /* stop when CTRL+C */
            public void run() {
                try {
                    unregister();
                } catch (Exception ex) {
                    log.error("CTRL+C", ex);
                }
            }
        });
    }

    public static void register() throws Exception {
        log.info("Registering...");
        // create subscriber
        Map<String, String> params = new HashMap<String, String>();
        params.put("subscriber-name", name);
        params.put("subscriber-persist", "false");
        params.put("subscriber-server-address", hostName);
        params.put("subscriber-server-port", Integer.toString(portNumber));
        subscriber = new Subscriber(params);
        // add subscription
        Subscription sub = Subscription.newBuilder(subscription).build();
        subscriber.add(sub);
        // register receiver
        EventReceiver receiver = new TestEventReceiver();
        subscriber.register(receiver);
        // probe
        log.info(
            "isActive: " + subscriber.isActive() +
            ", isConnected: " + subscriber.isConnected() +
            ", isRegistered: " + subscriber.isRegistered() +
            ", isFailed: " + subscriber.isFailed());
    }

    public static void unregister() throws Exception {
        log.info("Unregistering...");
        subscriber.unregister();
    }
}

class TestEventReceiver implements EventReceiver {
    static Logger log = LoggerFactory.getLogger(TestEventReceiver.class);
    public boolean receiveEvent(EventData event) throws SubscriberException {
        log.info(
            "Subscription: " + event.getSubscription() +
            ", Publisher: " + event.getPublisher() +
            ", DocumentName: " + event.getDocumentName() +
            ", Operation: " + event.getOperation().character() +
            ", TrackingId: " + event.getTrackingId() +
            ", SentTimestamp: " + new Date(event.getSentTimestamp()).toString() +
            ", CONO: " + event.getElementValue("CONO"));
        for (ElementData element : event.getElements()) {
            log.info(
                "Name: " + element.getName() +
                ", OldValue: " + element.getOldValue() +
                ", Value: " + element.getValue());
        }
        return true;
    }
}

b
It will persist a file data/subscriber/delivered/MyTest.rcv that contains a bunch of unique ids and that you can deserialize with a ConcurrentHashMap.
Thank you.

Java code in Event Analytics rules

To add custom Java code to a Drools rule in Event Analytics in the Infor Grid:

  1. Write your Java code, compile it, and archive it to a JAR file: 
    // javac thibaud\HelloWorld.java
// jar cvf HelloWorld.jar thibaud\HelloWorld.class
package thibaud;
public class HelloWorld {
    public static String hello(String CUNO) {
        return "Hello, " + CUNO;
    }
}

  2. Find the host of Event Analytics as explained here, copy/paste the JAR file to the application’s lib folder in the Infor Grid, and restart the application to load the JAR file:

    4_
  3. Write the Drools Rule that makes use of your Java code, reload the rules, and test:
    5
    6_

Thank you.

Event Analytics for Infor Process Automation (IPA)

Today I will illustrate how to setup Event Analytics for Infor Process Automation (IPA). Event Analytics is an application that subscribes to Event Hub, that filters events based on conditions, and that takes actions. My goal is to single out specific Infor M3 events to trigger IPA flows with accuracy, for example to trigger a HelloWrrrld flow only when an M3 Item number ABC123 has changed from Status 10 to 20, specifically. This post is intended for readers already familiar with IPA and Event Hub, yet not too familiar with Event Analytics. For an introduction on Event Hub for IPA, I invite you to read my previous article.

About Event Analytics

Event Analytics is an application for the Infor Grid that subscribes to Event Hub. It uses a rules engine with business rules to single out specific events out of the million of events produced by M3, i.e. it will find the needle in the haystack, and it will carry out actions. It’ s fast and scalable and doesn’t affect M3 performance. It’s used for example to pass Business Object Documents (BODs) to Infor ION.

It uses the Production Rule System JBoss Drools, a “Business Logic integration Platform which provides a unified and integrated platform for Rules, Workflow and Event Processing”,  and it uses the Drools Rule language, a declarative domain-specific language that looks like when <condition> then <action> . Drools Rule files have the .drl extension. The Smart Rules Editor is an optional plugin for Eclipse based on Drools Expert to help produce Drools Rules for Event Analytics. For further reading on JBoss Drools and Drools Rules, I recommend the Rules Programming tutorial by Srinath Perera.

Documentation

The Infor LifeCycle Manager (LCM) InfoCenter has detailed documentation about Event Analytics: facts, subscriptions, administration, example rules, etc. For that, go to your LCM InfoCenter at http://lcmserver:4062/ and then navigate to Documentation > Infor Smart Office Infocenter > Installation Guides > Infor ION Grid Extensions Installation and Administration Guide > Event Hub and Event Analytics Grid Extensions:
doc

Event Analytics or Event Hub?

Why should we use Event Analytics to trigger IPA flows when we can use Event Hub alone? Well, if we used Event Hub alone to directly trigger IPA flows we could potentially get too many false positives. For instance, in my example above I want to trigger a flow only when the Item number ABC123 has changed from Status 10 to 20; I don’t want events for other Item numbers nor Statuses. Unwanted events would create too many unnecessary WorkUnits in IPA, and that would clog the server with noise in the database even if we used an if-then-else Branch activity node at the start of the flow to eventually cancel the execution downstream. The solution is to filter events upstream with Event Analytics.

Dual subscriber/publisher

Once a condition is met in a Drools Rule, a typical action for Event Analytics is to post a new event to Event Hub. Then, subscribers like IPA can subscribe to those events with Publisher:EventAnalytics instead of the traditional Publisher:M3. Thus, Event Analytics is dual subscriber and publisher. It took me a while to figure out the gymnastics in my head, eventually it became clear.

Here is an illustration:

EventAnalytics

The HelloWrrrld scenario

For illustration purposes in this article, the simple scenario will be to trigger a HelloWrrrld flow when an M3 Item number ABC123 has changed from Status 10 to 20. The baby steps will be:

First, I will create a Drools Rule that will subscribe to events where Publisher:M3, Document:MITMAS, and Operation:U, and with the conditions ITNO=ABC123, old STAT=10, and new STAT=20. If that condition is met, the Rule will carry out the action to post a new event MITMAS_ABC123_20.

Then, with Infor Process Designer (IPD), I will create and deploy a simple HelloWrrrld flow. The flow will receive as input variables all the data from the event. So I will add a simple activity node that will show the M3 fields <!CONO>, <!ITNO>, <!ITDS>, and <!STAT>.

Then, in IPA Rich Client Admin, I will create a new Event Hub Receiver with a subscription to EventAnalytics:MITMAS_ABC123_20 that will trigger the HelloWrrrld flow.

Then, I will do a test. I will go to MMS001 in Smart Office, I will prepare an Item ABC123 with Status 10, I will save it, and then I will change it to Status 20. I will also update other Items to produce additional events (noise). M3 will send all those events to Event Hub. Event Hub will pass those events to Event Analytics. Event Analytics will single out the event that matches the condition ITNO=ABC123, old STAT=10, new STAT=20, and it will post a new Event MITMAS_ABC123_20. Then, the Event Hub Receiver will receive that event and will trigger my HelloWrrrld flow with the data.

Finally, the resulting WorkUnit will contain all the variables of the event, the M3 fields, the old values, and the new values.

OK let’s do it.

Create a Drools Rule

First, let’s create the new Drools Rule in Event Analytics:

  1. Go to Infor LifeCycle Manager (LCM).
  2. Find EventAnalytics in your Grid (expand the tree or use the filter).
  3. Right-click > Manage Application.
  4. There will be one or more Sessions. We’ll use Session Default for now. Click Rules.
  5. There will be zero or more Drools Rule Language Files, active or not. Click Create.
  6. Enter a Resource Name, for example MITMAS_ABC123_20_Rule.
  7. The editor will generate a sample Drools Rule with subscription M3:MITMAS:U, and condition elementValues[“STAT”]=”20″. Good. We’ll keep that.
  8. Rename the rule MITMAS_20_Demo to MITMAS_ABC123_20_Demo.
  9. Add the condition elementValues[“ITNO”]=”ABC123″ .
  10. Add the condition elementOldValues[“STAT”]=”10″ .
  11. In the actions, rename the postEvent to MITMAS_ABC123_20.
  12. Delete the rules Start_Demo, Time_Demo, and Stop_Demo.
  13. Click Save.
  14. The result will look like this:
    ea8
  15. Close the editor.
  16. Back in the list of Drools Rule Language File, select the checkbox next to your Rule to activate it.
  17. Click Reload to load your Rule.
  18. Verify in the list of Rules that your Rule is now there.

Create a HelloWrrrld flow

Then, with Infor Process Designer (IPD), let’s create and deploy the simple HelloWrrrld flow that will show the M3 fields <!CONO>, <!ITNO>, <!ITDS>, and <!STAT>.

It will look like this:
flow2

Create an Event Hub Receiver

Then, let’s create the new Event Hub Receiver in IPA Rich Client Admin:

  1. Go to IPA Rich Client Admin.
  2. Switch to the desired data area (development, test, production, etc.)
  3. Open Channels Administrator.
  4. Create a new Event Hub Receiver.
  5. Set the Subscription to EventAnalytics:MITMAS_ABC123_20.
  6. Select Process HelloWrrrld.
  7. Select Startup Type Automatic.
  8. Click Save.
  9. Select Actions > Activate.
  10. The status bar will show “Activate Completed”.

The result will look like this:
richclient3

Test in Smart Office

Then, let’s do a test in Smart Office.

  1. Go to MMS001 in Smart Office.
  2. Create an Item ABC123 with Status 10, and save it.
  3. Change the Item to Status 20:
    iso3
  4. Optionally, update other Items to produce additional events (noise).

Resulting WorkUnit

Finally, open the resulting WorkUnit in Rich Client Admin, switch to the Variables tab. It will show all the input variables of the event, the M3 fields, the old values, and the new values:
z_

That’s it!

If you liked this post, please subscribe to this blog by clicking the Follow button below. And leave your comments in the section below. That will support and grow the community. Also, spread the word to your colleagues, customers, and partners. And if you have something to share, let me know and I will send you an author invite. And even better, create your own blog to grow the community even more.

 

Event Hub for Infor Process Automation (IPA)

Today I will illustrate how to setup Event Hub for Infor Process Automation (IPA). The goal is to receive M3 events in IPA in order to trigger approval flows, for example to trigger a User approval flow when a new User is created in M3, or to trigger a Purchase Order flow when a new Purchase Order is created in M3. This technique has been around for several years and replaces pretty much all the previous techniques to trigger flows.

This post is intended for readers already familiar with IPA, yet not too familiar with Event Hub.

About Event Hub

Event Hub is a publish-subscribe distributed messaging system for M3. It seems to use JBoss HornetQ, the “open source project to build a multi-protocol, embeddable, very high performance, clustered, asynchronous messaging system”, it seems to use JGroups, “a toolkit for reliable messaging [that] can be used to create clusters whose nodes can send messages to each other”, it seems to use Netty, “an asynchronous event-driven network application framework for rapid development of maintainable high performance protocol servers & clients”, and it seems to use Disruptor, a “High Performance Inter-Thread Messaging Library”, based on unzipping the Grid Archive file Infor\LifeCycle Manager\LCM-Server\products\eventhub-installer\components\eventhub-gar-2.0.16.gar.

M3 produces millions of events as part of its daily operation. For example: users open programs, they create new records and update existing ones, the database gets updated, etc. M3 is the Producer of events. The Documents can be M3 Programs (such as M3 Customer – CRS610) and M3 Tables (such as OCUSMA). The Operations on M3 Programs can be: Start, eXit, Fail, reQuest, and Response. The Operations on M3 Tables can be Create, Update, and Delete. When an event happens in M3, M3 sends that event to Event Hub. Then Event Hub distributes that event to any subscriber that is interested in that event, for example to M3 Enterprise-Collaborator (MeC) whom will exchange BODs and initiate EDI transactions, to Infor Enterprise Search (IES) whom will update the search engine’s indexes, to Infor Process Automation (IPA) whom will trigger flows, to Infor Customer Lifecycle Management (CLM) whom will synchronize M3 and CLM customer records, etc.

Here’s an illustration:
hub

I like Event Hub because it’s a beautiful piece of engineering, and it’s based on modern, well documented, open source software.

Documentation

The Infor LifeCycle Manager (LCM) InfoCenter has detailed documentation about Event Hub: overview, events, documents, operations, subscriptions, administration, etc. For that, go to your LCM InfoCenter at http://lcmserver:4062/ and then navigate to Documentation > Infor Smart Office Infocenter > Installation Guides > Infor ION Grid Extensions Installation and Administration Guide > Event Hub and Event Analytics Grid Extensions:
1

The HelloWorld scenario

The simple Hello World scenario I will illustrate in this post is the following: when the user closes M3 Program EUS001 I will trigger a HelloWorld flow. It’s as simple as that. Why not. It doesn’t have any value from a functional point of view, but it’s a great illustration from a technical point of view. Here are the baby steps:

First, I will go to the Event Hub Configuration in my Grid and determine what the host and port number are to subscribe to Event Hub.

Then, I will enter the host and port number in IPA Rich Client Admin to setup IPA as a subscriber of Event Hub. (Conversely, IPA can also be a publisher and publish events to Event Hub but I won’t cover that scenario here.)

Then, I will create a HelloWorld flow, and I will setup a subscription M3:EUS001:X that will trigger the flow. The flow will be a simple Start -> End flow with no intermediate activity nodes. No need for fluff.

Finally, I will do a complete test, I will: start Infor Smart Office, open and close EUS001, and analyze the resulting WorkUnit in IPA.

Event Hub Configuration

Let’s go to the Event Hub Configuration in the Grid and determine what the host and port number are to subscribe to Event Hub:

  1. Open Infor LifeCycle Manager (LCM)
  2. Expand the Grid (for example, Development, Test, Production)
  3. Expand the Products until you find EventHub (you can expand the tree, or use the filter)
  4. Right-click > Configure Application
  5. In the Bindings section, write down the Host:
    lcm1
  6. Select Edit Properties
  7. Expand Server
  8. Write down the Port number:
    lcm2

Setup IPA as a subscriber of Event Hub

Then, let’s enter the host and port number in IPA Rich Client Admin to setup IPA as a subscriber of Event Hub:

  1. Start the IPA Rich Client Admin
  2. Switch the data area (for example, dev, test, prod, etc.)
  3. Start Channels Administrator (either search for channel, either go to Start > Applications > Process Server Administrator > Administration)
  4. Create an Event Hub Channel (Actions > Create):
    channel1
  5. Enter a Name, for example EventHub
  6. Enter a Description, for example EventHub
  7. Check the box External
  8. Enter the Host
  9. Enter the Port Number:
    channel2
  10. Click Save, the status bar will say “Channel Created”
  11. Select Actions > Activate, the status bar will say “Activate Completed”

Create a flow, the subscription, and the trigger

Then, let’s create a HelloWorld flow and setup a subscription M3:EUS001:X that will trigger the flow.

  1. Create a new HelloWorld flow in Infor Process Designer (IPD), a simple Start -> End flow with no intermediate activity nodes will suffice (you can add other nodes if you want), and deploy it on the server with Process > Upload process:
    ipd
  2. Back in the Event Hub Channel in IPA Rich Client Admin, switch to the tab Event Hub Channel Receivers and create a new Receiver:
    channel3
  3. Enter a Receiver and Description, for example HelloWorld.
  4. Enter Subscription M3:EUS001:X.
  5. Select Process HelloWorld (the flow).
  6. Select Startup type Automatic.
  7. Click Save, the status bar will say “Pfi Receiver Created”:
    channel4
  8. Select Actions > Activate, the status bar will “Activate Completed”.
  9. Close the Event Hub Receiver window.
  10. Close the Event Hub Channel Receivers window.
  11. You will be back in the Channels Administrator window. Make sure the Event Hub Channel EventHub is Active and the Event Hub Receiver HelloWorld is Active.
  12. You can close the Channels Administrator window.

Test

Finally, let’s do a complete test: start Infor Smart Office, open and close EUS001, and analyze the resulting WorkUnit in IPA.

  1. Go to Infor Smart Office.
  2. Open EUS001 (mforms://eus001), and close it (F3):
    eus001
  3. That will cause the event M3:EUS001:X to happen in M3, Event Hub will forward the event to IPA, and IPA will trigger the HelloWorld flow.
  4. Back in IPA Rich Client Admin, open the Work Units (Start > Applications > Process Server Administrator > Administration > Work Units)
  5. Find the latest WorkUnit for the HelloWorld Process:
    WorkUnit1
  6. Open it, and switch to the WorkUnit Variables, it will show all the keys/values for the event:
    WorkUnit3

That’s it! We setup IPA as a subscriber of Event Hub, we created a receiver to subscribe to a specific event and trigger our flow, we did a test and caused the event to happen, and we analyzed the resulting WorkUnit. That illustrates how to setup Event Hub for IPA to receive M3 events in order to trigger a flow.

Next time I will show you how to setup Event Analytics for IPA and how to setup Drools Rules to filter events with conditions.

If you liked this, please subscribe to this blog by clicking the Follow button, and let us know your comments in the section below. You can also become an author and share your ideas (let me know and I’ll send you an author invite).