Ruby Migration Guide

View as Markdown

Migrating the Ruby SDK from hellosign-ruby-sdk to dropbox-sign

Welcome! Dropbox Sign's new Ruby SDK is generated from our officially maintained OpenAPI spec. In this release, we've made important updates that introduce new functionality and create feature parity between the Dropbox Sign API and the Ruby SDK. However, some of these changes are considered "breaking" in the sense that they'll require you to update your existing code in order to continue using the SDK.

In this migration guide, we'll cover core concepts in the new SDK, highlight differences from legacy versions, and provide example code showing how past implementations map to the new version's syntax. We'll link out to supporting documents that offer more context behind the breaking changes and why we made them. We apologize for any inconvenience these changes may cause, but are confident the new features will add value to your integration.

Remember that we are here to help if you have any questions or need assistance along the way. Thank you for using Dropbox Sign's Ruby SDK. We hope you enjoy the improvements!

Architecture and Tooling

As mentioned above, the new Ruby SDK (dropbox-sign) is generated from our OpenAPI Spec. Some of the architectural changes impact the tools and locations you use to interact with the SDK.

SDK Resources

  • Download -- using this new rubygems repo. New Ruby SDK versions will now be published here.
  • Development -- active development against the Ruby SDK happens here: hellosign-openapi/sdks/ruby.
  • SDK GitHub Repo -- dropbox-sign-ruby is updated based on changes to hellosign-openapi/sdks/ruby, but no active development work happens there.
  • Reference Docs -- the automatically generated Reference Docs are a great way to explore the SDK.
  • Examples -- our full suite of ready to use examples will help you get started quickly.
  • Engagement -- use the OpenAPI repo to submit Issues or Pull Requests for the Ruby SDK.

Core Concepts and Patterns

This section contains the core concepts and patterns of the new SDK and highlights differences from the legacy SDK.

Installation

First time installation

  1. Install the dropbox-sign gem:

    $gem install dropbox-sign
  2. Add the following to your Gemfile:

    1gem 'dropbox-sign', '~> 1.0.0'

Updating gem version

  1. Modify the version on your Gemfile to point to the New Ruby SDK package specified on Ruby gems. Or, if using the Gem locally, point to the version specified on our Github repo:

    1gem 'dropbox-sign', '~> 1.0.0'
  2. Run bundle install


Importing the SDK

1require "hello_sign"

Authentication

The api_key parameter has been renamed to username, and it’s no longer possible to set the client_id on the configure block . The client_id must be set in each API call.

1require 'hello_sign'
2
3HelloSign.configure do |config|
4 config.api_key = 'api_key'
5end

Endpoints Grouped into Classes

The New Ruby SDK no longer uses the Client class. New classes have been introduced to execute specific endpoints and you will now need to instantiate a model specific client to access the methods needed to make your API calls.


Using Models to Pass Parameters

Models are used to define the structure and value of the parameters being passed. The fully assembled model is passed to the API endpoint method.

Legacy Ruby SDKNew Ruby SDK
Pass a hash of values directly to methodPass an instance of the object related to that API request

New SDK Using Models to Pass Parameters

1require "dropbox-sign"
2
3Dropbox::Sign.configure do |config|
4 config.username = "YOUR_API_KEY"
5end
6
7signature_request_api = Dropbox::Sign::SignatureRequestApi.new
8
9signer_1 = Dropbox::Sign::SubSignatureRequestSigner.new
10signer_1.email_address = "jack@dropboxsign.com"
11signer_1.name = "Jack"
12signer_1.order = 0
13
14# Passing an instance of the object related to the request as data
15obj = Dropbox::Sign::SignatureRequestSendRequest.new
16
17obj.title = "NDA with Acme Co."
18obj.subject = "The NDA we talked about"
19obj.test_mode = true
20obj.signers = [signer_1]
21obj.files = [File.open(__dir__ + "/NDA.pdf")]
22
23begin
24 result = signature_request_api.signature_request_send(obj)
25 p result
26rescue Dropbox::Sign::ApiError => e
27 puts "Exception when calling Dropbox Sign API: #{e}"
28end

Path and Query Parameters

In the legacy SDK you would pass Path and Query parameters alongside any POST data to the API endpoint:

Legacy SDK - Path and Query Parameters

1signature_request = @client.remind_signature_request(
2 signature_request_id: '75cdf7dc8b323d43b347e4a3614d1f822bd09491',
3 :email_address: 'john@example.com'
4)

The new SDK now requires POST data be an object when calling any API endpoint. Path and Query parameters must be passed individually to these methods.

New SDK - Path and Query Parameters

