Model State API

The Model State API brings an existing, persisted run from the database back into memory, either with the same id ("replay") or with a new id ("clone").

Runs must be in memory in order for you to update variables or call operations on them. Runs are automatically brought back into memory if you include the X-AutoRestore: true header, which is included by default for updating variables and calling operations. You can also use the Model State API to do this on demand.

The general implementation of the Model State API works by "re-running" the user interactions from the creation of the run up to the time it was last persisted in the database. This process uses the current version of the run's model. Therefore, if the model has changed since the original run was created, the retrieved run will use the new model — and may end up having different values or behavior as a result. Use with care!

The Model State API supports the following methods:

POST
GET
- View History of a Run

The Model State API operates on the following resources / data structures:

Run State record
Run History record

POST

Use the Model State API POST method to bring a run from the database back into memory, either with the same run id or a new one.

Replay a Run, using REPLAY mode

Replaying a run brings the run back into memory with the same run id. Runs are automatically replayed whenever you attempt to update variables (PATCH) or call operations (POST).

The default "mode" to bring a run back into memory is REPLAY.

REPLAY mode means that when a run is restored, all of the end user interactions, from the creation of the run up to the time it was last persisted in the database, are re-run. (This can make replay slow for complex models, and in some cases is not necessary. Consider using SNAPSHOT mode for replays instead. See below.)

Method: POST

URI:

/v2/model/state{original run id}

Headers:

Content-Type: application/json
Authorization: Bearer{access token}
- This can be either the user access token of any user (team member or end user) with access to the run, or the project access token for the project.

Body: JSON object with the required fields:

action: Required, set to replay.
stopBefore: Optional, set to {name of operation}. If included, the run advances only up to the first occurrence of this method.
exclude: Optional, set to array of {name of operation}. If included, the all of the decisions and operations are replayed except for the named operations.
For more information on the fields, see the Run State record.

Return Status:

200: Successful response, run retrieved from memory and replayed as specified.
500: Error, for example mismatched restore modes

Return Body: A JSON object with the action from the request body, as well as a run field whose value is the (existing) run id. See the Run State record for complete details.

Example:

curl -X POST \
    'https://api.forio.com/v2/model/state/00000152fbfbeae5d4e225640aebaef9a156' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{ "action": "replay", "stopBefore": "final_operation" }'

Example Response:

{
    "run": "00000152fbfbeae5d4e225640aebaef9a156",
    "action": "replay"
}

Notes:

The replay is done in REPLAY mode by default. This occurs when:
- There is no model configuration file;
- Or, the model configuration file's restoreMode parameter is not present;
- Or, the model configuration file's restoreMode parameter is present and set to REPLAY.
It is an error (mismatched restore mode) if the body of the request conflicts with the model's configuration file. For example, if the model configuration file has restoreMode set to SNAPSHOT, then stopBefore and exclude parameters both conflict with the configuration file — so if included, they cause an error. (See also Replay with Snapshot, below.)
CAUTION: Because this action reuses the original run id, in some cases, calling replay with stopBefore can have the side effect of overwriting data that was previously stored. For example: if the run called step three times, was stored in the database, and was replayed with a stopBefore of step, then the next time that step is called, the (original) first step information is updated, and so is overwritten. Use with care!
CAUTION: If the model for this run has changed since the original run was created, the replayed run will use the new model when it is advanced. If the model is different, some data stored in the run may be overwritten because the results of operations are different. Use with care!

Replay a Run, using SNAPSHOT mode

Replaying a run brings the run back into memory with the same run id. Runs are automatically replayed whenever you attempt to update variables (PATCH) or call operations (POST).

The default "mode" to bring a run back into memory is REPLAY. (See Replay with REPLAY mode, above).

The alternate "mode" to bring a run back into memory is SNAPSHOT.

SNAPSHOT mode means that the run is restored ONLY by copying in variables that have a restore attribute of true in the model's context file (.ctx or .cfg) file. Specific end user inputs and operations are NOT replayed.

The Model State API call for replaying a run using SNAPSHOT mode is identical to replay using REPLAY mode. Only the model context file is different.

Method: POST

URI:

/v2/model/state{original run id}

Headers:

Content-Type: application/json
Authorization: Bearer{access token}
- This can be either the user access token of any user (team member or end user) with access to the run, or the project access token for the project.

Body: JSON object with the required fields:

action: Required, set to replay.
For more information on the fields, see the Run State record.

Return Status:

200: Successful response, run retrieved from memory and replayed as specified.
500: Error, for example mismatched restore modes

Return Body: A JSON object with the action from the request body, as well as a run field whose value is the (existing) run id. See the Run State record for complete details.

Example:

curl -X POST \
    'https://api.forio.com/v2/model/state/00000152fbfbeae5d4e225640aebaef9a156' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{ "action": "replay" }'

Example Response:

{
    "run": "00000152fbfbeae5d4e225640aebaef9a156",
    "action": "replay"
}

Notes:

The Model State API call for replaying a run using SNAPSHOT mode is identical to replay using REPLAY mode. Only the model configuration file is different.
It is an error (mismatched restore mode) if the body of the request conflicts with the model's configuration file. For example, if the model configuration file has restoreMode set to SNAPSHOT, then stopBefore and exclude parameters both conflict with the configuration file — so if included, they cause an error.
CAUTION: If the model for this run has changed since the original run was created, the replayed run will use the new model when it is advanced. If the model is different, some data stored in the run may be overwritten because the results of operations are different. Use with care!

