Login
    Contents x
    Managing Document Layouts
    • 10 Oct 2024
    • 20 Minutes to read
    • Print
    • Dark
      Light
    • PDF
    Contents

    Managing Document Layouts

    • Updated on 10 Oct 2024
    • 20 Minutes to read
    • Print
    • Dark
      Light
    • PDF
    Article summary

    Java SDK.NET SDKREST APIAPEX SDK

    Java SDK

    To download the full code sample see our Code Share site.

    Templates and Layouts fulfill the same goal of automating the e-signature process by shortening the time it takes to send documents that include several signature blocks and data fields. Templates are ideal to use at the transaction level – you can pre-define your signers, documents, signature locations and e-signature workflows to streamline the e-signature process. A Layout on the other hand, is a type of template that allows you to create pre-defined locations for your signature blocks and data fields within a document. It acts like a ‘marker’ where signature blocks and data fields will sit in the document. Layouts are helpful for users who frequently send forms that may be slightly different per recipient but signature blocks and data fields remain in the same location throughout the document. What’s more, you can use multiple Layouts per document, and apply them to individual pages within your transaction.

    Finding your Layouts in the UI

    When editing documents, you will find all of your saved layouts under the toolbar, as shown below. Note that layouts can only be applied when transaction are in a Draft status.

    Creating a New Layout

    In this example, document extraction is used to extract the fields and save them as a layout. For more information, see Document Extraction.

    After creating your transaction, use the OneSpan Sign LayoutService to create a layout from your transaction. It is important to note that the Layout ID is required to apply layouts to documents. The following code will do this:

     String layoutId = eslClient.getLayoutService().createLayout(myPackage);   System.out.println(layoutId);

    Retrieving a Layout

    The following code will retrieve a layout. The first step is to retrieve the layouts from the first page. In this example, five layouts are retrieved, but you can set this to any number.

    List<DocumentPackage> layouts = eslClient.getLayoutService().getLayouts(Direction.DESCENDING, new PageRequest(i, 5));

while (!layouts.isEmpty()) {
    // Your logic here
}

    Next, you will create your iterator object. This will enable you to iterate through your list of layouts.

    Iterator<DocumentPackage> index = layouts.iterator();

while (index.hasNext()) {
    DocumentPackage documentPackage = index.next();
    // Your logic here
}

    Then, retrieve your layout name and id.

    while (index.hasNext()) {
    DocumentPackage myLayout = index.next();
    System.out.println(myLayout.getName() + " " + myLayout.getId());
    i++;
}

    Use the following code to retrieve layouts from each page in the transaction, repeating for every page:

    layouts = eslClient.getLayoutService().getLayouts(Direction.DESCENDING, new PageRequest(i, 5));

    Applying Layouts

    Use the OneSpan Sign LayoutService to apply layouts, by either Layout ID, or by name.

    eslClient.getLayoutService().applyLayout(packageId, "documentId", "layoutId");   
eslClient.getLayoutService().applyLayoutByName(packageId, "documentId", "layoutName");  

    Deleting a Layout

    To delete a layout, use the PackageService(). The following code will do this:

     eslClient.getPackageService().deletePackage(new PackageId("layoutId"));

    Results

    After running your code, you will see a list of all your layouts under the toolbar. Once your layout is saved, you can then apply it on subsequent documents.

    .NET SDK

    To download the full code sample see our Code Share site.

    Templates and Layouts fulfill the same goal of automating the e-signature process by shortening the time it takes to send documents that include several signature blocks and data fields. Templates are ideal to use at the transaction level – you can pre-define your signers, documents, signature locations and e-signature workflows to streamline the e-signature process. A Layout on the other hand, is a type of template that allows you to create pre-defined locations for your signature blocks and data fields within a document. It acts like a ‘marker’ where signature blocks and data fields will sit in the document. Layouts are helpful for users who frequently send forms that may be slightly different per recipient but signature blocks and data fields remain in the same location throughout the document. What’s more, you can use multiple Layouts per document, and apply them to individual pages within your transaction.

    Finding your Layouts in the UI

    When editing documents, you will find all of your saved layouts under the toolbar, as shown below. Note that layouts can only be applied when transaction are in a Draft status.

    Creating a New Layout

    In this example, document extraction is used to extract the fields and save them as a layout. For more information, see Document Extraction.

    After creating your transaction, use the OneSpan Sign LayoutService to create a layout from your transaction. It is important to note that the Layout ID is required to apply layouts to documents. The following code will do this:

    string layoutId = eslClient.LayoutService.CreateLayout(packageFromLayout);
