Introduction

Ce module permet d'interagir avec le service TIPI dans un workflow Lutece.

Pour cela, il contient :

• une classe abstraite permettant de faire le lien entre les objets métier de votre application et le service TIPI. Voir la section Création d'une tâche de workflow fournissant les données TIPI à partir d'un objet métier pour plus de détails.
• une tâche de workflow permettant de configurer les états du worklow lorsque le paiement TIPI est effectué. Voir la section Tâche de workflow de configuration des états après paiement pour plus de détails.
• un signet permettant d'ajouter le lien utilisable par l'usager dans une notification. Voir la section Tâche de workflow de notification pour plus de détails.
• un démon permettant de récupérer les informations des transactions en attente. Voir la section Démon de mise à jour des paiements pour plus de détails.

Voici un cinématique type applicable avec ce module :

• Un usager fait une demande via un téléservice (votre plugin métier)
• Un agent traite la demande en back-office. Il appuie sur le bouton d'action de workflow pour déclencher la procédure de paiement :
  • les informations nécessaires au paiement TIPI sont retrouvées à partir de votre objet métier (votre tâche de workflow faisant le lien entre votre plugin métier et TIPI)
  • Une notification (email, crm, etc.) est envoyée à l'usager (tâche Notifier un usager (guichet, mail et/ou SMS)). Cette notification contient un lien.
• L'usager clique sur le lien présent dans la notification :
  • ce module appelle le service TIPI pour obtenir un IdOp.
  • l'usager est renvoyé sur la page TIPI.
• L'usager renseigne sa carte bleue sur le service TIPI et valide.
• Le servce TIPI renvoie une notification vers ce module :
  • en fonction de l'état du paiement (accepté, refusé ou abandonné), l'état de workflow de votre ressource métier est mis à jour. Cet état correspond à l'état configuré dans la tâche de workflow Tache de configuration de TIPI.
  • si une action automatique est présente pour cet état, elle est exécutée. Voir la section Exécuter une action après le paiement pour plus de détails.

Création d'une tâche de workflow fournissant les données TIPI à partir d'un objet métier

Ce module ne peut pas deviner certaines données essentielles au paiement TIPI :

• la référence de la dette
• le montant de la dette
• l'adresse email de l'utilisateur

Ce module fournit une tâche de workflow abstraite que vous devez étendre pour fournir les données : fr.paris.lutece.plugins.workflow.modules.tipi.service.task.AbstractTipiProviderTask. Vous devez alors implémenter les méthodes suivantes :

• String getTitle( Locale ) : fournit le titre de votre tâche en fonction de la Locale passée en paramètre. Cette méthode n'est pas spécifique à la classe AbstractTipiProviderTask mais provient de l'interface fr.paris.lutece.plugins.workflowcore.service.task.ITask du workflow.
• String provideRefDet( ResourceHistory ) : fournit la référence de la dette à partir de l'objet ResourceHistory passé en paramètre.
• int provideAmount( ResourceHistory ) : fournit le montant de la dette à partir de l'objet ResourceHistory passé en paramètre. Ce montant est en centimes.
• String provideEmail( ResourceHistory ) : fournit l'adresse email de l'usager à partir de l'objet ResourceHistory passé en paramètre.

Voici un exemple d'implémentation :

public class MyTipiProviderTask extends AbstractTipiProviderTask
{
    @Inject
    public MyTipiProviderTask( IResourceHistoryService resourceHistoryService, ITipiService tipiService, ITipiRefDetHistoryService tipiRefDetHistoryService )
    {
        super( resourceHistoryService, tipiService, tipiRefDetHistoryService );

    }

    /**
     * {@inheritDoc}
     */
    @Override
    public String getTitle( Locale local )
    {
        return I18nService.getLocalizedString( MESSAGE_TASK_TITLE, local );
    }

    /**
     * {@inheritDoc}
     */
    @Override
    protected String provideRefDet( ResourceHistory resourceHistory )
    {
        return DatastoreService.getDataValue( DSKEY_REFDET, StringUtils.EMPTY );
    }

    /**
     * {@inheritDoc}
     */
    @Override
    protected int provideAmount( ResourceHistory resourceHistory )
    {
        return NumberUtils.toInt( DatastoreService.getDataValue( DSKEY_AMOUNT, StringUtils.EMPTY ), 0 );
    }

    /**
     * {@inheritDoc}
     */
    @Override
    protected String provideEmail( ResourceHistory resourceHistory )
    {
        return DatastoreService.getDataValue( DSKEY_EMAIL, StringUtils.EMPTY );
    }

}
                

Vous pouvez bien sûr redéfinir les méthodes classiques des tâches de workflow, pour ajouter une configuration à la tâche par exemple.

Vous devez ensuite déclarer votre tâche dans le contexte Spring, comme toute autre tâche de workflow :

<bean id="workflow-tipimymodule.myTipiProviderTask"
    class="fr.paris.lutece.plugins.workflow.modules.tipimymodule.service.task.myTipiProviderTask"
    scope="prototype" />

