https://code-industry.net/masterpdfeditor-help/digital_signatures/

La mise en place du formulaire basé sur un PDF se fait en 3 étapes :

• création du circuit des signatures

...

• (voir Gestion des circuits)
• création du PDF

...

• avec formulaire
• import du PDF avec formulaire dans esup-signature

Création d'un PDF Form

Pour éditer créer un formulaire et générer le fichier PDF et créer un formulaire, il faut se doter d'un outils dédié. Lest possible d'utiliser Libre Office. Il gère correctement la création de champs de formulaires (texte, cases à cocher,...) ainsi que la conversion au format PDF. La seule restriction concerne les champs signature. Pour palier au problème, l'université de Rouen utilise Adobe Acrobat PRO. Sous linux il existe Master PDF Editor (payant), disponible pour Windows, Linux et Mac.

Ajout d'un champ signature avec Master PDF Editor : https://code-industry.net/masterpdfeditor-help/digital_signatures/

L'opération consiste donc à placer les champs de formulaire puis à les configurer de la bonne façon.

Les champs doivent être configurés comme suit:

• Le nom . Esup(esup-signature utilisera ce nom comme identifiant du champ.)
• Cocher ou non "Obligatoire"Cocher ou non "Lecture seule"
• Esup-signature gère les champs texte, texte multi-lignes, cases à cocher, radio boutons et liste déroulantes
• Dans la partie "Format" des champs texte, sont gérés par esup-signature reconnait les type formats : Nombre , et Date et /Heure
  
  
• Toutes les autres options n'auront aucun effet sur le comportement d' Esupesup-signature
  

Une nomenclature de nommage des champs peut être utilisée pour signifier à Esup-signature d'opéré un traitement spécifique à un champ. On peut, via un nommage correcte, préciser si le champ doit être pré-rempli par Esup-signature et à quelles étapes le champ est modifiable.

La syntaxe à utiliser au niveau des scripts de calcul des champs est la suivante :

...

prefill.ldap(person, sn);

...

search.ldap(person, displayName);

...

Import du formulaire

Lorsque le formulaire PDF est terminé, il faut l'importer dans esup-signature. Pour cela il faut aller sur "Admin" puis "Formulaire" puis cliquer sur le bouton bleu "+" et enfin sur l’icône PDF.

Image Added

Vous devez saisir les informations suivantes :