1require "dropbox-sign"
2
3Dropbox::Sign.configure do |config|
4 config.username = "YOUR_API_KEY"
5end
6
7signature_request_api = Dropbox::Sign::SignatureRequestApi.new
8
9data = Dropbox::Sign::SignatureRequestRemindRequest.new
10data.email_address = "john@example.com"
11
12signature_request_id = "2f9781e1a8e2045224d808c153c2e1d3df6f8f2f"
13
14begin
15 result = signature_request_api.signature_request_remind(signature_request_id, data)
16 p result
17rescue Dropbox::Sign::ApiError => e
18 puts "Exception when calling Dropbox Sign API: #{e}"
19end

Error Handling and Warnings

The New SDK handles errors and warnings differently.

Error Handling

Errors are an instance of Dropbox::Sign::ApiError with its body method returning an instance of Dropbox::Sign::ErrorResponse class and should be handled using begin/rescue blocks.

New SDK - Error Handling

1require "dropbox-sign"
2
3Dropbox::Sign.configure do |config|
4 config.username = "YOUR_API_KEY"
5end
6
7account_api = Dropbox::Sign::AccountApi.new
8
9begin
10 result = account_api.account_get({ email_address: "jack@example.com" })
11 p result
12rescue Dropbox::Sign::ApiError => e
13 puts "Exception when calling Dropbox Sign API: #{e}"
14end

Warnings

Warnings are a list of Dropbox::Sign::WarningResponse.

New SDK - Warnings

1require "dropbox-sign"
2
3Dropbox::Sign.configure do |config|
4 config.username = "YOUR_API_KEY"
5end
6
7api = Dropbox::Sign::AccountApi.new
8
9data = Dropbox::Sign::AccountCreateRequest.new
10data.email_address = "newuser@dropboxsign.com"
11
12begin
13 result = api.account_create(data)
14 p result
15
16 # warning loop
17 result.warnings.each do | warning |
18 puts "Warning Name: #{warning.warning_name}"
19 puts "Warning Message: #{warning.warning_msg}"
20 end
21
22rescue Dropbox::Sign::ApiError => e
23 puts "Exception when calling Dropbox Sign API: #{e}"
24end

Instantiating Objects From Data

There are three ways to instantiate an object.

  • You can instantiate a class directly and pass a hash of data
  • You can use setter methods
  • You can use the init() static method
1signer_1 = Dropbox::Sign::SubSignatureRequestSigner.new({
2 :email_address => "jack@dropboxsign.com",
3 :name => "Jack",
4 :order => 0,
5})
6
7attachment1 = Dropbox::Sign::SubAttachment.new({
8 :name => "Attachment 1",
9 :instructions => "Please download this file",
10 :signer_index => 0,
11 :required => true,
12})
Note

init() creates a full object using all the data you pass, including nested data to instantiate nested objects. Any parameters that you do not pass data for will be set to their default value (including null).


Event Callback Helper

A callback helper class is included in the New SDK repo to assist in verifying callbacks. The helper simplifies:

  1. Checking event authenticity with built in event hash check
  2. Displaying event types (account callback vs. app callback)
  3. Displaying event messages

The EventCallbackHelper and EventCallbackRequest classes facilitate parsing of event data and assist in validating that a callback originated from Dropbox Sign.

We will send event callback payloads to you as a multipart/form-data request with a single json formfield that contains your event callback as a JSON string.

Example Event Callback Request From US to YOU

$curl -X POST 'https://example.com/YOUR_EVENT_CALLBACK_URL' \
> -F 'json={"event":{"event_type":"account_confirmed","event_time":"1669926463","event_hash":"ff8b03439122f9160500c3fb855bdee5a9ccba5fff27d3b258745d8f3074832f","event_metadata":{"related_signature_id":null,"reported_for_account_id":"6421d70b9bd45059fa207d03ab8d1b96515b472c","reported_for_app_id":null,"event_message":null}}}'

Example JSON Payload

1{
2 "event": {
3 "event_type": "account_confirmed",
4 "event_time": "1669926463",
5 "event_hash": "ff8b03439122f9160500c3fb855bdee5a9ccba5fff27d3b258745d8f3074832f",
6 "event_metadata": {
7 "related_signature_id": null,
8 "reported_for_account_id": "6421d70b9bd45059fa207d03ab8d1b96515b472c",
9 "reported_for_app_id": null,
10 "event_message": null
11 }
12 }
13}

How to use the EventCallbackHelper