<bean id="workflow-tipimymodule.myTipiProviderTypeTask"
    class="fr.paris.lutece.plugins.workflowcore.business.task.TaskType"
    p:key="myTipiProviderTypeTask"
    p:titleI18nKey="module.workflow.tipimymodule.task_my_provider_title"
    p:beanName="workflow-tipimymodule.myTipiProviderTask"
    p:taskForAutomaticAction="true" />
                

Configuration

Le fichier de configuration du module se trouve dans : WEB-INF/conf/plugins/workflow-tipi.properties.

Surcharger ce fichier pour y indiquer votre configuration (numéro client, objet, etc.).

Utilisation

Tâches de workflow

Pour pouvoir interagir avec le service TIPI dans le workflow Lutece, il faut utiliser 3 tâches de workflow dans l'action permettant de demander à l'usager de payer sa dette sur le service TIPI.

Note : Les 3 tâches peuvent être utilisées dans une action automatique. Cela permet de déclencher la procédure de paiement de manière automatique.

Note : Si votre workflow contient plusieurs actions permettant de demander à l'usager de payer sa dette (action de relance par exemple), il faut que les 3 tâches soient dans toutes les actions. Les états utilisés après la notification du service TIPI sont ceux de la dernière action déclenchée.

Tâche de workflow fournissant les données TIPI à partir d'un objet métier

La première tâche nécessaire est votre tâche fournissant les données TIPI à partir de votre objet métier. Voir la section Création d'une tâche de workflow fournissant les données TIPI à partir d'un objet métier pour implémenter cette tâche.

Tâche de workflow de configuration des états après paiement

La deuxième tâche nécessaire est la tâche nommée Tache de configuration de TIPI. Elle doit être configurée pour déterminer sur quel état de workflow sera positionné votre ressource métier lorsque :

• le paiement a été réalisé avec succès par le service TIPI
• le paiement a été refusé par le service TIPI.
• le paiement a été abandonnée par l'usager.

Tâche de workflow de notification

La troisième tâche nécessaire est la tâche nommée Notifier un usager (guichet, mail et/ou SMS). Ce module expose un signet ${tipi_url!} permettant d'insérer l'URL de traitement de paiements. Vous pouvez ajouter ce signet dans l'attribut href de la balise a pour ajouter un lien cliquable dans la notification :

<a href="${tipi_url!}">Lien de paiement</a>

Pour que ce signet soit disponible, il faut cocher les signets supplémentaires TIPI dans la configuration avancée.

Voir le module-workflow-notifygru pour plus de détails.

Démon de mise à jour des paiements

Ce démon récupère tous les paiements qui ont été initialisés par l'usager (clic sur le lien présent dans la notification) mais dont le résultat n'a pas été fourni par le service TIPI. Ce cas peut arriver s'il y a eu un problème réseau par exemple. Pour tous ces paiements, le démon interroge le service TIPI afin de les mettre à jour dans Lutece.

Par défaut, ce démon n'est pas activé. Si vous décidez de l'activer, Il est conseillé de soit le désactiver après la mise à jour des paiements, soit le laisser activé mais avec un intervalle de 24h minimum, afin de laisser le temps au service TIPI de notifier le module pour les transactions en cours. Mettre un intervalle trop court risquerait d'interférer avec le mécanisme nominal du service TIPI.

Exécuter une action après le paiement

Après la notification par le service TIPI du résultat de la transaction, il est possible d'exécuter automatiquement une action de workflow.

Note : L'explication ci-dessous se base sur une transaction acceptée, mais le même principe peut être appliqué sur une transaction refusée ou abandonnée.

Lorsque le service TIPI notifie ce module d'une transaction acceptée, le traitement appelle la première action automatique du workflow dont l'état initial est l'état défini dans la configuration de la tâche Tache de configuration de TIPI pour un paiement accepté.

Par conséquent, pour exécuter automatiquement une action du workflow après la notification du service TIPI :

• Créez un état dans le workflow. Cet état peut être utilisé uniquement pour ce but.
• Dans la configuration de la tâche TIPI, utilisez l'état créé dans le champ Etat si paiement accepté.
• Créez une action automatique dont l'état initial est l'état créé et l'état final est l'état de votre choix.
• Ajoutez les tâches de votre choix dans cette action.

Voici un exemple :

Etats du workflow. L'état Paiement accepté n'est utilisé que pour exécuter l'action automatique après notification par le service TIPI.

Actions du workflow.

L'action Payer contient les 3 tâches de workflow nécessaires au paiement de la dette. La tâche Tache de configuration de TIPI est configurée pour pointer sur l'état Paiement accepté lorsque le paiement est accepté.

L'action Notifier paiement accepté est une action automatique. C'est cette action qui sera exécutée automatiquement après notification d'un paiement accepté par le service TIPI. Elle contient les tâches souhaitées. Par exemple, on peut notifier l'usager que son paiement a été accepté :

Lien dans la notification

Lorsque l'usager clique sur le lien présent dans la notification, il est renvoyé vers le service TIPI uniquement si le paiement ne s'est pas déjà effectué avec succès. Dans le cas où le paiement s'est déjà effectué avec succès, un message d'information s'affiche pour avertir l'usager qu'il ne peut pas payer une deuxième fois.