Document Attributes

The following guides shows you how to add custom data attributes to your documents.

Document attributes are customized data related to a document in a transaction. The data in this section of the document information is not interpreted by OneSpan Sign. The users of this data are free to store and interpret whatever data they want.

The Code

The following code sample illustrates the simplest way of creating a package with customized document attributes. The samples illustrate how to create customized attributes with the keys “Department”, and “Employee”. The customized attribute data is constructed as a map.

DocumentPackage superDuperPackage = newPackageNamed(getPackageName())
        .describedAs("This is a package created using the OneSpan Sign SDK")
        .withSigner(newSignerWithEmail(email1)
                   .withCustomId("role1")
                   .withFirstName("John1")
                   .withLastName("Smith1"))
        .withDocument(newDocumentWithName(DOCUMENT_NAME)
                   .fromStream(documentInputStream1, DocumentType.PDF)
                   .withSignature(signatureFor(email1)
                          .onPage(0)
                          .atPosition(100, 100))
        .withData(newDocumentAttributes()
                   .addAttribute("Department", "1806")
                   .addAttribute("Employee", "135526")))
        .build();

If you want to retrieve your attributes at a later stage, you can do so as shown below:

DocumentPackage pkg = eslClient.getPackageService().getPackage(packageId);
		
Document doc = pkg.getDocument(DOCUMENT_NAME);
		
Map<String, Object> attributes = doc.getData();
		
for (Map.Entry<String, Object> entry : attributes.entrySet()){
	System.out.println("Key : " + entry.getKey() + " Value : " + entry.getValue());
}

Running Your Code

Below is a screenshot of the console output you can expect once you run the sample code above:

java

Get the Code

Document attributes are customized data related to a document in a transaction. The data in this section of the document information is not interpreted by OneSpan Sign. The users of this data are free to store and interpret whatever data they want.

The Code

The following code sample illustrates the simplest way of creating a package with customized document attributes. The samples illustrate how to create customized attributes with the keys “Department”, and “Employee”. The customized attribute data is constructed as a map.

DocumentPackage superDuperPackage = PackageBuilder.NewPackageNamed(PackageName)
    .DescribedAs( "This is a package created using the OneSpan Sign SDK" )
    .WithSigner( SignerBuilder.NewSignerWithEmail( email1 )
        .WithCustomId( "Client1" )
        .WithFirstName( "John" )
        .WithLastName( "Smith" )
        .WithTitle( "Managing Director" )
        .WithCompany( "Acme Inc." ) )
    .WithDocument( DocumentBuilder.NewDocumentNamed( DOCUMENT_NAME )
        .FromStream( fileStream1, DocumentType.PDF )
        .WithSignature( SignatureBuilder.SignatureFor( email1 )
            .OnPage( 0 )
            .AtPosition( 100, 100 ) )
        .WithData(DocumentAttributesBuilder.NewDocumentAttributes()
            .AddAttribute( "Department", "1806")
            .AddAttribute( "Employee", "135526"))
    )
    .Build();

If you want to retrieve your attributes at a later stage, you can do so as shown below:

DocumentPackage pkg = eslClient.GetPackage(packageId);

Document doc = pkg.GetDocument("sample doc");

IDictionary<string, object> attributes = doc.Data;

foreach (var attribute in attributes)
{
    Debug.WriteLine("Key : " + attribute.Key + " Value : " + attribute.Value);
}

Running Your Code

Below is a screenshot of the console output you can expect once you run the sample code above:

java

Get the Code

Document attributes are customized data related to a document in a transaction. The data in this section of the document information is not interpreted by OneSpan Sign. The users of this data are free to store and interpret whatever data they want.

The Code

The following JSON sample illustrates the simplest way of creating a package with customized document attributes. The samples illustrate how to create customized attributes with the keys “Department”, and “Employee”.

HTTP Request
POST /api/packages

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

Request Payload

------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="file"; filename="testDocumentExtraction.pdf"
Content-Type: application/pdf

%PDF-1.5
%µµµµ
1 0 obj
<>>>
endobj.... 

------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="payload"

{
  "autocomplete": true,
  "documents": [
    {
      "approvals": [
        {
          "fields": [
            {
              "extract": false,
              "height": 50,
              "left": 100,
              "page": 0,
              "subtype": "FULLNAME",
              "top": 100,
              "type": "SIGNATURE",
              "width": 200
            }
          ],
          "role": "Client1"
        }
      ],
      "data": {
        "Department": "1806",
        "Employee": "135526"
      },
      "name": "sample doc"
    }
  ],
  "name": "Document Attributes Example",
  "roles": [
    {
      "id": "Client1",
      "name": "Client1",
      "signers": [
        {
          "company": "Acme Inc.",
          "email": "mail32@mailinator.com",
          "firstName": "John",
          "id": "Client1",
          "lastName": "Smith",
          "title": "Managing Director"
        }
      ]
    }
  ],
  "trashed": false,
  "type": "PACKAGE",
  "visibility": "ACCOUNT"
}

------WebKitFormBoundary1bNO60n7FqP5WO4t--

For a complete description of each field, take a look at the JSON Properties section below.

Response Payload

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

If you want to retrieve your attributes at a later stage, you can do so by simply retrieving your document JSON:

GET https://sandbox.esignlive.com/api/packages/{packageId}/documents/{documentId}

And looping through the “data” field property.

Running Your Code

Below is a screenshot of the console output you can expect once you run the sample code above:

java

Get the Code

JSON Properties

Property Type Editable Required Default Sample Value(s)
status string Yes No DRAFT DRAFT / SENT / COMPLETED / ARCHIVED / DECLINED / OPTED_OUT / EXPIRED
autoComplete boolean Yes No true true / false
type string Yes No PACKAGE PACKAGE / TEMPLATE / LAYOUT
name string Yes Yes n/a Document Attributes Example
trashed boolean Yes No false true / false
visibility string Yes No ACCOUNT ACCOUNT / SENDER
documents
name string Yes No n/a sample doc
approvals
fields
subtype string Yes No n/a FULLNAME / INITIALS / CAPTURE / MOBILE_CAPTURE / LABEL / TEXTFIELD / TEXTAREA / CHECKBOX / DATE / RADIO / LIST
type string Yes No n/a SIGNATURE / INPUT
extract boolean Yes No false true / false
height integer Yes No 50 50 / 100 / 150 …
left integer Yes No 0 50 / 100 / 150 …
page integer Yes No 0 0 / 1 / 2 …
top integer Yes No 0 50 / 100 / 150 …
width integer Yes No 200 50 / 100 / 150 …
role string Yes No n/a Client1
data
Department string Yes No n/a 1806
Employee string Yes No n/a 135526
roles
id string Yes No n/a Client1
name string Yes No n/a Client1
type string Yes No SIGNER SIGNER / SENDER
signers
email string Yes Yes n/a preparer.email@example.com
firstName string Yes Yes n/a John
lastName string Yes Yes n/a Smith
phone string Yes No n/a 514-555-8888
id string Yes No n/a Client1
company string Yes No n/a Acme Inc.
title string Yes No n/a Managing Director