Configurer l'interaction avec un service distant via ORI-OAI-ext

Un workflow peut nécessiter l'interaction avec un service distant (i.e extérieur à l'environnement constitué par les modules ORI-OAI). C'est le cas par exemple des workflows default_ao_easy et default_ao_complex dédiés au référencement des publications scientifiques et qui interagissent avec la plateforme HAL.

Pour illustrer la description de la marche à suivre pour configurer une telle interaction, nous prendrons ici un exemple présent dans les deux workflows précités : l'envoi, conjoitement à sa publication locale, d'une fiche sur la plateforme HAL.

dans la description xml (fichier workflow_ao_easy.xml), on trouve :

Action de publication

<action id="1" name="aoe-publish">
    <restrict-to>
	<conditions type="AND">
	    <condition type="spring">
		<arg name="bean.name">hasRole</arg>
		<arg name="mask">AOE_OWNER</arg>
	    </condition>
	</conditions>
    </restrict-to>
    <results>
	<result old-status="Finished" status="Underway" split="1">
	    <conditions type="AND">
		<condition type="spring">
		    <arg name="bean.name">verifyXPathes</arg>
		    <arg name="xpath1">//dcterms:accessRights[@xsi:type = 'dcfr:envoi_HAL' and not(contains(text(), 'no_hal')) and not(contains(text(), 'unavailable_file')) and normalize-space(.)]</arg>
		    <arg name="annotation">aoe-send-hal.warn</arg>
		</condition>
	    </conditions>
	</result>
	<unconditional-result old-status="Finished"
			      status="Underway" step="3" />
    </results>
    <post-functions>
	<function type="spring">
	    <arg name="bean.name">deletePermission</arg>
	    <arg name="mask">USE_AOE_MODERATOR_FORM</arg>
	    <arg name="recipient">AOE_OWNER</arg>
	</function>
	<function type="spring">
	    <arg name="bean.name">saveOrUpdateIndex</arg>
		    <arg name="idOriIndexing">indexingServicePublic</arg>
	</function>
    </post-functions>
</action>

où l'on voit que selon la valeur d'un champ de la fiche (<dc:terms:accessRights xsi:type="dcfr:envoi_HAL">), on décide d'une publication locale avec envoi vers HAL (on se dirige alors vers le split d'idenfiant 1) ou d'une publication simple sans envoi vers HAL (on se dirige alors vers l'étape d'identifiant 3)

toujours dans workflow_ao_easy.xml, à l'issu du split d'identifiant 1 (se reporter à la documentation d'OsWorkflow pour de plus amples informations sur ce qu'est et comment fonctionne un split), l'instance de workflow se trouve simultanément dans 2 états : 'publié' (localement, étape 3) et 'en attente d'envoi vers HAL' (étape 6). Ce deuxième état fournit l'action suivante :

Action d'envoi vers HAL

<action id="13" name="aoe-hal_upload">
    <restrict-to>
	<conditions type="AND">
	    <condition type="spring">
		<arg name="bean.name">hasRole</arg>
		<arg name="mask">AOE_OWNER</arg>
	    </condition>
	    <condition type="spring">
		<arg name="bean.name">hasRemoteStatus</arg>
		<arg name="wsId">hal</arg>
		<arg name="wsStatus">EMPTY</arg>
	    </condition>
	</conditions>
    </restrict-to>
    <results>
	<unconditional-result status="Underway"
			      old-status="Finished" step="-1" />
    </results>
    <post-functions>
	<function type="spring">
	    <arg name="bean.name">deletePermission</arg>
	    <arg name="mask">AOE_DELETE USE_AOE_MODERATOR_FORM</arg>
	    <arg name="recipient">AOE_OWNER</arg>
	</function>
        <!-- FONCTION D'ENVOI VERS HAL -->
        <function type="spring">
            <arg name="bean.name">invokeWSOperation</arg>
            <arg name="wsId">hal</arg>
            <arg name="wsMethodId">upload</arg>
        </function>
	<function type="spring">
	    <arg name="bean.name">saveOrUpdateIndex</arg>
	    <arg name="idOriIndexing">indexingServicePublic</arg>
	</function>
	<function type="spring">
	    <arg name="bean.name">saveXmlHistory</arg>
	</function>
    </post-functions>
</action>

