Approbation à distance

Aperçu

La fonctionnalité d’Approbation à distance permet à l’utilisateur d’effectuer ses actions d’approbation par email, comme une alternative au lancement du formulaire dans le Portail utilisateur WorkflowGen.

L’Approbation à distance est une option facultative pour une action d’approbation standard dans un processus WorkflowGen. Elle est intégrée dans l’action d’approbation d’un formulaire qui lance une notification à un utilisateur de manière asynchrone depuis le moteur de notification WorkflowGen.

Les utilisateurs peuvent toujours approuver les demandes par le procédure d’approbation standard depuis le formulaire. Le système récupéra le résultat dans l’ordre d’arrivée et complétera l’action. Aucune action additionnelle n’est requise dans le processus du design de workflow.

La configuration de l’Approbation à distance est paramétrée sur l’onglet Approbation à distance dans le Panneau de configuration (voir Approbation à distance).

Configuration des actions d’Approbation à distance

L’Approbation à distance nécessite des paramètres pour définir quels informations sont à fournir à l’approbateur à distance, et de quelle façon. Ces paramètres contrôlent aussi la façon de retourner les résultats de l’approbation ainsi que d’autres informations au système WorkflowGen.

Utilisation des paramètres dans une action d’Approbation à distance

L’Approbation à distance nécessite des paramètres additionnels à ajouter à une action EFORMASPX. Ces paramètres définissent les questions à poser à l’approbateur à distance et la correspondance de sa réponse avec l’action.

Pour réaliser avec succès une action de formulaire Web avec l'Approbation à distance, l'action doit avoir un paramètre IN FORM_DATA valide. Dans le cas d'une première action (lorsque les données du formulaire ne sont pas disponibles), FORM_DATA doit avoir un fichier XML modèle au format suivant :

<?xml version="1.0" standalone="yes"?>
<NewDataSet>
    <Table1>
        <CURRENT_REQUEST></CURRENT_REQUEST>
    </Table1>
</NewDataSet>

Seules les réponses aux approbations et les informations de l’approbateur doivent être retournées via les paramètres d’Approbation à distance. Les autres paramètres qui passent les valeurs d’entrée et de sortie du formulaire Web demeurent inchangés.

Pour envoyer un email de notification à l’approbateur, une notification personnalisée doit être définie. Depuis l’onglet de notification d’une action d’approbation, ajoutez une notification additionnelle avec À faire comme événement, l’utilisateur auquel l’action est affectée comme destinataire et un gabarit d’email personnalisé avec les informations sur l’approbation. Cette notification personnalisée est la même que pour n’importe quelle autre action WorkflowGen.

Paramètres par défaut des actions d’Approbation à distance

• FORM_DATA (IN/OUT | FILE | obligatoire) : Le paramètre d’entrée/sortie qui contient le fichier de données du formulaire WorkflowGen. Ceci est un paramètre par défaut pour les actions EFORMASPX.

• FORM_ARCHIVE (OUT | FILE | par défaut) : L’Approbation à distance nécessite l’envoi de la donnée du processus FORM_ARCHIVE en tant que paramètre WorkflowGen afin de récupérer toutes les mises à jour des champs durant l’approbation. La direction du paramètre doit être OUT afin d’envoyer le contenu de l’archive mise à jour à WorkflowGen.

  Notes :

  • Aucune mise à jour ne sera apportée au formulaire Web archivé si le paramètre FORM_ARCHIVE n’est pas défini dans l’action d’Approbation à distance.

  • FORM_ARCHIVE est requis pour les actions EFORMASPX uniquement.

• KEYWORDS_BRACKETS (IN | TEXT | facultatif) : Pour répondre à une question d’Approbation à distance, il faut suivre une syntaxe pré-définie :

  Q1: [réponse]

  Les crochets ([ et ]) seront la valeur par défaut si ce paramètre n’est pas utilisé. Vous pouvez utiliser d’autres caractères à la place des crochets; par exemple, vous pouvez régler KEYWORDS_BRACKETS à ##* pour le format de réponse suivant :

  Q1: #réponse#

  Notes :

  • Seulement deux caractères (pour l’ouverture et la fermeture) sont permis.

  • Pour respecter la syntaxe, il ne faut pas mettre d’espace avant les deux points (:).

