Vous trouverez dans cette partie toutes les possibilités de configuration suivantes:

Si vous utilisez le module quick-install (fortement conseillé) , il ne vous sera pas nécessaire de modifer ces fichiers . Il  sera cependant utile de connaitre leur utilité si vous voulez adapter ou ajouter un workflow.

Configuration générale du module

La configuration générale du module se trouve sous conf/properties. Cette configuration s'applique à tous les workflows.

default-permissions-roles.xml

• Ce fichier  permet de configurer les permissions et rôles pouvant être utilisés par l'application (IHM)  ou par tous les workflows. Les "recipients" utilisés doivent être déclarés dans groups.xml
• par défaut, assigne le rôle d'administrateur de chaque workflow aux administrateurs de l'application

groups.xml

• Permet de configurer le nom et la définition des groupes disponibles dans l'application.
• par défaut,  définit le groupe des administrateurs de l'application ("admins")

namespaces.xml

• Définit les espaces de noms utilisés par plusieurs type de métadonnées
• Par défaut, contient le namespace "dc" utilisé par les formats Dublin Core et TEF (thèses)

metadataslist.xml

• Ce fichier permet de paramétrer les catégories de fiches qui seront affichées aux utilisateurs applicatifs déclarés dans groups.xml. Cela permet de mettre dans un même ensemble des fiches provenant de différents workflows ayant des états différents, sur lesquelles l'utilisateur a des rôles différents.
• Par défaut, ce fichier est vide

Conditions et fonctions OsWorkflow

OsWorkflow

La configuration de workflow(s) OsWorkflow est un élément capital dans le déploiement d'un Ori-Oai-Workflow. C'est le workflow qui dirige le module. Dans Ori-Oai-Workflow, OsWorkflow n'a pas été modifié ou personnalisé, les fichiers de configuration des workflows sont donc des fichiers spécifiques OsWorkflow. Ainsi vous pouvez tout à fait vous référer à la documentation d'OsWorkflow si vous en sentez le besoin de même que pour tous les fichiers de configuration de type Spring, vous pouvez vous référer à la documentation de Spring pour connaitre la syntaxe utilisée.

Dans un premier temps, il est important de comprendre ce qu'est un workflow, revoyez dans la section "Specifications" la partie sur le Workflow si ce n'est pas clair.

Dans un second temps, il vous faut connaître les possibilités en matière de condition et fonctions et arriver à penser vos cas d'utilisations du module en terme de Workflow. Pour ce faire, rien ne vaut la présentation d'un exemple exhaustif que vous devrez mettre en relation avec le document fonctionnel sur les cas d'utilisations (document rédigé par Rosa María Gómez de Regil et Romuald Lorthioir).

