World Modeler Server API Programmers Reference Section 1

7. Assets

While much can be achieved through the features supported by Decision Models, their evaluations, and simulations, just using those features alone would result in a closed and rigid system, which are rarely found in the real world. World Modeler™ offers an Assets based workflow which encapsulates the connections between a decision model and real world data. Each asset represents either a form of data or an operation performed on that data, and are made available to the expressions that compose a decision model.

Assets in World Modeler™ are perfectly analogous to a computer's file system, containing both directories and several different types of files. The types of assets currently supported and their properties can be seen below.

Asset Type	Purpose
AssetDirectory	AssetDirectories make up the folder structure of the Assets file system. Correspondingly they, and all of the files contained, follow many of the same rules we are accustomed to when using computer file systems.
DataSource	DataSources make up the actual data that is used in World Modeler™, but don't contain any data themselves. Through encrypted accessor strings, DataSources access data managed on separate servers. DataSources also come in several different types depending on the data they embody. (SQL server, Excel spread sheet, etc...)
DataReader	DataReaders represent operations performed on DataSources. This can involve querying an SQL server or returning a selection of cells from an Excel worksheet. The operation itself is highly dependant on the DataSource in question.
Model	Models contain the data, or pointers to data, necessary to instantiate and perform inferences on input data.
DataWriter*	DataWriters encompass write operations on DataSources
WMLLM	LLM(Large Language Model) assets can be learned about in section 8

* Not currently implemented

AssetDirectories

As mentioned in the above table, AssetDirectories are completely analogous to a computer's file system. This means that directories follow the following rules:

Every directory (and file) has a parent directory, with exception to the Root directory which is defined in code, rather than in the database.
Every directory (and file) can uniquely be determined through ID (a unique GUID) and FullPathName (/Path/To/Asset), which is made up of the names of the asset, and all of their parents', separated by the standard separator character '/'.
Every asset with the same parent must have a unique name, however it does not matter what the names of their parent and children files are.
If a directory is moved to a different location or deleted, all child directories and files will also be moved or deleted.
Directories have ownership, and are only visible to the user or organization that owns them.

When sent to and from World Modeler™ via the REST API, AssetDirectories are represented with JSON strings as follows:

      {
         "id": "unique_GUID",
         "name": "unique_name_among_siblings",
         "summary": "Short summary of this directory",
         "documentation": "string",
         "documentationMIMEType": "string",
         "parent": "/Path/To/Parent"
      }

Note that "parent" may be either the unique ID of the parent, or the FullPathName of the parent. When returned to the user, this json will have the additional field "members", which will contain a list of child directories and files.

AssetDirectories support the following REST API endpoints. Note that all {dir} parameters accept both the unique ID of the directory, as well as the URL encoded FullPathName of the directory. Only directories owned by the user or affiliated organizations can be accessed,

Method	Operation	Description
GET	`/assetDirectory?depth={depth}`	Retrieve all directories and their files to the specified {depth}, starting from the root directory. A depth argument of 0 will return only the root directory, a depth argument of -1 will return all directories. Each directory returned will also return populated with all non-directory assets.
GET	`/assetDirectory/{dir}?depth={depth}`	Retrieve all directories and their files to the specified {depth}, starting from the directory specified with {dir}. A depth argument of 0 will return only the specified directory, a depth argument of -1 will return the specified directory and all of its child directories. Each directory returned will also return populated with all non-directory assets.
POST	`/assetDirectory`	Creates a new directory according to the supplied JSON string. (see above) Note that the ID of the supplied JSON will be checked for uniqueness, and will fail if not unique. If the ID is not supplied, or left blank, a GUID will be generated.
PUT	`/assetDirectory/{dir}`	Updates the directory specified with {dir} according to the supplied JSON string. (see above)
DELETE	`/assetDirectory/{dir}`	Deletes the directory specified with {dir}.

Data Sources

DataSources being an asset follow many of the rules mentioned in the AssetDirectory section. They are considered a file of the filesystem, and will be returned whenever their parent directory is requested via the Rest API. DataSources also have the following properties:

