OneSpan Sign Developer: Role vs Signer - Part 1
In OneSpan Sign, Role and Signer are two different concepts. In a nutshell, one Role contains one Signer, but while Role is bound to signature approval, Signer contains information about the signer. Still confused? In this blog, we’ll try to untangle these two concepts.
Explaining Role and Signer?
To bring a more direct image of Role and Signer, below is a common payload structure that you can see in your response by calling
GET /api/packages/{packageId}
Let’s start with Signer, because it is likely more familiar to you. As you can see from the payload, all attributes describe the personal information of your recipient, including basic profile settings, authentication method, etc. Put another way, Signer varies from person to person, and the only thing to identify a signer within a transaction is the email address. That is to say, you can use email address to replace Signer ID in API calls wherever a Signer ID is needed.
“Role” is an abstraction concept describing how many functions related to Signers will be granted without knowing who the signer actually is. If you have tried our Template Feature, you will know that in a Template Package, you can leave the Signer’s information empty and these information can be injected until creating an actual package. From this point of view, Role acts as a placeholder which allows you to design your documents with signature fields and to assign functions to these roles without knowing your signers.
In addition:
- Email can completely replace the Signer ID anywhere when making an API call, regardless whether it’s used in an API URL or a request payload
- An approval (found in the right part of screenshot) represents a signature box being assigned to a Role, which means it needs to match with an existing Role ID
- Each Role contains one Signer. Though you can see “signers” with a JSON array value, it’s actually a one-to-one mapping. Even in the Group Signer Feature, all group members are in a group signer object
Retrieve in SDK
In the actual programming process, retrieving a Role ID or a Signer ID for as many API calls will need them is most important. Below, I’ve included Java SDK code as an example to demonstrate how to get them.
Role ID:
To retrieve Role ID, OneSpan Sign SDK enables us to locate the Role by using an email address:
EslClient eslClient = new EslClient(API_KEY, API_URL);
DocumentPackage documentPackage = eslClient.getPackage(new PackageId("your package id"));
String roleId = documentPackage.getSigner("signer’s id").getId();
Signer ID:
As mentioned above, Signer ID can be replaced by signer’s email since it’s unique within a single transaction, but they can still be retrieved with the following code snippet:
import com.silanis.esl.api.model.Role;
import com.silanis.esl.api.model.Signer;
String signerId = "";
List<Role> roles = eslClient.getPackageService().getRoles(new PackageId("your package id"));
for (Role role : roles) {
Signer signer = role.getSigners().get(0);
if (signer.getEmail().equals("signer’s email")) {
signerId = role.getSigners().get(0).getId();
break;
}
}
As you can see, Role and Signer objects are all API models (imported from model package). That’s because since signer Id can directly be replaced by email, so that in SDK level, these two concepts are combined into one object (com.silanis.esl.sdk.Signer). The ID attribute in this Signer object is actually Role ID.
Link to post
In my next blog, we will talk about the scenarios and API calls where you will need to use Role ID as well as Signer ID.
If you have any questions regarding this blog or anything else about integrating OneSpan Sign into your application, visit the Developer Community Forum. Your feedback matters to us!
