Skip to main content

The DSL explained

DSL is short for Domain Specific Language. DSLs contrast with General Purpose Languages in that they are designed explicitly to be good at one thing and one thing only. If they turn out later to be useful in other contexts, this is by accident rather than design.

Our DSL is the core of the Scrive Flow system. At its heart it is a simple language based on the existing JSON standard which allows a user to describe an e-signing workflow. We'll also use the term "process" here interchangeably.

Sample of a valid Flow DSL process​

{
  "dsl-version": "0.2.0",
  "stages": [
    {
      "user-stage": {
        "actions": [],
        "expect": {
          "signed-by": {
            "users": ["user"],
            "documents": ["doc1", "doc2"]
          }
        }
      }
    },
    {
      "viewer-stage": {
        "actions": [
          {
            "allow-viewing": {
              "users": ["viewer"],
              "documents": ["doc1", "doc2"]
            }
          },
          {
            "notify": {
              "users": ["viewer"],
              "methods": {
                "email": "viewer-message"
              }
            }
          }
        ],
        "expect": {}
      }
    },
    {
      "author-stage": {
        "actions": [
          {
            "notify": {
              "users": ["author"],
              "methods": {
                "email": "author-message"
              }
            }
          }
        ],
        "expect": {
          "signed-by": {
            "users": ["author"],
            "documents": ["doc1", "doc2"]
          }
        }
      }
    },
    {
      "confirmation-stage": {
        "actions": [
          {
            "notify": {
              "users": ["user"],
              "kind": "confirmation",
              "methods": {
                "email": "user-message"
              }
            }
          }
        ],
        "expect": {}
      }
    }
  ]
}

Root fields​

dsl-version​

This field is simply there to allow us to make changes to the schema at a later date. We will support older versions for a specific period of time. See API Lifecycle for details. In practice, currently, you can simply set it to 0.2.0 and not worry about it.

stages​

This field is where we store the actual information about our Flow e-signing workflow. It takes the form of a list of objects. Each object will have a single key determining the user-defined name of the stage. In the example above, we have the names user-stage, author-stage, confirmation-stage but these could be any text string that you feel best describes what occurs at this stage and which JSON would accept as a valid name.

Stages are executed in linear order from top to bottom. In future, we will likely allow more complex structures that include possibilities such as conditional branching and parallel stage execution.

Kinds of stage​

Regular stages​

These are the kinds of stage that you're already familiar with. They determine a step within the e-signing workflow. We'll not go into too much detail here given that familiarity. They stand in contrast to the confirmation stage.

The confirmation stage​

The confirmation stage is a special kind of stage. If it is present, the confirmation notification settings from the documents will be overridden in favour of a unified flow confirmation email, which links to the overview page.

Here is an example of a confirmation stage:

{
  "confirmation-stage": {
    "actions": [
      {
        "notify": {
          "users": ["user1"],
          "kind": "confirmation",
          "methods": {
            "email": "msg1"
          }
        }
      }
    ],
    "expect": {}
  }
}

What sets it apart from a regular stage is that is has kind: notification in the notify action object.

There must be at-most one of these stages in the process description, and it must occur as the final stage.

Components of a stage​

Each stage is primarily defined by two things:

  • What automatic actions are performed by the Scrive Flow system when we enter the stage?
  • What are the conditions by which a stage is considered to have been completed, allowing execution to proceed to the next stage?

actions​

An action contains a list of instructions to the Scrive Flow system to perform some specific task when the stage is entered. In the example above, author-stage and confirmation-stage both require that we send out some kind of communication to particular participants. viewer-stage gives viewing permissions to a viewer participant and sends out a specific notification to inform them about it. user-stage does not perform any actions and instead simply waits for the conditions by which it can move to the next stage.

expects​

These are the explicit conditions that will cause a stage to be considered complete. Until all of the conditions specified in expects are fulfilled, further execution of the process is not possible.

In the example above, user-stage awaits confirmation that user has signed both doc1 and doc2. The ordering is not important. user will be presented with the opportunity to sign both doc1 and doc2 when arriving at the overview page.

Types of action​

Internally, there are many kinds of action, but many of these are executed implicitly and are not available for configuration. An example of an internal action would be the special action which we use in order to schedule documents for sealing once all participants have signed / approved / etc.

Some of these may be exposed for broader user-configuration in the future, and yet other new actions will likely be included which the Flow user will have control over.

For now though, the only actions that we allow you to explicitly configure in the DSL relate to sending out (email and/or SMS) communications to participants, or managing viewing permissions in the e-signing workflow.

Standard notify actions​