Clone a Run

Cloning a run allows you to bring an existing run back into memory with a new run id.

Method: POST

URI:

/v2/model/state/{original run id}

Headers:

Content-Type: application/json
Authorization: Bearer{access token}
- This can be either the user access token of any user (team member or end user) with access to the run, or the project access token for the project.

Body: JSON object with the required fields:

action: Required, set to clone.
stopBefore: Optional, set to {name of operation}. If included, the new run advances only up to the first occurrence of this method.
exclude: Optional, set to array of {name of operation}. If included, the new run replays all of the decisions and operations except for the named operations.
For more information on the fields, see the Run State record.

Return Status:

200: Successful response, new run created
500: Error, for example mismatched restore modes

Return Body: A JSON object with the action from the request body, as well as a run field whose value is the new run id. See the Run State record for complete details.

Example:

curl -X POST \
    'http://api.forio.com/v2/model/state/00000152fbfbeae5d4e225640aebaef9a034' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{ "action": "clone", "stopBefore": "final_operation" }'

Example Response:

{
    "run": "00000152fbfbeae5d4e225640aebaef9a057",
    "action": "clone"
}

Notes:

After this request, the new run id is now available in memory. The new run includes a copy of all of the data from the original run, EXCEPT:
- The saved field in the new run record is not copied from the original run record. It defaults to false.
- The initialized field in the new run record is not copied from the original run record. It defaults to true.
- The user information for the new run is from the user that requested the clone, not the user on the original run record.
It is an error (mismatched restore mode) if the body of the request conflicts with the model's configuration file. For example, if the model configuration file has restoreMode set to SNAPSHOT, then stopBefore and exclude parameters both conflict with the configuration file — so if included, they cause an error. (See also Replay with Snapshot, above.)
CAUTION: If the model for this run has changed since the original run was created, the cloned run will use the new model when it is created and advanced. This means the cloned run may end up having different values than the original run, because the results of operations are different. Use with care!

GET

View History of a Run

You can view the history of a run using the Model State API GET method.

Method: GET

URI: /v2/model/state/{run id}

Headers:

Authorization: Bearer{access token}
- This can be either the user access token of any user (team member or end user) with access to the run, or the project access token for the project.

Body: None

Return Status:

200: Successful response

Return Body: An array of actions that have occurred for this run since its creation.

Example:

curl -G \
    'https://api.forio.com/v2/model/state/000001533965543534cd21a606beb8fe8b61' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

[
    {
        "created": "2016-03-03T22:20:17.279Z",
        "json": {
            "command": {
                "set": {
                    "actions": [
                        {
                            "mode": "LEGACY",
                            "value": "3",
                            "name": "radius"
                        }
                    ]
                }
            }
        }
    },
    {
        "created": "2016-03-03T22:20:36.502Z",
        "json": {
            "command": {
                "proc": {
                    "actions": [
                        {
                            "arguments": "[12]",
                            "name": "estimate"
                        }
                    ]
                }
            }
        }
    }
]

Notes:

The history of a run that has been cloned or replayed (either in replay mode or snapshot mode) is always listed in the response in its entirety. For example, if the run has been cloned or replayed with a stopBefore parameter, all of the actions that have occurred for the run appear in the history — including those after the operation named by the stopBefore parameter.

Data Structure

The Model State API operates on the Run State record and the Run History record.

Run State record

The Run State record is returned with any POST request to replay or clone a run.

Field	Required?	Description
`run`	yes	The identifier of the run. (You can use this to retrieve complete details of the run.)
`action`	yes	The type of action selected: "replay" or "clone."
`stopBefore`	no	The name of a model operation. Including `stopBefore` means that when the run is replayed (either with a new run id or with the same run id), it advances only up to the first occurrence of this model operation. Optional during the `POST` request for clones or replays.
`exclude`	no	An array of model operation names. Including `exclude` means that when the run is replayed (either with a new run id or with the same run id), it replays all of the decisions and operations except for the named operations. Optional during the `POST` request for clones or replays. In practice, this is used when you want to allow an end user working with your project to "play again" starting with the final decisions from a previous run.

**Example Run State Record**

An example Run State record returned as a response to a POST request:

{
    "run": "000001533965543534cd21a606beb8fe8b61",
    "action": "replay"
}

Run History record

The GET request for the history of a run returns an array of run history records.

Field	Required?	Description
`created`	yes	When the action occurred. This is a timestamp in ISO 8601 format.
`json`	yes	An enclosing JSON object for this element of the run's history.
`json.command`	yes	A JSON object describing the command (action) that occurred for the run.
`json.command.proc`	no	A description of a model operation that occurred for the run. Includes one element, `actions`, which is an array of objects describing the model operation as called during the `POST` request: each includes `name` and `arguments`.
`json.command.set`	no	A description of a model variable update that occurred for the run. Includes one element, `actions`, which is an array of objects describing the model variable update as called during the `PATCH` request: each includes `name` and `value`. The array element also includes a field `mode` with value `LEGACY` which is used only for internal system versioning purposes; it can be safely ignored.

**Example Run History Record**

An example of a Run History record returned as part of the response to a GET request:

{
    "created": "2016-02-22T18:21:56.815Z",
    "json": {
        "command": {
            "proc": {
                "actions": [
                    {
                        "arguments": "[100]",
                        "name": "estimate"
                    }
                ]
            }
        }
    }
}

Note that the response to GET request is always an array of Run History records.