Skip to main content

Processes with many stages and parties

In reality, it will be very uncommon that your document e-signing workflow will contain only one participant and/or one document. Generally speaking, it takes multiple parties to make a contract. Also, if you only need one document to be signed, then it's likely you will want to use the regular document API instead of the Scrive Flow API.

The Scrive Flow API is designed for coordinating the signing of multiple documents in a systematic way. So far we have used simple one-party, one-stage, one-document set-ups because they're the easiest way to illustrate the concepts. In this article we will set up a signing process which is more typical of the kinds that you will see in reality.

Setting up the process​

Here we will set up a simple process where two users will be asked to sign two documents in a specified order.

{
  "dsl-version": "0.2.0",
  "stages": [
    {
      "first": {
        "actions": [],
        "expect": {
          "signed-by": {
            "users": ["user1", "user2"],
            "documents": ["doc1"]
          }
        }
      }
    },
    {
      "second": {
        "actions": [],
        "expect": {
          "signed-by": {
            "users": ["user1", "user2"],
            "documents": ["doc2"]
          }
        }
      }
    }
  ]
}

As we can see above, we have two stages which have been given the (user-specified) names of first and second. Any arbitrary names that JSON will accept can be used.

In the first stage, we require that user1 and user2 sign doc1. Again, these are arbitrary variable names that describe the process abstractly.

In the second stage, we do the same with doc2. The system will not present doc2 for signing until all the expect conditions of first have been fulfilled.

Hopefully all this is fairly intuitive, so let's move on.

Setting up the documents​

We now need to set up a pair of documents and save them as drafts. We need to ensure that the parties of those documents are configured in a way that matches the values we intend to pass in when starting the instance from the flow draft.

Both documents will need to be set up as below:

Setting up the approver

As per the process description, user1 and user2 will sign both documents, starting with doc1, followed by doc2.

Perhaps you'd like to use a different PDF document for each, to better tell them apart. Either way, make sure to note your document IDs from the URL for the next stage:

Starting the instance​

Just like we did in the Getting Started article related to Instances, we are going to send a JSON object detailing concrete values for the variable names in the process:

{
  "title": "foobar",
  "process_parameters": {
    "documents": {
      "doc1": "2",
      "doc2": "3"
    },
    "users": {
      "user1": {
        "id_type": "email",
        "id": "foo@example.com"
      },
      "user2": {
        "id_type": "user_id",
        "id": "1"
      }
    },
    "messages": {}
  }
}
caution

These values must match the ones configured in the individual documents or the process will fail. The ordering of participants does not matter. Scrive flow will match them up to those in the document.

Accessing the overview page​

Upon starting the instance, I can see the following within the instance response:

"access_links": {
  "user1": "https://scrive.com/experimental/flow/overview/96b04326-11ac-4fc5-83c6-8393e5399574/user1/aea10dc024d1d9ee",
  "user2": "https://scrive.com/experimental/flow/overview/96b04326-11ac-4fc5-83c6-8393e5399574/user2/791ea39bbf752512"
}

These links allow you to authenticate as one of the two participants and go to their respective overview page.

Normally you'd distribute these to the relevant participants, but we're going to role-play as all of the participants for the sake of this guide:

Signing the documents​

user1 can sign doc1​

As you can see by following user1's access link, doc1 is available for signing:

User1 can sign document 1

user1 proceeds to the document and signs doc1:

User1 signs document 1

user1 has no further actions available​

After signing, user1 returns to the overview page to see that they have no further actions available.

User1 returns to the overview page

user2 can sign doc1​

Now that there are no further actions to perform as user1, let's authenticate via the access link for user2:

User2 can sign document 1

As expected from the process description, doc1 is still available for signing as user2. Let's proceed to the document page and sign doc1:

User2 signs document 1

user2 (and user1) can sign doc2​

With doc1 now signed by all parties let's return to the overview page:

User2 returns to the overview page

As you can see, now that both user1 and user2 have signed doc1, the execution of the instance has moved on to the second stage. This has made doc2 available for signing by both user1 and user2.

If we repeated the process here where user1 and user2 sign doc2, this would satisfy the expects conditions of second and we would move on to finalisation and termination of the instance.