Extraction de balises de texte

l'Text Tag Extraction permet aux intégrateurs d'extraire automatiquement des signatures et des champs en plaçant des balises de texte dans un document. OneSpan Sign analysera le document téléversé et remplacera chaque texte qui correspond au modèle de balise de texte par la signature ou le champ approprié.

Cette section traite des sujets suivants :

• Syntaxe des balises de texte
• Noms de rôles dans les balises de texte
• Types de balises de texte
• Paramètres des balises de texte
• Signataire avec plusieurs signatures

Meilleures pratiques pour l’utilisation des balises de texte

Voici quelques bonnes pratiques que vous devez garder à l'esprit lorsque vous utilisez des balises de texte :

• Lorsque plusieurs attributs sont spécifiés dans des balises de texte, essayez d'utiliser une virgule pour les séparer, comme ci-dessous :

  • {{esl:Signer1:textfield:size(40,15),Maxlen(3)}}

  Un exemple plus compliqué pourrait ressembler à ceci :

  • {{esl_checkbox1:Signer1:checkbox:offset(0,-15),size(275,25),Maxlen(40)}

• Essayez d'utiliser une police plus petite pour vos balises de texte. Cela vous permettra de gagner de l'espace et de ne pas affecter la mise en page de votre contenu.
• Assurez-vous que votre balise de texte se trouve sur une ligne.

Voici un exemple de code qui intègre ces suggestions :

{{esl_optionA:Signer1:Radio:Group("Frequency"),Value("X"),size(10,10),offset(40,-8)}}
{{esl_optionB:Signer1:Radio:Group("Frequency"),Value(""),size(10,10),offset(40,-8)}}
{{esl_optionC:Signer1:Radio:Group("Frequency"),Value(""),size(10,10),offset(40,-8)}}

Dans cet exemple, la taille des balises est fixée à 1, et la taille normale du texte est fixée à 12. Voici ce que vous obtenez après l'extraction vers ces champs :

Pour obtenir une copie du document Word utilisé dans cet exemple, cliquez ici.

Si vous avez des difficultés à placer vos balises de texte à l'endroit approprié, essayez d'utiliser l'attribut de décalage. Ceci est particulièrement utile lorsque vous utilisez un document Microsoft Word.

Syntaxe des balises de texte

La ligne suivante illustre la syntaxe d'une balise de texte :

• {{Xesl[_fieldName]:roleName:fieldType[:parameter1,parameter2,...]}}

Lorsque plusieurs attributs sont spécifiés dans des balises de texte, essayez d'utiliser une virgule pour les séparer, comme ci-dessous :

{{esl:Signer1:textfield:size(40,15),Maxlen(3)}}

Un exemple plus compliqué pourrait ressembler à ceci :

{{esl_checkbox1:Signer1:checkbox:offset(0,-15),size(275,25),Maxlen(40)}}

Les noms des champs sont alphanumériques. Ils ne peuvent pas contenir de caractères spéciaux autres que le trait de soulignement (_).

Notez à partir de cette ligne que :

• Le début et la fin d'une balise de texte ont des crochets doubles. Les accolades ne doivent apparaître nulle part ailleurs dans une balise de texte.
• Le troisième caractère - le X- est un caractère de remplacement pour un caractère facultatif. Ce caractère peut être soit un point d'interrogation (?) ou un astérisque (*). Un astérisque indique qu'un Input Field est obligatoire. Un point d'interrogation indique qu'un Input Field est facultatif. Le point d'interrogation est la valeur par défaut, c'est-à-dire que si aucun de ces caractères n'est présent, le Input Field est facultatif. Exemple : {{*esl:Signer1:textfield}}
• fieldName est le nom du champ qui sera créé par la balise de texte (une Signature, un Autofield ou un Input Field) - voir Types de balises de texte. S'il est spécifié, ce paramètre suivra le préfixe « esl ». Les noms des champs sont alphanumériques. Ils ne peuvent pas contenir de caractères spéciaux autres que le trait de soulignement (_). Si vous prévoyez de récupérer la valeur saisie pendant l'Signer Experience, saisissez un nom unique pour chaque champ. Exemple : {{esl_SignerAutograph:Signer1:Signature}}
• roleName est le nom du rôle associé au signataire prévu. Pour trouver le nom du rôle que vous devez utiliser, consultez Noms de rôles dans les balises de texte.
• fieldType est l'un des types de champ décrits dans la section Types de balises de texte.
• parameter1 et parameter2 sont des paramètres décrits dans la section Paramètres des balises de texte.

Veuillez prendre note des points suivants :

• Une balise de texte ne peut pas apparaître sur plusieurs lignes.

• Si une liste de paramètres est présente, elle doit être une liste séparée par des virgules.

La ligne suivante illustre la syntaxe valide la plus courte pour une balise de texte :

{{esl:roleName:fieldType}}

Noms de rôles dans les balises de texte

Si vous créez une transaction à l'aide de l'interface Web OneSpan Sign, le nom du rôle de l'expéditeur est toujours Owner.

Si vous créez un signataire destinataire ou un signataire de groupe à l'aide de OneSpan Sign, le nom du rôle du signataire est Signer#, où # commence à 1 et augmente de un pour chaque signataire. Le numéro le plus bas disponible est utilisé pour chaque nouveau signataire. Ainsi, si vous supprimez le signataire avec le nom de rôle Signer1 et ajoutez ensuite un nouveau signataire, le nom de rôle du nouveau signataire sera Signer1.

Si vous créez un signataire fictif, et que vous le nommez Client, alors Client sera le nom du rôle. Le client restera le nom du rôle lorsque cet espace réservé sera remplacé ultérieurement par un destinataire ou un groupe spécifique.

Si vous créez un signataire à l'aide du SDK et que vous lui attribuez un ID personnalisé, cet ID sera le nom du rôle du signataire. Si vous n'attribuez pas d'ID personnalisé au signataire, un ID est généré pour le signataire en utilisant les mêmes règles que lors de l'utilisation de l'interface Web OneSpan Sign.

Types de balises de texte

Il existe trois principaux types de balises de texte :

• Signatures
• ChampsAuto
• Champs de saisie

Signatures

Une balise de texte de Signature particulière peut être l'un des types de champ suivants :

• Signature - Ce bloc de signature est à cliquer pour signer. Le nom du signataire sera estampillé sur le bloc cliqué.
• Initiales - Ce bloc de signature est un Cliquez pour initialiser. Les initiales du signataire seront apposées sur le bloc cliqué.
• Capture - Le signataire clique sur ce bloc de signature et dessine sa signature à l'aide d'une souris ou d'un autre périphérique de saisie. Le signataire peut également choisir de signer sur un appareil mobile tel qu'un téléphone intelligent si l'expéditeur a activé la capture mobile sur son compte. Le dessin est ensuite estampillé sur le bloc de signature. Notez que l'utilisation d'un stylet n'est pas prise en charge dans l'interface utilisateur classique.
• Capture mobile - Pour signer électroniquement ce bloc de signature, le signataire recevra un lien par courriel qui le redirigera vers l'ouverture du document sur son téléphone portable. Il doit ensuite dessiner sa signature à l'aide de son doigt ou d'un stylet. Le dessin de la signature est ensuite estampillé sur le bloc. Notez que l'utilisation d'un stylet n'est pas prise en charge dans l'interface utilisateur classique.

ChampsAuto

Une balise de texte de Autofield particulière peut être l'un des types de champ suivants :

• Nom du signataire - Au moment de la signature, le système remplit automatiquement ce champ avec le nom complet du signataire.
• Titre du signataire - Si le titre du signataire est disponible, le système remplit automatiquement ce champ avec ce titre au moment de la signature. Sinon, le champ est laissé vide.
• Entreprise du signataire - Si le nom de l'entreprise du signataire est disponible, le système remplit automatiquement ce champ avec ce nom au moment de la signature. Sinon, le champ est laissé vide.
• Date de signature - Au moment de la signature, le système remplit automatiquement ce champ avec la date du jour.

Champs de saisie

Une balise de texte de Input Field particulière peut être l'un des types de champ suivants :

• Champ de texte - Cette zone accepte tout texte saisi par le signataire avant la signature.
• Zone de texte - Ce type est similaire au type TextField, en ce sens qu'il fournit une zone où un texte libre peut être saisi par les signataires. Toutefois, à la différence des champs de texte, il offre un habillage automatique. Chaque zone de texte peut accepter jusqu'à 4000 caractères.
• Liste - Ce menu déroulant permet de sélectionner l'une des nombreuses options.
• Radio - Les boutons radio permettent également de sélectionner une option parmi plusieurs.
• Case - Avant de signer, le signataire peut sélectionner ou désélectionner cette simple case.
• Étiquette - L'expéditeur du paquet peut ajouter un champ Étiquette pour intégrer du texte dans un document. Il s'agit d'un champ en lecture seule dont la valeur sera simplement apposée sur le PDF. Sur le site Signer Experience, le champ Étiquette est affiché sous forme de texte non modifiable.

Paramètres des balises de texte

Lors de la création d'une étiquette de texte, le système utilise les paramètres décrits dans le tableau suivant.

• Le Offset et la Size sont utilisés pour les trois types d'étiquettes de texte.

• Les autres paramètres du tableau ne sont utilisés que pour les types de Input Field.

• Tous les paramètres du tableau suivant sont facultatifs.

Si des guillemets sont requis dans un paramètre du tableau suivant, vous devez utiliser des guillemets droits. Vous ne pouvez pas utiliser de guillemets.

Paramètre	Description	Exemples
Offset	Décalage (en points x 1,3) à appliquer pour positionner le champ par rapport au coin supérieur gauche de la balise de texte S'il n'est pas spécifié, le champ sera inséré à la position exacte de la balise de texte. Les valeurs peuvent être positives ou négatives. Pour déplacer le champ extrait plus à droite et plus bas, utilisez des valeurs de décalage positives.	{{esl:Signer3:initials:offset(20,40)}} {{esl:Signer3:initials:offset(-20,-40)}}
Size	Taille du champ (en points x 1,3). Si elle n'est pas spécifiée, les valeurs par défaut du système seront utilisées. Les valeurs valides doivent être positives.	{{esl:Signer1:capture:size(200,50)}}
Group	Le groupe radio auquel le champ appartiendra S'il n'est pas spécifié, le système utilisera son groupe de radios par défaut.	{{esl:Signer1:Radio:Group("MyGroup"),Value("X")}}
Options	La liste des valeurs disponibles pour un champ List	{{esl_colour:signer1:list:options("Red", "Blue", "Green")}}
Value	La valeur par défaut du champ Pour les types de champs Radio et Checkbox : (1) si aucune valeur n'est spécifiée, l'option sera désélectionnée/décochée par défaut; (2) pour que l'option soit sélectionnée/cochée par défaut, la valeur « X » (3) si une autre valeur ou une chaîne vide est spécifiée, l'option sera désélectionnée/décochée par défaut.	{{esl:Signer1:label:value("This is a test label")}} {{esl_paymentMethod:signer1:textfield:value("Please enter your preferred payment method")}} {{esl:Signer1:checkbox:value("X")}}
Maxlen	La valeur maximale autorisée pour le champ	{{esl_paymentMethod:signer1:textfield:Maxlen(200)}}
Signature	Nom de la signature à laquelle un champ automatique est lié	{{esl:Signer1:SigningDate:signature("signer1Sig2")}}

Vous ne pouvez pas ajouter de champs personnalisés ou de champs de notaire via les balises de texte.

Signataire avec plusieurs signatures

Supposons qu'une extraction de document utilise des balises de texte et que le document a plus d'un champ de signature pour un signataire donné. Cela nécessite la spécification de métadonnées appropriées, comme l'expliquent les sections suivantes :

• Signatures

• ChampsAuto

• Champs de saisie

Signatures

Les métadonnées suivantes permettent à un document d'avoir deux signataires, chacun avec deux champs de signature :

Signataire1 : {{esl_signer1Sig1:Signer1:Signature}}

Signataire1 : {{esl_signer1Sig2:Signer1:Signature}}

Signataire2 : {{esl_signer2Sig1:Signer2:Signature}}

Signataire2 : {{esl_signer2Sig2:Signer2:Signature}}

ChampsAuto

Si l'un des champs automatiques SignerName, SignerTitle, SignerCompany ou SigningDate est lié à l'un des champs de signature multiples d'un signataire, les métadonnées du champ automatique doivent être mises à jour pour le champ de signature spécifique auquel il est lié (pas nécessairement lié au premier champ de signature du signataire).

Les métadonnées suivantes permettent aux signatures multiples d'un signataire d'avoir des horodatages différents dans le même document :

{{esl:Signer1:SigningDate:signature("signer1Sig2")}}

{{esl:Signer1:SigningDate:signature("signer1Sig1")}}

{{esl:Signer2:SigningDate:signature("signer2Sig1")}}

{{esl:Signer2:SigningDate:signature("signer2Sig2")}}

{{esl:Signer1:SignerName:signature("signer1Sig2")}}

{{esl:Signer1:SignerName:signature("signer1Sig1")}}

{{esl:Signer2:SignerName:signature("signer2Sig1")}}

{{esl:Signer2:SignerName:signature("signer2Sig2")}}

Champs de saisie

Si un champ de saisie est lié à l'un des multiples champs de signature d'un signataire, les métadonnées de ce champ de saisie doivent être mises à jour pour le champ de signature spécifique auquel il est lié (pas nécessairement lié au premier champ de signature du signataire).

Les métadonnées suivantes permettent aux signatures multiples d'un signataire d'avoir des liaisons de champ de texte et de zone de texte différentes dans le même document :

{{esl:Signer1:TextField:signature("signer1Sig2")}}

{{esl:Signer1:TextField:signature("signer1Sig1")}}

{{esl:Signer2:TextField:signature("signer2Sig1")}}

{{esl:Signer2:TextField:signature("signer2Sig2")}}

{{esl:Signer1:TextArea:signature("signer1Sig2")}}

{{esl:Signer1:TextArea:signature("signer1Sig1")}}

{{esl:Signer2:TextArea:signature("signer2Sig1")}}

{{esl:Signer2:TextArea:signature("signer2Sig2")}}

Tutoriel vidéo

Autres méthodes d'extraction

Vous pouvez également être intéressé par nos autres types d'extraction :

• Extraction de documents
• Extraction d'ancres de texte
• Extraction de la position

DocumentPackage pkg = PackageBuilder.newPackageNamed("Text Tag Example Package")
					.withStatus(PackageStatus.SENT)
					.withSigner(SignerBuilder.newSignerWithEmail("[email protected]")
					.withFirstName("John")
					.withLastName("Smith")
					.withCustomId("Signer1"))
					.withDocument(DocumentBuilder.newDocumentWithName("Sample Contract")
					.fromFile("C:/Users/hhaidary/Desktop/sample_contract.pdf")
					.withExtractionType(ExtractionType.TEXT_TAGS_ONLY)
					.enableExtraction())
				.build();

DocumentPackage pkg = PackageBuilder.NewPackageNamed("Text Tag Example Package")
					.WithStatus(DocumentPackageStatus.SENT)
					.WithSigner(SignerBuilder.NewSignerWithEmail("[email protected]")
					.WithFirstName("John")
					.WithLastName("Smith")
					.WithCustomId("Signer1"))
					.WithDocument(DocumentBuilder.NewDocumentNamed("Sample Contract")
					.FromFile("C:/Users/hhaidary/Desktop/sample_contract.pdf")
					.WithExtractionType(ExtractionType.TEXT_TAGS_ONLY)
					.EnableExtraction())
				.Build();

POST /api/packages

Accept: application/json
Content-Type: multipart/form-data
Authorization: Basic api_key

------WebKitFormBoundary1bNO60n7FqP5WO4t
					Content-Disposition: form-data; name="file"; filename="sample-contract.pdf"
					Content-Type: application/pdf
					%PDF-1.5
					%µµµµ
					1 0 obj
					<>>>
					endobj.... 
					------WebKitFormBoundary1bNO60n7FqP5WO4t
					Content-Disposition: form-data; name="payload"
					{
					"documents": [
					{
					"id": "sample-contract",
					"name": "Test Document",
					"extract": true,
					"extractionTypes":[
					"TEXT_TAGS"
					]
					}
					],
					"status": "DRAFT",
					"type": "PACKAGE",
					"roles": [
					{
					"id": "Signer1",
					"type": "SIGNER",
					"signers": [
					{
					"email": "[email protected]",
					"firstName": "John",
					"lastName": "Smith",
					"id": "Signer1"
					}
					],
					"name": "Signer1"
					}
					],
					"name": "Text Tags Example Package"
					}
				------WebKitFormBoundary1bNO60n7FqP5WO4t--

{
					"id": "9sKhW-h-qS9m6Ho3zRv3n2a-rkI="
				}

    	ESignLiveSDK sdk = new ESignLiveSDK();
         
					//Create package
					ESignLiveAPIObjects.Package_x pkg = new ESignLiveAPIObjects.Package_x();
					pkg.name = 'Test Text Tags - ' + Datetime.now().format();
					pkg.status = ESignLiveAPIObjects.PackageStatus.DRAFT;
        
					//Create Roles
					String roleId1 = 'Signer1';
					ESignLiveAPIObjects.Role role1 = new ESignLiveAPIObjects.Role();
					role1.signers = sdk.createRolesSigner('sigenr1_firstname', 'signer1_lastname', '[email protected]', 'CEO', 'ABC Bank');
					role1.id = roleId1;
					role1.name = roleId1;
					pkg.roles = new List<ESignLiveAPIObjects.Role>{role1};    //add role
        
					//Prepare Documents Blob
					String document1Name = 'Sample_Text_Tag';
					StaticResource sr = [SELECT Id, Body FROM StaticResource WHERE Name = 'test_text_tag' LIMIT 1];
					Map<String,Blob> documentBlobMap = new Map<String,Blob>();
					documentBlobMap.put(document1Name, sr.Body);
         
					//Create Document Metadata
					ESignLiveAPIObjects.Document document1 = new ESignLiveAPIObjects.Document();
					document1.name = document1Name;
					document1.id = document1Name;
					document1.extract = true;
					ESignLiveAPIObjects.Data data_x = new ESignLiveAPIObjects.Data();
					data_x.esl_doc_extract_type = '1';
					document1.data = data_x;
					pkg.documents = new List<ESignLiveAPIObjects.Document>{document1};    //add document
        
					//Send package One Step
					String packageId = sdk.createPackage(pkg,documentBlobMap);
				System.debug('PackageId: ' + packageId);