Technical Blog Post
Abstract
Event Driven Notifications comes handy to SB2Bi/SFG administrators
Body
If you are administering SB2Bi/SFG environments and wondering
* Is it possible to get notified through email whenever partner/user connects to server adapter?
* Is there a way to trigger a Business Process when user upload/download a file?
This blog is for you!!
SB2Bi offers a useful feature called "Event Driven Notifications" that allows administrators to create a BPML and configure it to be triggered when certain events happen. This BPML could perform any task such as generate email notification or perform some house-keeping activity etc
Here is link to product documentation
First things first. Let me cover configuration part to start with.
Copy Event listener class "XpathBPLauncherEventListener" from listenerStartup.properties and add to customer_overrides.properties. This is the class responsible for driving Event Driven Notifications.
In my test environment, this class was listed as Listener.Class.b2b_17 (number might be different in yours). So I just added following line to customer_overrides.properties with listenerStartup prefix.
listenerStartup.Listener.Class.b2b_17=com.sterlingcommerce.woodstock.dmi.visibility.event.XpathBPLauncherEventListener
Before I move on to configuration of what BP to be triggered for which event, Let us understand basics of events. How they look and what attributes do they have.
visibility.log in DEBUG mode is good place to track events. Here are 2 sample events from FTP Server. Doc for the complete list of events supported by Event Driven Notification Framework.
Event correspond to User connected to FTP Server Adapter --
DEBUG DmiVisEventWarehouseQueue.storeEvent() -storing event = Event: (Aft.Visibility.CommConnect.1) - Normal
TimeStamp = 1508516771557
endpoint2 = 1.2.3.4
endpoint1 = 5.6.7.8
protocol = FTP
adapterType = FtpServerAdapter
secureMode = none
wfId = -2
state = Starting.
endTime = 2017-10-20 12:26:11.557
endport1 = 57127
sessionArchiveId = 21004
endport2 = 18432
startTime = 2017-10-20 12:26:11.553
isSuccessful = true
isLocallyInitiated = false
sessionId = FTP_SERVER_ADAPTER_15085167715101:21004
adapterName = FTP_SERVER_ADAPTER
psInstance = local
wfStep = -1
Event correspond to file downloaded from FTP Server Adapter --
ALL DmiVisEventFactory.fireCommFileXferCompleteEvent() - created Event: (Aft.Visibility.CommFileXferComplete.1) - Normal
TimeStamp = 1508517089185
transferId = FTP_SERVER_ADAPTER_15085169111372:21005-6
bytesTransferred = 63
time = 2017-10-20 12:31:29.185
isSuccessful = true
isLocallyInitiated = false
sessionId = FTP_SERVER_ADAPTER_15085169111372:21005
ignoreTracking = false
isPut = false
Now let me resume other configuration to enable event specific notifications. It must happen through visibility.properties. In order to add this entry into customer_overrides.properties, please use dmivisibility prefix.
It's syntax of policy looks like this - bp_event_trigger.X=eventPreFilter,xPathExpression,bpname,userId
|
X |
a numerical index into each unique event-bp combination being registered. (1, 2, 3, and so on). |
| eventPreFilter |
prefix for the event type o the events to be evaluated (aft.visibility.xxx). The event can be any valid Sterling B2B Integrator event, not just visibility events. The eventPreFilter is comprised of scope (Aft), subsystem (Visibility), name (for example, CommAuthentication), and numTag (for example, 1). The numTag is optional. The values for name and numTag are provided towards end on this link |
| xPathExpression |
any valid Xpath expression that can be evaluated to a boolean result. P.S - xpath expression containing comma is not accepted as of today. e.g., starts-with (string(//Event/transferId), 'MYFTP')) |
| bpname | name of the business process to be launched |
| userId | the name of a valid Sterling B2B Integrator user used by the launched business process to determine any authorizations required by the business process. |
e.g.,
To launch an e-mail business process (MyNotification) with user credentials ‘admin' when there is a successful upload on to SFTP server:
dmivisibility.bp_event_trigger.1=Aft.Visibility.CommFileXferComplete.9,//Event/isPut='true' and //Event/isSuccessful='true',MyNotification,admin
e.g.,
To launch an e-mail business process (MyFTPNotification) with user credentials ‘admin' when there is attempt to connect to FTP Server instance "FTP_SERVER_ADAPTER"
dmivisibility.bp_event_trigger.2=Aft.Visibility.CommConnect.1,//Event/adapterName='FTP_SERVER_ADAPTER',MyFTPNotification,admin
e.g.,
To launch an e-mail business process (MyNotification2) with user credentials ‘admin' when there is failed download from SFTP server:
dmivisibility.bp_event_trigger.3=Aft.Visibility.CommFileXferComplete.9,//Event/isPut='false' and //Event/isSuccessful='false',MyNotification2,admin
e.g.,
To launch an e-mail business process (MailboxNotification) with user credentials ‘admin' when there is mailbox add service successful
dmivisibility.bp_event_trigger.4=Aft.Visibility.CommFileXferComplete.15,//Event/isSuccessful='true',MailboxNotification,admin
After adding these entries to customer_overrides.properties, make sure SB2Bi node is restarted to make changes permanent on JVM.
P.S. - As you see NumTag is optional in eventPreFilter value, starting 5.2.6.0 FP some of the iFixes have introduced regression that forces numTag is mandatory. It is addressed in 5262_5 through APAR IT20372 This fix made numTag optional again. If you are running on 5.2.6.0, 5.2.6.1_x, 5.2.6.2_x,5.2.6.3_x and event notifications do not work as expected, you may like to validate numTag in eventPreFilter of particular bp_trigger_event policy.
Quick Troubleshooting Tips --
visibility.log is central log to troubleshoot it.
* If you do not see Notification BP triggered as configured in bp_event_trigger.X property but it should have been, It is possible xpath expression might be incorrect. In such case, you will see error as below in visibility.log
ERROR XpathBPLauncherEventListener.parseBPLauncherPolicies() - malformed BP Launch policy ignored, key = bp_event_trigger.12, value =
* In order to identify which policy is used, you may keep log in DEBUG mode to see following sequence of log.
[2017-10-20 12:31:29.185] DEBUG XpathBPLauncherEventListener.handleEvent() - examining event[Aft.Visibility.CommFileXferComplete.1]
[2017-10-20 12:31:29.185] DEBUG XpathBPLauncherEventListener.handleEvent() - event is being xpath evaluated where:
event =
-----------------------------------------
<Event>
<Id>Aft.Visibility.CommFileXferComplete.1</Id>
<ExceptionLevel>Normal</ExceptionLevel>
<TimeStamp>1508517089185</TimeStamp>
<time>2017-10-20 12:31:29.185</time>
<bytesTransferred>63</bytesTransferred>
<transferId>FTP_SERVER_ADAPTER_15085169111372:21005-6</transferId>
<isLocallyInitiated>false</isLocallyInitiated>
<isSuccessful>true</isSuccessful>
<sessionId>FTP_SERVER_ADAPTER_15085169111372:21005</sessionId>
<ignoreTracking>false</ignoreTracking>
<isPut>false</isPut>
</Event>
-----------------------------------------
and xpath expression =
-----------------------------------------
//Event/isPut='false' and //Event/isSuccessful='true'
-----------------------------------------
[2017-10-20 12:31:29.187] DEBUG XpathBPLauncherEventListener.fireBusinessProcess() - entering method.
[2017-10-20 12:31:29.239] DEBUG XpathBPLauncherEventListener.fireBusinessProcess() - bp fired for policy: XpathBPLauncherEventListener id: bp_event_trigger.1, eventType: Aft.Visibility.CommFileXferComplete.1, xPath: //Event/isPut='false' and //Event/isSuccessful='true' bpName: KK.MBX.Delete, userid: admin, and event: Event: (Aft.Visibility.CommFileXferComplete.1) - Normal
UID
ibm11120983