Technical Blog Post
Abstract
Mailbox User Exits. How to plugin custom code with MailboxAdd
Body
Here is one more blog on user exit offering from Sterling B2B Integrator and Sterling File Gateway suite. Following are the blogs I published on other user exits in past. User Exit framework as such same for all of these but just differ in names of interfaces and configuration files.
FTP/SFTP server User Exits in SB2Bi 5.2.5
Login and Logout User Exits in SB2Bi 5.2.5/5.2.6 FixPack
As of date, SB2Bi 5.2.6.3 is latest fix-pack and it offers 7 User Exits around Mailbox. If you are in lower fixpack level, not all may exist. Following are corresponding Java Interfaces that can be implementable with custom logic.
I captured Interface list from <sb2bi_install>/properties/userexit/MailboxUserExits.xml file.
- com.sterlingcommerce.woodstock.userexit.services.mailbox.interfaces.IMailboxUserExit_OnMailboxCreate
- com.sterlingcommerce.woodstock.userexit.services.mailbox.interfaces.IMailboxUserExit_OnMailboxUpdate
- com.sterlingcommerce.woodstock.userexit.services.mailbox.interfaces.IMailboxUserExit_OnMailboxDeleteSet
- com.sterlingcommerce.woodstock.userexit.services.mailbox.interfaces.IMailboxUserExit_OnMessageDelete
- com.sterlingcommerce.woodstock.userexit.services.mailbox.interfaces.IMailboxUserExit_OnMessageExtract
- com.sterlingcommerce.woodstock.userexit.services.mailbox.interfaces.IMailboxUserExit_OnMessageExtractBegin
- com.sterlingcommerce.woodstock.userexit.services.mailbox.interfaces.IMailboxUserExit_OnMessageAdd
These Interface names themselves are self explanatory. More specifics can be found through Java Interface' API documentation accessible at <sb2bi_install>/userexit/docs/mailboxdocs.jar. Simply extract it's contents onto your desktop and navigate through.This is how it looks like.
SB2Bi installation comes with a default implementation class for "IMailboxUserExit_OnMessageAdd" Interface. It's job is to disallow upload of files that end with specific extensions. List of extensions can be configured through property "disallowExtensionsToUpload" in mailbox.properties.
Detailed steps to enable this particular user exit implementation can be seen here - http://www-01.ibm.com/support/docview.wss?uid=swg21986740
Snippet from configuration file - <sb2bi_install>/properties/userexit/MailboxUserExits.xml below. Absolute class name in bold is default implementation for "IMailboxUserExit_OnMessageAdd" shipped with installation
<bean id="com.sterlingcommerce.woodstock.userexit.services.mailbox.interfaces.IMailboxUserExit_OnMessageAdd" class="com.sterlingcommerce.woodstock.userexit.services.mailbox.MailboxUserExit"> <property name="implementations"> <list> <value>com.sterlingcommerce.woodstock.userexit.services.mailbox.MailboxUserExit</value> </list> </property> <property name="generalParameters"> <props> <prop key="return.on.exception">false</prop> <prop key="pool.size">100</prop> <prop key="maximum.queue.length">500</prop> <prop key="wait.time">60</prop> <prop key="execution.threshold.time">600000</prop> </props> </property> </bean>
|
Sample custom implementation for IMailboxUserExit_OnMessageAdd :
If you have business requirement to execute custom code or program through any of these user exit points (i.e., Java Interfaces), it is doable. It just requires a java class that implemented one of these interfaces. And plug it in through configuration files. Some of sample scenarios that can be achieved are
* Antivirus Scan before file upload into mailbox and fail the upload if scan reports failure.
* Prevent User to upload files larger than some size. say 1GB.
* Monitor and limit data uploaded by a user.
I have taken simple scenario here as proof of concept to illustrate. My Scenario is to prevent a particular User (producer1) uploading batch (.bat) files into any mailbox on SB2Bi.
It requires user exit implementation for Interface "com.sterlingcommerce.woodstock.userexit.services.mailbox.interfaces.IMailboxUserExit_OnMessageAdd". Here is API exposed in this Interface. (from API documentation)
As it explains, code your custom logic within this API and return boolean (true, false) value as required.
Here is implemented class for Java Interface "IMailboxUserExit_OnMessageAdd"
package kk.ue.mbx; import java.util.Map; import com.sterlingcommerce.woodstock.userexit.services.mailbox.interfaces.IMailboxUserExit_OnMessageAdd; * User by name "producer1" can not upload ".bat" files into mailbox. */ public class IBMmbxExit implements IMailboxUserExit_OnMessageAdd { static String CLASS_NAME = "IBMmbxExit"; public boolean onMessageAdd(java.util.Map inargs,java.util.Map outargs) throws java.lang.Exception { System.out.println("inargs: " + inargs);
if(((String)inargs.get(IMailboxUserExit_OnMessageAdd.KEY_USER_ID)).equals(USER_EXCLUDE) && ((String)inargs.get(IMailboxUserExit_OnMessageAdd.KEY_MESSAGE_NAME)).endsWith(FILE_EXTN)) { return false; System.out.println(CLASS_NAME + ".onMessageAdd(M,M) Exiting"); return true; } |
Next, compile and build jar file. Commands I used on Unix host for building jar file. Please note 2 jar files needed in classpath.
Run these commands from folder location where java class present.
<install>/jdk/bin/javac -cp <sb2bi_install>/userexit/jars/mailbox.jar:<sb2bi_install>/jar/mailbox/4_6/mailbox.jar -d . *.java
<install>/jdk/bin/jar cvf IBMUserExitsMbx.jar kk*
Add this class name into inst
<bean id="com.sterlingcommerce.woodstock.userexit.services.mailbox.interfaces.IMailboxUserExit_OnMessageAdd" class="com.sterlingcommerce.woodstock.userexit.services.mailbox.MailboxUserExit">
<property name="implementations">
<list>
<value>com.sterlingcommerce.woodstock.userexit.services.mailbox.MailboxUserExit</value>
<value>kk.ue.mbx.IBMmbxExit</value>
</list>
</property>
Plug in jar file "IBMUserExitsMbx.jar" to SB2Bi using install3rdParty.sh script under <sb2bi_install>/bin directory. This adds VENDOR_JAR entry to prop
e.g., ./in
Start SB2Bi to take all these changes effective.
After SB2Bi is back up and running, producer1 (user on SB2Bi) is not allowed to upload files with .bat extension onto SB2Bi mailboxes.
Please see test results below.
Uploading file into mailbox through FTP Server Adapter
Used FileZilla FTP Client to upload file
noapp.log.DateStamp :
[2017-05-16 14:27:08.308] ALL 000000000000 GLOBAL_SCOPE IBMmbxExit.onMessageAdd(M,M) Starting.
[2017-05-16 14:27:08.308] ALL 000000000000 GLOBAL_SCOPE inargs: {extractabilityPolicy=EXTRACTBLE, mailboxPath=/Producer1, createDateTime=2017-05-16 14:27:08.306, routingEligible=true, userId=producer1, dbConnection=com.sterlingcommerce.woodstock.util.frame.jdbc.ConnectionWrapper@87223a40, contentType=application/data, messageSize=2118, messageId=39, extractabilityCount=1, documentId=72767615c127aef39node1, messageName=test.bat}
mailbox.log :
[2017-05-16 14:27:08.308] ERROR RepositoryDB.addMessage() - Caught exception while adding message
[2017-05-16 14:27:08.308] ERROR [1494959228308] User Exit Error. files with '.bat' extension are not allowed by producer1
[2017-05-16 14:27:08.309] ERRORDTL [1494959228308]com.sterlingcommerce.woodstock.mailbox.repository.MailboxRepositoryException: User Exit Error. files with '.bat' extension are not allowed by producer1
at com.sterlingcommerce.woodstock.mailbox.impl.repositoryImpl.RepositoryDB$1.body(RepositoryDB.java:342)
at com.sterlingcommerce.woodstock.mailbox.db.DatabaseOperation._runInTransaction(DatabaseOperation.java:336)
at com.sterlingcommerce.woodstock.mailbox.db.DatabaseOperation.runInTransaction(DatabaseOperation.java:145)
ftp.log :
[2017-05-16 14:27:07.708] ALL AUDIT: User [producer1] storing file [/test.bat].
[2017-05-16 14:27:07.787] ERROR FtpState.handleSTORINGExit(FS)caught FtpMailboxRepositoryException.
[2017-05-16 14:27:07.787] ERROR [1494959227787] null
[2017-05-16 14:27:07.788] ERRORDTL [1494959227787]com.sterlingcommerce.woodstock.services.ftpserver.server.exception.FtpMailboxRepositoryException
at com.sterlingcommerce.woodstock.services.ftpserver.server.FtpMailboxDataStore.close(FtpMailboxDataStore.java:1699)
at com.sterlingcommerce.woodstock.services.ftpserver.server.FtpFile.closeWrite(FtpFile.java:131)
at com.sterlingcommerce.woodstock.services.ftpserver.server.FtpFile.close(FtpFile.java:101)
at com.sterlingcommerce.woodstock.services.ftpserver.server.FtpState.handleSTORINGExit(FtpState.java:312)
Caused by: com.sterlingcommerce.woodstock.mailbox.repository.MailboxRepositoryException: User Exit Error. files with '.bat' extension are not allowed by producer1
at com.sterlingcommerce.woodstock.mailbox.impl.repositoryImpl.RepositoryImpl.add(RepositoryImpl.java:304)
at com.sterlingcommerce.woodstock.mailbox.impl.repositoryImpl.RepositoryImpl.add(RepositoryImpl.java:180)
at com.sterlingcommerce.woodstock.services.ftpserver.server.FtpMailboxDataStore.closeWrite(FtpMailboxDataStore.java:1878)
Uploading file into mailbox through myfilegateway UI
mailbox.log :
[2017-05-16 14:08:53.402] ERROR RepositoryDB.addMessage() - Caught exception while adding message
[2017-05-16 14:08:53.402] ERROR [1494958133402] User Exit Error. files with '.bat' extension are not allowed by producer1
[2017-05-16 14:08:53.569] ERRORDTL [1494958133402]com.sterlingcommerce.woodstock.mailbox.repository.MailboxRepositoryException: User Exit Error. files with '.bat' extension are not allowed by producer1
at com.sterlingcommerce.woodstock.mailbox.impl.repositoryImpl.RepositoryDB$1.body(RepositoryDB.java:342)
at com.sterlingcommerce.woodstock.mailbox.db.DatabaseOperation._run(DatabaseOperation.java:293)
at com.sterlingcommerce.woodstock.mailbox.db.DatabaseOperation.runInTransaction(DatabaseOperation.java:140)
at com.sterlingcommerce.woodstock.mailbox.impl.repositoryImpl.RepositoryDB.addMessage(RepositoryDB.java:311)
at com.sterlingcommerce.woodstock.mailbox.impl.repositoryImpl.RepositoryImpl.lowLevelAdd(RepositoryImpl.java:382)
at com.sterlingcommerce.woodstock.mailbox.impl.repositoryImpl.RepositoryImpl$1.body(RepositoryImpl.java:284)
at com.sterlingcommerce.woodstock.mailbox.db.DatabaseOperation._run(DatabaseOperation.java:293)
Uploading file into mailbox through SFTP Server Adapter
Used WinSCP to upload file.
Errors are seen in sftpserver.log, mailbox.log, userexit.log.
Like these 3 test cases, any upload attempt by "producer1" uploading ".bat" file over any protocol fails. But other users should not be impacted and they should still be able to upload batch files.
UID
ibm11120965