Every DataSource possesses an accessor string. This string is the instruction on how to access the resource held by the DataSource, and is specific to the type of DataSource. An example is the SQLServer DataSource, which uses a connection string as instruction for how to access the SQL server database.
Every DataSource has a type, referred to as the registeredType, which specifies how the accessor string should be formatted, and how the resource should be read.

All of the supported registeredType's are as follows

Registered Type	Accessor	Description
SQLServer	connection string	This DataSource is an SQL server, it should be accessed with a connection string pointing to the server's location with the necessary login information, and all reader queries should be formatted as SQL queries.

Given the confidential nature of accessor strings, which are a means of directly accessing a client resource, all accessor strings are AES 256 encrypted when stored in the database, and are returned hidden when a data source is retrieved. accessor strings can be retrieved and modified by an individual with the correct credentials via alternate REST API endpoints.

When sent to and from World Modeler™ via the REST API, DataSources are represented with JSON strings as follows:

      {
         "id": "unique_GUID",
         "name": "unique_name_among_siblings",
         "summary": "Short summary of this data source",
         "documentation": "string",
         "documentationMIMEType": "string",
         "parent": "/Path/To/Parent",
         "connectionString": "accessor string",
         "registeredType": "SQLServer"
      }

Note that "parent" may be either the unique ID of the parent, or the FullPathName of the parent.

DataSources support the following REST API endpoints. Note that all {dir} parameters accept both the unique ID of the directory, as well as the URL encoded FullPathName of the directory. Only sources owned by the user or affiliated organizations can be accessed,

Method	Operation	Description
GET	`/dataSource`	Retrieve all data sources the user has access to.
GET	`/dataSource/{dir}`	Retrieve the data source specified by {dir}.
POST	`/dataSource`	Creates a new data source according to the supplied JSON string. (see above) Note that the ID of the supplied JSON will be checked for uniqueness, and will fail if not unique. If the ID is not supplied, or left blank, a GUID will be generated.
PUT	`/dataSource/{dir}`	Updates the data source specified with {dir} according to the supplied JSON string. (see above)
DELETE	`/dataSource/{dir}`	Deletes the data source specified with {dir}.
GET	`/dataSource/{dir}/accessorString`	Retrieves the accessor string of the data source specified by {dir} as plaintext.
PUT	`/dataSource/{dir}/accessorString`	Updates the accessor string of the data source specified by {dir} according to the supplied JSON string. The supplied json should have a single property "accessorString", whose value is set to the data source's accessor string.
POST	`/dataSource/evaluate/{dir}`	Performs an evaluation according to the supplied JSON string. (see below)
POST	`/dataSource/{id}/openTransaction`	Open a new transaction in the data source with the specified `id` (if supported by the data source type). (see below)
POST	`/dataSource/commitTransaction{xid}`	Commit the transaction with ID = `xid`, as genrated by `openTransaction`. (see below)
POST	`/dataSource/rollbackTransaction{xid}`	Roll back the transaction with ID = `xid` as genrated by `openTransaction`. (see below)

DataSource Evaluations

Evaluations are performed through a set of arguments provided by a JSON string. Each JSON string requires the following parameter:

      {
        "SourceString": "SELECT * FROM COMPANIES",
      }

Where the form of the "SourceString" is dependant on the type of dataSource being evaluated. DataSource evaluations also have optional parameters, the optional parameters with their default values are listed below:

Here "Action" refers to the name of the action specified in the DataReader section table, "Format" refers to the format that the data should be returned in, and can be seen in the following table

      {
        "queryParameters": { },
        "Action": "ReadTable",  
        "Format": "JSON"
      }

Format	Description
JSON	The query result is returned in a JSON, hierarchical format.
CSV	The query result is formatted into CSV format, and returned as a string.

If the query requires parameters to be specified, those parameters should be specified in the optional "queryParameters" property to the evaluation JSON string.

        "queryParameters": {
            "stringParameter": "value",
            "intParameter": 2,
        }

Transaction Control in Data Sources

The World Modeler Data Binding interface can utilize transaction control for those data repositories that support it, typically relational databases.

Overview of Transactions

In a non-transaction-controlled environment, when a data-modifying operation such as an insert, update, or delete, completes, the changes to the database are immediately visible to all clients connected to the database. In addition:

There is no "undo" possible, and
A single command is "atomic". That is, in a multi-tasking, multi-user environment, when a database command begins, it will not be interrupted by another command until the operation has completed. Therefore, the command will either complete in its entirety, or fail without making any changes to the data before any other command can make changes to the database.

However, sometimes a single "logical" operation requires the update of several tables requiring several database commands. To ensure data integrity, this requires that:

The group of operations have to be treated as effectively atomic. No other command can interrupt these commands until the whole sequence has completed.
The changes cannot become publicly visible until the sequence is complete because until this is so, the database tables may be in an inconsistent state.
If an error occurs after the group of operations starts, but before it is complete, the tables must be returned to their state before the first operation in the sequence began.

This group of requirements is satisfied by the concept of a Transaction. A transaction includes a sequence of commands treating them as if they were a single command. That is:

The transaction executes atomically when it is committed
Changes made within the transaction are only visible in the client session that made the changes, until the transaction is committed
If a transaction encounters an error, the entire transaction can be "rolled back" eliminating the changes pending in the session.

The sequence of events when using transaction control is:

Open the transaction
Perform the sequence of commands within the context of the transaction
If there is no error, commit the transaction. This pushes the changes pending in the session, to the publicly visible tables.
If an error occurred, roll back the transaction.

Support for Transactions in World Modeler

The World Modeler Server REST API supports transactions via three API calls:

/dataSource/openTransaction
/dataSource/commitTransaction
/dataSource/rollbackTransaction

When a set of data source commands is to be executed as a single transaction, the following steps should be used.

1. Open New Transaction

Before making any API calls, a call should be made to /dataSource/openTransaction. This will return a string-valued token (the Transaction ID) that is then passed to the API calls that perform the data update operations. The Transaction ID ensures that each data update occurs within the transaciton associated with the given ID. The signature of the REST call is shown below.

POST /dataSource/{id}/openTransaction

Upon success, the following body will be returned, with the Transaction ID specified by the value key.

{
  "status": "Success",
  "value": "b7606bca-8735-4fe3-8740-f23129db3538",
  "message": null,
  "requestTime": "0001-01-01T00:00:00",
  "duration": "00:00:00",
  "url": "http://hostname/dataSource/ac6b24bc-58e8-4eff-80fc-a46776d44ea6/openTransaction"
}

The Transaction ID should be retained by the client so that it can be passed to subsequent data source calls, as described below.

2. Update Data in the Data Source with /dataSource/add, /dataSource/update, and /dataSource/delete commands

Actual updates to the data in the data source are made by calling /dataSource/add, /dataSource/update, and /dataSource/delete. Ordinarily, these calls will establish a new connection to the data source, execute the operation, and then close the connection. However, each of these API calls accepts an arguemnt:

"TransactionID":"string"

which is either null or a Transaciton ID obtained by calling /dataSource/openTransaction on the same data source. If not null, the operation will be performed within the transaction associated with the Transaction ID. The Transaction ID remains valid until either /dataSource/commitTransaction or /dataSource/rollbackTransaction is called, after which the transaction no longer exists and the Transaction ID can no longer be used.

3. Commit or Rollback the Transaction

When the commands that update the data within the transaction have completed, the transaction must be either committed, if the commands succeeded, or rolled back, if an error occurred during the execution of the data update operations. This is done by calling one of the two APIs, below.

/dataSource/commitTransaction{xid}

/dataSource/rollbackTransaction{xid}

where xid is the Transaction ID obtained from the call to /dataSource/openTransaction

Example

A typical usage pattern in clients using data source transactions is shown below. Assume the functions openTransaction(), commitTransaction(), and rollbackTransaction() are wrappers around the corresponding REST API invocations.

var xid = openTransaction();

try
{
    updateData({data}, xid);
    addData({data}, xid);
    deleteData({data}, xid);

    commitTransaction(xid);
}
catch()
{
    rollbackTransaction(xid)
}
xid = null;

Data Readers

DataReaders being an asset follow many of the rules mentioned in the AssetDirectory section. They are considered a file of the filesystem, and will be returned whenever their parent directory is requested via the Rest API. DataReaders also have the following properties:

Every DataReader possesses a connection to a data source, which is what it queries during evaluations. The connection to a data source is stored as the path to that data source, which means that if the data source is deleted and replaced with another, this reader will still query whichever data source is at the path originally specified.
Every DataReader possesses a source string. This is the body of the data reader's query, and is dependent on the type of data source being queried.

Every DataReader possesses an action. The action specifies how the data returned from an evaluation should be returned to the user. Actions have the following properties:

Action int	Action name	Description
0	ReadTable	The entire query is returned to the user.
1	ReadScalar	Only the first result is returned to the user. If the result is a table, only the value of the first column of the first row is returned.
2	ReadNone	Nothing is returned to the user.

When sent to and from World Modeler™ via the REST API, DataReaders are represented with JSON strings as follows:

      {
         "id": "unique_GUID",
         "name": "unique_name_among_siblings",
         "summary": "Short summary of this data reader",
         "documentation": "string",
         "documentationMIMEType": "string",
         "parent": "/Path/To/Parent",
         "dataSource": "/Path/To/DataSource",
         "action": 0,
         "sourceString": "Select * From Table"
      }

Note that "parent" may be either the unique ID of the parent, or the FullPathName of the parent. "action" makes use of the Action int specified in the above table.

DataReaders support the following REST API endpoints. Note that all {dir} parameters accept both the unique ID of the directory, as well as the URL encoded FullPathName of the directory. Only readers owned by the user or affiliated organizations can be accessed,

Method	Operation	Description
GET	`/dataReader`	Retrieve all data readers the user has access to.
GET	`/dataReader/{dir}`	Retrieve the data reader specified by {dir}.
POST	`/dataReader`	Creates a new data reader according to the supplied JSON string. (see above) Note that the ID of the supplied JSON will be checked for uniqueness, and will fail if not unique. If the ID is not supplied, or left blank, a GUID will be generated.
PUT	`/dataReader/{dir}`	Updates the data reader specified with {dir} according to the supplied JSON string. (see above)
DELETE	`/dataReader/{dir}`	Deletes the data reader specified with {dir}.
POST	`/dataReader/evaluate/{dir}`	Performs an evaluation according to the supplied JSON string. (see below)

DataReader Evaluations

Evaluations are performed through a set of arguments provided by a JSON string, however all of the arguments used in DataReader evaluations are optional.

The optional parameters with their default values are listed below:

Here "Format" refers to the format that the data should be returned in, and can be seen in the following table

      {
        "queryParameters": { },
        "Format": "JSON"
      }

class="wm-api-table"> FormatDescription JSON The query result is returned in a JSON, hierarchical format. CSV The query result is formatted into CSV format, and returned as a string.

If the query requires parameters to be specified, those parameters should be specified in the optional "queryParameters" property to the evaluation JSON string.

        "queryParameters": {
            "stringParameter": "value",
            "intParameter": 2,
        }

Models

Models being an asset follow many of the rules mentioned in the AssetDirectory section. They are considered a file of the filesystem, and will be returned whenever their parent directory is requested via the Rest API. Models also have the following properties:

Every Model possesses a source string. This string contains information needed to build the model it represents. Because models may involve sensitive information, the source string is AES 256 encrypted when stored in the database, and are returned hidden when a model is retrieved. Source strings can be retrieved and modified by an individual with the correct credentials via alternate REST API endpoints.
Every Model possesses a source mode that indicates how the source string contains the information. Currently supported modes are as follows

Source Mode Description

PlainText The source string is in a plaintext representation.
Every Model possesses a source format that indicates the type of file to deserialize. Currently supported types are as follows

Source Format Supported Models Description

