OneSpan Sign How To: Injecting Fields

Haris Haidary, March 23, 2016
Thumbnail

With OneSpan Sign, you have the ability to customize your document. One of many ways to do so is with field injection. This feature stamps values directly onto the document during document upload. For instance, a signer might have an agent number, and that agent number needs to appear in the final document next to his signature. By injecting a signer's agent number onto the document, this new text will become part of the underlying document and cannot be tampered with.

To enable field injection, you will need a PDF with form fields. In addition, the names of your form fields in your PDF must be the same as the injected field names in your code. Note that currently injecting data into a document, using OneSpan Sign, can only be done when uploading your document and can only be done through the API/SDKs. In this blog, I will show you how to use injected fields with the Java SDK, .NET SDK, and REST API.

The Code

With our objective set, you can go ahead and skip to the section which applies to your method. I will cover the exact same content in each segment.Full code for this blog can be found in the Developer Community Code Share: Java, .NET, and REST.

Java SDK

I’ll start with the Java SDK. In my example, I chose to inject text fields as this is probably what you will end up doing. However, you can inject any type of unbound field you like. You can find a complete list of OneSpan Sign’s unbound fields here. The sample code below shows you how to edit the document block for injecting text fields. The withName() method is where you input the name of your PDF form field you want to inject text to, as it is named in your PDF form. The withValue() method is the text you want to stamp on your document. If you need a comparison to the basic document object creation or if this is your first time creating a package with the Java SDK, see this blog.

.withDocument(DocumentBuilder.newDocumentWithName("Sample Contract")
		.enableExtraction()
		.fromStream(fs, DocumentType.PDF)
		.withInjectedField(FieldBuilder.textField()
				.withName("Text1")
				.withValue("200 E MAIN ST, PHOENIX AZ, 85123 USA"))
		.withInjectedField(FieldBuilder.textField()
				.withName("Text2")
				.withValue("Lawn mower"))
		.withInjectedField(FieldBuilder.textField()
				.withName("Text3")
				.withValue("Fertilizer"))
		.withInjectedField(FieldBuilder.textField()
				.withName("Text4")
				.withValue("100"))
		.withInjectedField(FieldBuilder.textField()
				.withName("Text5")
				.withValue("12   12   12")))

 

OneSpan Developer Community

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today

.NET SDK Next, I’ll cover the .NET SDK. In my example, I chose to inject text fields as this is probably what you will end up doing. However, you can inject any type of unbound field you like. You can find a complete list of OneSpan Sign’s unbound fields here. The sample code below shows you how to edit the document block for injecting text fields. The withName() method is where you input the name of your PDF form field you want to inject text to, as it is named in your PDF form. The withValue() method is the text you want to stamp on your document. If you need a comparison to the basic document object creation or if this is your first time creating a package with the .NET SDK, see this blog.

.WithDocument(DocumentBuilder.NewDocumentNamed("sample contract")
                .EnableExtraction()
                .FromStream(fs, DocumentType.PDF)
                .WithInjectedField(FieldBuilder.TextField()
                    .WithId("Text1")
                    .WithName("Text1")
                    .WithValue("200 E MAIN ST, PHOENIX AZ, 85123 USA"))
                .WithInjectedField(FieldBuilder.TextField()
                    .WithId("Text2")
                    .WithName("Text2")
                    .WithValue("Lawn mower"))
                .WithInjectedField(FieldBuilder.TextField()
                    .WithId("Text3")
                    .WithName("Text3")
                    .WithValue("Fertilizer"))
                .WithInjectedField(FieldBuilder.TextField()
                    .WithId("Text4")
                    .WithName("Text4")
                    .WithValue("100"))
                .WithInjectedField(FieldBuilder.TextField()
                    .WithId("Text5")
                    .WithName("Text5")
                    .WithValue("12   12   12"))

REST API

Finally, I’ll go over the REST API. I included the JSON that will create your document package with injected text fields for convenience. In my example, I chose to inject text fields as this is probably what you will end up doing. However, you can inject any type of unbound field you like. You can find a complete list of OneSpan Sign’s unbound fields here. Also, note that checkboxes and radio buttons are simply checkboxes with an "X" value when selected. The sample JSON below shows you how to edit the document object for injecting text fields. In the fields object, the name attribute is where you input the name of your PDF form field you want to inject text to. The value attribute is where you input the text you want to inject on your document. If you need a comparison to the basic document object creation or if this is your first time creating a package with the REST API, see this blog.

{
  "documents": [
    {
      "fields": [
        {
          "value": "200 E MAIN ST, PHOENIX AZ, 85123 USA",
          "name": "Text1"
        },
        {
          "value": "Lawn mower",
          "name": "Text2"
        },
        {
          "value": "Fertilizer",
          "name": "Text3"
        },
        {
          "value": "100",
          "name": "Text4"
        },
        {
          "value": "12   12   12",
          "name": "Text5"
        }
      ],
      "extract": true,
      "name": "Sample Contract"
    }
  ],
  "type": "PACKAGE",
  "status": "DRAFT",
  "roles": [
    {
      "id": "client",
      "index": 0,
      "type": "SIGNER",
      "signers": [
        {
          "email": "[email protected]",
          "firstName": "John",
          "lastName": "Smith",
          "id": "client"
        }
      ],
      "name": "client"
    },
    {
      "id": "contractor",
      "index": 1,
      "type": "SENDER",
      "signers": [
        {
          "email": "[email protected]",
          "firstName": "Haris",
          "lastName": "Haidary",
          "id": "contractor"
        }
      ],
      "name": "contractor"
    }
  ],
  "name": "Field Injection Example"
}

Running Your Code

Once you’ve run your code, if you log into OneSpan Sign, you should find the appropriate text fields stamped in the document in your OneSpan Sign document package, as seen below.

result_text_inject

If you have questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the developer community forums: https://community.onespan.com. That's it from me. Thank you for reading! If you found this post helpful, please share it on Facebook, Twitter, or LinkedIn.

Haris Haidary

Junior Technical Evangelist

LinkedIn | Twitter