Working with Change Preprocessors

Creating a Change Preprocessor Handler

To create a change preprocessor handler, you must implement the preprocessObjectChange method of the Java™ ChangePreprocessor interface. The following examples show Java and JavaScript implementations, each of which checks that instances of a user-defined class meet mime type requirements. Note that the MimeType property can be set only on check-in.

Java Example

/* For AccountsReceivable class, enforce mime type requirement 
of "application/x-transactionmanager". */
package sample.actionhandler;
import com.filenet.api.action.*;
import com.filenet.api.core.IndependentlyPersistableObject;
import com.filenet.api.constants.PropertyNames;
import com.filenet.api.exception.*;

public class ChangePreprocessorHandler implements com.filenet.api.engine.ChangePreprocessor
{
   public boolean preprocessObjectChange(IndependentlyPersistableObject sourceObj)
   {
      try {
         boolean checkMimeType = false;

         // Check MimeType property only for create and checkin actions.
         PendingAction actions[] = sourceObj.getPendingActions();
         for ( int i = 0; i < actions.length && !checkMimeType; i++ )
         {
            if ( actions[i] instanceof Create || actions[i] instanceof Checkin ) 
               checkMimeType = true;
         }
         if ( !checkMimeType ) return false;

         // Verify that MimeType property is in collection before attempting to retrieve it.
         if (sourceObj.getProperties().isPropertyPresent(PropertyNames.MIME_TYPE) )
         {
            // Change MimeType value if it does not conform to the requirement.
            String mimeType = sourceObj.getProperties().get(PropertyNames.MIME_TYPE).getStringValue();
            if (mimeType == null ||!mimeType.equalsIgnoreCase("application/x-transactionmanager") )
            {
               sourceObj.getProperties().putValue("MimeType", "application/x-transactionmanager");
               return true;
            }
         }
         return false;
      }
      catch (Exception e) {
         throw new RuntimeException(e);
      }
   }
}

JavaScript Example

/* For AccountsReceivable class, enforce mime type requirement 
of "application/x-transactionmanager". */
importPackage(java.lang);
importPackage(Packages.com.filenet.api.action);
importClass(Packages.com.filenet.api.core.IndependentlyPersistableObject);
importClass(Packages.com.filenet.api.constants.PropertyNames);

function preprocessObjectChange(sourceObj)
{
   try { 
      var checkMimeType = false;
      
      // Check MimeType property only for create and checkin actions.
      var actions = sourceObj.getPendingActions(); 
      for ( var i = 0; i < actions.length && !checkMimeType; i++ )
      {
         if ( actions[i] instanceof Create || actions[i] instanceof Checkin )
            checkMimeType = true;
      }
      if ( !checkMimeType ) return false;
      
      // Verify that MimeType property is in collection before attempting to retrieve it.
      if (sourceObj.getProperties().isPropertyPresent(PropertyNames.MIME_TYPE) )
      {
            // Change MimeType value if it does not conform to the requirement.
            var mimeType = sourceObj.getProperties().get(PropertyNames.MIME_TYPE).getStringValue();
            if (mimeType == null ||!mimeType.equalsIgnoreCase("application/x-transactionmanager") )
            {
               sourceObj.getProperties().putValue("MimeType", "application/x-transactionmanager");
               return true;
            }
      }
      return false;     
   }
   catch (e) {
      throw new RuntimeException(e);
   }
}

Creating a ChangePreprocessorAction Object

A CmChangePreprocessorAction object identifies the change preprocessor handler to start on an instance of a class that is associated with a change preprocessor. The following Java and C# examples show how to create two CmChangePreprocessorAction objects, one that references a handler that is implemented with Java and one that references a handler that is implemented with JavaScript.

For the first CmChangePreprocessorAction object that is created, the handler that is implemented with Java is contained within a code module, requiring retrieval of the CodeModule object and setting it on the CodeModule property of the CmChangePreprocessorAction object.

For the second CmChangePreprocessorAction object that's created, the change preprocessor handler is implemented in JavaScript, requiring that the script is set on the object's ScriptText property.

Java Example

// Create change preprocessor action for Java handler.
CmChangePreprocessorAction cpaJava = Factory.CmChangePreprocessorAction.createInstance(os, "CmChangePreprocessorAction");

