OneSpan Sign How To: Creating Layouts

Document layouts can be a powerful tool when creating new document packages. It allows you to create a new document package by using a previous document as blueprint. Once saved as a layout, you can apply it on successive documents, enabling quicker creation of packages. In this blog, I will show you how to create, retrieve, and apply layouts using the OneSpan Sign Java SDK, .NET SDK, and REST API.

Layouts in the UI

The first step is to locate your layouts in the UI. When editing documents, you will find all of your saved layouts under the toolbar as shown below. It is important to note that layouts can only be applied when document packages are in draft status.

The Beginner's Guide to Electronic Signatures

This essential briefing introduces important legal concepts and key considerations when creating digital business processes with e-signatures.

Download Now

The Code

You can skip to the section which applies to you. Each segment will cover the same information. In my example, I will be using document extraction to extract the fields and saving them as a layout. If you are unsure on how to use document extraction, you can find the link to the blog here. Full example code for this blog can be found in the Developer Community Code Share: Java, .NET, and REST.

Java SDK

First, I will go over the Java SDK. After creating your package, you call on your OneSpan Sign LayoutService to create your layout from your package. You can also create a layout from an existing package. It is important to note that the layout id will required when applying layouts to documents.

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

You can also retrieve all of your saved layouts. Below is a sample code on how to retrieve all your layouts, which comes as a page from OneSpan Sign, along with their names and ids. The layout ids will be required in order to apply layouts. In the code below, the number of layouts returned in the PageRequest is set to 5. The maximum number of layouts that you can retrieve per page is 50. The first value in the PageRequest (variable ‘i’) is the starting point in the overall list of layouts that should be returned. This variable is incremented as we step through our layouts to keep track of where we are in the overall list of layouts.

int i = 1;

// The first step is to retrieve the layouts from the first page. In my example, I chose to retrieve 5 layouts at a time but you can set this to any number.
List<DocumentPackage> layouts = eslClient.getLayoutService().getLayouts(Direction.DESCENDING, new PageRequest(i, 5));
	     
while (!layouts.isEmpty()) {

   // Next, you will create your iterator object. It will enable you to iterate through your list of layouts.	    	 
   Iterator<DocumentPackage> index = layouts.iterator();
     
      while (index.hasNext()) {
         
         //This is where you retrieve your layout name and id. 
         DocumentPackage myLayout = index.next();
         System.out.println(myLayout.getName() + " " + myLayout.getId());
         i++;

      }
      
      // Finally, you will retrieve your next 5 layouts from the second page and start over up until you’ve retrieved all your layouts.     
      layouts = eslClient.getLayoutService().getLayouts(Direction.DESCENDING, new PageRequest(i, 5));

}

Similarly, you call on your OneSpan Sign LayoutService to apply layouts, where you would need your package id, document id, and your layout id.

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

.NET SDK

Next, I will go over the .NET SDK. After creating your package, you call on your OneSpan Sign client to create your layout from your package. You can also create a layout from an existing package. It is important to note that the layout id will required when applying layouts to documents.

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

You can also retrieve all of your saved layouts. Below is a sample code on how to retrieve all your layouts, which comes as a page from OneSpan Sign, along with their names and ids. The layout ids will be required in order to apply layouts. In the code below, the number of layouts returned in the PageRequest is set to 5. The maximum number of layouts that you can retrieve per page is 50. The first value in the PageRequest (variable ‘i’) is the starting point in the overall list of layouts that should be returned. This variable is incremented as we step through our layouts to keep track of where we are in the overall list of layouts.

int i = 1;

// The first step is to retrieve the layouts from the first page. In my example, I chose to retrieve 5 layouts at a time but you can set this to any number.
IList<DocumentPackage> layouts = eslClient.LayoutService.GetLayouts(Direction.DESCENDING, new PageRequest(i, 5));

int count = layouts.Count;

while (count != 0) {

   foreach (DocumentPackage j in layouts){

      //This is where you retrieve your layout name and id.
      Debug.WriteLine(j.Name + " " + j.Id);
      i++;

   }
   
   // Finally, you will retrieve your next 5 layouts from the second page and start over up until you’ve retrieved all your layouts.
   layouts = eslClient.LayoutService.GetLayouts(Direction.DESCENDING, new PageRequest(i, 5));
   count = layouts.Count;

}

Similarly, you call on your OneSpan Sign LayoutService to apply layouts, where you would need your package id, document id, and layout id.

eslClient.LayoutService.ApplyLayout(packageId, "documentId", "layoutId");

REST API

Finally, I will cover the REST API. The JSON string sample below shows you how to create a layout from an existing document. It is important to note that the layout id will required when applying layouts to documents.

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

You can also retrieve all of your saved layouts. The code below will parse your JSON response and print out the name and id of each layout.

HttpClient myClient = new HttpClient();
myClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", apiKey);
myClient.DefaultRequestHeaders.Add("Accept", "application/json");

//retrieve all layouts
var layouts = myClient.GetAsync(new Uri(apiUrl + "?from=0&to=100")).Result;
JObject layoutsJSON = JObject.Parse(layouts.Content.ReadAsStringAsync().Result);
var results = layoutsJSON["results"];

foreach (var q in results)
{
   var name = q["name"];
   var id = q["id"];
   Debug.WriteLine(name + " " + id);
}

Similarly, to apply a layout, you will need the packageId, documentId, and layoutId.

var response = myClient.PostAsync(new Uri(apiUrl + "{packageId}/documents/{documentId}/layout?layoutId=fb76da60-b4ad-4c97-8b93-da48c0384601"), jsonContent).Result;
Debug.WriteLine(response.Content.ReadAsStringAsync().Result);

The Results

After running your code, you can find a list of all your layouts from the toolbar.

Once your layout is saved, you can then apply it on subsequent documents through the SDKs/API or through the UI.

There you go. You have successfully created and applied a new layout. If you have questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the developer community forums: https://developer.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 Product Evangelist

LinkedIn | Twitter