Class EvaluateController

The Controller class for the evaluate REST interface.

Inheritance
object
ControllerBase
EvaluateController
Inherited Members
Namespace: Quantellia.WMServer.Execution
Assembly: WMServer.dll
Syntax
[Authorize]
[Route("evaluate")]
[ApiController]
public class EvaluateController : ControllerBase
Remarks

The World Modeler execution processor is accessed via the REST API by requesting the evaluate operation. The call syntax for this is:

[application root]/evaluate/{id}

where:

[application root]is the root URL of the application, that is, the full URL to which / is resolved.
{id}is the ID of the DecisionModel that is to be evaluated.
The body of the request must contain a JSON object, formatted as shown below. 
{
    "processorID":      string, empty string, or null,
    "returnElements":   [ array of strings  ] or null,
    "arguments":        { empty object or object with name = value pairs } or null,
    "saveAs"
    "UserData":         string or null
}
processorIDThe ID of a processor which has been created by a previous call to Runand is still valid. If this is the first time Run is being called, processorID should be null, or an empty string and the new processor ID will be returned in the response if the call succeeded. See Lifecycle of a processor, below..
returnElementIDsAn array of strings, each of which is the ID, FullyQualifiedName, or Name of a DecisionModelElement in the DecisionModel specified in the id URL argument. Note that the search for matching elements is performed in the order specified above.

The purpose of this is to allow the caller to limit the data that is returned when the processor evaluates the model to only those elements that the caller is interested in. This improves efficiency and reduces network traffic when large models are evaluated.

The following values may be specified:

nullAll elements in the model and their values are returned
[] (empty array)No elements in the model are returned
["element1","element2"...]The elements whose IDs, FullyQualifiedNames, or Names are included in the array.
argumentsA JSON object containing name = value pairs, where each name identifies an element in the DecisionModel and instructs the processor to set the specified element to the specified value before evaluating the model. Each model element name may be specified either by its FullyQualifiedName or its Name. The value must satisfy the following:
  • Must be a literal constant, or an expression that includes only literal constants or calls to built-in function
  • Must be one of the supported types. In the current version, these are given by the following JSON value types:
    • Numbers (integers and floating point)
    • DateTimes represented as strings.
    • Strings

For example:
Correct 

{   "processorID":      null,
                "returnElements":   null,
                "arguments:  {
                                 "stringElement":   "This is a string",
                                 "numberElement":   3.14159,
                                 "dateTimeElement": "10/31/2021"
                             },
                "UserData":    null
            }
Incorrect 
{   "processorID":      null,
                "returnElements":   null,
                "arguments:  {
                                 "stringElement":   "This is a string that depends on a " + modelElement,
                                 "numberElement":   3.14159 * aNumericalModelElement,
                                 "dateTimeElement": aDateTimeValuedModelElement 
                             },
                "UserData":    null
            }
saveAsIf the inputs and results of the execution are to be saved, then this argument specifies the name used to refer to the saved execution. If this argument is null, then the execution will not be saved.
summaryMay be null.
If the saveAs argument is not null, then this argument allows a short summary string to be included in the record of the saved execution run. If saveAs is null, then this argument is ignored.
documentationMay be null.
If the saveAs argument is not null, then this argument allows a longer documentation string to be included in the record of the saved execution run.The MIME type of the string must be specified in the documentationMIMEType argument.
If saveAs is null, then this argument is ignored.
documentationMIMETypeIf both the saveAs argument and the documentation argument are not null, then this argument must be set to the string identifying the MIME type of text in the documentation argument.
If either saveAs or documentation are null, then this argument is ignored.
UserDataAn optional, user-defined text string that can be passed with the call. If defined, thie string will be returned in the response to this call. This can be used for associating response instances with the calls they belong to, for example, to sort the sequence of returned responses to be the same as the order in which the requests were made.

Lifecycle of a processor

When the World Modeler API receives a request to evaluate a DecisionModel for the first time, it creates a Processor instance that is then associated with the Decision Model for its entire lifetime. As with all other objects in World Modeler, a Processor is identified by its ID, a GUID that will not change for the life of the Processor instance. The mapping between the Processor and its Decision model is immutable; a single processor will always evaluate one and only one Decision Models (although multiple processors may be running evaluations of the same Decision Models in some circumstances). So the relationship between Decision Moldels and Processors in one-to-many.

The lifecyle of a Processor from creation to evaluating its decision model is shown below.

Before a Processor can be used, it must first be initialized. This is a relatively resource-intensive process as the Deicsion Model must be laoded (possibly from the database), source code generated from the model, the source code compiled to binary code, the Processor instance created, the binary code loaded into the Processor, and the Processor initialized. Ideally, this should only be done once, and once initialized, the Processor should be retained and service future requests to evaluate the decision model again with changes to the arguments. For this reason, when a new Processor is created, World Modeler Server stores it in a cache and retrieves it for futuer evaluation requests, using its ID as the cache key.

How the Procssor lifecycle affects API requests

The API Run operation is the primary means of invoking a processor. The interaction with the Processor lifecycle is primarkly via the processorID argument and the value to which it is set. The normal protocol is as follows.

First time Run is called for a Decision Model:The processorID argument is set to null. This triggers the initialization process shown in the above diagram, which is necessary to create and configure the Processor the first time it is used, but only the first time.

When the first call to Run for a Decision Model returns, it returns the processorID that was assigned to the new processor, which makes it retrievable from the cache. It is important the clients of the API retain the processorID value so that the cached Processor can be used in future calls to Run.

Subsequent calls to Run for the same Decision ModelIn subsequent calls to Run, the processorID should be set in the requerst body, as shown above. This will prevent re-initialization of a new Processor, will retrieve the existing Processor from the cache, and evaluate the Decision Model with the specified arguments.


  • Note that at any stage, calling Run with processorID = null will invalidate the current Processor and cause a new Processor instance to be created and initialized, following the process shown in the above diagram.
  • Note that re-initializing the Processor will restore the model to its default state and previously calculated values will be reset.

Will a cached Processor always be available in the future?

No. There are two reasons an existing cached processor may "disappear".:
  1. The cache timeout expires. This set set in the instance configuration of the World Modeler Server but is typically set to several hours or longer.
  2. The Decision Model associated with the cached Processor is changed. In this situation, the model must be re-loaded, re-compiled, and the Processor re-initialized.

Handling status code 410 (Gone)

If the ID of a Processor that was once available in the cache, but is no longer available, is used in a call to Run, the status code 410 (Gone) is returned. The reason the Processor has been removed from the cache is also returned in the message field of the response. If a 410 status code is returned as the response to a Run request, a new request should be sent to the Run API with processID = null and the normal procedure followed after that.

Constructors

EvaluateController(WMAppDbContext)

Declaration
public EvaluateController(WMAppDbContext context)
Parameters
Type Name Description
WMAppDbContext context

Methods

Evaluate(string, EvaluationArgs)

Executes or initializes a decision model.

Declaration
[HttpPost("{id}")]
public Task<ActionResult<EvaluationResult>> Evaluate(string id, EvaluationArgs args)
Parameters
Type Name Description
string id

ID of the decision model to execute.
EvaluationArgs args
Returns
Type Description
Task<ActionResult<EvaluationResult>>

The result calculated by the decision model.
Remarks

The body of this request must contain a JSON string formatted as follows:

JSON...

Please see the online World Modeler API Reference for further information about the JSON arguments passed to the Run operation