1. un nom (technique)
2. un titre (affiché sur le bouton de création d'un nouveau document)
3. sélectionner votre modèle PDF Form
4. choisir la visibilité pour tous ou saisir les rôles pour définir qui peut accéder à ce formulaire
5. choisir le type de pré-remplissage
6. choisir un circuit qui aura été créé au préalable

Lorsque vous validez le formulaire, esup-signature analyse le PDF Form et constitue la structure du formulaire. Vous aurez ensuite accès à la configuration des champs.

Voici un exemple de l'édition des champs d'un formulaire dans l'interface administrateur d'esup-signature ("Admin" → "Formulaire" → "Modifier les champs" :

Image RemovedImage Added

On voit ici les propriétés modifiables des champs, elle sont les suivantes :

...

Exemple de rendu d'un formulaire :

Image Added

Pré-remplissage et auto-complétion

Comme vu précédemment, esup-signature permet le pré-remplissage des champs. Les services disponibles sont définis à l'aide de classes de type "ExtValue" (valeur externes)

Esup-signature est fourni avec les classes LdapExtValue, RestExtValue et DefaulExtValue.

LdapExtValue

La classe LdapExtValue permet d'accéder aux informations, présentes dans LDAP en fonction de l'utilisateur courant. Pour l'utiliser il faut selectionner ldap au niveau de "Nom du service" puis person ou organizationalUnit au niveau de "Type de données". Enfin il reste à saisir manuellement le nom du champ ldap dans "Attribut retourné". 

Ex:

Image Added

RestExtValue

La classe RestExtValue permet d'obtenir les données de l'utilisateur courant depuis l'appel d'un web service. Dans ce cas vous devez mettre en place un web service type REST accéssible par l'apllicationn esup-signature via une requête de type POST.

Le web service obtiendra l'attribut 'eppn" de l'utilisatuteur courant ainsi que l'attribut "signRequestId" qui correspond à l'ID de la demande en cours.

En retour, le web service doit renvoyer un objet json de type Map<String, Object>, autrement dit une map clés/valeurs contenant les informations mise à disposition concernant l'utilisateur (l'eppn)

Voici en exemple de web service en python utilisant Flask (apt install sudo apt install python3-flask)

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/', methods=['POST'])
def test():
    data = request.form.to_dict()
    eppn = data.get('eppn', '')
    sign_request_id = data.get('signRequestId', '')
    
    response_data = {
        'eppn': eppn,
        'signRequestId': sign_request_id,
        'test': 'SUCCESS'
    }
    return jsonify(response_data)

if __name__ == '__main__':
    app.run(port=8081)

Coté esup-signature il faut configurer rest-ext-value-url: http://localhost:8081 (dans notre cas) puis au niveau du formulaire utiliser rest au niveau de "Nom du service" puis data au niveau de "Type de données" et enfin à saisir manuellement le nom de la clé voulue dans "Attribut retourné". 

Image Added

DefaultExtValue

La

Sur cette copie d'écran on voit que le champ "prenom" est configuré comme suit : Obligatoire, pré-rempli du "givenName" de l"utilisateur courant, avec une auto-completion qui retour le givenName (exemple pas vraiment utile en temps normal mais qui illustre la possibilité de cumuler pré-remplissage et auto-completion) et enfin, modifiable à l'étape 0.

Esup-signature est fourni avec les classes DefaulExtValue et LdapExtValue. La classe DefaultExtValue est utilisable en mettant "default" dans le nom du service et "system" au niveau du type. Elle propose les données attributs (calculéescalculés) suivante :suivant :

...

...

...

...

...

...

...

Vous pouvez créer vos propres Comme c'est le cas pour les classes workflow, vous pouvez créer vos propre classes de données externes en implémentant le type "ExtValue" en reprenant DefaultExtValue.java par exemple.

Classe de pré-remplissage

Pour pré-remplir ou auto-compléter un formulaire, Esupesup-signature se base une une classe de "pré-remplissage" du type "PreFill". D'origine Esupesup-signature est fourni avec la classe DefaultPreFill qui prend en charge les données externes de type Default DefaultExtValue et LdapLdapExtValue. Ceci répond à une grande partie des besoins.

Cependant, tout comme cela peut être le cas pour les workflows, il se peut qu'il soit nécessaire de calculer certaines données à pré-remplir spécifiquement pour un formulaire (donnée calculée en fonction de l'utilisateur courant par exemple). Dans ce cas il y a là encore la possibilité d'implémenter votre propre classe de type PreFill (voir DefaultPreFill.java pour l'exemple)

Import du formulaire

Lorsque le formulaire PDF est terminé, il faut l'importer dans Esup-signature. Pour cela il faut aller sur "Admin" puis "Formulaire" puis cliquer sur le bouton bleu "+" et enfin sur l'icone PDF.

Image Removed

Vous devez saisir un nom (technique) et un titre (beau titre), sélectionner votre modèle PDF Form, saisir un rôle pour definir qui peut accéder à ce formulaire, choisir le type de pré-remplissage, un circuit qui aura été créer au préalable et éventuellement un dossier de destination.

Lorsque vous validez le formulaire, Esup-signature analyse le PDF Form et constitue la structure du formulaire. Sur cet exemple, on voit qu'il a bien pris en compte la nomenclature des champs. Il est possible de modifier les informations saisies lors de la création en cliquant sur le bouton jaune "crayon"

Image Removed