// Get CodeModule object with Java component.
CodeModule cm = Factory.CodeModule.getInstance(os, "CodeModule",
                new Id("{1DFCEDCC-B734-45AD-93D6-03874E8F1288}") ); 

// Set CodeModule property.
cpaJava.set_CodeModule(cm);

// Set ProgId property with fully qualified name of handler class.
cpaJava.set_ProgId("sample.actionhandler.ChangePreprocessorHandler");

// Set other properties and save.
cpaJava.set_IsEnabled(false);
cpaJava.set_DisplayName("MimeType validation");
cpaJava.save(RefreshMode.REFRESH);

// Create change preprocessor action for JavaScript handler.
CmChangePreprocessorAction cpaJavascript = Factory.CmChangePreprocessorAction.createInstance(os, "CmChangePreprocessorAction");

// Set ProgId property to script type identifier.
cpaJavascript.set_ProgId("Javascript");

// Call method to read script from a file, and set the script text on the action object.
String inputScript = readScriptText();
cpaJavascript.set_ScriptText(inputScript);

// Set other properties and save.
cpaJavascript.set_IsEnabled(true);
cpaJavascript.set_DisplayName("MimeType validation");
cpaJavascript.save(RefreshMode.REFRESH);

C# Example

// Create change preprocessor action for Java handler.
ICmChangePreprocessorAction cpaJava = Factory.CmChangePreprocessorAction.CreateInstance(os, "CmChangePreprocessorAction");

// Get CodeModule object with Java component.
ICodeModule cm = Factory.CodeModule.GetInstance(os, "CodeModule",
                 new Id("{1DFCEDCC-B734-45AD-93D6-03874E8F1288}") ); 

// Set CodeModule property.
cpaJava.CodeModule = cm;

// Set ProgId property with fully qualified name of handler class.
cpaJava.ProgId = "sample.actionhandler.ChangePreprocessorHandler";

// Set other properties and save.
cpaJava.IsEnabled = false;
cpaJava.DisplayName = "MimeType validation";
cpaJava.Save(RefreshMode.REFRESH);

// Create change preprocessor action for JavaScript handler.
ICmChangePreprocessorAction cpaJavascript = Factory.CmChangePreprocessorAction.CreateInstance(os, "CmChangePreprocessorAction");

// Set ProgId property to type of script.
cpaJavascript.ProgId = "Javascript";

// Call method to read script from a file, and set the script text on the action object.
String inputScript = readScriptText();
cpaJavascript.ScriptText = inputScript;

// Set other properties and save.
cpaJavascript.IsEnabled = true;
cpaJavascript.DisplayName = "MimeType validation";
cpaJavascript.Save(RefreshMode.REFRESH);

Creating a ChangePreprocessorDefinition Object

After you create the change preprocessor handler and the CmChangePreprocessorAction object, you are ready to create a CmChangePreprocessorDefinition object. In the following Java and C# examples, the CmChangePreprocessorDefinition object is set on the SubscribableClassDefinition object that represents the user-defined AccountsReceivable class.

Java Example

// Create change preprocessor definition object.
CmChangePreprocessorDefinition cpDef = Factory.CmChangePreprocessorDefinition.createInstance(os);
cpDef.set_DisplayName("Accounts Receivable - MimeType validation");
cpDef.set_IsEnabled(true);

// Get CmChangePreprocessorAction and set on definition object.
CmChangePreprocessorAction action = Factory.CmChangePreprocessorAction.getInstance(os, "CmChangePreprocessorAction",
     new Id("{45A990F2-1B0D-4CF2-AB3E-9B6B06A5410E}") );
cpDef.set_ChangePreprocessorAction(action);

// Create change preprocessor definition list object and add definition object.
CmChangePreprocessorDefinitionList cpdList=Factory.CmChangePreprocessorDefinition.createList();
cpdList.add(cpDef);

// Get AccountsReceivable class definition and set definition list object on it. 
SubscribableClassDefinition objClassDef = Factory.SubscribableClassDefinition.getInstance(os, new Id("3ADC7781-ED70-43E4-97C3-40CF7DE2D565}") );
objClassDef.set_ChangePreprocessorDefinitions(cpdList);

objClassDef.save(RefreshMode.NO_REFRESH);

C# Example

