PDF with multiple Signature Capture Fields - some of which are optional

Okay. Let me explain a little bit more on the first option. I'm not sure I'm fully understanding why there would be an issue. If my explanation here doesn't make sense, I'll have you email me directly and we can set up a call. So, for your package, throughout the various documents you have in the package, you will always have 4 signers set up using the eSignLive naming convention. Because of this, uploading with only 1, 2, or 3 signers will always fail as you don't have a 4th signer defined in your JSON. To get around this, you would simply need to add dummy signers to the package on top of the signer(s) that will actually be there. For example, you have a package with all of the documents you talked about above, but you only have two applicants and no guarantors. In this scenario, your system knows of the two signers and creates the signers in the JSON payload. If you send it this way, it will fail. If you always add a 3rd and 4th signer with the roleID of the guarantor spots, the documents will upload without issue. NOW, this cannot be sent this way or you'll have signature blocks for these dummy signers you added, so you need to make sure the package is created with status of DRAFT. Once the package is created, you'll receive a JSON response with a package ID in it. From here, you simply must run DELETE http calls for the dummy signers that you know are extras as your system knows there are only two signers for this package. Once you delete the dummy roles, none of their associated fields will remain in the documents. You are now safe to send this package and it will only have the fields for the two signers originally defined by your system. I hope this makes more sense. I can always set up a simple example to show you this, if you'd like. As for the other option, I can set up an example for this, as well. You can definitely define your own custom field names in your JSON, you just have to include definitions for each field vs just extracting automatically with eSignLive nomenclature. And yes, unfortunately, we don't have the optional signer functionality, at this time. Hopefully it's in there, early 2017, but there is no defined date, as of yet. Anyways, let me know on the above. If we're still not on the same page, we'll set up a call. :)

Unfortunately, optional signatures are not possible at this time. That is on the roadmap for 2016 sometime, I believe. I will have to double check on that though. One thing you could do would be to have two forms created. One for a single applicant and the other for two applicants. Then, just use the different document to create the transaction for each case. Another would be to provide a dummy second signer for extraction purposes, for when a second signer wasn't defined by the user or pulled from your database. Then, you'd simply need to remove the second signer from the package after the document has successfully uploaded and the package created but before you SEND the package or create a signing session. This option would get rid of the mess of creating multiple versions of each form, but would require a little workaround in the code. This is a popular request for a feature, so you could also post in the Enhancement Ideas forum as well. Our product management team monitors this forum for ideas from customers.

I'd like to explore the following suggestion as maintaining 2 or more versions of a form is not feasible ( some forms may have up to 4 signatures ..)

Another would be to provide a dummy second signer for extraction purposes, for when a second signer wasn’t defined by the user or pulled from your database. Then, you’d simply need to remove the second signer from the package after the document has successfully uploaded and the package created but before you SEND the package or create a signing session. 

What do you mean "simply need to remove the second signer from the package" - are you talking about the JSON ? RIght now the workflow Im using is The Create and Send Package ( as per the sample blog you wrote for REST API) - 1. This is where I have my JSON constructed at runtime with the no of Applicants (described in roles\signers in the JSON), and the PDF with the predefined no of Signature fields ( right now I'm using a sample PDF with 2 predefined signatures - using a convention [SignerId#].[Capture#] so that my JSON will have the proper naming convention to define the number of actual Signers in the PDF. 2. The JSON is uploaded with the PDF to /packages/ 3. At this point an instantaneous email is sent to the Signers So WHERE does this "removal of those dummy signers" takes place and HOW is this achieved? Can you provide me with a sample or point me to the proper section or documentation? Thanks

Yeah. I haven't done it yet, so I'll have to create an example really quick. You would have to change the original JSON payload to be DRAFT instead of SENT so it wouldn't send with the dummy info. I create a quick example and post it in the code share and point you to it. :) Stay tuned!

Okay. All you have to do is create the package as you are, only passing dummy info for the second signer. Use a status of DRAFT instead of SENT, as I said above, then, you'd send a delete request to:

https://sandbox.esignlive.com/api/packages/{packageId}/roles/{roleId}

This will remove all fields for the second signer from the document as well, so nothing needs to be done, there. From there, you simply need to send the package, which should be done by sending a PUT request to:

https://sandbox.esignlive.com/api/packages/{packageId}

with a JSON payload of:

{
    "status": "SENT"
}

I didn't create a full example since it is pretty much only 2 lines. If you need more detail, let me know and I can put an example in the code share in whatever language you're using REST in. Let me know. :)

Oh, and I almost forgot. I checked into the optional signature feature being added. Currently, it is slated for 2017 sometime, but is not yet tied to a release, so things are still fluid.