Votre formulaire sera disponible sur la page d'accueil des personnes autorisées à y accéder. Voici un exemple du rendu dans Esup-signature :

.

Voici un cas pratique se basant sur une base de donnée mariaDb :

1. Il faut configurer une connexion au niveau du fichier de configuration. Ici pour une base de données nommée "tot" on ajouter un "totoDataSource". Ne pas utiliser le nom "userListDataSource" pour la source de données car il est réserver pour un autre service.
   
   

   Bloc de code
   language yml theme RDark
   extdb: datasources: totoDataSource: driver-class-name: org.mariadb.jdbc.Driver password: ******** url: jdbc:mariadb://serveur.univ-ville.fr:3306/toto username: consult name: toto

   
   

2. ajouter une classe TotoExtValue dans src/main/java/org/esupportail/esupsignature/service/interfaces/extvalue/impl/ . Voici un exemple :
   
   

   Bloc de code
   language java theme RDark
   package org.esupportail.esupsignature.service.interfaces.extvalue.impl; import org.esupportail.esupsignature.entity.SignRequest; import org.esupportail.esupsignature.entity.User; import org.esupportail.esupsignature.service.extdb.ExtDbService; import org.esupportail.esupsignature.service.interfaces.extvalue.ExtValue; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.jdbc.core.JdbcTemplate; import org.springframework.stereotype.Component; import javax.annotation.PostConstruct; import javax.annotation.Resource; import java.sql.ResultSet; import java.util.HashMap; import java.util.List; import java.util.Map; @Component @ConditionalOnProperty(name = "extdb.datasources.totoDataSource.name") public class TotoExtValue implements ExtValue { private JdbcTemplate jdbcTemplate; @Resource private ExtDbService extDbService; @PostConstruct public void initJdbcTemplate() { this.jdbcTemplate = extDbService.getJdbcTemplateByName("totoDataSource"); } @Override public String getValueByName(String name, User user, SignRequest signRequest) { return initValues(user, signRequest).get(name).toString(); } @Override public List<Map<String, Object>> search(String searchType, String searchString, String searchReturn) { return null; } @Override public String getName() { return "toto"; } @Override public Map<String, Object> initValues(User user, SignRequest signRequest) { Map<String, Object> values = new HashMap<>(); jdbcTemplate.query("select nom_user, prenom_user from user where eppn='" + user.getEppn() + "'", (ResultSet rs) -> { values.put("nom", rs.getString("nom_user")); values.put("prenom", rs.getString("prenom_user")); }); return values; } }

   Dans ce cas précis, on suppose que que l'on souhaite récupérer les nom / prénom du l'utilisateur courant dans notre base mariaDB. On affecte les valeurs récupérées dans la une map d'attributs (on y nomme les attributs comme on le souhaite).
   
   

   Info
   Les attributs disponibles au niveau de la méthode initValues sont : User user : l'utilisateur courant avec en particulier l'EPPN dans getEppn() et l'email dans .getEmail() SignRequest signRequest : le demande de siagnture courante (voir https://github.com/EsupPortail/esup-signature/blob/master/src/main/java/org/esupportail/esupsignature/entity/SignRequest.java)

   
   