On notera que ce graphe représentant le workflow des documents que l'on veut indexer n'a pas grand chose de spécifique à OsWorkflow ou à ORI-OAI. Il faut également se rappeler que les rôles, les permissions (dont les permissions d'utiliser tel ou tel formulaire) sont des éléments configurables comme  on le verre ci-dessous.

Une fois ce graphe conçu, la plus grosse partie du travail est faite : il reste à concevoir le XML implémentant ce diagramme en "langage" OsWorkflow, même si il en résulte un XML qui peut être conséquent, le langage XML d'OsWorkflow n'est pas complexe.

Notes sur les conditions et fonctions disponibles actuellement et en natif dans Ori-Oai-Workflow :

spring/spring-osworkflow-helpers.xml

• C'est ici que sont déclarés les beans spring utilisés dans les workflows OsWorkflow pour implémenter des conditions et des fonctions OsWorkflow.

• L'administrateur/développeur voulant rajouter des fonctionnalités dans son Workflkow liées à son contexte de déploiement d'Ori pourra de la même façon qu'ici ajouter ses propres beans spring qu'il utilisera dans la configuration des workflows d'OsWorkflow. Le mieux sera de déclarer ses beans dans un fichier dédié à cela (vide par défaut) : conf/properties/spring/spring-custom.xml

Conditions:

Condition sur le fait que l'utilisateur courant a une permission donnée.

Condition sur le fait que l'utilisateur courant a un rôle donné.

Vérifie que la résolution de chaque XPath donné en paramètre correspond à au moins un noeud à chaque fois. Place un message dans le listing d'informations de l'instance/fiche considéré si ce n'est pas le cas.

Exécute le schématron (transformation XSL/XSLT via la XSL résultant de la "compilation XSL" d'un schématron) sur la fiche XML pour vérifier qu'il n'y a pas d'erreurs (règles schématron). Place des messages d'erreurs en conséquence dans le listing d'informations de l'instance/fiche considéré.

Fonctions:

Ajoute une permission à un rôle sur l'instance courante.

Ajoute un rôle à un utilisateur ou groupe ou utilisateur courant sur l'instance courante.
Un XPath et une valeur attendue sur le xpath donnée sont des paramètres optionnelles à cette fonction. Ils permettent de conditionner ce positionnement de rôle selon la présence ou non d'une valeur à un xpath donné. Par exemple cela permet de donner le rôle de modérateur au groupe de professeurs de mathématiques si la discipline dans la fiche LOM a été positionnée à Mathématiques.

Demande à un ORI-OAI-Indexing de supprimer l'index courant de l'instance courante (si elle a été indexée préalablement).

Supprime une permission à un rôle sur l'instance courante.

Supprime un rôle à un utilisateur ou groupe ou utilisateur courant sur l'instance courante.

Restore une version de la fiche d'un ancien état (il faut pour cela que dans cet ancien état, un SaveXmlHistory ait été fait).

Demande à un ORI-OAI-Indexing d'indexer ou de réindexer la fiche de l'instance courante.

Depuis la 1.1.* cette fonction n'appelle pas/plus la fonction SaveXmlHistory : les 2 fonctions sont dissociées et indépendantes.
Cette fonction DOIT obligatoirement être configurée comme étant une post-function dans OsWorkflow.

Sauve le XML actuel comme un historique (archive) de l'état initial à la transition.

Cette fonction DOIT obligatoirement être configurée comme étant une post-function dans OsWorkflow.

Envoie des emails aux utilisateurs d'un rôle donné sur l'instance et/ou à un mail donné "en dur" dans le workflow.
Cette fonction est donc capable de récupérer tous les emails des utilisateurs qui ont un rôle via un positionnement direct sur l'instance, via un positionnement au travers d'un groupe, etc. ... cela signifie que le nombre d'emails peut suivant les configurations être conséquent. La récolte des emails peut actuellement prendre un certain temps si la liste est longue (multiples requêtes ldap). [l'envoi des emails se fait toutefois dans des threads séparés). Nous recommandans la mesure du possible d'utiliser une liste de diffusion (mail "en dur") pour l'envoi de mails à tout un groupe donné et bien défini ...

Place des identifiants (propre à l'instance/fiche ou à l'entrée/entité considéré) au niveau d'un xpath donné.

Appelle une transformations XSL sur la fiche XML de l'instance. Notez que dans le workflow_easy.xml donné par défaut, xslTransform est utilisé en utilisant par exemple properties/xsl/osfunctions/lomSetLifecycleAuthor.xsl : cette transformation fait appel directement à de la logique métier via une expression du type select="document('#{domainService.getCurrentUserName()}')"

Notez que l'ordre des fonctions dans le fichier de config n'est pas annodin.
Un certain nombre des fonctions présentées ci-dessus vont fonctionner dans un contexte transactionnel .... mais pas toutes ....
Les fonctions qui tournent dans un contexte transactionnel annuleront leurs effets automatiquement si une des fonctions provoquait une erreur innatendue.
Dans ce contexte, et par rapport au listing ci-dessus, il est recommandé de lancer

• en tout dernier l'envoi d'emails (notez que contrairement aux autres fonctions, si l'envoi d'email échoue, rien n'est annulé pour autant),
• en avant dernier l'appel à des WebServices et donc à ori-oai-indexing par exemple,

Notez enfin que vous pouvez vous appuyer au mieux sur les workflows livrés (des plus simples default_dc_very_easy aux plus complets default_lom_complex)  qui vous fournissent ainsi des exemples significatifs.

Configuration des workflows

Cette configuration est propre à chaque workflow; elle se trouve sous  conf/properties/workflows/[nom_workflow]

Catégories et types de métadonnées

addonContext.xml

• Il permet de paramétrer les types de fiches que peut ajouter un utilisateur. Notez toute fois qu'un utilisateur pourra effectivement ajouter une fiche d'un type donné si les conditions d'ajout déclarées dans le workflow correspondant sont vérifiées (conditions sur initial-action). Un type de fiche Ori-Oai-Workflow est ainsi déterminé par un workflow OsWorkflow (identifié par workflowName), un nom de schéma, un xsl (permettant à partir d'un xml de produire un html), un fichier xml de défaut qui sera donné comme fiche vide à la création d'une nouvelle fiche (sauf dans le cas où l'utilisateur utilise des patrons de fiches).

• C'est ici également que l'on configure les XForms à mettre en relation avec les fiches. On a une liste de XForms par type de contenu. Pour chaque XForms est donné un identifiant (réutilisé dans le positionnement des permissions) et une url correspondant à l'adresse du Serveur Orbeon présentant le XForms voulu (et c'est ici par exemple que vous pourrez ajouer un pointeur sur vos formulaires personnalisés ou vous permettant de supporter d'autres formats de MétaDonnées).

• Ce fichier permet aussi de paramétrer les catégories de fiches qui seront affichées à l'utilisateur. Cela permet de mettre dans un même ensemble des fiches ayant des états différents, sur lesquelles l'utilisateurs a des rôles différents. Ce fichier est donc à modifier en fonction du workflow (états, permissions et rôles)  et en fonction de ses besoins propres.

Acegi Security : roles et permissions

Pour infos, les configurations possibles ici proviennent de l'implémentation spécifique de la politique de sécurité de Ori-Oai-Workflow.

default-permissions-roles.xml