1require "dropbox-sign"
2
3# use your API key
4api_key = "324e3b0840f065eb51f3fd63231d0d33daa35d4ed10d27718839e81737065782"
5
6# callback_data represents data we send to you
7callback_data = JSON.parse(req.POST.json, :symbolize_names => true)
8
9callback_event = Dropbox::Sign::EventCallbackRequest.init(callback_data)
10
11# verify that a callback came from HelloSign.com
12if Dropbox::Sign::EventCallbackHelper.is_valid(api_key, callback_event)
13 # one of "account_callback" or "api_app_callback"
14 callback_type = Dropbox::Sign::EventCallbackHelper.get_callback_type(callback_event)
15
16 # do your magic below!
17end

Differences from Legacy SDK

This section highlights larger changes to be aware of when migrating to the new SDK.

Form Fields per Document

The Form Fields per Document parameter has changed from a two dimensional array, to a one dimensional array—allowing you to designate which file you to add the field to using document_index. You can learn more about this change here: Form Fields per Document.

1form_fields_per_document: [
2 [
3 {
4 name: 'address',
5 type: 'text',
6 x: 160,
7 y: 80,
8 width: 206,
9 height: 32,
10 signer: 0
11 }
12 ],
13 [
14 {
15 name: 'phone',
16 type: 'text',
17 x: 160,
18 y: 150,
19 width: 206,
20 height: 32,
21 signer: 1
22 }
23 ]
24]

Instantiating the Correct Field Class

There are several different types of form fields you can define, identified by the value of the type field and a few ways to instantiate the correct object when making an API request.

The different classes for each type are:

You can use ::init() on the base request class

1# instantiates a new `SignatureRequestSendRequest` object
2data = Dropbox::Sign::SignatureRequestSendRequest.init({
3 title: "NDA with Acme Co.",
4 subject: "The NDA we talked about",
5 message: "Please sign this NDA and then we can discuss more.",
6 signers: [
7 {
8 email_address: "jack@dropboxsign.com",
9 name: "Jack",
10 order: 0,
11 },
12 ],
13 files: [File.open(__dir__ + "/pdf-sample.pdf")],
14 form_fields_per_document: [
15 {
16 type: "signature",
17 document_index: 0,
18 api_id: "4688957689",
19 name: "signature1",
20 x: 5,
21 y: 7,
22 width: 60,
23 height: 30,
24 required: true,
25 signer: 0,
26 page: 1,
27 },
28 ],
29})

You can use ::init() on the field class

1form_field_1 = Dropbox::Sign::SubFormFieldsPerDocumentSignature.init({
2 type: "signature",
3 document_index: 0,
4 api_id: "4688957689",
5 name: "signature1",
6 x: 5,
7 y: 7,
8 width: 60,
9 height: 30,
10 required: true,
11 signer: 0,
12 page: 1,
13})

You can instantiate the class directly

1form_field_1 = Dropbox::Sign::SubFormFieldsPerDocumentSignature.new
2form_field_1.type = "signature"
3form_field_1.document_index = 0
4form_field_1.api_id = "4688957689"
5form_field_1.name = "signature1"
6form_field_1.x = 5
7form_field_1.y = 7
8form_field_1.width = 60
9form_field_1.height = 30
10form_field_1.required = true
11form_field_1.signer = 0
12form_field_1.page = 1

Form Fields per Document Examples using the new SDK:

1form_field_1 = Dropbox::Sign::SubFormFieldsPerDocumentSignature.init({
2 type: "signature",
3 document_index: 0,
4 api_id: "4688957689",
5 name: "signature1",
6 x: 5,
7 y: 7,
8 width: 60,
9 height: 30,
10 required: true,
11 signer: 0,
12 page: 1,
13})

“role” Value in signers Object

In the Legacy SDK when making a Signature Request using a Template the signers property was an object with the role name as the key. In the new SDK the role value has been moved into the signer object itself.

For example for the /signature_request/send_with_template endpoint the signers property could be represented as:

1{
2 "signers": {
3 "Client": {
4 "name": "George",
5 "email_address": "george@example.com"
6 },
7 "Manager": {
8 "name": "Bob",
9 "email_address": "bob@example.com"
10 }
11 }
12}

Using the new SDK you would now send this data as follows:

1require "dropbox-sign"
2
3Dropbox::Sign.configure do |config|
4 config.username = "YOUR_API_KEY"
5end
6
7signature_request_api = Dropbox::Sign::SignatureRequestApi.new
8
9data = Dropbox::Sign::SignatureRequestSendWithTemplateRequest.init({
10 template_ids: ["c26b8a16784a872da37ea946b9ddec7c1e11dff6"],
11 subject: "Purchase Order",
12 message: "Glad we could come to an agreement.",
13 signers: [
14 {
15 role: "Client",
16 email_address: "george@example.com",
17 name: "George",
18 },
19 {
20 role: "Manager",
21 email_address: "bob@example.com",
22 name: "Bob",
23 }
24 ],
25})
26
27begin
28 result = signature_request_api.signature_request_send_with_template(data)
29 p result
30rescue Dropbox::Sign::ApiError => e
31 puts "Exception when calling Dropbox Sign API: #{e}"
32end

