IBM Support

Mailbox User Exits. How to plugin custom code with MailboxAdd

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.

  1. com.sterlingcommerce.woodstock.userexit.services.mailbox.interfaces.IMailboxUserExit_OnMailboxCreate
  2. com.sterlingcommerce.woodstock.userexit.services.mailbox.interfaces.IMailboxUserExit_OnMailboxUpdate
  3. com.sterlingcommerce.woodstock.userexit.services.mailbox.interfaces.IMailboxUserExit_OnMailboxDeleteSet
  4. com.sterlingcommerce.woodstock.userexit.services.mailbox.interfaces.IMailboxUserExit_OnMessageDelete
  5. com.sterlingcommerce.woodstock.userexit.services.mailbox.interfaces.IMailboxUserExit_OnMessageExtract
  6. com.sterlingcommerce.woodstock.userexit.services.mailbox.interfaces.IMailboxUserExit_OnMessageExtractBegin
  7. 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.

image

 

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.

image

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";
   static String FILE_EXTN=".bat";
   static String USER_EXCLUDE="producer1";

   public boolean onMessageAdd(java.util.Map inargs,java.util.Map outargs) throws java.lang.Exception {
        System.out.println(CLASS_NAME + ".onMessageAdd(M,M) Starting."); // System.out lines printed in noapp.log.date log file

        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)) {
                outargs.put(IMailboxUserExit_OnMessageAdd.KEY_ERROR_BUFFER, new StringBuffer("User Exit Error. ").append("files with \'" + FILE_EXTN + "\' extension are not allowed by " + USER_EXCLUDE));
                outargs.put(IMailboxUserExit_OnMessageAdd.KEY_LOG_BUFFER, new StringBuffer("User Exit Error. ").append("Files with \'" + FILE_EXTN + "\' extension are not allowed by " + USER_EXCLUDE));

                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 install/properties/MailboxUserExits.xml under corresponding user exit bean tag as below.

        <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 properties/dynamiclcasspath.cfg and properties/dynamiclcasspathAC.cfg (for containers). Please make sure SB2Bi is stopped before running this step.

e.g., ./install3rdParty.sh userexitMBX 1_0 -j <path_to_jar>/IBMUserExitsMbx.jar


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

image

 

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

 

image

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.

image

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.

 

[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SS3JSW","label":"IBM Sterling B2B Integrator"},"Component":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"","Edition":"","Line of Business":{"code":"LOB59","label":"Sustainability Software"}}]

UID

ibm11120965

Page Feedback