To download the full code sample see our Code Share site.
Sometimes it's convenient to share requests for signatures among the members of a group. For example, it might be convenient to treat the pharmacists in a particular pharmacy as a group, so that any available member of the group can sign the paperwork for a patient's prescriptions.
In OneSpan Sign, a Signer Group is a set of OneSpan Sign users who can act as a single signer from the perspective of a transaction's creator. Users who can become group members must already be members of the associated OneSpan Sign account.
OneSpan Sign group members receive an email invitation to sign a transaction. Among those members, signing is on a "First Come, First Serve" basis. When one member is signing, all other members are locked out.
Any member who signs does so on behalf of the group, but their name will be stamped on the documents they sign. Anyone verifying a document through the Audit Trail will see the individual member's signature information and identity.
All group members can monitor the progress of the group's transactions, which helps to ensure that those transactions are completed on time.
Finding Your Groups in the UI
First, locate your Groups in the OneSpan Sign Web UI. To do this, log into your OneSpan Sign account and click Admin > Groups. After running your code, all your groups will appear here. If you do not see the Groups option in the toolbar, it could be because they have not been enabled on your account. To enable them, please contact our Support Team.
For more information, see Administering Groups.
Creating Groups
The sample code below will create a group called Java Developers, with two members. It is important to note that these members have to be Senders in your account. The withIndividualMemberEmailing() method will send emails to the members of the group instead of the specified group email. If you wish to send emails to the group email instead, use withoutIndividualEmailing().
Group group1 = GroupBuilder.newGroup( "Java Developers" )
.withEmail( "[email protected]" )
.withIndividualMemberEmailing()
.withMember( GroupMemberBuilder.newGroupMember( "[email protected]" )
.as( GroupMemberType.REGULAR ) )
.withMember( GroupMemberBuilder.newGroupMember( "[email protected]" )
.as( GroupMemberType.REGULAR ) )
.build();
Once you have done this, you can call on your OneSpan Sign GroupService to create your group.
Group createdGroup1 = eslClient.getGroupService().createGroup( group1 );
You can also create an empty group, and invite members to join your group at a later date.
esl.getGroupService().inviteMember( createdEmptyGroup.getId(),
GroupMemberBuilder.newGroupMember( "[email protected]" )
.as( GroupMemberType.REGULAR )
.build() );
Retrieving Groups
Retrieving your groups can come in handy when you wish to invite members to your group. It is important to note that the group id is required when sending invitations. The first line in the sample code below will retrieve your groups as a list. Then, for each group object in the list, the group name, email, and id are retrieved. With your group ids, you can retrieve each member, along with their email, first name, and last name.
List<Group> allGroups = esl.getGroupService().getMyGroups();
for ( Group group : allGroups ) {
System.out.println( group.getName() + " with email " + group.getEmail() + " and id " + group.getId() );
List<GroupMember> allMembers = esl.getGroupService().getGroupMembers( group.getId() );
for ( GroupMember member : allMembers ) {
System.out.println( member.getGroupMemberType().toString() + " " + member.getFirstName() + " " + member.getLastName() + " with email " + member.getEmail());
}
}
Adding a Group Signer
Once your group has been created, you can now then add a group signer to your package. The code below shows you how to edit the signer block in order to add a group signer.
If you need a comparison to a basic document object creation, or if this is the first time creating a package with the Java SDK, see this topic.
DocumentPackage myPackage = newPackageNamed( "My Package with Group Signers Java Developers" )
.withSigner( SignerBuilder.newSignerFromGroup( myGroup.getId() )
.canChangeSigner()
.deliverSignedDocumentsByEmail() )
.withDocument( newDocumentWithName( "My Document" )
.fromFile("DOCUMENT_FILE_PATH" )
.withSignature( signatureFor( myGroup.getId() )
.onPage( 0 )
.atPosition( 370, 680 ) ) )
.build();
PackageId packageId = esl.createAndSendPackage( myPackage );
Results
After executing your code, you will find your newly created groups in your OneSpan Sign account. To see these groups, log into your OneSpan Sign account and click Admin > Groups. You will also find your group signature in your list of recipients.
If you used the sample code in this topic to retrieve your groups, here is the output:
To download the full code sample see our Code Share site.
Sometimes it's convenient to share requests for signatures among the members of a group. For example, it might be convenient to treat the pharmacists in a particular pharmacy as a group, so that any available member of the group can sign the paperwork for a patient's prescriptions.
In OneSpan Sign, a Signer Group is a set of OneSpan Sign users who can act as a single signer from the perspective of a transaction's creator. Users who can become group members must already be members of the associated OneSpan Sign account.
OneSpan Sign group members receive an email invitation to sign a transaction. Among those members, signing is on a "First Come, First Serve" basis. When one member is signing, all other members are locked out.
Any member who signs does so on behalf of the group, but their name will be stamped on the documents they sign. Anyone verifying a document through the Audit Trail will see the individual member's signature information and identity.
All group members can monitor the progress of the group's transactions, which helps to ensure that those transactions are completed on time.
Finding Your Groups in the UI
First, locate your Groups in the OneSpan Sign Web UI. To do this, log into your OneSpan Sign account and click Admin > Groups. After running your code, all your groups will appear here. If you do not see the Groups option in the toolbar, it could be because they have not been enabled on your account. To enable them, please contact our Support Team.
For more information, see Administering Groups.
Creating Groups
The sample code below will create a group called Java Developers, with two members. It is important to note that these members have to be Senders in your account. The withIndividualMemberEmailing() method will send emails to the members of the group instead of the specified group email. If you wish to send emails to the group email instead, use withoutIndividualEmailing().
Group group1 = GroupBuilder.NewGroup("My Group")
.WithCustomId(new GroupId(Guid.NewGuid().ToString()))
.WithMember(GroupMemberBuilder.NewGroupMember("[email protected]")
.AsMemberType(GroupMemberType.MANAGER))
.WithMember(GroupMemberBuilder.NewGroupMember("[email protected]")
.AsMemberType(GroupMemberType.REGULAR))
.WithEmail("[email protected]")
.WithIndividualMemberEmailing()
.Build();
Once you have done this, you can call on your OneSpan Sign GroupService to create your group.
Group createdGroup1 = eslClient.GroupService.CreateGroup(group1);
You can also create an empty group, and invite members to join your group at a later date.
eslClient.GroupService.InviteMember(createdEmptyGroup.Id, GroupMemberBuilder.NewGroupMember("[email protected]")
.AsMemberType(GroupMemberType.REGULAR)
.Build());
Retrieving Groups
Retrieving your groups can come in handy when you wish to invite members to your group. It is important to note that the group id is required when sending invitations. The first line in the sample code below will retrieve your groups as a list. Then, for each group object in the list, the group name, email, and id are retrieved. With your group ids, you can retrieve each member, along with their email, first name, and last name.
List<Group> allGroups = eslClient.GroupService.GetMyGroups();
foreach (Group group in allGroups)
{
Debug.WriteLine(group.Name + " with email " + group.Email + " and id " + group.Id.Id);
List<GroupMember> allMembers = eslClient.GroupService.GetGroupMembers(group.Id);
foreach (GroupMember member in allMembers)
{
Debug.WriteLine(member.GroupMemberType.ToString() + " " + member.FirstName + " " + member.LastName + " with email " + member.Email);
}
}
Adding a Group Signer
Once your group has been created, you can now then add a group signer to your package. The code below shows you how to edit the signer block in order to add a group signer.
DocumentPackage superDuperPackage = PackageBuilder.NewPackageNamed("My Package with Group Signers .NET Developers")
.WithSigner(SignerBuilder.NewSignerFromGroup(myGroup.Id)
.CanChangeSigner()
.DeliverSignedDocumentsByEmail())
.WithDocument(DocumentBuilder.NewDocumentNamed("My Document")
.FromFile("DOCUMENT_FILE_PATH")
.WithSignature(SignatureBuilder.SignatureFor(myGroup.Id)
.OnPage(0)
.AtPosition(370, 680)))
.Build();
PackageId packageId = eslClient.CreateAndSendPackage(superDuperPackage);
Results
After executing your code, you will find your newly created groups in your OneSpan Sign account. To see these groups, log into your OneSpan Sign account and click Admin > Groups. You will also find your group signature in your list of recipients.
If you used the sample code in this topic to retrieve your groups, here is the output:
To download the full code sample see our Code Share site.
Sometimes it's convenient to share requests for signatures among the members of a group. For example, it might be convenient to treat the pharmacists in a particular pharmacy as a group, so that any available member of the group can sign the paperwork for a patient's prescriptions.
In OneSpan Sign, a Signer Group is a set of OneSpan Sign users who can act as a single signer from the perspective of a transaction's creator. Users who can become group members must already be members of the associated OneSpan Sign account.
OneSpan Sign group members receive an email invitation to sign a transaction. Among those members, signing is on a "First Come, First Serve" basis. When one member is signing, all other members are locked out.
Any member who signs does so on behalf of the group, but their name will be stamped on the documents they sign. Anyone verifying a document through the Audit Trail will see the individual member's signature information and identity.
All group members can monitor the progress of the group's transactions, which helps to ensure that those transactions are completed on time.
Finding Your Groups in the UI
First, locate your Groups in the OneSpan Sign Web UI. To do this, log into your OneSpan Sign account and click Admin > Groups. After running your code, all your groups will appear here. If you do not see the Groups option in the toolbar, it could be because they have not been enabled on your account. To enable them, please contact our Support Team.
For more information, see Administering Groups.
Creating Groups
The sample code below will create a group with two members. It is important to note that these members have to be Senders in your account.
HTTP Request
POST /api/groups
HTTP Headers
Accept: application/json Content-Type: application/json Authorization: Basic api_key
Request Payload
{
"email": "[email protected]",
"name": "your_group_name",
"members": [
{
"pending": true,
"email": "[email protected]",
"memberType": "REGULAR",
"firstName": "Max",
"lastName": "Domi"
},
{
"pending": true,
"email": "[email protected]",
"memberType": "REGULAR",
"firstName": "John",
"lastName": "Smith"
}
]
}
Response Payload
{
"id": "bc65203e-99df-47b4-a51c-33e8082780c5",
"members": [
{
"userId": "2q37oSloj5AD",
"pending": false,
"lastName": "Tango",
"email": "[email protected]",
"firstName": "Mike",
"memberType": "REGULAR"
},
{
"userId": "FxktNzFzmkIY",
"pending": false,
"lastName": "Domi",
"email": "[email protected]",
"firstName": "Max",
"memberType": "REGULAR"
}
],
"emailMembers": false,
"reciprocalDelegation": false,
"data": null,
"account": {
"id": "3vD0Dc9Fh7wQ",
"data": null,
"updated": "2017-11-20T19:03:28Z",
"company": {
"id": "",
"data": null,
"address": null,
"name": ""
},
"licenses": [],
"logoUrl": "",
"providers": null,
"customFields": [],
"created": "2017-11-20T19:03:28Z",
"owner": "",
"name": ""
},
"updated": "2017-11-20T19:03:28Z",
"email": "[email protected]",
"created": "2017-11-20T19:03:28Z",
"name": "your_group_name"
}
You can also create an empty group, and invite members to join your group at a later date.
HTTP Request
POST /api/groups
HTTP Headers
Accept: application/json Content-Type: application/json Authorization: Basic api_key
Request Payload
{
"email": "[email protected]",
"name": "REST Developers"
}
Response Payload
{
"id": "540b86f9-2d93-4498-bdb4-b7b320540bb6",
"members": [],
"emailMembers": false,
"reciprocalDelegation": false,
"data": null,
"account": {
"id": "3vD0Dc9Fh7wQ",
"data": null,
"updated": "2017-11-20T19:04:38Z",
"company": {
"id": "",
"data": null,
"address": null,
"name": ""
},
"licenses": [],
"logoUrl": "",
"providers": null,
"customFields": [],
"created": "2017-11-20T19:04:38Z",
"owner": "",
"name": ""
},
"updated": "2017-11-20T19:04:38Z",
"email": "[email protected]",
"created": "2017-11-20T19:04:38Z",
"name": "REST Developers"
}
Retrieving Groups
Retrieving your groups can come in handy when you wish to invite members to your group. It is important to note that the group id is required when sending invitations.
HTTP Request
GET /api/groups
HTTP Headers
Accept: application/json Content-Type: application/json Authorization: Basic api_key
Response Payload
{
"count": 1,
"results": [
{
"account": {
"providers": null,
"updated": "2016-01-07T18:49:19Z",
"company": {
"id": "",
"address": null,
"data": null,
"name": ""
},
"licenses": [],
"logoUrl": "",
"customFields": [],
"created": "2016-01-07T18:49:19Z",
"owner": "",
"id": "zRcJCHV3ztIB",
"data": null,
"name": ""
},
"updated": "2016-01-07T13:58:33Z",
"email": "[email protected]",
"members": [
{
"userId": "1XyqlkXM9uIX",
"email": "[email protected]",
"firstName": "John",
"lastName": "Doe",
"memberType": "REGULAR",
"pending": false
},
{
"userId": "kVooKpofKuUK",
"email": "[email protected]",
"firstName": "Mary",
"lastName": "Doe",
"memberType": "REGULAR",
"pending": false
}
],
"emailMembers": false,
"reciprocalDelegation": false,
"created": "2016-01-07T13:58:33Z",
"id": "4a8868d7-1968-4172-aedb-0a9dc8edb683",
"data": null,
"name": "REST Developers"
}
]
}
Adding a Group signer
Once your group has been created, you can now then add a group signer to your package. The code below shows you how to edit the signer block in order to add a group signer.
If you need a comparison to the basic document object creation or if this is the first time creating a package with the REST API, see this guide.
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"
{
"roles": [
{
"id": "1945f2e1-3390-4297-bc3b-89af3c92e567",
"type": "SIGNER",
"index": 0,
"signers": [
{
"group": {
"id": "540b86f9-2d93-4498-bdb4-b7b320540bb6",
"email": "[email protected]",
"name": "REST Developers"
},
"id": "98b9db64-39ca-4b5b-a1eb-629e49c46dec",
"email": "[email protected]",
"firstName": "REST Developers",
"lastName": ""
}
],
"name": "Signer1"
}
],
"status": "DRAFT",
"language": "en",
"documents": [
{
"id": "90277a614bf73b783fe2a5e04b68a99d4badf449b33ecfbf",
"approvals": [
{
"id": "cVvJzBDX7lwP",
"role": "1945f2e1-3390-4297-bc3b-89af3c92e567",
"fields": [
{
"subtype": "FULLNAME",
"height": 52,
"extract": false,
"width": 235,
"left": 217,
"top": 512,
"type": "SIGNATURE"
}
]
}
],
"name": "sample_contract"
}
],
"visibility": "ACCOUNT",
"type": "PACKAGE",
"name": "Group Signature Example"
}
------WebKitFormBoundary1bNO60n7FqP5WO4t--
Response Payload
{
"id": "9sKhW-h-qS9m6Ho3zRv3n2a-rkI="
}
Results
After executing your code, you will find your newly created groups in your OneSpan Sign account. To see these groups, log into your OneSpan Sign account and click Admin > Groups. You will also find your group signature in your list of recipients.
Request Payload Table
| Property | Type | Editable | Required | Default | Sample Values |
|---|---|---|---|---|---|
| string | Yes | No | n/a | [email protected] | |
| name | string | Yes | No | n/a | your_group_name |
| members | |||||
| pending | boolean | No | No | n/a | true / false |
| string | Yes | No | n/a | [email protected] | |
| memberType | string | Yes | No | REGULAR | REGULAR / MANAGER |
| firstName | string | Yes | No | n/a | Max |
| lastName | string | Yes | No | n/a | Domi |