Extracción de etiquetas de texto

la Text Tag Extraction permite a los integradores extraer automáticamente firmas y campos mediante la colocación de etiquetas de texto en un documento. OneSpan Sign analizará el documento cargado y sustituirá todo el texto que coincida con el patrón de la etiqueta de texto por la firma o el campo correspondiente.

En esta sección, se describe lo siguiente:

• Sintaxis de etiquetas de texto
• Nombres de roles en etiquetas de texto
• Tipos de etiquetas de texto
• Parámetros de etiquetas de texto
• Firmante con múltiples firmas

Prácticas recomendadas para el uso de etiquetas de texto

A continuación, se indican algunas prácticas recomendadas que debe tener en cuenta al utilizar etiquetas de texto:

• Cuando tenga varios atributos especificados en las etiquetas de texto, intente utilizar una coma para separarlos, como se indica a continuación:

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

  Un ejemplo más complicado podría ser el siguiente:

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

• Intente utilizar una fuente más pequeña para sus etiquetas de texto. Ahorrará espacio y evitará que se vea afectado el formato de su contenido.
• Asegúrese de que su etiqueta de texto esté en una línea.

A continuación, se muestra un código de ejemplo que incorpora estas sugerencias:

{{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)}}

En este ejemplo, el tamaño de las etiquetas se establece en 1 y el tamaño del texto normal se establece en 12. Esto es lo que se obtiene después de extraer a esos campos:

Para obtener una copia del documento de Word utilizado en este ejemplo, haga clic aquí.

Si tiene problemas para colocar las etiquetas de texto en su ubicación correcta, pruebe a usar el atributo offset. Esto es especialmente útil cuando se utiliza un documento de Microsoft Word.

Sintaxis de etiquetas de texto

La siguiente línea ilustra la sintaxis de una etiqueta de texto:

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

Si tiene varios atributos especificados en las etiquetas de texto, intente separarlos con una coma, como se indica a continuación:

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

Un ejemplo más complicado podría ser el siguiente:

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

Los nombres de los campos son alfanuméricos. No pueden contener caracteres especiales, excepto el guion bajo (_).

Tenga en cuenta de esta línea que:

• El principio y el final de una etiqueta de texto tienen corchetes curvados. Los corchetes no deben aparecer en ninguna otra parte de una etiqueta de texto.
• El tercer carácter —X— es un marcador de posición para un carácter opcional. Este carácter puede ser un signo de interrogación (?) o un asterisco (*). Un asterisco indica que un Input Field es obligatorio. Un signo de interrogación indica que un Input Field es opcional. El signo de interrogación es el valor predeterminado, es decir, si ninguno de los dos caracteres está presente, un Input Field será opcional. Ejemplo: {{*esl:Signer1:textfield}}
• fieldName es el nombre del campo que creará la etiqueta de texto (una Signature, un Autofield o un Input Field); consulte Tipos de etiquetas de texto. Si se especifica, este parámetro seguirá al prefijo "esl". Los nombres de los campos son alfanuméricos. No pueden contener caracteres especiales, excepto el guion bajo (_). Si planea recuperar el valor ingresado durante la Signer Experience, ingrese un nombre único por campo. Ejemplo: {{esl_SignerAutograph:Signer1:Signature}}
• roleName es el nombre del rol asociado al firmante previsto. Para encontrar el nombre de rol que necesita usar, consulte Nombres de roles en etiquetas de texto.
• fieldType es uno de los tipos de campo descritos en Tipos de etiquetas de texto.
• parameter1 y parameter2 son parámetros descritos en Parámetros de etiquetas de texto.

Tenga en cuenta lo siguiente:

• Una misma etiqueta de texto no puede aparecer en varias líneas.

• Si se usa una lista de parámetros, debe ser una lista separada por comas.

La siguiente línea ilustra la sintaxis válida más corta para una etiqueta de texto:

{{esl:roleName:fieldType}}

Nombres de roles en etiquetas de texto

Si crea una transacción utilizando la interfaz de usuario web de OneSpan Sign, el nombre del rol del remitente siempre es Owner.

