REST Endpoint: POST: https://rason.net/api/model/{nameorid}/solvetype

A REST API endpoint that binds model to data (optional), creates a new model instance, enqueues model to be solved (solvetype = datamine, decision, diagnose, optimize, solve or simulate) and returns a Location header with a new instance ID. The POST rason.net/api/model/{nameorid}/solve endpoint automatically creates an OData endpoint to allow for easy querying of the results. (Model must first be posted using POST https://rason.net/api/model.) A result with the following fields is returned.

• modelId: The unique identifier for the model
• modelName: The name of the model taken from the model text.
• modelDescr: The model description taken directly from the model text
• modelFiles: The list of files used by the model as taken from the model text.
• runtimeToken: Lists any runtime token associated with this model
• modelType: Lists the type of model such as "origin", "version", "instance".
• “origin” – the initially posted model
• “version” – means that this model is a version of a previously POSTed or PUT model
• “instance” – these are models created whenever a model is run.
• modelKind: Lists the kind of model such as "fitted", "excel" or "rason".
• “fitted” – fitted Data Science model in PMML/JSON format
• “excel” – models defined in Excel language
• “rason” – models defined in RASON language
• isChampion: True if model is marked as the “Champion” using the REST API endpoint PATCH rason.net/api/model/{nameorid}.
• parentModelId: Identifies the model from which this model is derived. In the case of “Origin” models, this is always empty. Otherwise, this property identifies the model used to create this model. For example, if a user POST’s a model and then PUT’s another version of this model, "parentModelId" of the version will be the modelId of the originally posted model. Similar logic holds for posting versions of version and instances of version.
• queryString: The query string associated with the model when it was created. In the case of unnamed models, this will change throughout the model’s lifecycle. A user may post an unnamed model with a particular query string but then solve the model with another. In the case of named models, this is the query string associated with the action used to create the model. A model could be posted with one query string, have several versions with different query strings and associated instances with yet another query string. If a particular version or instance doesn’t have a query string, it will inherit the query string of the parent.

• URL:
• https://rason.net/api/model/{nameorid}/datamine
• https://rason.net/api/model/{nameorid}/decision
• https://rason.net/api/model/{nameorid}/diagnose
• https://rason.net/api/model/{nameorid}/optimize
• https://rason.net/api/model/{nameorid}/simulate
• https://rason.net/api/model/{nameorid}/solve
• Method: POST
• URL Params
• Required: None
• Optional:

• Any data component may be passed as a query parameter if a binding property exists for that parameter. For example, see the RASON example code snippet below.

            
              data: {
              profits: {
              value: [[75, 50, 35]],
              binding: 'get'
              }
            
          

  To change a query parameter outside of the RASON model environment, use:

  $.Post("https://rason.net/api/optimize?profits=100,150,75",...

  RASON Server will map "profits=?" with "profits = 100, 150, 75". A query can return any number of rows that satisfy the filtering condition, from 0 to infinity.

  To perform a query using multiple parameters (say custID, maritalStatus and age) outside of the RASON model environment, use the query parameter:

  $.get(https://rason.net/api/decision? custID=c2&maritalStatus=s&age=40 .....

  Or in general,

  $.get(https://rason.net/api/decision?par1=val1&par2=val2.....

  In a data science model, any datasource component may be passed as a query parameter if a binding property exists for that datasource. For example, see the RASON example code snippet below.

            
              "datasources": {
              "srcCustomers": {
              "type": "csv",
              "connection": "customers_dt.txt",
              "selection": "custID = $parCustID1 or custID = $parCustID2",
              "parameters": {
              "parCustID1": {
              "binding": "get",
              "value": "c1"
              },
              "parCustID2": {
              "binding": "get",
              "value": "c3"
              }
              }
              }
              },
            
          

  To query custID =$parCustID1 or custID=$parCustID2 outside of the RASON model environment, use:

  $.get(https://rason.net/api/datamine?parCustID1=c1&parCustID2=c2…

  Or in general,

  $.get(https://rason.net/api/datamine?par1=val1&par2=val2.....

  RASON Server will map "custID=$parCustID1" with "parCustID1=c1" and "custID = $parCustID2" with "parCustID2=c3". A query can return any number of rows that satisfy the filtering condition, from 0 to infinity.

• Optional: This endpoint offers five optional parameters controlling the content of the final results and if and where intermediate results are stored: stage, data-storage, keep-intermediate-results, simplify-final-results and response-format.

  • Data-storage = DATABASE/JSON
    
    

    This parameter controls whether the SQLite DATABASE or JSON file storage is used to store the results of intermediate stages. Database mode does not affect terminal stages. When database mode is selected, the in-memory SQLite database is used to store the results of intermediate stages and will spill on disk in out-of-memory conditions. The default setting is Database.

    DATABASE mode can be orders of magnitude faster than JSON mode. In JSON mode, costs are incurred when reading/writing to/from disk. However, in DATABASE mode all in-memory database read/write operations are much more efficient. Intermediate results can still be stored and examined in DATABASE mode. These results may be queried with REST API or OData but they will not appear in the JSON response as serialized data frames.

    If data-storage = database and

    • keep-intermediate-results =False, the database stays in memory and will be discarded after terminal stages are processed.
    • keep-intermediate-results = True, an in-memory database is saved to disk to enable later querying.

    Example: POST: https://rason.net/api/model/{nameorid}/solve?data-storage=json

    Example: POST: https://rason.net/api/model/{nameorid}/solve?data-storage=json&keep-intermediate-results=true

  • Keep-intermediate-results = True/False
    
    

    This parameter determines whether the RASON server stores the results of the intermediate stages in the workflow, returns them with JSON response and makes them available for REST or OData querying later. Currently, this parameter not only affects the "pipeline solve" (i.e. when a single terminal stage is specified) but also the entire workflow solve, which might have multiple terminal stages. The default setting is False.

    Example: POST: https://rason.net/api/model/{nameorid}/solve?keep-intermediate-results=true

  • Response-format = STANDALONE/WORKFLOW
    
    

    Use this parameter to switch between the default dataframe-based workflow reporting format (for both single and multi-stage workflows) and the default reporting format (for single-stage workflows only). When response-format= workflow and simplify-final-results = false, the formula outputs are reported as dataframes. The default setting is WORKFLOW.

    Note: If a formula refers to a decision table, the dataframe will be complete with column headers--as defined in the "outputs" section of the decision table definition, and property types – that will be available in both the JSON response and later in REST/OData queries. If a generic formula, RASON will use default column names and the best possible type for each result column.

    Example: POST: https://rason.net/api/model/{nameorid}/solve?response-format=standalone

    Example: POST: https://rason.net/api/model/{nameorid}/solve?response-format=workflow

  • Schedule=interval/automatic
    
    
    • "interval" (ISO 8601 time or repeating time interval)
      
      

      If time is specified, the RASON Server will run the model once on that day and time. If a repeating time interval is specified, the server will run the model at the starttime. After the model finishes and duration has elapsed, the server will run the model again for the specified number of repetitions. A new model instance is created each time the model is run. Applications will typically use a model name (rather than an ID) in API Calls to GET rason.net/api/model/{name}/status to refer to the most recent run.

    • "automatic"

      This parameter behaves differently on standalone models versus decision flows. RASON Decision Services utilizes a new property, "modelRecency":"time-since-last-run", at the same level as the existing modelName, modelDescription and modelType properties.

      This new property informs the RASON server of how recently the model was run in order to determine if the results (in JSON or OData form) can be considered "current". The object "time-since-last run" must be in ISO 8601 time duration format (i.e. "PT12H" for 12 hours or "P1W" for 1 week). With this property in place, the user may add "?schedule=automatic" to the existing REST API call POST rason.net/api/model/{name}/solve. The RASON Server will consult past runs to determine the maximum time a solve usually takes to complete (max-time), and will arrange to run the model at intervals of time-since-last-run – max-time. If the "modelRecency" property is omitted, the default value is infinity; the '?schedule=automatic' will simply cause the model to run one time.

      More importantly, when a workflow of multiple stages is run using POST rason.net/api/model/{nameorid}/solve?schedule=automatic, the RASON Server will take into account modelRecency information for each stage in the workflow. For example, suppose a workflow has a final stage dependent on two intermediate stages A and B: If both A and B have runs that satisfy their recency requirement, the RASON Server will just run the final stage, using the previous results from A and B. If A has model Recency=PT24H, takes 2 hours to run and last finished 23 hours ago, and B has modelRecency=Pt8H, takes 1 hour to run and last finished 6.5 hours ago, the server will re-run both A and B, and use the latest results (2 hours from now) to run the final stage. (The modelRecency property must be added to each stage in the decision flow.)

      Calling POST rason.net/api/model/{name}/solve?keep-intermediate-results=true&schedule=automatic solves the flow and persists the stage results on the server. These results may be accessed using the OData endpoint described in the next section.

      To obtain the results from the last scheduled run, click the Editor tab at www.RASON.com. The results will be listed under Results beneath the model name. In order to obtain results from an earlier scheduled run, click My Account, then Run Details on the Overview tab. Highlight and copy the Model ID of the desired model instance and use this Model ID while calling the REST API Endpoint, GET rason.net/api/model/{nameorid}/result.

  • Simplify-final-results = True/False
    
    

    When True, this parameter tells the engine to store and report the results of, only, terminal stages as simplest possible JSON object: a scaler for 1x1 dataframe, 1d - array for Nx1 dataframe and 2d – array for NxM dataframe, No headers or index columns are stored. This option does not affect the results of intermediate stages, these are always dataframes. These simple results are reported in JSON Response may be queried with a REST call. Currently OData does not recognize these objects. The default setting is False.

    Example: POST: https://rason.net/api/model/{nameorid}/solve?simplify-final-results=true

  • Stage={stage-name}
    
    

    Use this parameter to retrieve information related to a specific stage of a decision flow. If this parameter is passed, the endpoint solves only the part of the decision flow required to solve the specified terminal stage, <stage-name>. The information produced by this optional parameter may be helpful during the creation or debugging phase. If a stage is not specified, a full Directed Acyclic Graph (DAG) solve is performed. To view all stages in a workflow, click or use the REST endpoint GET: https://rason.net/api/model/{nameorid}/stages/all.

    Example: POST: https://rason.net/api/model/{nameorid}/solve?stage=imputation

  When submitted together, the two parameters, data-storage and keep-intermediate-results, create four cases.

  Example: POST: https://rason.net/api/model/{nameorid}/solve?data-storage = json&keep-intermediate-results=true

  • data-storage = JSON and keep-intermediate-results = True
  • SQLite database is not used to store results. Rather, JSON files are used for solving, storing, responses and querying. The results of intermediate and terminal stages are reported in JSON response as well as being available for REST/OData querying.
  • data-storage = JSON and keep-intermediate-results = False
  • Same as when data-storage = JSON and keep-intermediate-results = True, except intermediate results are discarded after the decision flow solve. These results are not reported in JSON response and are not available for querying.
  • data-storage = DATABASE and keep-intermediate-results = True
  • SQLite database is used for solving and storing the results of intermediate stages. Results are not returned within JSON response and are available for REST/OData querying only from the stored database. The results of terminal stages are initially stored in JSON files, reported within JSON response and available for REST/OData querying from stored JSON files.
  • data-storage = DATABASE and keep-intermediate-results = False
  • Same as if data-storage = DATABASE and keep-intermediate-results = True except the database with intermediate results is discarded after the decision flow is solved. These results are not reported in JSON response and are not available for later querying.
  
  
  
• Solving Excel Models in Rason

RASON Version 20.5 supports the solving of Excel models as standalone models or from within a stage in a decision flow. When solving an Excel model using RASON Services, most of the options and features of the POST rason.net/api/model/{nameorid}/solve endpoint is inherited. The unified structured response will be returned with indexed data frames available for OData querying, users can control response-format=STANDALONE/WORKFLOW to receive the old response format, simplify-final-results=true/false is to receive the JSON response with the objects coerced to the simplest possible type. Scheduling is also available. Note: When POST rason.net/api/model/{nameorid}/solvetype is used to POST and solve an Excel model, the Excel workbook is uploaded and stores on the Rason server.

When solving an Excel model, use ?worksheet=<worksheet-name> to specify the name of the worksheet containing the model to be solved. If omitted, the active sheet is considered.

Note: Options such as stage, keep-intermediate-results and data-storage are not supported when solving an Excel model.

• Headers:

  Required: Authorization - Example: Authorization: bearer {your RASON token}

  Optional: None

• Data Params: None
• Success Response:

  Code: 202 (Accepted)

          
            {
            "ModelId": "2590+dmMLRWorkflow+2020-06-09-02-44-22-635754",
            "ModelName": "dmMLRWorkflow",
            "ModelDescr": "",
            "ModelFiles": [],
            "RuntimeToken": "",
            "ModelType": "Instance",
            "ModelKind": "Excel",
            "IsChampion": false,
            "ParentModelId": "2590+dmMLRWorkflow+2020-06-09-00-18-07-773177",
            "QueryString": ""
            }