Hi Michael, I think I may have another problem based on the suggested solution. This means I will need to keep track of the number of Signature Controls on each PDF .. so that my initial JSON will contain the number of Roles matching the Number of Signature Fields in the PDF, right? Then at runtime, for a given loan with 1 applicant, determine those which are filled with dummy data, to delete them, right? In this case in some PDF i may have 1 dummy ( 2signatures), 2 dummy ( 3 signatures) or 3 dummy roles ( 4 signatures ), right? I think this alone will be a show stopper for us and maintaining additional forms or fields per PDF will not be acceptable. I'll have to circle it back to my team to see where we take it from here. With regards to the DRAFT vs SENT in the status... can you point me to the documentation on what they are and why would someone use DRAFTS, vs SENT ? What I mean was that, when I did the test with DRAFT, does the applicants in the roles receive an email or is it ONLY submitted when I instruct it as "SENT" - ? I think Harry mentioned in a sample JSON to send it as DRAFT but I never understood this part - WOuld you have some documentation to explain why it is there and under what circumstances I would use one over the other?

DRAFT is an unsent stage. No notifications are made until you update it to SENT. As for keeping track of the signers, when you go to remove any extra signers, you could simply add a few lines of code to do a GET request to get all signers on the package and check the email addresses to see where dummy addresses are. Then, loop through and delete them. I can help with this, if needed. For JSON payloads to set up the package in the first place, you'd always need to know how many signers there will be for setting up the signers in your JSON payload. How are you currently doing this? Or is this not part of the problem? Let me know. I'll also investigate what others may have done to get around the optional signature issue and post back.

Forgot to include this earlier. Here is the documentation page that shows how to update a package. You would only need to update the status: http://docs.e-signlive.com/doku.php?id=esl:api:e-signlive_packages#put_packages_packageid As for other options, one I had thought of before but didn't suggest because of the messy JSON you could encounter (and redoing your forms), is to not use the eSL naming conventions on your fields (use custom names) and only extract the necessary fields for the number of signers. Again, this creates a more complex JSON payload as you must now define all fields in your JSON. Another suggestion was for a feature that is coming soon which is a new text extraction feature that would allow for optional fields. This is just text in the document and not acrofields though. As we've talked about already, an enhancement request has already been put in for this feature and it is slated for next year. If anything changes, I will update this thread.

