Managing Metadata
Larry Kluger and Mark Belanger discuss best practices for managing metadata.
By Larry Kluger and Mark Belanger
“No man is an island, entire of itself; every man is a piece of the continent, a part of the main.”
— John Donne (1572–1631)
John Donne’s famous words on human nature apply to data, too: context and connections are crucial. In software terms, we call this context and connection information “metadata.”
Docusign provides many features for storing and managing the metadata associated with your envelopes. We will discuss several of these features in this blog post. Some of these metadata features are only available for developers’ use via the eSignature REST or SOAP APIs; others can also be used via the Docusign web tool.
Envelope metadata: Envelope Custom Fields
Envelope object metadata is stored within Envelope Custom Fields.
Envelope Custom Fields are available in list and text formats. They are defined at the account level and can be added to envelopes by the sender of the envelope via using either the Docusign web tool or via the eSignature REST API. An envelope can include more than one Envelope Custom Field. Fields They can also be optionally included in the envelope’s certificate of completion.
The Docusign web tool enables users to search for envelopes by Envelope Custom Field values.
You can also store additional envelope metadata as an attachment to an envelope (see below). Use an attachment if you need to associate large amounts of metadata (kilobytes or more) with an envelope.
Recipient metadata
Recipient metadata is stored within the customFields attribute of an EnvelopeRecipients object.
All envelopes include one or more recipients. Some recipients are signers; others are not. Recipient metadata can only be set via the eSignature REST API. The customFields attribute of the EnvelopeRecipients object stores an array of individual strings. One common way to type customField metadata is by using the array itself. For example, you could store customer_id as the first value in the array to indicate that the second value in the array is the actual customer ID for that recipient.
For recipients who will sign via an embedded Signing Ceremony, the recipient objects’ clientUserId attribute provides the important link between your application’s record of the signer and Docusign.
Document metadata
Document metadata is stored within the documentFields attribute of a document object.
All envelopes include one or more documents. You can store metadata for individual documents by setting the document object’s documentFields attribute. This attribute is set to an array of objects, each of which has a name and a value field. For example, you could store the revision information about a document in the attribute.
Envelope attachments
Metadata can also be stored as an envelope attachment. For many use cases, you can limit the visibility and access to an attachment that contains your metadata via the attachment’s accessControl attribute. Attachments can be very large, providing flexibility for specific use cases.
Data in XML format can be saved in an attachment.
Envelope document content
Metadata can also be included in the documents that are visible to recipients. For example, you could include metadata as plain text or as a bar code within your documents. Documents are always converted to PDF format by Docusign.
Summary
Docusign enables you to write, read, and manage metadata for all of your envelope’s major objects: the envelope itself, its recipients, and its documents. Our goal is to make it easy for you to integrate Docusign within your business processes.
Comments? Let us know via developers@docusign.com.
Larry Kluger is the Lead Developer Evangelist for Docusign. He has many years of tech industry experience as a software developer, product manager, and evangelist. An award-winning speaker, he enjoys giving talks and meeting members of the developer community.
Mark Belanger is the Director of Engineering for the Docusign Platform Provisioning and Administration teams.
Additional resources
Larry Kluger has over 40(!) years of tech industry experience as a software developer, developer advocate, entrepreneur, and product manager. An award-winning speaker with a 48K StackOverflow reputation, he enjoys giving talks and helping the ISV and developer communities.
Twitter: @larrykluger
LinkedIn: https://www.linkedin.com/in/larrykluger/
Related posts
Discover what's new with Docusign IAM or start with eSignature for free
