Having seen a more than a few IBM Content Navigator / Case Manager customization’s, i noticed almost every solution i encountered has responsiveness problems. Now, while it might be the result of the team composition (focus on backend development), i personally think it’s due to DoJo, lacking a nice layout framework, such as the grid system i love from Bootstrap.

Now, after googling a bit i finally came across flexboxgrid. A pure CSS system relying on the flex display property, that compared to other grid frameworks i came across doesn’t collide with any of the existing DoJo or ecm css/javascript.

Want to use it? Simply add the flexboxgrid.css to a ICN plugin, and you’re ready!

A few days ago i decided to pick up work on a simple web-game i once tried to created when i was 15 (see related: Generating isometric tiles and slopes). And while working on it i decided the architecture should be able support multiple workers performing on a single database. As a consequence i required all my worker’s to be able to all use the same datetime.

Now as i’m not in control of the host machines to actually perform a time-sync, i figured i should best use the remote-database time as the single truth.

I ended up writing the following utility class, i’m really curious on what you guys think of it.

note: Unfortunately no generic JPA query, but one specific to mysql

package nl.ivojonker.sm.model.util;

import java.sql.Timestamp;
import java.util.Date;

import javax.annotation.PostConstruct;
import javax.ejb.Singleton;
import javax.ejb.Startup;
import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;

/**
 * Utility class for obtaining the current datetime from the database server.
 * @author Ivo
 *
 */
@Singleton
@Startup
public class DBDate {

	private static long localCacheDate=System.currentTimeMillis();
	private static long remoteCacheDate=System.currentTimeMillis(); 

	@PersistenceContext 
	private EntityManager em;

	/**
	 * Returns the date-time from the server.
	 * @return
	 */
	public static Date getDate(){
		return new Date(remoteCacheDate+(System.currentTimeMillis()-localCacheDate));
	}

	@PostConstruct
	private void init(){
		long beforRequest=System.currentTimeMillis();
		Timestamp remoteDate = (Timestamp)(em.createNativeQuery("select CURRENT_TIMESTAMP").getSingleResult());
		long latency = System.currentTimeMillis() - beforRequest;
		
		localCacheDate=beforRequest;
		remoteCacheDate=remoteDate.getTime()-latency;
		
		System.out.println(String.format("Local date: %1$s, remote set to date: %2$s, taking into account an estimated latency of: %3$s ms ", new Date(localCacheDate),new Date(remoteCacheDate),latency));
	}
}

Case Manager developers are expected to be multi disciplinary. e.g. they’re expected to be experienced ECM consultants, guru in solution design, expert in Filenet P8 configuration/development, and both Java EE as wel as Web expert.

The thing is, most of the developers only excel in one, and lack expert knowledge of another. In practice most will definately be able to create some java (or dojo), but more than once i’ve seen people get stuck on the debugging. So, in this article, i’ll share a few short lines on how to debug your widgets/plugins.

Debugging java-code that’s run on the server.

This part assumes the use of Websphere and Eclipse.

First of all, know that all your Case Manager Widget’s or Content Navigator plugin’s java-code runs on the server. The .ear files you’ve included within your widget.zip are installed as applications on the webserver; and the navigator plugins you’ve included are run from within the Navigator web-application -> that’s run on Websphere as well.

So following that your java code is run on Websphere there are two things we need to do to be able to debug.

1. Enable debug-mode in Websphere.

