forio Toggle navigation

Model State API

The Model State API brings an existing, persisted run from the database back into memory. Runs must be in memory in order for you to update variables or call operations on them.

Using this API assumes some knowledge about how runs are stored. See more information on run persistence.

In particular, the implementation of the Model State API works by "re-running" the run (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 HTTP methods:

POST: Replaying or Cloning a Run from the Database

Use the Model State API POST method to bring a run from the database back into memory.

Replaying a Run: Bring Back into Memory with the Same Run ID

Runs are automatically replayed whenever you attempt to update variables (PATCH) or call operations (POST).

Method: POST

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

Headers: Content-Type: application/json, Authorization: Bearer{access token}

Body: JSON object with the following 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 run advances through all of the decisions and operations except for the named operations. (Typically this field is only used with an action of clone.)

Return Status: 200 (successful response)

Return Body: The original run id and action.

Example:

curl -X POST \
    'https://api.forio.com/model/state/1723b97f-80c5-4d35-80cb-6d5cafddbcb6' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{"action": "replay"}'

Example Response:

{
    "run": "1723b97f-80c5-4d35-80cb-6d5cafddbcb6",
    "action": "replay"
}

Notes:

  • The run, with its original run id, is now available in memory. (It continues to be persisted into the Epicenter database at regular intervals.)

  • Including stopBefore in the body means that when the run id is retrieved from the database, the run is advanced only up to the first occurrence of that method. For example:

      {"action": "replay", "stopBefore": "step"}

    advances the run up to the first call of the step() operation. The step() operation is not called.

  • The stopBefore parameter is IGNORED if the model's context file has restoreMode set to SNAPSHOT.
    • A restoreMode of SNAPSHOT means that the run is instead restored only by copying in variables that have a restore attribute of true in the model's context file. Specific end user inputs and operations are NOT replayed.
    • See additional information on Model Context files.
  • 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!

Cloning a Run: Bring Back into Memory with a New Run ID

Method: POST

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

Headers: Content-Type: application/json, Authorization: Bearer{access token}

Body: JSON object with the following 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.

Return Status: 200 (successful response)

Return Body: The new run id and action.

Example:

curl -X POST \
    'https://api.forio.com/model/state/1723b97f-80c5-4d35-80cb-6d5cafddbcb6' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{"action": "clone"}'

Example Response:

{
    "run": "54e3c529-49cb-45d1-a412-0f86af492a88",
    "action": "clone"
}

Notes:

  • The original run remains only in the database.
  • 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 false but may change to true as the new run is advanced. For example, if there has been a call to the step function (for Vensim models), the initialized field is set to true.

  • In the body, including stopBefore means that when the new run id is created, that run advances only up to the first occurrence of that method. For example:

      {"action": "clone", "stopBefore": "step"}

    advances the new run up to the first call of the step() operation. The step() operation is not called.

  • The stopBefore parameter is IGNORED if the model's context file has restoreMode set to SNAPSHOT.
    • A restoreMode of SNAPSHOT means that the run is instead restored only by copying in variables that have a restore attribute of true in the model's context file. Specific end user inputs and operations are NOT replayed.
    • See additional information on Model Context files.

  • In the body, including exclude means that when the new run id is created, that run replays all of the decisions and operations except for the named operations. For example:

      {"action": "clone", "exclude": ["step"]}

    calls all operations except for step(). 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.

  • 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

Method: GET

URI: /model/state/{run id}

Headers: Authorization: Bearer{access token}

Return Status: 200 (successful response)

Return Body: An array of actions that have occurred for this run since its creation. Each action includes a type, date, and data. Some actions also include a command.

Example:

curl -G \
    'https://api.forio.com/model/state/e2210f6a-3f39-44a0-8778-9dd55c185ff9' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9'

Example Response:

[
   {
       "type": "EVENT",
       "command": "initialize",
       "date": "2014-10-30T17:06:57.578+0000"
   },
   {
       "type": "OPERATION",
       "command": "addToInt",
       "data": [
           3
       ],
       "date": "2014-10-30T17:07:10.478+0000"
   },
   {
       "type": "VARIABLE",
       "data": {
           "sampleString": "new string"
       },
       "date": "2014-10-30T17:09:33.035+0000"
   }
]

Notes:

  • The action types are:

    • EVENT: System actions for this run. Typically only initialize.
    • OPERATION: A call to a method from the model, for example using the Model Operation API or one of the APIs built on top of it (for example, Run API or Flow.js).
    • VARIABLE: The update of a model variable due to a call to the Model Variable API or one of the APIs built on top of it (for example, Run API or Flow.js).

  • For an OPERATION, a command is also included in the action listing. This is the name of the operation (method) called from the model.

  • The date is a timestamp in ISO 8601 format.
  • The array of actions is automatically paged, with a default page size of 1000.

Paging: Retrieving Many Records at Once

When you use the GET method for an API, your request may return many records at once.

The default page size is 100 (for most APIs) or 1000 (for the Data API). You can limit the number of records returned by adding the Range header.

Method: GET

URI: Any Epicenter API call

Headers: Range: records {i}-{j}

Return Status:

  • 200: Successfully retrieved all records
  • 206: Successfully retrieved the partially complete response, for example if you request records 0-20 and there are 35 records
  • 416: No records are found in a given search range (e.g. Range: records 10-15 when there are only 8 records)

Response Headers:

Whether or not you add the Range header to your request, the response header contains:

Content-Range: records i-j/k

where

  • i is the index of the first record returned
  • j is the index of the last record returned
  • k is the total number of records in the result set, or * if that number is computationally infeasible (for example, because you are querying across multiple projects)

For example, Content-Range: records 0-9/57 or Content-Range: records 20-29/*.

Response Body: An array of records. The array includes only those records indicated in the Content-Range header.

Example:

curl -G \
    'https://api.forio.com/v2/EpicenterAPI' \
    --header 'Range: records i-j'

Notes:

  • If no records are returned, the response body is empty.

  • If you leave off the start index, this is considered an implied start index of 0 rather than an invalid range. The response header includes status code of 200 or 206 depending on the ending index.

  • This use of the Range header is part of the RFC 2616 (see details in Section 14.16 and 14.35).

OPTIONS: View Reference Information about the API

For any Epicenter API, use the OPTIONS method to view reference information on properties and arguments of that API.

View Reference Information about the API

Method: OPTIONS

URI: /model/state

Example:

curl -X OPTIONS 'https://api.forio.com/model/state'