Skip to main content

Create a new Flow Draft

In this article, we will be creating our first Flow Draft. A draft is a basic description of the signing process that you would like to go through. It will generally be a set of named stages which will be stepped through iteratively. These will contain information about who should do what to which documents during each stage.

In this first basic example, we will be constructing the most basic signing process that we support; one with a single stage, a single document, and a single signatory.

Describing the process using the DSL​

We define this process using the Flow DSL (Domain Specific Language) which is a subset of JSON.

The language has an intuitive structure that allows the description of signing processes.

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

Note that, at this point, we're not talking about any specific users or documents, we're just describing the process in an abstract sense:

  • The version of the Flow DSL that we're using is 0.2.0.
  • The flow contains at least one stage.
  • We have named the first stage as initial (although any name is permissible which the JSON standard would consider valid).
  • When the initial stage is executed, we don't need any special actions to be performed.
  • We expect this stage to involve user1 signing doc1. Again, these names are just user-specified variable names. user-who-I-want-to-sign and orbital-launch-agreement would be equally valid here.
  • Once the expect conditions are met, the flow will move on to the next stage. In this case, there is only one stage, so this will trigger the process of finalising the flow.

Creating a new draft from our process description​

Now that we have defined our signing flow, we need to submit it via the API.

The way in which we submit a new draft is to send a POST request to the /experimental/flow/drafts endpoint.

To send our draft above, this will involve POSTing the following:

{
  "title": "Simple Flow",
  "process": {
    "dsl-version": "0.2.0",
    "stages": [
      {
        "initial": {
          "actions": [],
          "expect": {
            "signed-by": {
              "users": ["user1"],
              "documents": ["doc1"]
            }
          }
        }
      }
    ]
  }
}

Place the above JSON in a file called draft.json.

"Simple Flow" is our name that we've given the draft. This name only serves as a human-readable name for the draft. It does not matter beyond this purpose. The process contains the JSON object, as shown above, for our DSL process description.

We will assume you have constructed the auth header as demonstrated earlier in this guide.

Make sure that you are currently in the same directory as draft.json and execute the following:

$ curl -i -X POST -H "${auth_header}" \
  -H 'content-type: application/json' "${base_url}/experimental/flow/drafts" \
  -d @draft.json

I included the -i flag above so that it would display the HTTP response headers.

Adding -d @draft.json to the curl invocation causes the contents of draft.json to be sent as the HTTP body.

Successful create response​

When you execute the command above, you should see something like the following:

HTTP/2 201
server: nginx
date: Wed, 24 Feb 2021 13:58:14 GMT
content-type: application/json;charset=utf-8
strict-transport-security: max-age=31536000
p3p: CP="NOI ADM DEV COM NAV OUR STP"

{
  "id": "8ebb15ef-5aed-46d3-a978-bb616e2be919",
  "title": null,
  "process": {
    "dsl-version": "0.2.0",
    "stages": [
      {
        "initial": {
          "actions": [],
          "expect": {
            "signed-by": {
              "users": ["user1"],
              "documents": ["doc1"]
            }
          }
        }
      }
    ]
  },
  "process_parameters": {
    "documents": {},
    "users": {},
    "messages": {}
  },
  "callback": null,
  "created": "2021-04-06T12:58:15.488559Z",
  "author_id": "1",
  "folder_id": "2"
}

The important parts of this are:

  • The HTTP 201 code. This signifies a successful request which caused something to be created.
  • The response body which contains a JSON object with an id that you can use to reference your newly created draft (along with all the other current values for your draft).

Other fields in the draft​

In this example we chose to set the process field of the draft. However, if you look at the draft JSON which was returned, you'll see that there are many other fields such as process_parameters or callback. Many of these could have been set during creation. It is also permissible to leave process unset when creating a draft.

We are starting by specifying the process first for the sake of this guide, as there's a logical progression to "designing the process in an abstract manner" and then "providing the concrete implementation values". This is not a hard requirement however. Drafts allow a lot of freedom.

Setting process_parameters at the time of draft creation, then providing the actual process later, or when starting an instance from the draft, are also valid ways to approach the problem.

You may also provide everything required to start an instance from the draft at the moment of creation, this is also perfectly acceptable. Creating a completely blank draft is also permissible.

Error responses​

At this stage, we do not validate the structure of the DSL JSON which was passed as the process field. This is to allow you to edit the process fairly freely until it's time to actually start an instance from it.

You're only likely to see errors if you submitted a HTTP body that is malformed (i.e. not valid JSON, syntactically) or if you fail to authenticate correctly with the Scrive API.

Further Reading​

If you would like a deeper knowledge of the topics covered here, then the following articles may be useful. You are not required to read them in order to understand the rest of this guide.