When enabling debug mode within Websphere, we bascially set enable debug mode in the Java Virtual machine. The easiest way to do this is by using the WAS console (https://<server>:9043/ibm/console)

Step 1. Login to the WAS console and locate your server (server1 in the below screenshot). Click on it.

Step 2. In the screen that follows, locate  “Debugging Service”  under “Additional Properties”, click it.

Step 3. Check the “Enable service at server startup” and enter a “JVM-debug port”. Can be be arbitrary as long as it’s not in use.

Step 4. Reboot Websphere. The debugging port won’t be upon until after reboot.

2. Connect to the JVM debug port using Eclipse.

Step 1. Open the Debug Configurations screen.

Step 2. Add a new “Remote Java Application”.

Step 3. Choose the Project you want to debug and enter the your websphere IP as HOST, and port 7777 as port. Then press debug. The screen will close, and the debugger will connect.

3. Set your breakpoints and debug.

Place your breakpoint, execute the corresponding functionality in your application and watch the debugger kick in.

Debugging your widget’s javascript.

Debugging javascript is quite easy in modern browsers. Although IBM cleary notes it’s designing its products for use with FireFox and Internet Explorer, i personally prefer Chrome.

When in chrome, simply press the F12 key.  In the screen that opens (The Developer Tools) then search for the Sources tab. This tab will list all .js files loaded, including your plugin script.

An easier way to locate your line of code, is by pressint CTRL+SHIFT+F, allowing you to search all code for a specific line as shown below.

Once you’ve found your file, just click the line-numbers to place a breakpoint and you’re set!

Debugging your Script-adapter’s javascript.

The above doesn’t really count for script adapters. As the script written in the adapters is executed through eval() or runscript. There are two workarounds.

1. Externalize your script in a .js and call it from the script adapter.
   No much explanation needed i guess 🙂
2. Make use of the debugger; statement.
   The debugger statement will force to hold execution whenever the Developer Tools are open (all browsers supported). The below screenshots demonstrates a simple ScriptAdapter that pauses on the debugger statement.

Additionally, if you can also drag your script-adapter from the hidden part in the page-designer onto the page. This way your script adapter will (if checked) actively show the payloads received by your script adapter.

After finding out that it’s a real bad idea to store certain information in ICN plugins, i started looking for alternatives. Eventually i came up with the idea to create a new ICN plugin to be able to manage a central configuration repository that is secure and has support for multi server/application access.

Basically the plugin has the following characteristics:

• It stores data in key/value format.
• The data is centrally stored in a database, and accessed via a JNDI registered datasource.
• It’s values are accessible both front-end as back-end
• It’s accessible from all applications in a multi-server environment.
• It’s data is centrally stored.
• Security can be applied to prevent leakage of passwords or api keys.
• The configuration can be managed within the Content Navigator Admin page;
• And can be configured with a familiar look and feel.
• The configuration can be bulk-updated by replacing a JSON allowing easy management of OTAP configurations.

Example of the management interface.

As you can see below a property is identified by a key; keys are alphabetically grouped, and all values can be composed of multi-line strings. Each value can be marked ‘evaluate at front-end’ which means the key/value combination will be accessible trough JavaScript. Additionally values can be “evaluated” which basically means JavaScripts’ eval function is called – this can be handy to to have a JavaScript function or Object stored in the configuration.

For convenience all properties can have a description (click the info icon) so any administrator can easily discover the purpose of the configuration entry.

Sample JavaScript code:

require("CentralConfiguration").get("filenet.ce.iiop")

A second parameter can be provided to return a default value if the key ends up to be null or not present in the configuration repository.

Sample Java code:

Please take into account that the Central Configuration plugin requires the application to be run within a WebSphere context.

package nl.ivojonker.sample;

import nl.ivojonker.icn.configuration.Configuration;

public class SampleUsage {
	
	public static void doStuff(){
		
		boolean useCache = false;
		
		//Retrieves the singleton with default useCache = true Simply re-uses earlier collected configuration 
		Configuration config = Configuration.getInstance();
		
		//Retrieves the singleton with the option to provide useCache=false
		config = Configuration.getInstance(useCache);
		
		//Retrieves the singleton, but will not throw exceptions upon failure - might sometimes be convenient.
		//The risk of not having a configuration available might be mitigated by using the following .getProperty(key,default) function.
		config = Configuration.getInstanceSupressExceptions(useCache)

		//retrieves the value for filenet.ce.defaultobjectstore.
		config.getProperty("filenet.ce.defaultobjectstore");
		

		//retrieves the value for filenet.ce.defaultobjectstore, but returns default if the value does not exist.
		config.getProperty("filenet.ce.defaultobjectstore","TARGET");
	}

}

Download & support

You can download the .jar with source & javadoc here.

The manual can be found here.

If by any chance you have feature requests, feel free to request them by mail or via the form below. The same for any bugs you encounter.

If you make any profound additions or changes to the code, please send them in so we can share them to the world:)

I always strive to publish at least one article a month; this month however will be skipped due to preparations for my upcoming holiday.

As always i tend to go to places where i’m totally disconnected. E.g. my last holiday’s were in the (middle of the) Amazon rain forest, the Norwegian highlands and in the Croatian back country.

Next holiday won’t be any different, but a lot closer to home along with my new born daughter Mila.

Can’t wait!

From my experience as a P8 engineer i know many are actually struggling with this. So in this post i’ll share a textbook example on how to  re-use your BPF/ICN/ICM authentication in your own custom Java EE application.