“role” Value in ccs Property

In the Legacy SDK when making a Signature Request using a Template the ccs property was an object with the role name as the key. In the new SDK the role value has been moved into the cc object itself, alongside a new email_address property.

For example for the /signature_request/send_with_template endpoint the ccs property could be represented as:

1{
2 "ccs": {
3 "Client": "george@example.com",
4 "Manager": "bob@example.com"
5 }
6}

Using the new SDK you would now send this data as follows:

1require "dropbox-sign"
2
3Dropbox::Sign.configure do |config|
4 config.username = "YOUR_API_KEY"
5end
6
7signature_request_api = Dropbox::Sign::SignatureRequestApi.new
8
9data = Dropbox::Sign::SignatureRequestSendWithTemplateRequest.init({
10 template_ids: ["c26b8a16784a872da37ea946b9ddec7c1e11dff6"],
11 subject: "Purchase Order",
12 message: "Glad we could come to an agreement.",
13 signers: [
14 {
15 role: "Client",
16 email_address: "george@example.com",
17 name: "George",
18 },
19 {
20 role: "Manager",
21 email_address: "bob@example.com",
22 name: "Bob",
23 }
24 ],
25 ccs: [
26 {
27 role: "Client",
28 email_address: "george@example.com",
29 },
30 {
31 role: "Manager",
32 email_address: "bob@example.com",
33 }
34 ]
35})
36
37begin
38 result = signature_request_api.signature_request_send_with_template(data)
39 p result
40rescue Dropbox::Sign::ApiError => e
41 puts "Exception when calling Dropbox Sign API: #{e}"
42end

“name” Value in custom_fields Property

In the Legacy SDK when making a Signature Request with the custom_fields property it was an object with the name as the key. In the new SDK the name value has been moved into the custom_field object itself.

For example for the /signature_request/send_with_template endpoint the custom_fields property could be represented as:

1{
2 "custom_fields": {
3 "company": {
4 "value": "ABC Corp",
5 "required": true
6 }
7 }
8}

Using the new SDK you would now send this data as follows:

1require "dropbox-sign"
2
3Dropbox::Sign.configure do |config|
4 config.username = "YOUR_API_KEY"
5end
6
7signature_request_api = Dropbox::Sign::SignatureRequestApi.new
8
9data = Dropbox::Sign::SignatureRequestSendWithTemplateRequest.init({
10 template_ids: ["c26b8a16784a872da37ea946b9ddec7c1e11dff6"],
11 subject: "Purchase Order",
12 message: "Glad we could come to an agreement.",
13 signers: [
14 {
15 role: "Client",
16 email_address: "george@example.com",
17 name: "George",
18 },
19 {
20 role: "Manager",
21 email_address: "bob@example.com",
22 name: "Bob",
23 }
24 ],
25 custom_fields: [
26 {
27 name: "company",
28 value: "ABC Corp",
29 required: true,
30 },
31 ]
32})
33
34begin
35 result = signature_request_api.signature_request_send_with_template(data)
36 p result
37rescue Dropbox::Sign::ApiError => e
38 puts "Exception when calling Dropbox Sign API: #{e}"
39end

template_id to template_ids

The template_id parameter has been removed. You must now use template_ids.

Legacy SDK versionNew SDK Version
Template ID (template_id) is passed as a singular string:
template_id : “1234567890”
Template ID is passed as an array of strings (template_ids):
template_ids:[“1234567890”]

file to files

The file parameter has been renamed to files. Usage remains the same.

Use .files([...]);


file_url to file_urls

The file_url parameter has been renamed to file_urls. Usage remains the same.

Use .file_urls([...]);


Interacting with Files

The new SDK version introduces some new patterns around uploading and downloading files. You can read about them more in depth here: Interacting with Files.

Uploading Files

The file upload process changed with the newly-adopted OpenAPI-specification — it is no longer possible to pass file paths into file upload methods. You can learn more about this update here: New Patterns: Interacting with Files.

Legacy SDK

  • Supports passing filepath as a string

New Ruby SDK

  • Files needs to be instance of File
  • Construct instance of Fileusing either File.open or File.new
1client.send_signature_request(
2 :test_mode => 1,
3 :title => 'NDA',
4 :files => ['/Users/NDA.pdf']
5)