• Qx_KEYWORDS_n (IN | TEXT | par défaut) : Voir la section Personnalisation des emails pour des informations sur ce paramètre.

• Qx_RESULT_n (IN | TEXT | par défaut) : Voir la section Personnalisation des emails pour des informations sur ce paramètre.

• Qx_RETURN_FIELDNAME (IN | TEXT | par défaut) : Le résultat du paramètre Qx_RESULT_n sera envoyé au nom du champ spécifié par ce paramètre.

  Note : Aucun autre paramètre ne doit être défini dans une approbation à distance avec le suffixe _RETURN_FIELDNAME.

• USER_NAME_FORMAT (IN | TEXT | facultatif) : Le nom complet de l’approbateur qui répond sera récupéré dans la base de données WorkflowGen. Le nom complet de l’approbateur sera retourné au contrôle de champ dans le formulaire Web si USER_NAME_FIELDNAME est défini. Par défaut, le nom complet de l’utilisateur sera dans le format Firstname Lastname (Prénom Nom). Vous pouvez personnaliser ce format en utilisant les caractères de contrôle L (pour nom) et F (pour prénom). Par exemple :

  Jean Dupont → F L Dupont, Jean → L, F Jean (Dupont) → F (L)

• USER_NAME_FIELDNAME (IN | TEXT | facultatif) : Les formulaires Web standard peuvent utiliser des macros WorkflowGen pour récupérer le nom complet de l’utilisateur assigné. Dans l’Approbation à distance, l’approbateur est défini basé sur la réception de la réponse à l’approbation; un paramètre spécifique est nécessaire pour retourner le nom de l’approbateur réel.

  Ce paramètre spécifie l’identifiant de contrôle du champ qui recevra le nom de l’approbateur renvoyé. Seulement les contrôles du champ de type TextBox sont supportés.

• USER_FIRSTNAME_FIELDNAME (IN | TEXT | facultatif) : Ce paramètre est créé en définissant l’identifiant de contrôle du champ dans votre formulaire pour afficher le prénom de l’approbateur dans le profil d’utilisateur WorkflowGen dans la page d’archive du formulaire.

• USER_LASTNAME_FIELDNAME (IN | TEXT | facultatif) : Ce paramètre est créé en définissant l’identifiant de contrôle du champ dans votre formulaire pour afficher le nom de l’approbateur dans le profil d’utilisateur WorkflowGen dans la page d’archive du formulaire.

• USER_TITLE_FIELDNAME (IN | TEXT | facultatif) : Ce paramètre est créé en définissant l’identifiant de contrôle du champ dans votre formulaire pour afficher le titre de l’approbateur dans le profil d’utilisateur WorkflowGen dans la page d’archive du formulaire. Seuls les identifiants de contrôle des champs de type TextBox, RadioButtonList et DropDownList sont supportés.

• COMMENT_FIELDNAME (IN | TEXT | facultatif) : Ce paramètre est créé en définissant l’identifiant de contrôle du champ dans votre formulaire pour afficher les commentaires des approbateurs dans la page d’archive du formulaire. Seuls identifiants de contrôle des champs de type TextBox sont supportés.

  Note : Vous pouvez spécifier l’identifiant de contrôle en saisissant la chaîne de texte ou en envoyant une donnée du processus seulement si la donnée contient l’identifiant de contrôle. Si aucun identifiant de contrôle n’est trouvé ou si l’identifiant est invalide, aucun nom ne sera affiché et ce paramètre ne sera pas pris en compte.

• COMMENT_REQUIRED_RESULTS (IN | TEXT | facultatif) : Ce paramètre est créé en définissant les résultats de l’approbateur qui nécessiteront un commentaire obligatoire. Le résultat de l’approbateur est représenté par le paramètre Qx_RESULT_n. Vous pouvez saisir une chaîne de texte séparé par virgules afin de spécifier plus d’un résultat nécessitant un commentaire. Par exemple :

  Q1_RESULT_2,Q2_RESULT_2,Q3_RESULT_1

  Ici, les deuxièmes réponses aux questions 1 et 2 (Q1 et Q2) et la première réponse à la troisième question (Q3) nécessiteront des commentaires.

  Notes :

  • Les commentaires obligatoires nécessitent le paramètre COMMENT dans l’action.

  • Tous les résultats nécessaires partagent le même paramètre COMMENT.

  • L’approbateur recevra un email de ré-approbation si un commentaire obligatoire est manquant.