3. ajouter une classe TotoPreFill dans src/main/java/org/esupportail/esupsignature/service/interfaces/prefill/impl/ . Il est possible de repartir de la classe https://github.com/EsupPortail/esup-signature/blob/master/src/main/java/org/esupportail/esupsignature/service/interfaces/prefill/impl/TestPreFill.java en la modifiant comme suit :

   Bloc de code
   language java theme RDark
   @Override public Map<String, List<String>> getTypes() { Map<String, List<String>> types = new HashMap<>(); types.put("ldap", Arrays.asList("person")); types.put("default", Arrays.asList("system")); types.put("toto", Arrays.asList("attributs")); #Ajout d'un nom de type représentant le type de données return types; } ................ public List<Field> preFillFields(List<Field> fields, User user, SignRequest signRequest) { List<Field> filledFields = new ArrayList<>(); PDFont font = PDType1Font.HELVETICA; PDResources resources = new PDResources(); resources.put(COSName.getPDFName("Helvetica"), font); ExtValue extDefaultValue = extValueService.getExtValueServiceByName("default"); Map<String, Object> defaultValues = extDefaultValue.initValues(user, signRequest); ExtValue extTotoValue = extValueService.getExtValueServiceByName("toto"); #déclaration du nouveau extValue Map<String, Object> totoValues = extTotoValue.initValues(user, signRequest); #initialisation des valeurs ExtValue extLdapValue = extValueService.getExtValueServiceByName("ldap"); Map<String, Object> ldapValues = extLdapValue.initValues(user, signRequest); for(Field field : fields) { if(field.getExtValueServiceName() != null && !field.getExtValueServiceName().isEmpty()) { if(field.getExtValueServiceName().equals("ldap")) { String extValueName = field.getExtValueReturn(); if(ldapValues.containsKey(extValueName)) { if(extValueName.equals("schacDateOfBirth")) { field.setDefaultValue(extLdapValue.getValueByName("schacDateOfBirth", user, signRequest)); } else { field.setDefaultValue((String) ldapValues.get(extValueName)); } } } else if(field.getExtValueServiceName().equals("default")) { String extValueName = field.getExtValueReturn(); if(defaultValues.containsKey(extValueName)) { field.setDefaultValue((String) defaultValues.get(extValueName)); } if(field.getExtValueReturn().equals("covid(duree)")) { field.setDefaultValue("1"); } } else if(field.getExtValueServiceName().equals("toto")) { #gestion des champs pré-remplis par toto String extValueName = field.getExtValueReturn(); if(totoValues.containsKey(extValueName)) { field.setDefaultValue((String) totoValues.get(extValueName)); } } } filledFields.add(field); } return filledFields; }

   On y ajoute le nouveau service ExtValue "toto" en respectant la syntaxe. A ce niveau il est en possible de faire des calculs ou de mettre des données en dur avant l'affectation de la valeur aux champs du formulaire. A noter que l'on pourrait imaginer qu'un ExtValue puisse retourner différents types de données comme c'est le cas avec LdapExtValue (person, organizationalUnit). Dans ce cas on dispatche arbitrairement les données au moment du pré-remplissage.
   
   

4. Après recompilation / redémarrage et redéploiement, le service de pré-remplissage "toto" doit être disponible. On choisi donc le service puis le type de données (dans notre cas, "toto" puis "attributs") et on saisie manuellement le nom de l'attribut "nom" ou prenom..

Gestionnaire du formulaire

Il est possible de définir un ou plusieurs gestionnaires au niveau des paramètres du formulaire.

Image Added

Les personnes désignées auront accès en lecture à tous les documents correspondant a ce formulaire. De plus il leur sera possible de télécharger toutes les données saisies au format CSV.

L'accès à ces données se fait par le menu "Outils" → "Espace gestionnaire"

Actions Javascript 

Les actions qui peuvent être incorporées dans le PDF Form ne sont pas prises en compte lors de l'import et du rendu du formulaire. Cependant, pour rendre le formulaire plus dynamique, il est possible de coder des comportements à l'aide du champ "Action". Dans la mesure du possible il est préférable de ne pas avoir à utiliser cette fonction. En général cela peut dépanner pour verrouiller/déverrouiller des champs en fonction d'autres champs. 

Le fonctionnement est simple, vous devrez identifier les ID des éléments prenants part au dynamisme, à l'aide de l’inspecteur de code de votre navigateur. Ensuite pourrez écrire du code, en Javascript et/ou en jQuery, en vous référant aux identifiants des éléments du formulaire. Aucune fonction spécifique à esup-signature n'est présente, il s'agit de javascript totalement standard.

...