// Create change preprocessor definition object.
ICmChangePreprocessorDefinition cpDef = Factory.CmChangePreprocessorDefinition.CreateInstance(os);
cpDef.DisplayName = "Accounts Receivable - MimeType validation";
cpDef.IsEnabled = true;

// Get ICmChangePreprocessorAction and set on definition object.
ICmChangePreprocessorAction action = Factory.CmChangePreprocessorAction.GetInstance(os, "CmChangePreprocessorAction"
     new Id("{0551C740-3502-46D1-9DB0-98CBDBD70232}") );
cpDef.ChangePreprocessorAction=action;

// Create change preprocessor definition list object and add definition object.
ICmChangePreprocessorDefinitionList cpdList=Factory.CmChangePreprocessorDefinition.CreateList();
cpdList.Add(cpDef);

// Get AccountsReceivable class definition and set definition list object on it. 
ISubscribableClassDefinition objClassDef = Factory.SubscribableClassDefinition.GetInstance(os, new Id("3ADC7781-ED70-43E4-97C3-40CF7DE2D565}") );
objClassDef.ChangePreprocessorDefinitions = cpdList;

objClassDef.Save(RefreshMode.NO_REFRESH);

Retrieving Change Preprocessor Actions

The following Java and C# examples show how to retrieve a collection of CmChangePreprocessorAction objects from an object store.

Java Example

// Retrieve change preprocessor actions from the object store.
FilterElement fe = new FilterElement(null, null, null, PropertyNames.CHANGE_PREPROCESSOR_ACTIONS, null);
PropertyFilter pf = new PropertyFilter();
pf.addIncludeProperty(fe);
os.fetchProperties(pf);
CmChangePreprocessorActionSet cpActionSet = os.get_ChangePreprocessorActions();

// Iterate the action set.
Iterator iter = cpActionSet.iterator();
while (iter.hasNext() )
{
   CmChangePreprocessorAction cpAction = (CmChangePreprocessorAction)iter.next();
   System.out.println("Action: " + cpAction.get_DisplayName() + " | IsEnabled: " + cpAction.get_IsEnabled() );
}

C# Example

// Retrieve change preprocessor actions from the object store.
FilterElement fe = new FilterElement(null, null, null, PropertyNames.CHANGE_PREPROCESSOR_ACTIONS, null);
PropertyFilter pf = new PropertyFilter();
pf.AddIncludeProperty(fe);
os.FetchProperties(pf);
ICmChangePreprocessorActionSet cpActionSet = os.ChangePreprocessorActions;

// Iterate the action set.
foreach (ICmChangePreprocessorAction cpAction in cpActionSet)
{
   System.Console.WriteLine("Action: " + cpAction.DisplayName + " | IsEnabled: " + cpAction.IsEnabled );
}

Retrieving Change Preprocessor Definitions

The following Java and C# examples show how to retrieve a list of CmChangePreprocessorDefinition objects from a class definition.

Java Example

// Fetch AccountsReceivable class definition and get list of CmChangePreprocessorDefinition objects. 
SubscribableClassDefinition scd = Factory.SubscribableClassDefinition.fetchInstance(os, new Id("3ADC7781-ED70-43E4-97C3-40CF7DE2D565}"), null);
CmChangePreprocessorDefinitionList cpdList = scd.get_ChangePreprocessorDefinitions();

// Iterate the definition list.
Iterator iter = cpdList.iterator();
while (iter.hasNext() )
{
   CmChangePreprocessorDefinition cpDef = (CmChangePreprocessorDefinition)iter.next();
   System.out.println("Definition: " + cpDef.get_DisplayName() + " | IsEnabled: " + cpDef.get_IsEnabled() );
}

C# Example

// Fetch AccountsReceivable class definition and get list of CmChangePreprocessorDefinition objects. 
ISubscribableClassDefinition scd = Factory.SubscribableClassDefinition.FetchInstance(os, new Id("3ADC7781-ED70-43E4-97C3-40CF7DE2D565}"), null);
ICmChangePreprocessorDefinitionList cpdList = scd.ChangePreprocessorDefinitions;

// Iterate the definition list.
foreach (ICmChangePreprocessorDefinition cpDef in cpdList)
{
   System.Console.WriteLine("Definition: " + cpDef.DisplayName + " | IsEnabled: " + cpDef.IsEnabled );
}