OneSpan Sign How To: Creating Groups
A group is a collection of signers that can act as a single signer from the package creator's perspective. This can be useful if you require any member within a group of your organization to sign a document (i.e. someone from HR). You can achieve this in OneSpan Sign by creating a group, and assign the signature to the group. In this blog, I will show you how to create, manage, and use groups with the OneSpan Sign Java SDK, .NET SDK, and REST API.
Groups in the UI
The first thing you want to do is locate groups in the UI. After logging into your OneSpan Sign account, click on GROUPS in the toolbar. After running your code, you will find all of your groups in here, as shown in the "Running Your Code" section below . You can always create groups directly from the UI if that's what you wish. You do not need to go any further into this blog. If you do not see the GROUPS option in the toolbar, they are likely not enabled on your account. Please contact our support team at [email protected]. [promotion id="14704"]
The Code
You can go ahead and skip to the section which applies to your technology. I will cover the same information in each segment. Full example code for this blog can be found in the Developer Community Code Share: Java, .NET, and REST. JAVA SDK Let’s start with the Java SDK. The sample code below creates a group object 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, you would use withoutIndividualEmailing(). Then, you call on your OneSpan Sign GroupService to create your group.
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(); Group createdGroup1 = eslClient.getGroupService().createGroup( group1 );
On the other hand, you can create an empty group and subsequently invite members to join your group.
esl.getGroupService().inviteMember( createdEmptyGroup.getId(), GroupMemberBuilder.newGroupMember( "[email protected]" ) .as( GroupMemberType.REGULAR ) .build() );
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. You call on your OneSpan Sign GroupService to retrieve your groups, which are returned to you as a list. In my example, I retrieved the group name, group email, and group id for each group. Finally, 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());
}
}
When you have your group created, you can now 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 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 );
.NET SDK Next, I will go over the .NET SDK. The sample code below creates a group object called ".NET 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, you would use WithoutIndividualEmailing(). Then, you call on your OneSpan Sign GroupService to create your group.
Group group1 = GroupBuilder.NewGroup(".NET Developers")
.WithMember(GroupMemberBuilder.NewGroupMember("[email protected]")
.AsMemberType(GroupMemberType.REGULAR))
.WithMember(GroupMemberBuilder.NewGroupMember("[email protected]")
.AsMemberType(GroupMemberType.REGULAR))
.WithEmail("[email protected]")
.WithIndividualMemberEmailing()
.Build();
Group createdGroup1 = eslClient.GroupService.CreateGroup(group1);
On the other hand, you can create an empty group and subsequently invite members to join your group.
eslClient.GroupService.InviteMember(createdEmptyGroup.Id, GroupMemberBuilder.NewGroupMember("[email protected]")
.AsMemberType(GroupMemberType.REGULAR)
.Build());
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. You call on your OneSpan Sign GroupService to retrieve your groups, which are returned to you as a list. In my example, I retrieved the group name, group email, and group id for each group. Finally, 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);
}
}
When you have your group created, you can now 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);
REST API Finally, I will cover the REST API. The JSON string below will create your group with two members in a single request. It is important to note that in this case, the members have to be senders in your account. [code language="javascript"]{ "email": "your_group_email", "name": "your_group_name", "members": [ { "pending": true, "email": "[email protected]", "memberType": "REGULAR", "firstName": "John", "lastName": "Doe" }, { "pending": true, "email": "[email protected]", "memberType": "REGULAR", "firstName": "Mary", "lastName": "Doe" } ] } On the other hand, you can create an empty group and subsequently invite members to join your group. [code language="javascript"]{ "email": "[email protected]", "name": "REST Developers" } 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. In this case, you only need to make a GET request to https://sandbox.onespan.com/api/groups. You can also retrieve an individual group by making a request to https://sandbox.onespan.com/api/groups/{groupId}. In this case, you will need the group id. Below is a sample response you might see when making this request to retrieve your groups: [code language="javascript"]{ "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" } ] } When you have your group created, you can now add a group signer to your package. The code below shows you how to do so.
string apiUrl = "https://sandbox.onespan.com/api/packages";
string jsonString = "{ \"role\" : \"cc5d5296-ae92-48ec-a0ee-2a327d8a66b9\", \"fields\":[ { \"top\":680, \"left\":370, \"width\":200, \"height\":50, \"page\":0, \"type\":\"SIGNATURE\", \"value\":null, \"subtype\":\"FULLNAME\" }] }";
StringContent jsonContent = new StringContent(jsonString, Encoding.UTF8, "application/json");
HttpClient myClient = new HttpClient();
myClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", apiKey);
myClient.DefaultRequestHeaders.Add("Accept", "application/json");
var response = myClient.PostAsync(new Uri(apiUrl + "/{packageId}/documents/{documentId}/approvals"), jsonContent).Result;
Debug.WriteLine(response.Content.ReadAsStringAsync().Result);
Running Your Code
You can now run your code. Once you have done this, you will find your newly created groups in your OneSpan Sign account as described at the beginning in the "Groups in the UI" section. When retrieving your groups with the SDKs as shown above, I included the code that grabbed the group email and id, and listed each member in the console. If you went through the REST API section, I've already shown a sample response from the GET request already. Furthermore, you will find your group signature in your document as shown below. There you go. You have successfully created groups with OneSpan Sign. 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