Debug.WriteLine(layoutId);

    Retrieving a Layout

    The following code will retrieve a layout. The first step is to retrieve the layouts from the first page. In this example, five layouts are retrieved, but you can set this to any number.

    List<DocumentPackage> layouts = eslClient.getLayoutService().getLayouts(Direction.DESCENDING, new PageRequest(i, 5));
while (!layouts.isEmpty()) {
    // Your code here
}

    Next, you will create your iterator object. This will enable you to iterate through your list of layouts.

    var index = layouts.GetEnumerator();
while (index.MoveNext()) {
    DocumentPackage myLayout = index.Current;
    // Your code here
}

    Then, retrieve your layout name and id.

    DocumentPackage myLayout = index.Current;
Console.WriteLine($"{myLayout.getName()} {myLayout.getId()}");
i++;
}

    Use the following code to retrieve layouts from each page in the transaction, repeating for every page:

    Applying Layouts

    Use the OneSpan Sign LayoutService to apply layouts, by either Layout ID, or by name.

    eslClient.getLayoutService().applyLayout(packageId, "documentId", "layoutId");   
eslClient.getLayoutService().applyLayoutByName(packageId, "documentId", "layoutName");  

    Deleting a Layout

    To delete a layout, use the PackageService(). The following code will do this:

     eslClient.PackageService.DeletePackage(new PackageId("layoutId"));

    Results

    After running your code, you will see a list of all your layouts under the toolbar. Once your layout is saved, you can then apply it on subsequent documents.

    REST API

    To download the full code sample see our Code Share site.

    Templates and Layouts fulfill the same goal of automating the e-signature process by shortening the time it takes to send documents that include several signature blocks and data fields. Templates are ideal to use at the transaction level – you can pre-define your signers, documents, signature locations and e-signature workflows to streamline the e-signature process. A Layout on the other hand, is a type of template that allows you to create pre-defined locations for your signature blocks and data fields within a document. It acts like a ‘marker’ where signature blocks and data fields will sit in the document. Layouts are helpful for users who frequently send forms that may be slightly different per recipient but signature blocks and data fields remain in the same location throughout the document. What’s more, you can use multiple Layouts per document, and apply them to individual pages within your transaction.

    Finding your Layouts in the UI

    When editing documents, you will find all of your saved layouts under the toolbar, as shown below. Note that layouts can only be applied when transaction are in a Draft status.

    Creating a New Layout

    In this example, document extraction is used to extract the fields and save them as a layout. For more information, see Document Extraction.

    Use the following code to create a layout from a document:

    HTTP Request

    POST /api/layouts

    HTTP Headers

    Accept: application/json   
Content-Type: application/json   
Authorization: Basic api_key

    Request Payload

     {   "name":"Layout 02",   "type":"LAYOUT",   "id":"packageId",   "visibility":"SENDER",   "documents":[   {   "id":"documentId"   }   ]   }

    For a complete description of each field, see the Request Payload table below.

    Response Payload

    {
    "name": "Layout 02",
    "type": "LAYOUT",
    "id": "packageId",
    "visibility": "SENDER",
    "documents": [
        {
            "id": "documentId"
        }
    ]
}

    It is important to note that theLayout ID is required to apply layouts to documents.

    Retrieving a Layout

    You can also retrieve all of your saved layouts. The following code will do this:

    HTTP Request

    GET /api/layouts?from={fromPage}&to={toPage}

    HTTP Headers

    Accept: application/json   