notify actions are a substitute for sending out the access links contained in the instance JSON response via your own means. If you would like Scrive to send out emails and/or SMSs to specific participants, then you can delegate that task to us via a notify action.

note

Take care, when specifying the process, that you expect the participant to possess all of the communication details required by the notify action.

For example, if you later try to instantiate a process that sends out email notifications with a participant who is identified by only phone number, you will receive an API error.

Special confirmation kind notify actions​

See section on the Confirmation Stage above.

Viewing permissions​

The allow-viewing and deny-viewing actions allow you to add and remove viewers in a Flow. A viewer is a participant that has viewing access to a document. The deny-viewing action is used to remove a viewing permission previously assigned.

Types of expects conditions​

There are a large number of possible conditions that can be asserted. The majority of them are related to actions to be performed by a participant upon a document. Like actions, there are some internal kinds of implicit expects values, but these will not affect the execution of your user-defined DSL stages.

Some of those internal expects types may be exposes for configuration one day, and others are likely to be added. For now though, Flow users can configure the following kinds of expects conditions:

approved-by​

This condition specifies that one or more specific users must approve one or more specific documents in order for the condition to be fulfilled. All the users must approve all the documents in order to fulfil the condition.

signed-by​

This condition specifies that one or more specific users must sign one or more specific documents in order for the condition to be fulfilled. All the users must sign all the documents in order to fulfil the condition.

approved-by-group-of​

This condition specifies that one or more specific users must approve one or more specific documents in order for the condition to be fulfilled. For each listed document, only a specific number of approvals is required. This is different to approved-by, where All of the listed users must approve. The required number of approvers is given by the key "required-approvals".

For example, to require approvals from two of the listed users:

"approved-by-group-of": {
  "required-approvals": 2,
  "users": ["author", "user1", "user2"],
  "documents": ["doc1", "doc2"]
}

Note that this condition is satisfied when any two users approve each document. For example, "doc1" could be approved by "author" and "user1", and "doc2" could be approved by "user1" and "user2".

signed-by-group-of​

This condition specifies that one or more specific users must sign one or more specific documents in order for the condition to be fulfilled. For each listed document, only a specific number of signatures is required. This is different to signed-by, where All of the listed users must sign. The required number of signatures is given by the key "required-signatures".

For example, to require signatures from two of the listed users:

"signed-by-group-of": {
  "required-signatures": 2,
  "users": ["author", "user1", "user2"],
  "documents": ["doc1", "doc2"]
}

Note that this condition is satisfied when any two users sign each document. For example, "doc1" could be signed by "author" and "user1", and "doc2" could be signed by "user1" and "user2".

viewed-by​

danger

viewed-by is deprecated and will be removed from the DSL soon.

You should not use this condition. Its behaviour is unspecified and likely to lead to errors and stuck processes. Please use the allow-viewing and deny-viewing actions instead.

This action specifies that one or more specific users must view one or more specific documents in order for the condition to be fulfilled. All the users must view all the documents in order to fulfil the condition.

redirect-to​

This condition specifies that one or more users will be redirected to a specific URL. A redirect-to condition for a user can only be combined with one or more document related conditions. Assigned users will be redirected after they successfully completed all their document related actions for the stage. Users are not redirected after rejecting a process and all redirections will be performed to the same website. The redirect URL is given by the key "url".

example with non-group conditions​

"approved-by": {
  "users": ["user1"],
  "documents": ["doc1"]
},
"signed-by": {
  "users": ["user2", "user3"],
  "documents": ["doc1"]
},
"redirect-to": {
  "users": ["user1", "user2"],
  "url": "https://www.example.com/"
}

In this example, user1 will be redirected after they have approved doc1 and user2 will be redirected after they sign doc2. user3 is not in the list of users to be redirected and so they will not be redirected.

example with group-of conditions​

"signed-by-group-of": {
  "required-signatures": 2,
  "users": ["author", "user1", "user2"],
  "documents": ["doc1"]
},
"redirect-to": {
  "users": ["user1", "user2"],
  "url": "https://www.example.com/"
}

In this example, user1 and user2 will only be redirected if they are within the group of 2 participants that have signed the document. author will not be redirected as they are not in the redirect list.

example with validation errors​

"redirect-to": {
  "users": ["user1"],
  "url": "https://www.example.com/"
}
"approved-by": {
  "users": ["user1"],
  "documents": ["doc1"]
},
"redirect-to": {
  "users": ["user2"],
  "url": "https://www.example.com/"
}

In the above examples both process will not be validated as user1 in the first example and user2 in the second do not participate in a document expect condition in the respective stages.