Download the complete sample project here

The following project assumes the use of IBM Websphere with support for EE6 (personally using 8.5.5.).

The sample project contains a few essential parts:

1. A Simple rest-service that exposes two methods;

1. a /ping api that will be accessible to all;
2. and a /getObjetStoreID api that is only available to users currently logged on.

/**
 * Sample rest service for which access is managed by the container.  
 * @author nl.ivojonker
 */
@Stateless
public class SampleService {


	private static final String CPEIIOPURL = "iiop://";
	private static final String OBJECTSTORENAME = "OBJECTSTORENAME";

	/**
	 * Accesible to everyone (see web.xml)
	 * @return
	 */
	@Path("/ping")
	public String ping(){
		return "pong!";
	}

	/**
	 * A simple api call that requires the user to be authenticated (see web.xml) 
	 * @return
	 */
	@Path("/getObjectStoreID")
	@Produces(MediaType.TEXT_PLAIN)
	public Response someApi(){
		Connection connection = Factory.Connection.getConnection(CPEIIOPURL);

		Subject subject = UserContext.getAmbientSubject();
		if (subject == null) {
			return Response.status(Status.FORBIDDEN).entity("No SSO or existing session").build();
		}

		UserContext.get().pushSubject(subject);

		Domain domain = Factory.EntireNetwork.fetchInstance(connection, null).get_LocalDomain();
		ObjectStore store = Factory.ObjectStore.fetchInstance(domain, OBJECTSTORENAME, null);

		return Response.ok(store.get_Id().toString()).build();
	}

}

2. A web.xml in which is specified what resources (urls) are behind authentication, and which urls are not.

	<security-constraint>
		<web-resource-collection>
			<web-resource-name>SampleService</web-resource-name>
			<description>While the complete application is secured....</description>
			<url-pattern>/*</url-pattern>
		</web-resource-collection>
		<auth-constraint>
			<role-name>All Authenticated</role-name>
		</auth-constraint>
		<user-data-constraint>
			<description>User data constraints</description>
			<transport-guarantee>NONE</transport-guarantee>
		</user-data-constraint>
	</security-constraint>

	<security-constraint>
		<web-resource-collection>
			<web-resource-name>SampleService</web-resource-name>
			<description>Everyone is allowed to access the ping page</description>
			<url-pattern>/rest/ping</url-pattern>
		</web-resource-collection>
		<user-data-constraint>
			<description>User data constraints</description>
			<transport-guarantee>NONE</transport-guarantee>
		</user-data-constraint>
	</security-constraint>

	<security-role>
		<description>All Authenticated</description>
		<role-name>All Authenticated</role-name>
	</security-role>
	<security-role>
		<description>Everyone</description>
		<role-name>Everyone</role-name>
	</security-role>

3. An (websphere specific) ibm-application-bnd.xml file in which we map security roles to subjects.

Note that this can be managed from within the wasadmin as well.

<?xml version="1.0" encoding="UTF-8"?>
<application-bnd xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://websphere.ibm.com/xml/ns/javaee"
    xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-application-bnd_1_0.xsd" version="1.0">
  <security-role name="All Authenticated">
    <special-subject type="ALL_AUTHENTICATED_USERS"/>
  </security-role>
  <security-role name="Everyone">
    <special-subject type="EVERYONE"/>
  </security-role>
</application-bnd>

Wrapping it all up; there’s just no need for complex mechanisms, – or worse, storing and sharing passwords between services 🙂

For those creating IBM Content Navigator plugins, please be advised not to store any tokens, passwords or API keys in the plugin configuration, as it will be accessible to all authenticated users.

Although you would expect the ICN admin-api to be limited to admin-users, the following snippet works for everyone 🙂

require (["ecm/model/admin/ApplicationConfig"],function(ApplicationConfig){ 
    ApplicationConfig.getPluginObjects(function (plugins){
        console.log(plugins)
    })
})

A suggestion would be to create a ‘central configuration’ plugin, that stores its configuration (though the configurationpane) in a different location/datasource – only accesible for admin users. A nice addition would be to create a java class that performs a server-side lookup of the datasource allowing access to the configuration just anywhere within your server context 🙂

p.s. Did you know the IBM ICA/Watson plugin requires configuting an API key?

Update: I translated my own suggestion into a working solution:) See Central Configuration plugin for multi-server ICN/ICM environments

Just a quick write as i encounter a lot of web applications where the front-end is using UTF-8 encoding to post values to the backend, while the backend, is interpreting them with different (java default iso-8859-1).

Now since Servlet 2.3, there is the Request.setCharacterEncoding(), but unfortunately this doesn’t work if any single parameter has been read before setting the character encoding. In that case, you might do the following:

String someText = request.getParameter("someText");
someText = new String(jsCaseProps.getBytes(Charset.defaultCharset()),request.getCharacterEncoding())

Where Charset.defaultCharset() is probably the ISO-8859-1, as it is default for most application servers.

Note to self: Don’t forget to annotate complex fiels with the @Mutable annotation.

It might sound noobish, but i’ve just spend the last 2 hours trying to find out why my jpa/eclilpse link entity wasn ‘t updating my ‘complex’ (hashmap) field. At first, i figured it had something to do with the @Converter i was using to serialize/deserialize the HashMap into a JSON string. But eventually it turned out, that the change-tracking mechanism only works for non-mutable/basic fields. And thus, no updates were detected, as i was updating the hashmap, instead of replacing it.

So as it turns out (i should have read the manual ;)) the @Mutable annotation is there to use.

@Entity
public class BasicEntity {

	@Id
	@GeneratedValue
	private int id;
	
	@JsonAdapter(BasicEntityTypeAdapter.class)
	private BasicEntityType type;

	private String location;
	
	private float x;
	private float y;
	
	
	@Convert(converter = JPAHashmapToStringConverter.class) /*store as String/json*/
	@Column(length=4096)
	@Mutable
	private HashMap<String, Object> properties;
}