Si crea un firmante de "Destinatario" o un firmante de Grupo usando OneSpan Sign, el nombre de rol del firmante es Signer#, donde # comienza en 1 y aumenta en uno con cada firmante. Con cada nuevo firmante, se usa el número más bajo disponible. Por lo tanto, si elimina el firmante con el nombre de rol Signer1 y luego agrega un nuevo firmante, el nombre de rol del nuevo firmante será Signer1.

Si crea un firmante de marcador de posición y lo nombra Cliente, Cliente será el nombre del rol. Cliente se mantendrá como nombre de rol cuando ese marcador de posición se reemplace más tarde con un destinatario o grupo específico.

Si crea un firmante con el SDK y asigna un ID personalizado a ese firmante, ese ID será el nombre de rol del firmante. Si no asigna un ID personalizado al firmante, se genera uno para el firmante utilizando las mismas reglas que cuando se utiliza la interfaz de usuario web de OneSpan Sign.

Tipos de etiquetas de texto

Existen tres tipos principales de etiquetas de texto:

• Firmas
• Campos automáticos
• Campos de entrada

Firmas

Una etiqueta de texto de Signature en particular puede ser cualquiera de los siguientes tipos de campo:

• Firma: este bloque de firma es de tipo Hacer clic para firmar. El nombre del firmante se estampa en el bloque en el que se hace clic.
• Iniciales: este bloque de firma es de tipo Hacer clic para colocar iniciales. Las iniciales del firmante se estamparán en el bloque en el que se hace clic.
• Captura: el firmante hace clic en este bloque de firma y dibuja su firma utilizando el mouse u otro dispositivo de entrada. El firmante también puede optar por firmar en un dispositivo móvil, como un teléfono inteligente, si el remitente tiene activada la captura en dispositivo móvil en su cuenta. A continuación, se estampa el dibujo en el bloque de firma. Tenga en cuenta que el uso de un lápiz óptico no es compatible con la interfaz de usuario clásica.
• Captura_Móvil: para firmar electrónicamente este bloque de firma, el firmante recibirá un vínculo por correo electrónico que le redirigirá para abrir el documento en su teléfono celular. A continuación, se les pide que dibujen su firma utilizando su dedo o un lápiz óptico. A continuación, se estampa el dibujo de la firma en el bloque. Tenga en cuenta que el uso de un lápiz óptico no es compatible con la interfaz de usuario clásica.

Campos automáticos

Una etiqueta de texto de Autofield en particular puede ser cualquiera de los siguientes tipos de campo:

• SignerName: en el momento de la firma, el sistema rellena automáticamente este campo con el nombre completo del firmante.
• SignerTitle: si el título del firmante está disponible, el sistema rellena automáticamente este campo con ese título en el momento de la firma. De lo contrario, el campo se deja en blanco.
• SignerCompany: si el nombre de la empresa del firmante está disponible, el sistema rellena automáticamente este campo con ese nombre en el momento de la firma. De lo contrario, el campo se deja en blanco.
• SigningDate: en el momento de la firma, el sistema rellena automáticamente este campo con la fecha actual.

Campos de entrada

Una etiqueta de texto de Input Field en particular puede ser cualquiera de los siguientes tipos de campo:

• TextField: este cuadro acepta cualquier texto ingresado por el firmante antes de firmar.
• TextArea: es similar al tipo TextField, ya que proporciona un área en la cual los firmantes pueden ingresar texto de forma libre. Sin embargo, a diferencia de los Campos de texto, proporciona un ajuste automático. Cada Área de texto puede aceptar hasta 4000 caracteres.
• List: este menú desplegable ofrece la posibilidad de seleccionar una de las muchas opciones.
• Radio: los botones de radio también ofrecen la posibilidad de seleccionar una opción entre muchas.
• Checkbox: antes de firmar, el firmante puede seleccionar o desactivar esta casilla de verificación simple.
• Label: el remitente del paquete puede agregar un campo de etiqueta para incrustar texto en un documento. Es un campo de solo lectura con un valor que simplemente se estampará en el PDF. Durante la Signer Experience, el campo Etiqueta se muestra como texto no editable.

Parámetros de etiquetas de texto

