[FIXED] How to pause a signature workflow with TemplateRoles?

Issue

I'm trying to pause a signature workflow using a Template. I have four Recipients and the workflow needs to pause before the 4th signature (role name : Partner).

This is my code to create the envelope, I followed the documentation, the main difference is that I'm using TemplateRole instead of Signer :

        $envelope_definition = new EnvelopeDefinition([
            'template_id' => $args['template_id'],
        ]);

        $cc = new TemplateRole([
            'email' => 'name' => $args['cc_email'], 'name' => $args['cc_name'],
            'role_name' => 'cc', 'routing_order' => '1',
        ]);

        $commercial = new TemplateRole([
            'email' => $args['commercial_email'], 'name' => $args['commercial_name'],
            'role_name' => 'Commercial', 'routing_order' => '2',
        ]);

        $client = new TemplateRole([
            'email' => $args['commercial_email'], 'name' => $args['client_name'], 'in_person_signer_name' => $args['commercial_name'],
            'role_name' => 'Client', 'routing_order' => '3',
        ]);

        $partner = new TemplateRole([
            'email' => args['partner_email'], 'name' => $args['partner_name'],
            'role_name' => 'Partner', 'routing_order' => '4',
        ]);

        $envelope_definition->setTemplateRoles([$cc, $commercial, $client, $partner]);

        $workflow_step = new WorkflowStep([
            'action' => 'pause_before',
            'trigger_on_item' => 'routing_order',
            'item_id' => '4',
        ]);
        $workflow = new Workflow([
            'workflow_steps' => [$workflow_step,],
        ]);

        $envelope_definition->setWorkflow($workflow);

        $envelope_definition->setStatus('sent');

        $envelope_api = new EnvelopesApi($apiClient);
        $envelope_api->createEnvelope($account_id, $envelope_definition);

When I'm trying to returns my created envelope's workflow definition with /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/workflow I'm getting 404 error with empty response.

The workflow doesn't seem to stop before the 4th signer, he still recieve an email.

Am I missing something ?

Thanks

Solution

Your plan to create an envelope based on a template, and include workflow steps with the envelope is very reasonable. Unfortunately, there is a known bug that is interfering. The internal tracking id is RR-59.

Please contact DocuSign customer service to have your company (and the client, if applicable) added to the bug tracking ticket.

Work-around: a "workflow" recipient

The work-around is to add an additional recipient to the template or to the envelope. (Probably easier to add to the template.) The extra recipient's routing order should be a value where you want the envelope paused.

For example, the template has two signers, and you want to pause before the second. Add the extra recipient with routing order 2 (and make the second recipient routing order 3.)

Then, when DocuSign reaches routing order 2, it will stop. But the extra recipient needs to be the right type. Something like:

Name: Pause Routing
Recipient type: signer
Routing order: 2
ClientUserID: 10
Email: noone@example.com

In this case, the pause routing recipient is an embedded (captive) recipient. So DocuSign will wait until your app (normally) has the recipient sign via an embedded signing ceremony. But in this case, your app, instead, will do whatever it wants by correcting the envelope. Then delete the recipient and the envelope routing will continue with the next recipient.

If you use an embedded signer then you need to add the ClientUserID when the envelope is sent. Here is a live example of adding a ClientUserID via the API Request Builder.

An alternative for the pause recipient is to make them be a certifiedDelivery recipient. In this case, you'd need to provide an email address that is a blackhole (email sent to the address is silently swallowed and discarded.)

Use the Connect Webhook system to notify your application that the envelope has been sent to your pause recipient -- that indicates that the envelope has been paused.

Answered By - Larry K

Answer Checked By - Clifford M. (PHPFixing Volunteer)