What is an instance?
An instance is a running Scrive Flow e-signing workflow. This is the core of the Scrive Flow system. It contains all of the information about the running process. The information includes the process as described using our DSL. It includes the current state of execution. It includes all of the access links which can be used to invite the participants to come and fulfil their roles in the e-signing workflow. It also includes various pieces of metadata about who owns the instance, when it was created, etc.
We will go through all these components in detail in this article.
Example of an instance as returned by the API
{
"id": "b91b18b3-b3ac-4eee-bea1-8ce7ee5a546b",
"title": "to the moon",
"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": {
"user1": {
"id_type": "user_id",
"id": "1",
"auth_to_view": null,
"auth_to_view_archived": null
}
},
"messages": {
"msg1": "foobar"
}
},
"state": {
"available_actions": [
{
"type": "sign",
"user": {
"id_type": "user_id",
"id": "1"
},
"document": "3"
}
]
},
"access_links": {
"user1": "https://scrive.com/experimental/flow/overview/b91b18b3-b3ac-4eee-bea1-8ce7ee5a546b/user1/aeb5b7a6e74a0251"
},
"status": "in_progress",
"started": "2021-03-08T11:47:31.045949Z",
"last_event": "2021-03-08T11:47:31.045949Z",
"callback": null,
"author_id": "1",
"folder_id": "2"
}
Metadata
Metadata fields generally tell you something about the instance. You cannot directly set these values for the most part (one exception being folder_id). The values are generally fixed at instance-creation (e.g. id and started) or will change automatically as the we step through the e-signing workflow (e.g. status and last_event).
id
This field is fairly trivial. It is simply an auto-generated UUID value that is used to uniquely identify a given instance when dealing with our API.
title
This field is user-specifiable. The title field has no inherent meaning and is not used for anything other than providing a human-readable name for the instance. You may leave this as null, set it at instance creation, or edit its value during execution. It's up to you, this field is for human use only.
started
This is simply the datetime that the instance was started. It is expressed in ISO 8601 format.
last_event
This is simply the datetime that the last event was received. It is expressed in ISO 8601 format. Events are, generally speaking, when the instance was started or whenever a sign/approve/etc action is completed within the e-signing workflow.
author_id
This corresponds to the Scrive user ID of the person who set up and started the instance from its Draft (whether via API or web interface). Author cannot be set manually (i.e. you cannot create an instance which would then be owned by another user, no matter your permissions upon that user).
folder_id
It is permissible to set this field. It will be set, by default, as the home folder of the instance's author. You may transfer the instance to another folder, however, as long as you possess the required permissions to do so.
See the Access Control section of the main Scrive API docs for further details.
Process description and parameters
These fields contain all of the specific information about the e-signing workflow which is being executed by the instance. Taken together they give a complete picture of the process, the participants and the documents involved.
process
process_parameters
As a general description. This contains all of the values which are required to "fill out" the variables in the DSL process description. This object provides a mapping of how to, for example, populate user1 into a concrete participant. It is a fixed carbon copy of the values which were provided when the instance was started. See the Getting Started article about starting an instance for more details.
Current instance state
status
Here we have a low-resolution view of the current state of execution for the instance:
in_progressfinalisingcanceledrejectedcompletedfailed
These are all somewhat self-explanatory. The only one that perhaps needs some explanation is finalising. This status means that all participants have performed their required actions. The instance's execution is now essentially complete. The only thing that remains is for the Scrive Flow system to perform some automated actions to finalise the various documents and the instance itself. When these have completed, the instance will move into completed state automatically.
state
This field contains a list of all the actions that are currently available to be performed by any of the participants. For example, if you expect that user1 should sign doc3 in the first stage, and you are currently in the first stage, then you will see something similar to what is shown in the example above.
The is not currently a way to directly determine the name of the stage that the instance's execution is within. We will likely rectify this in future.
Access Links
access_links
The access links are provided so that, if you decide not to use Scrive's own notification email/sms systems, you may take the access links and send them out to the various participants yourself.
Following one of these links will set up a cookie that identifies you as the correct participant and takes you to the overview page. Obviously, if required by the instance configuration, you may be need to perform further authentication before you actually see the overview page.
Callbacks
callback
What is stored in this field is a fixed carbon copy of the callback value which was provided when the instance was started. See the How-to article about Callbacks for more details.