• QUICKAPPROVALMODE (IN | TEXT | facultatif) : Le mode rapide peut être activé ou désactivé par défaut pour toutes les actions d’Approbation à distance de façon globale dans le Panneau de configuration. Par contre, si le paramètre QUICKAPPROVALMODE est défini pour une action d’Approbation à distance particulière, ce défaut global sera passé outre.

  Note : La seule chaîne de texte permise pour ce paramètre est Y ou N.

Questions d’Approbation à distance

L’Approbation à distance supporte trois types de questions d’approbation : choix multiples, questions avec des réponses numériques et questions avec des réponses textes à structure libre.

En général, l’Approbation à distance est utilisée pour fournir des questions d’approbations avec deux réponses possibles (par exemple, Oui et Non. Pour ce faire, trois paramètres principaux sont utilisés :

• Qx_KEYWORDS_n : Ce paramètre contient une liste de mots-clés possibles (séparés par virgules) pour le choix n.

• Qx_RESULT_n : Ce paramètre contient la réponse normalisée pour la choix n.

• Qx_RETURN_FIELDNAME : Ce paramètre contient le nom de champ du formulaire Web qui contient la réponse normalisée finale pour la question x.

Comme il peut y avoir plus d’une question dans une action, la lettre x dans ces paramètres représente le numéro de la question. La lettre n à la fin représente le choix de réponse. Vous pouvez définir autant de mots-clés et de résultats que vous avez besoin.

Définition d’une question avec deux choix

Dans cet exemple, il y a deux questions O/N (oui/non) dans une action d’Approbation à distance :

Question 1

Q1_KEYWORDS_1=oui,o,ok
Q1_RESULT_1=oui

Q1_KEYWORDS_2=non,n,refusé
Q1_RESULT_2=non

Question 2

Q2_KEYWORDS_1=approuvé,approuver,ok
Q2_RESULT_1=approuvé

Q2_KEYWORDS_2=refusé,refuser,rejeté,rejeter
Q2_RESULT_2=refusé

Si l’approbateur répond o à la première question et rejeté à la deuxième, les réponses normalisées des questions 1 et 2 seront donc oui et refusé, respectivement.

Définition d’une question avec plus de deux choix

Si vous devez définir plus de deux choix, vous devez ajouter une nouvelle combinaison de mots-clés et résultats. Par exemple :

Q1_KEYWORDS_1=oui,o,ok
Q1_RESULT_1=oui

Q1_KEYWORDS_2=non,n,refusé,refuser
Q1_RESULT_2=non

Q1_KEYWORDS_3=modifier,plus d’info
Q1_RESULT_3=plusinfo

Vous pouvez définir autant de combinaisons de mots-clés et de résultats que vous avez besoin.

Définition d’autres types de questions

L’Approbation à distance permet aussi des questions de type numérique et de type texte à structure libre.

Une question de type numérique nécessite les combinaisons de mots-clés et de résultats suivantes :

Qx_KEYWORDS_1=[0-9] ([0-9] est un mot-clé réservé aux questions de type numérique; il suffit d’utiliser Qx_KEYWORDS_1)

Qx_RETURN_FIELDNAME (le nom du champ du formulaire Web qui contient la réponse récupérée)

Une question de type texte à structure libre ne nécessite pas de mot-clé, seulement Qx_RETURN_FIELDNAME (le nom du champ du formulaire Web qui contient la réponse récupérée).

Comment répondre à une demande d’Approbation à distance

Il y a deux modes de réponse d’Approbation à distance : normal et rapide.

Dans le mode normal, un email d’Approbation à distance peut demander plus d’une question, nécessitant des réponses dans un format structuré.

Dans le mode rapide, le destinataire de l’email peut répondre à la première question sans aucun formatage requis. Le destinataire peut également inclure un commentaire en l’ajoutant à la deuxième ligne sous la réponse de la première question. Ce mode accepte une seule question, donc des questions autres que Q1_RETURN spécifiées comme paramètres d’action ne seront pas prises en compte.

Exemple en mode d’approbation normal

Un email d’approbation contient le suivant :

Quel est votre choix ?  
Question 1: O ou N  
Question 2: O ou N

Pour répondre à ces questions, il faudra répondre à l’email avec la syntaxe suivante :

Q1: [O]  
Q2: [N]  
COMMENT: [Demande approuvée.]

Chaque réponse est précédée par Qx:, dont x représente le numéro de la question. De plus, les réponses sont encadrées dans des crochets afin d’indiquer le début et la fin de la réponse. De même, le commentaire a la même structure, mais est précédé par le mot réservé COMMENT:.

Exemple en mode d’approbation rapide

Seul un mot-clé pour la première question est requis, avec un commentaire facultatif. Dans l’exemple ci-dessous, la première ligne représente la réponse à la première question, et la deuxième ligne est le commentaire :

O  
Demande approuvée.

Validation des emails d’approbation

Une notification « à faire » personnalisée doit être définie afin d’être envoyée aux cessionnaires d’actions pour une action d’Approbation à distance. Ceci ressemble à la notification « à faire » par défaut d’une action EFORMASPX standard. L’email personnalisé utilise le système de notification de WorkflowGen afin de distribuer l’email d’approbation à un ou plusieurs approbateurs.

Afin d’éviter du pourriel ou la réception d’autres emails hasardeux dans la boîte de réception d’Approbation à distance, ainsi que pour s’assurer de l’identité de l’approbateur, une réponse valide à une demande d’Approbation à distance doit adhérer aux quatre conditions suivantes :

1. Le sujet de l’email ne peut être vide.

2. L’email de réponse doit avoir la même clé d’en-tête (« Thread-Index ») que celle configurée pour l’action de demande associée dans la base de données WorkflowGen.

3. L’adresse email de l’approbateur à distance doit correspondre à celle utilisée par WorkflowGen afin d’assurer que l’adresse de réponse appartienne à un utilisateur WorkflowGen valide.

4. L'approbateur à distance doit être un des utilisateurs assignés à l'action.

Les emails invalides seront automatiquement supprimés de la boîte de réception.

Dans certains cas exceptionnels, certains types ou configurations de serveurs email pourraient automatiquement supprimer la clé d’en-tête défaut (« Thread-Index ») des emails entrants. Pour éviter ce problème :

1. Cochez l’option Validation par le sujet sur l’onglet Approbation à distance dans le Panneau de configuration du Module d’administration.

2. Ajouter les identifiants de la demande et de l’action dans le sujet de l’email dans le format suivant :

   • Identifiant de demande WorkflowGen précédé de # (carré)

   • Identifiant d’action WorkflowGen précédé de - (trait d’union)

Voici un exemple d’un sujet email avec les identifiants de demande et action WorkflowGen :

Autorisation de dépenses requise #1374-4

Ici, Autorisation de dépenses est le sujet, 1374 est l’identifiant de la demande (précédé d’un carré) et 4 est l’identifiant de l’action (précédé d’un trait d’union).

Le sujet de l’email est défini dans la première ligne du gabarit d’email personnalisé, précédé de SUBJECT. Les identifiants de demande et d’action WorkflowGen peuvent être ajoutés au sujet avec les macros WorkflowGen <WF_PROCESS_INST_ID> et <WF_ACTIVITY_INST_ID>, respectivement.

L’Approbation à distance validera la réponse en vérifiant les identifiants de demande et action récupérés du sujet de l’email. Les conditions de validation 2 et 3 ci-dessus sont toujours applicables durant le processus de validation.

Personnalisation des emails

Il faut définir un email de notification personnalisé afin de distribuer les emails d’Approbation à distance aux approbateurs.

Créer le gabarit email

La création des notifications personnalisées suivent les mêmes règles que n’importe autre notification personnalisée WorkflowGen; tous les macros WorkflowGen sont supportées. Voir Notifications personnalisées pour plus de renseignements.

Pièces-jointes

Les données de processus de type fichier peuvent être attachées à un email d’Approbation à distance afin que l’approbateur puisse accéder directement à n’importe quelle donnée de type fichier. Une macro spéciale peut être utilisée pour ajouter une donnée de type fichier à l’email :

<WF_PROCESS_INST_RELDATA_FILE.XXXXX>

Ajoutez cette balise au corps du texte de l’email, puis le fichier de la donnée XXXXX sera annexé à l’email comme pièce-jointe. Le gabarit ne sera pas traduit en texte dans le corps de l’email. Si plusieurs pièces-jointes sont requises, ajoutez cette balise plusieurs fois avec le nom de donnée correspondant.

Configurer la notification de retard

Si une notification de retard doit être envoyée, ajoutez une notification additionnelle en spécifiant l’événement comme « en retard », utilisant le même gabarit d’email de notification.

Pour les notifications additionnelles, seuls les événements « à faire » et « en retard » incorporeront la clé d’en-tête (« Thread-Index ») pour la validation des emails.

Design des formulaires Web Approbation à distance

Considérations

L’Approbation à distance tente de traiter une réponse d’approbation comme si un approbateur a effectivement lancé une action d’approbation et soumis le formulaire Web. Les données du formulaire et les valeurs de paramètres d’actions sont mises à jour en conséquence. Donc, quand la prochaine action est lancée, WorkflowGen récupérera les données de formulaire de l’Approbation à distance et pourra afficher le résultat dans le formulaire Web.

Pourtant, afin de refléter le résultat de l’approbation dans les archives du formulaire, le contrôle du champ d’approbation doit être visible avant que l’action d’approbation à distance soit soumise. L’Approbation à distance met à jour l’archive du formulaire générée par l’action précédente en cherchant le contrôle du champ correspondant et ensuite en attribuant la valeur via JavaScript. Le formulaire Web ne sera pas rendu de nouveau. Par exemple, si un processus comprend deux actions, et que le champ d’approbation dans la première action est caché par défaut dans le formulaire Web, l’archive du formulaire générée par la première action ne contiendra pas le contrôle du champ d’approbation.

L’Approbation à distance ne remplira pas le résultat d’une approbation dans l’archive du formulaire bien que WorkflowGen peut toujours récupérer les données du formulaire les plus récentes ainsi que les valeurs des paramètres des actions.

Les champs d’Approbation à distance supportent seulement les contrôles CheckboxList, RadiobuttonList, Listbox et DropdownListBox. Les champs de commentaires d’Approbation à distance supportent seulement les contrôles TextBox et TextArea.

En considérant l’ajout de l’Approbation à distance dans une action, nous vous suggérons de :

• Régler le champ d’approbation toujours visible mais en lecture seule dans l’action précédente.

• Régler le champ d’approbation comme visible uniquement après que SubmitToWorkflow() ne soit appelé dans l’action précédente afin d’y ajouter le champ d’approbation sur la page de l’archive uniquement.

• Utiliser CSS pour cacher le champ d’approbation dans l’action précédente.

Enregistrement des erreurs

Fichier de log

L’Approbation à distance générera automatiquement des événements dans l’Observateur d’événements de Windows, ainsi que des fichiers de log détaillés dans le dossier WorkflowGen \App_Data. Par défaut, le fichier de log se trouve dans le dossier Web WorkflowGen DISQUE:\wwwroot\wfgen\App_Data\LogFiles\RemoteApproval.

Si vous avez configuré WorkflowGen pour utiliser une autre ApplicationDataPath (défini dans le fichier web.config), les fichiers de log se trouveront dans le chemin spécifié dans le fichier config. Par exemple, si ApplicationDataPath est réglé sur \SERVEUR_B\App_Data\, les fichiers log d’Approbation à distance seront créés dans \SERVEUR_B\App_Data\LogFiles\RemoteApproval.

Le nom du fichier de log est la date, au format suivant : AAAA-MM-DD.log.

Le fichier de log contient un résumé des activités, y compris les détails des problèmes techniques, et des informations sur les actions WorkflowGen clôturées depuis l’application d’Approbation à distance. Il y a cinq niveaux de détails :

0 – Désactivé : Aucun (aucun fichier de log ne sera créé)

1 – Messages généraux : Résumé des messages d’exécution seulement

2 – Messages d’erreur : Messages d’erreur d’exception seulement

3 – Messages généraux et messages d’erreurs : Résumé des messages d’exécution et messages d’erreur d’exception

4 – Détails complets pour déboggage (incluant l'Observateur d'événements) : Résumé des messages d’exécution et messages d’exception détaillés (y compris les logs de l’Observateur d’événements)

Le niveau 3 (messages généraux et messages d’erreurs) est recommandé car la taille des fichiers et des détails sont bien balancés.

Le niveau des détails du fichier log est réglé dans le Panneau de configuration du Module d’administration (voir Approbation à distance dans la section Panneau de configuration.

Messages d’erreur

Le tableau ci-dessous présente des messages d’erreur possibles et leurs descriptions, qui se trouvent dans le fichier de log d’Approbation à distance.

Message d’erreur	Description
Socket Error: No such host is known.	L’application n’a pas pu se connecter au serveur de réception des emails. Vérifier le réglage de IncomingServerAddress.
Server Respond: ERR access denied.	Il y a une erreur dans le nom d’utilisateur du serveur de réception des emails. Vérifier les orthographes de IncomingServerUsername et IncomingServerPassword.
Socket Error: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond [server address]:[port number].	Le serveur email ne répond pas et s’est déconnecté. Des raisons possibles :
System Error: The token supplied to the function is invalid.	Sécurité de serveur email incorrecte possible. Vérifier MailServerSecurity.
Server Respond: ERR maildrop already locked.	L’email de réponse est verrouillé par le serveur email.
The request failed with HTTP status 401: Unauthorized.	Le nom d’utilisateur ou le mot de passe utilisés pour connecter à WorkflowGen est erroné.
wfgResponse Error: Remote reply for action (Req #xxxx) cannot be accepted. Action may have already been expired/opened/completed by webform.	L’application ne peut compléter l’action, possiblement à cause d’une erreur de connexion à WorkflowGen, ou bien l’action serait peut-être expirée, clôturée ou complétée dans le portail d’utilisateur de WorkflowGen.
Cannot clean up temp file ([FILENAME]) yet. It may be still in use.	L’application a fait le ménage des fichiers temporaires dans le dossier tmp tandis qu’un fichier soit toujours en service; dans ce cas, l’application sautera la suppression de ce fichier.
The response for Request #xxxx is in an incorrect format ([YOUR ANSWER]). An email has been sent.	Le formatage d’une réponse est incorrect, aucun mot-clé n’a été détecté dans le corps de l’email, ou le mot-clé est invalide. Vérifier aussi si le mode d’application est réglé à QuickApprovalMode.
Email subject does not indicate it is a Remote Approval reply; email has been removed from mailbox.	Un email reçu par le serveur ne contient pas le préfixe obligatoire « RE: » qui indique que l’email s’agit d’une réponse à une demande d’approbation à distance. Cet email sera automatiquement supprimé du serveur.
Error parsing request information or reading email header/content before processing reply.	Un email reçu par le serveur ne contient pas toutes les informations nécessaires, par exemple le thread-index ou les IDs de demande/action dans le sujet, qui sont requis pour identifier l’action WorkflowGen associé. Vérifier si le thread-index a été supprime de la configuration du serveur email, ou bien ajouter les IDs de demande/action au sujet de l’email de notification.
The response for Request #XXXX is missing a mandatory comment for answer ([YOUR ANSWER]). An email has been sent.	La réponse fournie nécessite un commentaire obligatoire. L’approbateur doit ajouter COMMENT: [YYYYYY] (ou YYYYY si QuickApprovalMode = Y) dans la réponse email. L’email sera automatiquement supprimé du serveur.
Client found response content type of ‘text/html; charset=utf-8’, but expected ‘text/xml’	Le service Web WorkflowGen API ne retourne pas les bonnes données XML. Vérifier que le dossier \ws est activé en tant qu’application IIS.
Applicative error + detail (level 4)	Cette erreur s’agit du détail d’exception qui détermine le source de l’erreur. Vérifier les configurations suivantes qui pourraient causer l’application à lancer une erreur applicative :