• Ce fichier  permet de configurer les permissions et rôles par défaut dans le workflow. Les masks utilisés doivent être déclarés dans groups.xml

groups.xml

• Permet de configurer le nom ("key") et la définition ("value") des groupes disponibles dans le workflow.
• Les noms des groupes sont utilisés dans les autres fichiers de configuration du workflow
• Un groupe peut-être défini de trois façons, selon la syntaxe utilisée:

"ldap:<groupeLdap>" pour des groupes déclarés dans l'annuaire ldap
"virtual:<filtreLdap>" pour définir des groupes "virtuels" (ou "dynamiques")
shib:shibAttrsMap.get("Shib-InetOrgPerson-mail").equals("administrateur@mon-etabl.fr")&nbsp;

Le workflow

workflows.xml

• C'est le point d'entrée du workflow

workflow_[type].xml

• C'est le workflow en lui_même, c'est à dire la liste des états ("step"),  des actions utilisateur ("action") pouvant être faites sous certaines conditions ("condition" ) : les fonctions OsWorkflow ("function") exécutées alors et l'état résultant  ("result") .

Authentification / Autorisation avec Shibboleth

Depuis la version 1.4.0 ori-oai-workflow peut utiliser Shibboleth à la fois pour l'authentification et l'autorisation. LDAP et CAS ne sont alors plus nécessaires et il est possible de partager une même instance d'ori-oai-workflow entre plusieurs établissements.

Pour que les mécanismes shibboleth soient pris en compte au niveau de ori-oai-workflow, ce dernier attend de pouvoir interpréter directement les attributs Shibboleth positionnés dans les paramètres HTTP de la requête cliente. On peut pour ce faire utiliser directement le mod_shib d'apache, dans lequel on requerra une authentification Shibboleth sur l'ensemble de l'applicatif.

Voici un exemple d'une telle configuration (le mod_shib et proxy_ajp (ProxyPass) sont ici utilisés et donc chargés par ailleurs :

ProxyPass /ori-oai-workflow-spring ajp://localhost:8009/ori-oai-workflow-spring

<Location /ori-oai-workflow-spring>
  AuthType shibboleth
  ShibRequireSession On
  ShibUseHeaders On
  require valid-user
</Location>

Reste ensuite à configurer l'interprétation des attributs Shibboleth au niveau ori-oai-workflow : on va pouvoir définir d'une part l'attribut Shibboleth qui va correspondre à l'identifiant d'un individu dans ori-oai-workflow (dans conf/properties/spring/acegi/acegi-authentication-shib.xml ) , puis d'autres part les règles qui vont permettre de définir à quel(s) groupe(s) appartient l'individu connecté; ces règles, à paramétrer par l'exploitant, devront s'appuyer sur les attributs shibboleth disponibles (dans groups.xml, cf plus haut).

conf/properties/spring/acegi/acegi-authentication-shib.xml

<beans>

	<bean name="shibAuthenticator" class="org.orioai.workflow.services.application.shib.ShibAuthenticator">
		<property name="remoteUserShibAttr" value="Shib-InetOrgPerson-mail"/>
		<property name="oriGroupConfigs" ref="oriGroupConfigs"/>
	</bean>

</beans>

groups.xml

Les règles de constitution ("values") doivent correspondent à des expressions Java renvoyant un boolean (true, false). Si l'expression interprétée renvoie true, alors on affecte à l'individu connecté le groupe donné en clé. groupsMap est le nom de la variable définissant une table de hashage regroupant l'ensemble des attributs Shbboleth disponibles : nom/valeur.

Voici un exemple d'école avec le workflow DC "easy" :

<bean name="oriGroupConfigGeneral_DCE" class="org.orioai.workflow.services.acls.OriGroupConfig">

	<property name="groupsMap">
		<description>
			groupsMap defines a Map where
				* keys are groups names
				* values are ldap, virtual or shibboleth groups used
		</description>
		<map>
		  <entry key="DCE_all">
			<value>shib:shibAttrsMap.get("Shib-EP-PrimaryAffiliation").equals("professor")</value>
		  </entry>
		  <entry key="DCE_moderators">
			<value>shib:shibAttrsMap.get("Shib-EP-UnscopedAffiliation").equals("faculty;member") &amp;&amp; shibAttrsMap.get("Shib-EP-PrimaryAffiliation").equals("professor")</value>
		  </entry>
		  <entry key="DCE_admins">
			 <value>shib:shibAttrsMap.get("Shib-InetOrgPerson-mail").equals("Vincent.Bonamy@univ-rennes1.fr")</value>
		  </entry>
		</map>
	</property>

</bean>

Limitations: de par le mode de fonctionnement de shibboleth, il n'est pas possible de retrouver dynamiquement tous les individus d'un groupe donné. On ne pourra donc pas utiliser dans un workflow l'envoi de mails à l'ensemble des individus d'un groupe. On contournera ce problème en définissant directement les individus un à un comme destinataires des mails, ou mieux encore en définissant en amont une mailing-list permettant cet envoi de mails à un ensemble prédéfini d'individus.