Enrichir les données stockées à travers FlowerDocs avec un référentiel tiers.

Un lookup consiste en la récupération de données issues d’un référentiel tiers. Il permet ainsi d’enrichir les données stockées ou restituées à travers FlowerDocs. L’API JavaScript Lookup permet de faire appel à des lookups, au sein d’une extension JavaScript de FlowerDocs, de manière dynamique.

Cette fonctionalité s’appuie sur une notion de plugin permettant d’exécuter différents types d’appels/requêtes (base de données, web services…).

Lookup plugins

Plugin JavaScript

Un lookup plugin peut être défini en JavaScript à l’aide de l’API mise à disposition. Pour cela, il est nécessaire d’instancier un objet LookupPlugin comme indiqué dans l’exemple ci-dessous. Un plugin de ce type dispose d’un LookupHandler appelé lorsque le lookup est exécuté afin de fournir à FlowerDocs une liste de résultats correspondants.

var lookupPlugin = new LookupPlugin();
lookupPlugin.setLookupHandler(function(fieldName, fieldValue, callback){
	var results = new Array();
	callback.onSuccess(results);
});

Chaque plugin doit ensuite être mis à disposition de l’application. Le snipet ci-dessous indique comment enregistrer le plugin où lookupId correspond au nom du lookup.

var lookupAPI = JSAPI.get().getLookupAPI();
lookupAPI.register("lookupId", lookupPlugin);

Plugin serveur

Pour rendre un LookupPlugin disponible depuis l’interface graphique, il faut :

Définir le plugin dans le contexte Spring :

<bean id="BusinessReferenceLookup" class="com.flower.docs.gui.server.lookup.sql.DBLookupPlugin">
<property name="dataSource" ref="lookupDataSource" />
<property name="requests">
	<list>
	  <bean class="com.flower.docs.gui.server.lookup.sql.FieldLookupRequest">
		<property name="request" value="Select DISPLAY_NAME from BUSINESS_REFERENCES WHERE REF LIKE '%{value}%'" />
		<property name="column" value="DISPLAY_NAME" />
	  </bean>
	</list>
</property>
</bean>

Référencer le plugin au sein du catalogue LookupPluginCatalog :

<entry key="<id du plugin>" value-ref="<id du bean Spring>" />

Exemple complet :

<util:map id="LookupPluginCatalog" map-class="java.util.HashMap">
	<entry key="BusinessReferenceLookup" value-ref="BusinessReferenceLookup" />
</util:map>
<bean id="BusinessReferenceLookup" class="com.flower.docs.gui.server.lookup.sql.DBLookupPlugin">
	<property name="dataSource" ref="lookupDataSource" />
	<property name="requests">
		<list>
			<bean class="com.flower.docs.gui.server.lookup.sql.FieldLookupRequest">
				<property name="request" value="Select DISPLAY_NAME from BUSINESS_REFERENCES WHERE REF LIKE '%{value}%'" />
				<property name="column" value="DISPLAY_NAME" />
			</bean>
		</list>
	</property>
</bean>
<bean id="lookupDataSource" class="oracle.jdbc.pool.OracleDataSource" destroy-method="close">
	<property name="connectionCachingEnabled" value="true" />
	<property name="URL" value="${jdbc.url:jdbc:oracle:thin:@//localhost:1521/orcl}" />
	<property name="user" value="${jdbc.username:hr}" />
	<property name="password" value="${jdbc.password:oracle}" />
	<property name="connectionCacheProperties">
		<props merge="default">
			<prop key="MinLimit">${jdbc.minLimit:1}</prop>
			<prop key="MaxLimit">${jdbc.maxLimit:20}</prop>
			<prop key="InitialLimit">${jdbc.initialLimit:1}</prop>
			<prop key="ConnectionWaitTimeout">${jdbc.connectionWaitTimeout:120}</prop>
			<prop key="InactivityTimeout">${jdbc.inactivityTimeout:180}</prop>
			<prop key="ValidateConnection">${jdbc.validateConnection:true}</prop>
		</props>
	</property>
</bean>

Utilisation d’un lookup

Les lookups enregistrés au sein de l’application peuvent être consommés de différentes manières en fonction des besoins.

Utilisation adhoc

L’exemple ci-dessous décrit l’exécution de manière adhoc d’un LookupPlugin. Cette exécution peut tout aussi bien être utilisée au sein d’un abonnement aux modifications d’un tag afin de remplir un autre tag.

Exemple : exécution d’un lookup BusinessReferenceLookup

JSAPI.get().getLookupAPI().lookup("BusinessReferenceLookup" ,"BusinessReference", "ref123", function(results) {
	// Utilisation des résultats du lookup
});

L’objet results est un tableau d’objets LookupResult qui sont utilisables tel que :

Fonctions	Description
getKey()	Permet de récupérer la clé d’un résultat (i.e nom symbolique )
getValue()	Permet de récupérer la valeur ou le libellé d’un résultat

Dans cet exemple, on execute le LookupPlugin dont l’identifiant Spring Beans est BusinessReferenceLookup avec en paramètre le nom du tag concerné et sa valeur.

Exemple : Suggestion de valeur pour un tag

formAPI.registerForFieldChange("Montant", function(fieldName, fieldValue) {			
	JSAPI.get().getLookupAPI().lookup("DBLookup","Montant", fieldValue, function(results) {
		formAPI.suggest("Montant", results);
	});
});

Dans cet exemple, le lookup DBLookup est utilisé pour suggérer des valeurs au tag Montant

Exemple : Définition des valeurs autorisées dans une liste

formAPI.registerForFieldChange("Montant", function(fieldName, fieldValue) {			
	JSAPI.get().getLookupAPI().lookup("DBLookup","Montant", fieldValue, function(results) {
		var restrictedAllowedValues = new Array();
		for ( var i in results) {
			result = results[i];
			var allowedValue = buildAllowedValue(result.getName(), result.getValue());
			restrictedAllowedValues[i] = allowedValue;
		}
		formAPI.setAllowedValues("EDS", restrictedAllowedValues);
	});
});

function buildAllowedValue(symbolicName, label) {
	var language = new Language("EN");

	var allowedValue = new AllowedValueDefinition();
	allowedValue.setSymbolicName(symbolicName);

	var displayNames = new I18NLabel()
	displayNames.setLabel(language, label);
	allowedValue.setDisplayNames(displayNames);
	return allowedValue;
}

Binding

Cette API JavaScript fournit également la possibilité de remplir automatiquement un champ lorsqu’il est modifié à partir du retour d’un LookupPlugin. Pour cela, il est possible d’utiliser la fonction bindFieldOnLookup(String tagName, String lookupId) où :

tagName est l’identifiant du tag concerné
lookupId est l’identifiant du LookupPlugin à utiliser.

Exemple : Binding d’un tag sur le lookup userLookup

var formAPI = JSAPI.get().getLastComponentFormAPI();
formAPI.bindFieldOnLookup("DestinatairePourInfo", "userLookup");

Lookups