Skip to main content

What is a draft?

A draft is what the name implies: it is a draft workflow that can be started later. It may have a complete set of information needed in order to start a running instance, or it may have a partial amount.

Example of a draft as returned by the API​

{
  "id": "134af19f-d017-432e-a8fb-5aa8f71b299f",
  "title": "User specified title",
  "process": {
    "dsl-version": "0.2.0",
    "stages": [
      {
        "initial": {
          "expect": {
            "signed-by": {
              "users": ["user1"],
              "documents": ["doc1"]
            }
          },
          "actions": [
            {
              "notify": {
                "users": ["user1"],
                "methods": {
                  "email": "msg1"
                }
              }
            }
          ]
        }
      }
    ]
  },
  "process_parameters": {
    "documents": {
      "doc1": "3"
    },
    "users": {},
    "messages": {}
  },
  "callback": null,
  "created": "2021-03-08T10:32:35.512844Z",
  "author_id": "1",
  "folder_id": "2"
}

Components of a draft​

Metadata​

The title field​

Currently, the only user-specified metadata which we associate with a draft is the title value. This need not be unique either globally, or within your own drafts. It's simply designed to be an identifier that you can set in order to distinguish one process from another.

Our system does not make use of this value in any way internally.

The created field​

This is an auto-generated piece of metadata that tracks when the draft was created. Its purpose is pretty self-explanatory and it can't be set by the user.

The author_id field​

This field records the ID of the Scrive user who created the draft. It is fixed and cannot be changed. We don't support the notion of transferring ownership of a draft.

Process description​

We describe our process in terms of the Flow DSL. This language is a subset of the JSON standard. We provide the DSL process description as a JSON object subtree within this field.

Process parameters​

These are the values that are needed in order to start an instance from a draft. These must correspond to the values that are in the process description in order to be able to start the instance.

For example, in the example above, the process DSL contains the variables doc1, user1 and msg1. However, our process_parameters object only contains a definition for doc1. Therefore, will will need to update the process_parameters or provide the missing values when calling the /start endpoint.

Callback​

The example above does not have a defined callback. However, if you would like to set up an endpoint within your own system that we can call with information about events that occur during execution of the instance, then you can do it here. See Callbacks for more details.

The folder_id field​

This field is used to determine what folder the draft will be created into. You may set this, providing that you have sufficient permissions on the target folder.

The folder ID is important in that it will determine who can view this draft or start instances from it. It also will determine which folder, by default, any new created instances are created in.