Al crear una etiqueta de texto, el sistema utiliza los parámetros descritos en la siguiente tabla.

• Offset y Size se utilizan para los tres tipos de etiquetas de texto.

• Los otros parámetros de la tabla se utilizan solo para los tipos de Input Field.

• Todos los parámetros de la siguiente tabla son opcionales.

Si se requieren comillas en cualquier parámetro de la siguiente tabla, debe usar comillas rectas. No se pueden usar comillas curvadas.

Parámetro	Descripción	Ejemplos
Offset	Desplazamiento (en puntos x 1,3) que se aplicará al posicionar el campo en relación con la esquina superior izquierda de la etiqueta de texto Si no se especifica, el campo se insertará en la posición exacta de la etiqueta de texto. Los valores pueden ser positivos o negativos. Para desplazar el campo extraído más a la derecha y más abajo, utilice valores de desplazamiento positivos.	{{esl:Signer3:initials:offset(20,40)}} {{esl:Signer3:initials:offset(-20,-40)}}
Size	Tamaño del campo (en puntos x 1,3). Si no se especifica, se utilizarán los valores predeterminados del sistema. Los valores válidos deben ser positivos.	{{esl:Signer1:capture:size(200,50)}}
Group	El grupo de radio al que pertenecerá el campo Si no se especifica, el sistema utilizará su grupo de radio predeterminado.	{{esl:Signer1:Radio:Group("MyGroup"),Value("X")}}
Options	La lista de valores disponibles para un campo List	{{esl_colour:signer1:list:options("Red", "Blue", "Green")}}
Value	El valor predeterminado del campo Para tipos de campo Radio y Checkbox: (1) si no se especifica ningún valor, la opción se deseleccionará/desmarcará de forma predeterminada; (2) para que la opción se seleccione/marque de forma predeterminada, se debe especificar el valor "X"; (3) si se especifica cualquier otro valor o la cadena vacía, la opción se deseleccionará/desmarcará de forma predeterminada.	{{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	El valor máximo permitido para el campo	{{esl_paymentMethod:signer1:textfield:Maxlen(200)}}
Firma	Nombre de la firma a la que está vinculado un campo automático	{{esl:Signer1:SigningDate:signature("signer1Sig2")}}

No puede agregar Campos personalizados ni Campos de notario mediante etiquetas de texto.

Firmante con múltiples firmas

Supongamos que la extracción de un documento utiliza etiquetas de texto y que el documento tiene más de un campo de firma para un determinado firmante. Esto requiere la especificación de metadatos apropiados, como se explica en las siguientes secciones:

• Firmas

• Campos automáticos

• Campos de entrada

Firmas

Los siguientes metadatos permiten que un documento tenga dos firmantes, cada uno con dos campos de firma:

Firmante1: {{esl_signer1Sig1:Signer1:Signature}}

Firmante1: {{esl_signer1Sig2:Signer1:Signature}}

Firmante2: {{esl_signer2Sig1:Signer2:Signature}}

Firmante2: {{esl_signer2Sig2:Signer2:Signature}}

Campos automáticos

Si alguno de los autocampos SignerName, SignerTitle, SignerCompany o SigningDate está vinculado a alguno de los múltiples campos de firma del firmante, los metadatos del autocampo deben actualizarse para el campo de firma específico al que está vinculado (no necesariamente vinculado al primer campo de firma del firmante).

Los siguientes metadatos permiten que las múltiples firmas de un firmante tengan diferentes marcas de fecha en el mismo documento:

{{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")}}

Campos de entrada

Si un campo de entrada está vinculado a cualquiera de los múltiples campos de firma de un firmante, los metadatos de ese campo de entrada deben actualizarse para el campo de firma específico al que está vinculado (no necesariamente vinculado al primer campo de firma del firmante).

Los siguientes metadatos permiten que las múltiples firmas de un firmante tengan distintos enlaces de Campo de texto y Área de texto en el mismo documento:

{{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")}}

Videotutorial

Otros métodos de extracción

También pueden interesarle nuestros otros tipos de extracción:

• Extracción de documentos
• Extracción de delimitadores de texto
• Extracción de posiciones

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);