Content-Type: application/json   
Authorization: Basic api_key

    Response Payload

    {
    "results": [
        {
            "roles": [
                {
                    "id": "564fd009-7673-4a5f-9314-5c5b3d5f3869",
                    "data": null,
                    "emailMessage": {
                        "content": ""
                    },
                    "attachmentRequirements": [],
                    "locked": false,
                    "reassign": false,
                    "specialTypes": [],
                    "type": "SIGNER",
                    "index": 0,
                    "signers": [],
                    "name": "Signer2"
                },
                {
                    "id": "a3bfe56c-da0a-4ff0-bfef-efe55fd28a0c",
                    "data": null,
                    "emailMessage": {
                        "content": ""
                    },
                    "attachmentRequirements": [],
                    "locked": false,
                    "reassign": false,
                    "specialTypes": [],
                    "type": "SIGNER",
                    "index": 0,
                    "signers": [],
                    "name": "Signer1"
                },
                {
                    "id": "bjyxbrypiHw6",
                    "data": null,
                    "emailMessage": null,
                    "attachmentRequirements": [],
                    "locked": false,
                    "reassign": false,
                    "specialTypes": [],
                    "type": "SENDER",
                    "index": 0,
                    "signers": [
                        {
                            "group": null,
                            "language": "en",
                            "signature": {
                                "handdrawn": "AQAAADJI+a4cnf0t3Dlf0GqWJceCA+4AAwADAN8BAAADAAAAggPuAOgAAAACfyxAUkAlQCdAOUA6QDtAHEAtQBtACkAJQBVAFBIyfkA0QBVABkAYQCpAHEAtQC9ALkAtQDxAO0A6QEhAN0AlQCQyTjZAgEBwQIBAoFDSUOFQ8lDiUNJQ0lCiQHBAUCIXGVBSUCVQN1BJUDpQXVA9UE5QLlAuUDpQOVAkm1BhQLZAd0B7QFpAXUBPQTBAHkAdQAtAB2AmYBRgQmCAcJVwmHC5Mh42QFBAkECAQKBAsEDAQNBQ8VDyUPJQ81DTULRQg1ByUEGeIgQ6QDhAJ0AmQCZAFItwbHBtMhdBUCafUGJQcVCSUJFQoUDAQKBAsECBQHNAdEBEQDRABkAFYCdgR2BXYHhgd2CIYIVgdmBDYEJAUUBwQIFAkECwQLBA0EDAQLBAoEBwQGASG0xAc0BnQEhASkArQBxADEAKQAlABkAFMkVKUENQUVBBUGFQYVCRUKJQsVDCUNJQsUDQQKBAkEBwQFJAREAlIllVUHFQUVByUKFQslDSUNJQ9VDlUPZQ1lDWUKVQZVBEUCQyCxivr2BjYGRgdGB1YHZgZmBWYEdgRkAFQClAREBjQJNAk0CzQKNAs0CjQJNAQo9gRWBjYJNgs2DCYNRg1GCkYKRgY2Bkrg==",
                                "textual": null
                            },
                            "id": "8ceWLxUo1Gg1",
                            "delivery": {
                                "provider": false,
                                "email": true,
                                "download": true
                            },
                            "knowledgeBasedAuthentication": null,
                            "auth": {
                                "scheme": "NONE",
                                "challenges": []
                            },
                            "data": null,
                            "title": "Silanis",
                            "external": null,
                            "updated": "2017-11-14T20:31:34Z",
                            "phone": "",
                            "professionalIdentityFields": [],
                            "userCustomFields": [],
                            "company": "Silanis",
                            "email": "haris.haidary@gmail.com",
                            "firstName": "Haris",
                            "lastName": "Haidary",
                            "name": "",
                            "address": null,
                            "created": "2017-11-14T20:31:34Z",
                            "specialTypes": []
                        }
                    ],
                    "name": "Owner"
                }
            ],
            "status": "DRAFT",
            "description": "",
            "language": "en",
            "id": "rr8lE3YwF-LaCNxSjntn2udM8hc=",
      "data": {
                "origin": "api"
            },
            "autocomplete": true,
            "documents": [
                {
                    "status": "",
                    "description": "",
                    "id": "dfe8ac46006b31f6",
                    "signedHash": null,
                    "extractionTypes": [],
                    "signerVerificationToken": null,
                    "data": {},
                    "approvals": [
                        {
                            "id": "akmT717La0YP",
                            "role": "a3bfe56c-da0a-4ff0-bfef-efe55fd28a0c",
                            "data": null,
                            "signed": null,
                            "accepted": null,
                            "fields": [
                                {
                                    "binding": null,
                                    "validation": null,
                                    "id": "AooaSEwkp0oG",
                                    "page": 0,
                                    "data": null,
                                    "subtype": "FULLNAME",
                                    "height": 39.99995853281021,
                                    "extract": false,
                                    "width": 199.99979266405106,
                                    "extractAnchor": null,
                                    "left": 94.00000655210017,
                                    "top": 752.0005724167823,
                                    "type": "SIGNATURE",
                                    "value": "",
                                    "name": "AooaSEwkp0oG"
                                }
                            ],
                            "name": ""
                        },
                        {
                            "id": "anR9R3fLlQYE",
                            "role": "564fd009-7673-4a5f-9314-5c5b3d5f3869",
                            "data": null,
                            "signed": null,
                            "accepted": null,
                            "fields": [
                                {
                                    "binding": null,
                                    "validation": null,
                                    "id": "AvqDbyKBeIoX",
                                    "page": 0,
                                    "data": null,
                                    "subtype": "FULLNAME",
                                    "height": 39.99995853281021,
                                    "extract": false,
                                    "width": 199.99979266405106,
                                    "extractAnchor": null,
                                    "left": 94.00000655210017,
                                    "top": 832.999669445753,
                                    "type": "SIGNATURE",
                                    "value": "",
                                    "name": "AvqDbyKBeIoX"
                                }
                            ],
                            "name": ""
                        }
                    ],
                    "pages": [
                        {
                            "id": "dfe8ac46006b31f6_0_-1_1.png",
                            "height": 1030,
                            "width": 796,
                            "left": 0,
                            "top": 0,
                            "version": 0,
                            "index": 0
                        }
                    ],
                    "external": null,
                    "extract": false,
                    "fields": [],
                    "index": 0,
                    "name": "cleaning_contract",
                    "size": 197171
                }
            ],
            "sender": {
                "status": "ACTIVE",
                "language": "en",
                "signature": {
                    "handdrawn": "AQAAADJI+a4cnf0t3Dlf0GqWJceCA+4AAwADAN8BAAADAAAAggPuAOgAAAACfyxAUkAlQCdAOUA6QDtAHEAtQBtACkAJQBVAFBIyfkA0QBVABkAYQCpAHEAtQC9ALkAtQDxAO0A6QEhAN0AlQCQyTjZAgEBwQIBAoFDSUOFQ8lDiUNJQ0lCiQHBAUCIXGVBSUCVQN1BJUDpQXVA9UE5QLlAuUDpQOVAkm1BhQLZAd0B7QFpAXUBPQTBAHkAdQAtAB2AmYBRgQmCAcJVwmHC5Mh42QFBAkECAQKBAsEDAQNBQ8VDyUPJQ81DTULRQg1ByUEGeIgQ6QDhAJ0AmQCZAFItwbHBtMhdBUCafUGJQcVCSUJFQoUDAQKBAsECBQHNAdEBEQDRABkAFYCdgR2BXYHhgd2CIYIVgdmBDYEJAUUBwQIFAkECwQLBA0EDAQLBAoEBwQGASG0xAc0BnQEhASkArQBxADE

    Similarly, to apply a layout, you will need the packageId, documentId, and layoutId/layoutName, to make your request:

    If using LayoutID:

    HTTP Request

    POST /api/packages/{packageId}/documents/{documentId}/layout?layoutId={layoutId}

    HTTP Headers

    Accept: application/json   
Content-Type: application/json   
Authorization: Basic api_key

    If using layout name:

    HTTP Request

    POST /api/packages/{packageId}/documents/{documentId}/layout?layoutName={layoutName}

    HTTP Headers

    Accept: application/json   
Content-Type: application/json   
Authorization: Basic api_key

    Deleting a Layout

    To delete a layout use the following code:

    HTTP Request

    DELETE /api/packages/{layoutId}

    HTTP Headers

    Accept: application/json   
Content-Type: application/json   
Authorization: Basic api_key

    Results

    After running your code, you will see a list of all your layouts under the toolbar. Once your layout is saved, you can then apply it on subsequent documents.

    Request Payload Table

    Property

    Type

    Editable

    Required

    Default

    Sample Values

    type

    string

    Yes

    No

    PACKAGE

    PACKAGE / TEMPLATE / LAYOUT

    name

    string

    Yes

    Yes

    n/a

    Layout Example

    id

    string

    Yes

    No

    n/a

    rr8lE3YwF-LaCNxSjntn2udM8hc=

    visibility

    string

    Yes

    No

    ACCOUNT

    ACCOUNT / SENDER

    documents

    id

    string

    Yes

    No

    n/a

    sample-contract

    APEX SDK

    To download the full code sample see our Code Share site.

    Templates and Layouts fulfill the same goal of automating the e-signature process by shortening the time it takes to send documents that include several signature blocks and data fields. Templates are ideal to use at the transaction level – you can pre-define your signers, documents, signature locations and e-signature workflows to streamline the e-signature process. A Layout on the other hand, is a type of template that allows you to create pre-defined locations for your signature blocks and data fields within a document. It acts like a ‘marker’ where signature blocks and data fields will sit in the document. Layouts are helpful for users who frequently send forms that may be slightly different per recipient but signature blocks and data fields remain in the same location throughout the document. What’s more, you can use multiple Layouts per document, and apply them to individual pages within your transaction.

    Finding your Layouts in the UI

    When editing documents, you will find all of your saved layouts under the toolbar, as shown below. Note that layouts can only be applied when transaction are in a Draft status.

    Creating a New Layout

    In this example, document extraction is used to extract the fields and save them as a layout. For more information, see Document Extraction.

    After creating your package, use the following encapsulated function to create your layout from an existing package.

    public ESignLiveAPIObjects.package_x createLayout(String packageId, String documentId, String layoutName, TestLayout.Visibility visibility) {
    // Your code here
}

    It is important to note that the Layout ID is required to apply layouts to documents. The following code will do this:

    ESignLiveAPIObjects.package_x createLayout = createLayout(pkgId, 'Sample_Document_Extraction', 'Layout Created from Apex SDK', TestLayout.Visibility.ACCOUNT);
String layoutId = createLayout.id;

    Retrieving a Layout

    The following code will retrieve a layout.

    // Retrieve all layouts
Integer totalCount = getLayoutCount();
Integer index = 0;
System.debug('Total layout count: ' + totalCount);

while (index < totalCount) {
    List<ESignLiveAPIObjects.package_x> layouts = getLayouts(index, index + 49);
    for (ESignLiveAPIObjects.package_x layout : layouts) {
        System.debug('Layout name: ' + layout.name + ' with id: ' + layout.id);
    }
    index += 50;
}

    Similarly, to creating layouts, use the following encapsulated functions to apply a layout to your document. This code will pass in your layout ID, target package ID and target Document ID.

      public void applyLayout(String packageId, String documentId, String layoutId)

    Deleting a Layout

    To delete a layout, use the following code:

      //delete layout   ESignLiveSDK sdk = new ESignLiveSDK();   sdk.deletePackage(layoutId);

    Results

    After running your code, you will see a list of all your layouts under the toolbar. Once your layout is saved, you can then apply it on subsequent documents.

    Was this article helpful?
    What's Next
    Change password!
    Changing your password will log you out immediately. Use the new password to log back in.
    Change profile
    Success!
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.
    Logout
    ESC

    Eddy AI, facilitating knowledge discovery through conversational intelligence