With regards to Keeping track of the signers, may be I'm looking at it differently and do not see the whole picture from your prespective ( the RESTAPI). So let me give you a summary of the problem I see. 1. We have a lot of legal forms from various Centrals , Province, Federal. 2. All of those forms are designed to have either one Applicant to Multiple Applicants ( Up to 4). What this means is that they will have predefined section for one applicant or multiple sections each reserved for each of the applicant on the loan. ( Example Primary Applicant, Co-Applicant, Guarantor 1, Guarantor 2). For each of the above mentioned applicant, we have a corresponding Signature Field at the end of the form. 3. On a typical loan, when we print, we assemble all the FORMS required (the form set) which consists of a mix of a Per Applicant Form ( example a Member's Financial Statement) to a Combined Form where all Applicants on the Loan will appear under their corresponding sections. As an example, For a loan with a Primary Applicant and Co-Applicant, Imagine our Form Set consist of : 1. Member Financial Statement for Applicant A with 1 Signature Field (Merged data on this PDF will contain Member's A Information) 2. Member Financial Statement for Applicant B with 1 Signature Field (Merged data on this PDF will contain Member's B Information) 3. Combined Loan Application . This form includes all the details of the Loan Application, so will include the Applicants and Guarantors. In this case we will have 2 out of the 4 pre defined sections on this PDF prefilled. Normally, our software will merge all data related to the PDF Templates we have ( Those templates are PDF with TextFields, Checkboxes...etc defined in ADOBE - The text Fields are mostly fields which we use for extracting and merging data - we will be adding NEW Signature Text Fields according to your format SignerId#.Cature#). All forms will be merged and combined into 1 PDF of multiple pages. Some of the fields, like the Signature Fields will therefore remain unmapped until we CreateAndSendPackage to the REST API. In other words, we combine all the PDF into 1 PDF and this is when we are ready to send it over for Signature Package Creation and eventually the Signing Ceremonu. So my challenge is that because we will have to define the Signature Fields according to your nomenclature, we will therefore create those new Signature TextFields in all the PDF where the Signature is required.: 1. All Signature Fields will have a prefix "SignerId"#.Capture# - So if there are 2 Signatures on the forms for 2 different applicants, we will keep the prefix "SignerId" and just change the # for each of the applicants. 2. When we create the JSON payload, our system will know exactly how many signer roles to create in the payload. However, each PDF may have different number of (predefined) Signature Capture TextFields. In my case for the Combined Loan Application, the PDF will have SIgnerId1.Capture1, SignerId2.Capture2,SignerId3.Capture3, SignerId4.Capture4; where only SignerId1.Capture1 and SignerId2.Capture2 will be defined in the JSON Payload ( as they are the only 2 applicants on the loan with NO GUARANTORS). Based on your recommendation, our logic will need to prepare a payload with 4 signer roles because the PDF has 4 Signature Fields, right? So this is where it implies I will need to keep track for each PDF i'm about to print how many SIgnature Fields there are so that I fill it with dummy data in the payload. If I can compare it with the competition ADOBE ECHOSIGN, They handle this in a similar fashion for Document Extraction. However, if the signers are not sent in the payload, the Signature Field is Ignored at runtime during the signing Ceremony. As such, I can have 4 pre defined signature fields according to the SIgnature Nomenclature but yet only send 1 Signer Role. Hope this helps defining my constraint and requirement . Let me know if this makes sense ... I'm hoping i'm wrong about this validation on the SIgners in JSON vs SIgners predefined in the PDF approach - or if there is another approach to this?

As for other options, one I had thought of before but didn’t suggest because of the messy JSON you could encounter (and redoing your forms), is to not use the eSL naming conventions on your fields (use custom names) and only extract the necessary fields for the number of signers. Again, this creates a more complex JSON payload as you must now define all fields in your JSON.

Hi Michael, I'm interested in this bolded piece where you suggest "I can only extract the necessary fields for the number of signers "? LIke I mentioned, I came from the ADOBE ECHOSIGN for extacting Document Signatures using special tags in the PDF - so I thought the ESL naming conventions are the only way to go about defining the SIgnature Fields... From the sound of your suggestion, I do not need the ESL Text Fields but rather I can define it in the JSON, did I understand correctly? Can you extrapolate on this? I'm not afraid of the JSON strings as Im using the Serializer/Deserializer classes based on a sample JSON which worked just my tests. In other words, as long as I know how to structure the JSON ( the schema) , I can create a class out of the sample and always ensure I send the same format with the proper information... Let me know ... I just want to make sure I try all available methods before i report it back. Thanks

Ok I was able to overcome the problem where I thought I had to save the number of Signature Controls on EACH of the PDF as some kind of meta data. I've used the principle that I can send a DRAFT with a max no of signers = 6 ( This is the maximum of Signature Controls which we can have in some PDF ). So by populating the Roles with actual signers , then filling up with DUMMY data, then Deleting the DUMMY roles in a subsequent CALL.

Fantastic! Glad it's working! Let us know whenever you have questions. :)

Hi Michael You mentioned last year about the possibility of having Optional Signature Fields so that the application does not report an error when the JSON payload does not match the Capture Fields in the PDF being uploaded to create a package. In the PDF package which our Application generates can have a variable number of Signature Fields ( each of which are based on the type of application being printed ). Our templated PDF are all edited to contain the Document Extract Tags eg [SignerId#.Capture#] at pre determined spots on the legal forms. Some of the forms may have 1 to 6 signature fields. So we are creating those tags for each of those signature fields with the Document Extract Tags. Since not all Signatures may be applicable ( example if only 1 applicant , 1 out of the 6 fields on a typical form will be requested to be signed SIgnerId1.Capture1 ... The other fields SIgnerId2 to 6 although are on the PDF will not be assigned to anyone as there is only one applicable signer. Until now, I'm using the DUMMY ROLES filled with DUMMY DATA , as you suggested to work around ... So my JSON payload on the initial upload with the pdf will contain 6 roles where only the 1st one is the actual role required to be signed. Then Issue a delete signers (2 to 6) . Can you please let me know if this feature is available? Can you point me to the relevant info / url I need to achieve this?

Helpful thread. Has the optional signer functionality been added in any release yet? If so, which release, thank you. Todd

Unfortunately, optional signatures is still not on the roadmap (unplanned backlog). Each quarter, our Product Managers review the backlog for potential enhancement requests to be put on the roadmap. I will let you know once optional signatures are on the roadmap. Haris Haidary, Technical Evangelist eSignLiveâ„¢ by VASCO – When e-signatures matter to your business Tel: 514-337-5255 ext 1806 E: [email protected]

The work around, until this feature is implemented, is to create dummy roles, signature definition in the JSON on Creating the package with DRAFT and then deleting them in a separate call.

Thank you.

Its a great article and real time need every business goes through. Was any enhancement made around this option fields? Any documentation around Text extraction fields? For our case, I can't define the Role id in Roles object related to specific field id or so, is it possible to put some hidden text on PDF wherever we needed and then link that text to Signer name/Initials/click to sign type when creating the package? Similar to this example, we also have a requirement, where the number of Signers does change for each transaction, but on document we have fields defined to accommodate maximum possible signers. I know the possible signers for a given transaction and all the pre-defined fields(which will have hidden text), is their any way, I can define to link the fields to signer at run time, so that I dont have to do any clean up or so in post creation process before updating package status to SENT?