DocuSign API - Role Removed When Programmatically Specifying Routing Order

Question

We need to specify routing orders when creating an envelope using the SDK. Routing orders can vary envelope to envelope.

Unfortunately, when specifying the routing order programmatically during envelope creation the role seems to either get removed or not processed correctly. This results in a "free form" signing experience for every signer after the first.

In this example I have a server template with 3 roles: Buyer, CoBuyer, and Seller. The routing order of the recipients can vary from envelope to envelope. I have setup the signers to receive emails and enabled embedded signing. The routing order and first signer signing process works as expected, but every subsequent signer is given a free form signing experience ( where they add their own tabs ). It seems that the role is being removed or not processed properly.

env.compositeTemplates = [
            {
                compositeTemplateId: 1,
                serverTemplates: [
                    {
                        sequence: 1,
                        templateId: '1234',
                    }
                ],
                inlineTemplates: [
                    {
                        sequence: 2,
                        recipients: {
                            {
                                email: "[email protected]",
                                name: "Person One",
                                clientUserId: 1000,
                                recipientId: 1,
                                routingOrder: 3, //this can vary for each envelope
                                roleName: "Buyer",
                                tabs: { ... },
                                embeddedRecipientStartURL: 'SIGN_AT_DOCUSIGN'
                            },
                            {
                                email: "[email protected]",
                                name: "Person Two",
                                clientUserId: 1001,
                                recipientId: 2,
                                routingOrder: 2, //this can vary for each envelope
                                roleName: "CoBuyer",
                                tabs: { ... },
                                embeddedRecipientStartURL: 'SIGN_AT_DOCUSIGN'
                            },
                            {
                                email: "[email protected]",
                                name: "Person Three",
                                clientUserId: 1002,
                                recipientId: 3,
                                routingOrder: 1, //this can vary for each envelope
                                roleName: "Seller",
                                tabs: { ... },
                                embeddedRecipientStartURL: 'SIGN_AT_DOCUSIGN'
                            },
                        }
                    },
                ]
            },
        ];

On the DocuSign backend, subsequent signers after the first one will not have their role tabs unless I specify a signing order in the template and pass in the exact same routing order when generating the envelope programmatically via the SDK Envelopes::createEnvelope. If I do not specify a signing order or the signing order differs from what is in the template, subsequent signers after the first will have a free form signing experience without tab data.

This works ( if the routing order matches when creating the envelope via the SDK ) - it does not work for any subsequent signer after the first if the routing order is different:

This does not work for any signer after the first:

Can someone please advise on how to make this work?

Answer 1

Unfortunately, composite templates cannot be used to update a role's routing order.

Instead of using a template, your Envelopes: create call could create the entire envelope object. You could then set the routing order programmatically.

Added

Re: OP's comment (below).

Your proposal of creating the envelope as a draft, then adding to it would work. But often better is to create the entire envelope with one Envelopes:create call. In that one call you can include one or more documents, recipients, their tabs (fields), etc.

And send off the envelope (status: "sent")

Only issue is if the total size of the docs exceeds 25MB. In that case, you'd need to add the documents one at a time.

Here's a Node example of creating an Envelope object that includes three docs, a signer and cc recipients. See example number 2 in our other SDK languages as well.

You are welcome to call the API directly too. About half of our developers use the SDKs, the other half call the API directly.