Downloading Files

The file retrieval process changed with the newly-adopted OpenAPI-specification — one endpoint was branched off into three separate endpoints. You can learn more about this update here: New Patterns: Interacting with Files.

Legacy SDK

  • Returns different file formats depending on parameters used from a single endpoint.

New SDK

  • Original endpoint broken into 3 separate endpoints to return different file formats.
1client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
2file_bin = client.signature_request_files :signature_request_id => 'fa5c8a0b0f492d768749333ad6fcc214c111e967', :file_type => 'pdf'
3open("files.pdf", "pdf") do |file|
4 file.write(file_bin)
5end

Downloading Templates

1client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
2file_bin = client.get_template_files :template_id => 'fa5c8a0b0f492d768749333ad6fcc214c111e967', :file_type => 'pdf'
3open("files.pdf", "pdf") do |file|
4 file.write(file_bin)
5end

Endpoint Mapping

This section shows you how endpoints in the legacy SDK map to the new SDK. It doesn’t cover all endpoints, but gives you an idea of mapping implementations between the two SDKs. Please reach out if you think we’re missing an important example.

Non-Embedded Signature Request

1client = HelloSign::Client.new
2 client.send_signature_request(
3 :test_mode => 1,
4 :title => 'NDA',
5 :subject => 'Please sign this NDA',
6 :message => 'Please sign this NDA and then we can discuss more. Let me know if you have any
7 questions.',
8 :signers => [
9 {
10 :email_address => 'example@example.com',
11 :name => 'Jack',
12 :order => 0,
13 },
14 {
15 :email_address => 'example+1@example.com',
16 :name => 'Jack 2',
17 :order => 1,
18 }
19 ],
20 :files => ['path_to_file']
21 )
22end

Embedded Signature Request

1client.create_embedded_signature_request(
2 :test_mode => 1,
3 :client_id => 'b6b8e7deaf8f0b95c029dca049356d4a2cf9710a',
4 :title => 'NDA with Acme Co.',
5 :subject => 'The NDA we talked about',
6 :message => 'Please sign this NDA and then we can discuss more. Let me know if you have any
7 questions.',
8 :signers => [
9 {
10 :email_address => 'jack@example.com',
11 :name => 'Jack',
12 :order => 0,
13 },{
14 :email_address => 'jill@example.com',
15 :name => 'Jill',
16 :order => 1,
17 }
18 ],
19 :files => ['NDA.pdf', 'AppendixA.pdf']

Send Signature Request with Template

1client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
2client.send_signature_request_with_template(
3 :test_mode => 1,
4 :template_id => 'c26b8a16784a872da37ea946b9ddec7c1e11dff6',
5 :subject => 'Purchase Order',
6 :message => 'Glad we could come to an agreement.',
7 :signers => [
8 {
9 :email_address => 'george@example.com',
10 :name => 'George',
11 :role => 'Client'
12 }
13 ],
14 :ccs => [
15 {
16 :email_address =>'accounting@example.com',
17 :role => "Accounting"
18 }
19 ],
20 :custom_fields => [
21 {
22 :name => 'Cost',
23 :value => '$20,000'
24 }
25 ]
26)

Get Signature Request

1client.get_signature_request :signature_request_id => 'fa5c8a0b0f492d768749333ad6fcc214c111e967'

List Signature Request

1client.get_signature_requests :page => 1

Download Files

1client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
2file_bin = client.signature_request_files :signature_request_id => 'fa5c8a0b0f492d768749333ad6fcc214c111e967', :file_type => 'pdf'
3open("files.pdf", "pdf") do |file|
4 file.write(file_bin)
5end

Get Account

1client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
2client.get_account

Supporting Legacy SDKs

Following the official release of the new SDK version, we'll be preparing to deprecate all legacy versions of the Ruby SDK for one year after launch. That means, once fully launched, we'll only support critical vulnerabilities and bug fixes for legacy SDK versions 3.7.7 for 12 months. After that, legacy versions are considered officially deprecated and are no longer supported. You can find more information in our SDK Versioning Policy.

We encourage you to start migrating (or planning to migrate) to the new SDK as soon as possible. Please don't hesitate to reach out if you have questions or need assistance.


Feedback and Assistance

We know that dealing with "breaking" changes is inconvenient for those of you currently using the legacy SDK, but believe the new SDK offers a better experience while providing access to more features. If you need help or get stuck, please reach out to API support: Submit a Ticket

We warmly welcome your feedback, feature requests, and bug reports in our OpenAPI repo. All of the engineering work on the Ruby SDK happens in the Ruby folder of the repo.