Skip to navigation

Configure agreement types and fields

View as Markdown

Agreement Manager includes a catalog of standard agreement types and standard fields. The Docusign CLI enables you to extend this catalog by creating custom fields and agreement types, and by adding fields to both standard and custom agreement types. You configure these customizations programmatically using a manifest file, then upload the manifest to Agreement Manager using the CLI.

For a walkthrough of the Agreement Manager configuration process, see this video:

Supported agreement type and field customizations

The Docusign CLI supports the following Agreement Manager customizations.

Custom fields

You can define custom fields to capture information specific to your organization that is not covered by Agreement Manager’s standard fields. Each custom field has a name, a data type (string, number, date/time, or dropdown), and an optional AI extraction configuration..

Once defined in the manifest, a custom field must be mapped to at least one agreement type—standard or custom—to be valid. Custom field names and labels must not duplicate those of any standard field.

Standard agreement types with additional fields

Agreement Manager provides a set of standard agreement types, each with a predefined set of default standard fields. You can extend any standard agreement type by mapping additional standard fields or custom fields to it. This enables you to capture more information from agreements of that type without creating a new type. The default standard fields for each standard agreement type cannot be removed or changed.

Custom agreement types

You can create custom agreement types to represent categories of agreements that are not covered by Agreement Manager’s standard types. Each custom agreement type has a name, a category, and a set of fields. By default, every custom agreement type includes six standard fields: Title, Parties, Execution Date, Effective Date, Status, and Line of Business. You can add additional standard fields and custom fields beyond these defaults. Custom agreement type names and labels must not duplicate those of any standard agreement type.

Process overview

Configuring agreement types and fields involves four main steps:

1. Retrieve standard and custom catalogs

Run the ds agm get catalog command to retrieve the current Agreement Manager configuration for your account. This generates two reference files: a standard catalog containing the out-of-the-box agreement types and fields, and a custom catalog containing any existing customizations. Use these files as a reference when building your manifest.

If your account already has customizations that you want to replicate or extend in another account, run the ds agm catalog-to-manifest command. This command automatically generates a manifest file based on your account’s existing configuration, which you can then modify and upload to another account. This is particularly useful for porting configurations across accounts.

For details and command options, see Retrieve standard and custom catalogs.

2. Create a package in your workspace

An Agreement Manager package is a bundle that contains everything needed to configure Agreement Manager programmatically. It includes a manifest file that defines your customizations and, when AI extraction is enabled for custom agreement types, a set of example agreements used to train the AI.

The manifest file must be created at the following path in your workspace:

{workspaceName}/{projectName}/agreement-manager/configs/agreement-manager-manifest.json

The manifest defines your custom fields, custom agreement types, and any extensions to standard agreement types. For custom agreement types where AI extraction is enabled, you must also add at least five example agreements to the following directory:

{workspace}/{project}/agreement-manager/files/train/

For details on package contents and how to structure your manifest, see Create a package.

3. Update the manifest with your customizations

Use the standard and custom catalogs retrieved in step 1 as a reference when defining your customizations in the manifest. The manifest supports three types of customizations:

  • Define custom fields in the fields array. Each field requires a unique key (starting with C_), a display name, a data type, and an AI extraction setting.
  • Extend standard agreement types by adding entries to the standardAgreementTypes array. Specify the additional standard fields and custom fields to map to each type.
  • Create custom agreement types by adding entries to the customAgreementTypes array. Specify the fields to map and, if AI extraction is enabled, a description and example agreements for AI training.

For the full manifest structure and property descriptions, see the Manifest reference.

4. Upload the package to Docusign

Once your manifest is complete and your training documents are in place, run the following command to upload the package:

ds agm upload

After a successful upload, Agreement Manager reflects your customizations: custom fields and agreement types are created, fields are mapped to the specified agreement types, and AI extraction training begins for any custom types and fields where it is enabled.

For upload command options and information about what to expect after a successful upload, see Upload a package.

Restrictions

The following restrictions apply to Agreement Manager customizations.

Custom fields

  • Maximum custom fields: 300
  • Maximum custom fields with AI extraction enabled: 50 (this limit is shared with custom agreement types; see below)
  • Custom field names and labels must not duplicate standard field names and labels
  • Every custom field newly defined in the manifest must be referenced in at least one agreement type’s customFields array

Custom agreement types

  • Maximum custom agreement types: 200
  • Maximum custom agreement types with AI extraction enabled: 15
  • Custom agreement type names and labels must not duplicate standard agreement type names and labels

AI extraction limit (shared)

The total number of custom fields and custom agreement types with AI extraction enabled cannot exceed 50. No more than 15 of those 50 can be custom agreement types. The following are examples of valid distributions:

  • 50 custom fields with AI extraction enabled, 0 custom agreement types
  • 35 custom fields + 15 custom agreement types
  • 40 custom fields + 10 custom agreement types

Additional restrictions

  • All labels in additionalStandardFields must exist in the standard catalog
  • All labels in customFields must match a custom field label defined in the manifest’s fields array
  • Training documents are required for custom agreement types with customExtractionEnabled set to true, and must exist in the {workspace}/{project}/agreement-manager/files/train/ directory

Frequently asked questions

What is the difference between a standard field and a custom field?

Agreement Manager standard fields are provided out of the box and apply broadly to many agreement types. Custom fields are defined by you in the manifest to capture organization-specific information that standard fields do not cover. Custom fields must be mapped to at least one agreement type before they can be used.

Can I add the same field to multiple agreement types?

Yes. You can map a custom field to as many agreement types - standard or custom - as needed. Standard fields can also be mapped as additional fields to multiple agreement types, as long as they are not already included as default fields for those types.

Can I remove fields from an agreement type after uploading?

You can disassociate additional standard fields and custom fields from an agreement type by removing the corresponding labels from the additionalStandardFields or customFields arrays in the manifest and running ds agm upload again. However, the six default standard fields included in every custom agreement type (Title, Parties, Execution Date, Effective Date, Status, and Line of Business) cannot be removed.

What happens if I run the upload command more than once?

The upload command is safe to run multiple times. If the manifest has not changed, the CLI makes no updates. If the manifest includes changes, the CLI updates the existing configuration in Agreement Manager with the values defined in the manifest. Custom fields and custom agreement types that were previously uploaded are not duplicated.

Can I use the Docusign CLI to replicate my Agreement Manager configuration in another account?

Yes. Run ds agm catalog-to-manifest on the source account to generate a manifest based on its existing configuration. You can then authenticate to the target account and run ds agm upload to apply the configuration there. For details, see Retrieve standard and custom catalogs.

Next steps