PMML Decision Tree The source string is represented as an XML file using the PMML format. (https://dmg.org/pmml/pmml-v4-3.html)
Every Model has a type, referred to as the registeredType, which specifies what type of model it is, and how it should perform inferences on input data.
All of the supported registeredType's are as follows

Registered Type Description

DecisionTree This Model is a Decision Tree.

When sent to and from World Modeler™ via the REST API, Models are represented with JSON strings as follows:

      {
         "id": "unique_GUID",
         "name": "unique_name_among_siblings",
         "summary": "Short summary of this data source",
         "documentation": "string",
         "documentationMIMEType": "string",
         "parent": "/Path/To/Parent",
         "sourceString": "<PMML...",
         "sourceFormat": "PMML",
         "sourceMode": "PlainText",
         "registeredType": "DecisionTree"
      }

Note that "parent" may be either the unique ID of the parent, or the FullPathName of the parent.

Models support the following REST API endpoints. Note that all {dir} parameters accept both the unique ID of the directory, as well as the URL encoded FullPathName of the directory. Only models owned by the user or affiliated organizations can be accessed,

Method	Operation	Description
GET	`/model`	Retrieve all models the user has access to.
GET	`/model/{dir}`	Retrieve the model specified by {dir}.
POST	`/model`	Creates a new model according to the supplied JSON string. (see above) Note that the ID of the supplied JSON will be checked for uniqueness, and will fail if not unique. If the ID is not supplied, or left blank, a GUID will be generated.
PUT	`/model/{dir}`	Updates the model specified with {dir} according to the supplied JSON string. (see above)
DELETE	`/model/{dir}`	Deletes the model specified with {dir}.
GET	`/model/{dir}/sourceString`	Retrieves the source string of the model specified by {dir} as plaintext.
PUT	`/model/{dir}/sourceString`	Updates the source string of the model specified by {dir} according to the supplied JSON string. The supplied json should have a single property "sourceString", whose value is set to the model's source string.
POST	`/model/evaluate`	Performs an evaluation according to the supplied JSON string. (see below)

Model Evaluations

Evaluations are performed through the arguments provided by the following JSON string:

Where "model" is the ID or full path name of the model to be evaluated, and parameters has a name-value pair for every parameter in the model's input vector.

    {
        "model": "/Path/To/Model",
        "parameters": {
            "stringParameter": "value",
            "intParameter": 2,
        }
    }

Organization Ownership

In addition to users, organizations can also own assets. In the case that an organization owns an asset, all members of that organization will be granted access to that asset. Organization ownership of an asset can be specified by adding the following two optional parameters when creating an asset via its POST HTTP method.

      {
        "ownerType": "WMOrganization",
        "ownerID": "organization ID",
      }

The currently supported types are:

Owner Type	Description
*	If the "ownerType" value is not in this table, or if the optional parameters are omitted entirely, the asset will be owned by the user who created it.
WMOrganization	This asset belongs to an organization. The organization can be specified by entering its ID in the "ownerID" property. The user creating this asset must be a member of the organization, otherwise this will fail.

Full Path Names

All assets have a unique FullPathName. This path specifies the location of the asset in the file hierarchy, and follow the following rules.

Every FullPath starts with '/'. If a directory with name Directory1 is placed in the Root directory, its FullPathName will be /Directory1; correspondingly, if we place a data source with name Source2 in that directory, its FullPathName will be /Directory1/Source2
The exception to this rule is the Root directory, which can be specified in several different ways. If a JSON parameter is requesting a path, entering ("", " ", "/", "Root", null), or simply leaving out that JSON parameter will specify the Root directory.

Rest API Status Codes

The status of the request is returned to the caller as the HTTP status code value. A full list of HTTP status codes can be found here. Those most commonly used by the World Modeler API and their meanings are listed below:

HTTP Status Code	Meaning
200	Success
400	Bad Request. The request was not well formed or did not meet the API specification.
401	Unauthorized. The required authorization information was missing or invalid. See section 3, below, for further information on World Modeler’s authorization and authentication features.
403	Forbidden. The user credentials under which the request is being made do not have permission to perform the specified operation on the requested resource.
404	Not Found. The requested resource does not exist.
500	An error occurred on the server while trying to fulfill the request. In this case, the message field of the RESTResponse object in the body of the response (see above) will contain further diagnostic information.

⇦ Prev: 6. Simulation Next: 8. LLMs⇨

Source Mode	Description
PlainText	The source string is in a plaintext representation.

Source Format	Supported Models	Description
PMML	Decision Tree	The source string is represented as an XML file using the PMML format. (https://dmg.org/pmml/pmml-v4-3.html)

Registered Type	Description
DecisionTree	This Model is a Decision Tree.