Sending Docusign Envelopes with Existing Templates and Prefilled Values in Ruby on Rails

Question

I'm currently working on a Ruby on Rails application integrated with Docusign using code grant authentication. My goal is to send Docusign envelopes without attaching any documents from my Rails app. Instead, I aim to utilize existing templates on Docusign that already contain documents. Additionally, I want to prefill the values of these templates and send them to users for signature. Finally, once the user signs the document, I need to retrieve the signed document back to my Rails app in PDF form.

Here's a breakdown of what I've achieved so far and where I'm facing challenges:

1. Current Progress:

   • Successfully integrated Docusign with my Rails app using code grant authentication.

   • Able to create envelopes and send them using existing templates.

   • Receive unsigned PDF responses.

2. Challenges Encountered:

   • Unable to send envelopes without attaching documents. If I try to send an envelope without a document, I receive a "document missing" error, leading to a failed request.

   • Unsure about how to prefill values in the existing templates before sending them to users for signature.

   • Need guidance on how to retrieve the signed document back to my Rails app in PDF form.

Here is my current code

 def send_data_using_template(access_token)
    template_id = "8f33b649-****-4aa2-804a-01f2*****5e3"
    recipient_name = "ali676750"
    recipient_email = "abc@gmail.com"
    document_file_path = "config/Software licensing agreement.pdf"

    fields_to_prefill = {
      "name" => "ahmad",
      "title" => "software engineer"
    }
  
    signer1 = DocuSign_eSign::Signer.new(
      email: recipient_email,
      name: recipient_name,
      recipientId: '11',
      routing_order: '11'
    )
  
    document_base64 = Base64.strict_encode64(File.read(document_file_path))
    document = {
      documentBase64: document_base64,
      name: File.basename(document_file_path),
      fileExtension: File.extname(document_file_path).delete('.'),
      documentId: '1'
    }

    tabs = DocuSign_eSign::Tabs.new

    recipients = DocuSign_eSign::Recipients.new(
      signers: [signer1],
    )
    
    envelope_definition = DocuSign_eSign::EnvelopeDefinition.new(
        emailSubject: "Your subject line here",
      status: "sent",
      template_id: template_id,
      documents: [document],
      tabs: tabs
    )


    envelope_definition.recipients = recipients

    response = HTTParty.post("https://demo.docusign.net/restapi/v2.1/accounts/#{ENV['DOCUSIGN_ACCOUNT_ID']}/envelopes", 
                              headers: { "Authorization" => "Bearer #{access_token}", "Content-Type" => "application/json" },
                              body: envelope_definition.to_json)

    if response.code == 201
      puts "Envelope created successfully "
      envelope_id = response.parsed_response["envelopeId"]

      response = HTTParty.get(
        "https://demo.docusign.net/restapi/v2.1/accounts/#{ENV['DOCUSIGN_ACCOUNT_ID']}/envelopes/#{envelope_id}/documents/combined",
        headers: { "Authorization" => "Bearer #{access_token}" }
      )
      
      decoded_content = Base64.decode64(response.body)

      file_path = "config/signed_document.pdf"

      File.open(file_path, "wb") { |file| file.write(decoded_content) }

      puts "PDF file saved successfully at #{file_path}"
    else
      puts "Error creating envelope: #{response.body}"
    end
  end

Here's what I'm seeking assistance with:

1. Sending Envelopes without Attaching Documents: Is there a way to send envelopes using existing templates that already contain documents without attaching additional documents from my Rails app?

2. Prefilling Values in Templates: How can I prefill values in the existing templates before sending them for signature?

3. Retrieving Signed Documents: What is the process for retrieving the signed document back to my Rails app in PDF form after the user has signed it?

I would greatly appreciate any insights, suggestions, or code snippets that could help me overcome these challenges. Thank you in advance for your assistance!

Answer 1

1+2 is done in a similar fashion to the code you wrote. You can find fully ready to use code example - https://github.com/docusign/code-examples-ruby/blob/master/app/services/e_sign/eg017_set_template_tab_values_service.rb which shows how to use a template and not add documents and set tab values.

Couple of notes:

1. Your code shows attaching documents. If you use a template that has document(s) in it, and you make sure to put correct template_id in your envelope_definition there's no need to add documents, they will come from template.
2. In order to ensure you can set tab values you need to either add the tabs in your code like the example I linked, or you have to first find the ID of the tabs that was created in the the envelope from the template and then make another API call to update their value. The first method is a single API call and you can send the envelope in that call. The second method requires 4 API calls and you can only send the envelope at the final call. So, if you add the tabs yourself - it will save you a bunch of work.
3. Recipients can either be using template_roles or they can be set like you did. Note that if you do it the way you did, you cannot have the recipients on the template and you cannot have tabs on the template. However, creating a template like this can only be done via API. If you created your template via the UI, you will have to have at least one recipient, and if you want that recipients to have tabs that are added by your API call you have to use template_roles and add them to that specific object.

As for your final question, the most recommended method to do this is using a Web hook called Connect where messages will be sent to you by Docusign to let you know the envelope is ready. That's the main trickiness here - the timing. As it is a bad practice to poll consistently to know when the envelope was complete. If you know it's complete then downloading the PDF is simple, see Ruby code for doing this here - https://github.com/docusign/code-examples-ruby/blob/master/app/services/e_sign/eg007_envelope_get_doc_service.rb