Groups

This guide will cover how to create/manage groups and add a group signature on your document.

A group is a collection of signers that can act as a single signer from the package (transaction in the new UI) creator’s perspective.

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 your name in the toolbar and select Admin. From the menu on the left-hand side, select “Groups”. After running your code, you will find all of your groups in here, as shown in the “Running Your Code” section below. 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 sign.support@onespan.com.

The Code

This segment of the guide only shows snippets of code. You can download the full sample code from the Developer Community Code Share, here.

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, you would use withoutIndividualEmailing().

Group group1 = GroupBuilder.newGroup( "Java Developers" )
            .withEmail( "mygroup@aol.com" )
            .withIndividualMemberEmailing()
            .withMember( GroupMemberBuilder.newGroupMember( "manager@mycompany.com" )
                .as( GroupMemberType.REGULAR ) )
            .withMember( GroupMemberBuilder.newGroupMember( "group-member@mycompany.com" )
                    .as( GroupMemberType.REGULAR ) )
                .build();

Then, you call on your OneSpan Sign GroupService to create your group.

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( "member1@example.com" )
                .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. 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());
     }
}

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. If you need a comparison to the basic document object creation or if this is the first time creating a package with the Java SDK, see this guide.

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 );

Running Your Code

After executing your code, you will find your newly created groups in your OneSpan Sign account as described at the beginning in the “Groups in the UI” section.

Capture

Included in this guide was the code that grabbed the email and id, and listed each member in the console, when retrieving your groups.

list

Furthermore, you will find your group signature in your document as shown below.

Capture

Get the Code

A group is a collection of signers that can act as a single signer from the package (transaction in the new UI) creator’s perspective.

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 your name in the toolbar and select Admin. From the menu on the left-hand side, select “Groups”. After running your code, you will find all of your groups in here, as shown in the “Running Your Code” section below. 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 sign.support@onespan.com.

The Code

This segment of the guide only shows snippets of code. You can download the full sample code from the Developer Community Code Share, here.

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, you would use withoutIndividualEmailing().

Group group1 = GroupBuilder.NewGroup("My Group")
               .WithCustomId(new GroupId(Guid.NewGuid().ToString()))
               .WithMember(GroupMemberBuilder.NewGroupMember("robert.paulson@email.com")
                    .AsMemberType(GroupMemberType.MANAGER))
               .WithMember(GroupMemberBuilder.NewGroupMember("tyler.durden@email.com")
                    .AsMemberType(GroupMemberType.REGULAR))
               .WithEmail("bob@aol.com")
               .WithIndividualMemberEmailing()
               .Build();

Then, you call on your OneSpan Sign GroupService to create your group.

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("bob@aol.com")
            .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. 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);
            }
        }

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. If you need a comparison to the basic document object creation or if this is the first time creating a package with the .NET SDK, see this guide.

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);

Running Your Code

After executing your code, you will find your newly created groups in your OneSpan Sign account as described at the beginning in the “Groups in the UI” section.

Capture

Included in this guide was the code that grabbed the email and id, and listed each member in the console, when retrieving your groups.

list

Furthermore, you will find your group signature in your document as shown below.

Capture

Get the Code

A group is a collection of signers that can act as a single signer from the package (transaction in the new UI) creator’s perspective.

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 your name in the toolbar and select Admin. From the menu on the left-hand side, select “Groups”. After running your code, you will find all of your groups in here, as shown in the “Running Your Code” section below. 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 sign.support@onespan.com.

The Code

This segment of the guide only shows sample requests. You can download the full sample code from the Developer Community Code Share, here.

The request 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.

HTTP Request
POST /api/groups

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

Request Payload

{
  "email": "your_group_email@example.com",
  "name": "your_group_name",
        "members": [
    {
      "pending": true,
      "email": "mail55@mailinator.com",
      "memberType": "REGULAR",
      "firstName": "Max",
      "lastName": "Domi"
    },
    {
      "pending": true,
      "email": "mail72@mailinator.com",
      "memberType": "REGULAR",
      "firstName": "John",
      "lastName": "Smith"
    }
  ]
}

Response Payload

{
    "id": "bc65203e-99df-47b4-a51c-33e8082780c5",
    "members": [
        {
            "userId": "2q37oSloj5AD",
            "pending": false,
            "lastName": "Tango",
            "email": "mail72@mailinator.com",
            "firstName": "Mike",
            "memberType": "REGULAR"
        },
        {
            "userId": "FxktNzFzmkIY",
            "pending": false,
            "lastName": "Domi",
            "email": "mail55@mailinator.com",
            "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": "your_group_email@example.com",
    "created": "2017-11-20T19:03:28Z",
    "name": "your_group_name"
}

On the other hand, you can create an empty group and subsequently invite members to join your group.

HTTP Request
POST /api/groups

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

Request Payload

{
    "email": "invitee@email.com",
    "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": "invitee@email.com",
    "created": "2017-11-20T19:04:38Z",
    "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.

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": "group@email.com",
      "members": [
        {
          "userId": "1XyqlkXM9uIX",
          "email": "member.1@email.com",
          "firstName": "John",
          "lastName": "Doe",
          "memberType": "REGULAR",
          "pending": false
        },
        {
          "userId": "kVooKpofKuUK",
          "email": "member.2@email.com",
          "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 request 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": "invitee@email.com",
            "name": "REST Developers"
          },
          "id": "98b9db64-39ca-4b5b-a1eb-629e49c46dec",
          "email": "540b86f9-2d93-4498-bdb4-b7b320540bb6@groups.e-signlive.com",
          "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="
}

Running Your Code

After executing your code, you will find your newly created groups in your OneSpan Sign account as described at the beginning in the “Groups in the UI” section.

Capture

Furthermore, you will find your group signature in your document as shown below.

Capture

Get the Code

JSON Properties

Property Type Editable Required Default Sample Value(s)
email string Yes No n/a your_group_email@example.com
name string Yes No n/a your_group_name
members
pending boolean No No n/a true / false
email string Yes No n/a mail55@mailinator.com
memberType string Yes No REGULAR REGULAR / MANAGER
firstName string Yes No n/a Max
lastName string Yes No n/a Domi