Parmi les post-functions invoquées par cette action, celle qui nous intéresse ici est invokeWSOperation. Cette fonction prend 2 arguments :

wsId : nom du service distant
wsMethodId : nom de la méthode ou fonction à invoquer auprès de ce service

pour que la post-function invokeWSOperation décrite ci-dessus fonctionne, il faut qu'elle corresponde à une configuration présente dans le fichier remote-services-configs.xml de la contribution (ou du workflow par défaut comme le cas qu'on présente ici)

Comme le suggère le titre de cette page, l'appel au service distant (HAL dans cet exemple) n'est pas direct : il se fait via le module ORI-OAI-ext, ce qui permet de masquer la diversité de ces services derrière une interface unique, et de les invoquer d'une unique manière. Si l'on parle de configuration d'appels à un service distant, cela signifie donc en fait configuration de la communication avec ORI-OAI-ext et même, pour être plus précis, avec un plugin existant dans ORI-OAI-ext.

Comme le fichier addonContext.xml, remote-services-configs.xml est un fichier de configuration Spring. Il comprend donc un certain nombre de déclarations de beans Spring. Plus précisément, ce fichier doit déclarer :
- uniquement des beans de classe org.orioai.workflow.beans.remote.RemoteServiceConfig
- un bean RemoteServiceConfig par méthode ou fonction d'un service distant à appeler
Ainsi, pour l'appel à la méthode upload du service hal, on trouvera dans remote-services-configs.xml :
Configuration nécessaire à l'appel de la méthode upload du service hal
```
<bean class="org.orioai.workflow.beans.remote.RemoteServiceConfig">
	<property name="halUserId" value="${ext.hal.account.id}" />
	<property name="halUserPassword" value="${ext.hal.account.password}" />
	<property name="wsId" value="hal" />
	<property name="wsMethodId" value="upload" />
	<property name="metadataTypeId" value="dc_plus_fr_easy" />
	<property name="statusKey" value="halArtStatus" />
	
	<property name="xPathesParams">
	    <map>
		<entry key="fullTextName" value="//dc:title" />
		<entry key="fullTextFormat" value="//dc:format" />
		<entry key="fullTextUri" value="//dc:relation[@xsi:type = 'dcfr:file']" />
		<entry key="envoiHal" value="//dcterms:accessRights[@xsi:type = 'dcfr:envoi_HAL']" />
	    </map>
	</property>
	
	<property name="xmlContentEditionParams">
	    <map>
		<entry key="//dc:identifier[@xsi:type = 'dcfr:hal_id']" value="halArtId halArtVersion halArtPassword|," />
	    </map>
	</property>
	
	<property name="downloadResourcesParams">
	    <map>
		
		<entry key="downloadDecisionKey" value="envoiHal" />
		<entry key="downloadDecisionValues" value="file_hal link_file_hal" />
		<entry key="resourcesUrisKey" value="fullTextUri" />
		<entry key="downloadWsId" value="download" />
		<entry key="downloadWsMethodId" value="downloadResource" />
	    </map>
	</property>
</bean>
```
Un bean RemoteServiceConfig comprend donc un certain nombre de propriétés qu'on explicite ci-après :
- wsId: Identifiant du service distant
- wsMethodId: Nom de la méthode du service distant
- metadataTypeId: Identifiant du metadataType donné dans addonContext.xml
- statusKey: Nom de la clé, dans l'XML retourné par ORI-OAI-ext, à laquelle est associé le statut actuel de la fiche au niveau du service distant
- commentKey: Nom de la clé, dans l'XML retourné par ORI-OAI-ext, à laquelle est associé un éventuel commentaire accompagnant la réponse du service distant à l'appel de la méthode
- xpathesParams: Associations de clés et de valeurs : les clés sont définies dans le plugin correspondant au service avec lequel on interagit ; les valeurs sont des expressions xpaths permettant d'extraire des valeurs de la fiche correspondant à l'instance de workflow courante
- xmlContentEditionParams: Associations de clés et de valeurs : les clés sont des expressions xpaths permettant d'éditer des champs de la fiche correspondant à l'instance de workflow courante ; les valeurs sont définies dans le plugin correspondant au service avec lequel on interagit
- downloadResourcesParams: Paramètres nécessaires au téléchargement d'une ressource à passer en paramètre de la méthode à appeler