@Converter
public class JPAHashmapToStringConverter implements AttributeConverter<HashMap<String, Object>,String>{

	  private final static Gson gson = new Gson();
	  private final static Class hashMapClass = new HashMap<String,Object> ().getClass();

	  @Override
	  public String convertToDatabaseColumn(HashMap<String, Object> meta) {
		  if (meta==null)meta = new HashMap<String,Object>();
	      return gson.toJson(meta);
	  }

	  @Override
	  public HashMap<String, Object> convertToEntityAttribute(String dbData) {
		 
		  return gson.fromJson(dbData,hashMapClass);
	  }

}

I’ve been creating web-app’s for ages. And what’s been annoying me for quite a while, is that – due to the client/server separation – i end up duplicating a lot of client-side validation-logic on the server-side.

Now, as for solutions to this counter-intuitive phenomonem, i’ve encountered and implemented all of the below:

1. None, or sloppy server-side validations are written.
   Those lazy, or unable to know something’s wrong or without a sense of urgency (security or usability aspects) will probably delay finding a solution, and end up writing no or proper validations on either one of the sides.
2. Microservices-like backend validation.
   A proper solution, but one with a lot of communication overhead limiting realtime validation.
3. Statefull “External Data Source” approach.
   An approach where the server keeps a live model and dictates the client what valid values are. Limited as it is statefull.

But one thing i never thought of, is to share exact the same code, both front-end and backend. But today, i saw the opportunity to do so while working on a greenfeeld side-project.

The solution

The solution is to write all validation code in Javascript, and share the script both client & serverside. The requirement that follows is that your (server-side) data-model should be representable in JSON. And that JSON should be the model for your client-side code.

A sample project could be as fllows:

• Java
  • model
    • UserProfile.java
      e.g. a JPA annotated POJO that has been setup to serialize to JSON usable as front-end-model.
  • restapi
    • UserProfiles.java
      an interface providing the UserProfile JSON and business logic
  • validation
    • Validator.java
      Containing Javascript ‘javax.script.ScriptEngine’ that exposes a validate(functionName, BusinessObject…) function
• Web
  • sharedJS
    • UserProfileValidation.js
      That contains a function to validate a UserProfile Javascript Object.
  • Index.html
    A webpage to show and manipulate UserProfiles. It makes use of the UserProfileValidation.js to check if everything is correct.

The flow:

1. The index.html invokes the restapi and retrieves a JSON representing a specific UserProfile.
2. Upon client-side manipulation the’new’ JSON is validated real-time using the functions in the UseProfileValidation.js.
3. Eventually the client sends back any manipulations back to the restapi, which constructs an update UserProfile.
4. When JPA wants to persist the entity, it asks the Validator to validate.
5. The validator constructs a JavascriptEngine, injects the UserProfile as JavascriptObject(using JSON), and validates using the UserProfileValidation
6. Upon failure to validate, rolls-back the transaction.