Model Objects Evaluate

The modelobjects_evaluate tool runs an evaluation of a Model Object and returns its results. An evaluation is a calculation that a Model Class defines to return results from a Model Object, for example a price recommendation. The tool first returns the parameters that the evaluation expects. A second call with parameter values runs the evaluation. To find a Model Object and the names of its evaluations, use the Model Objects Search tool.

Tool Name – modelobjects_evaluate

Title – Model Objects Evaluate

Type – Private

Access Profile – Operator

Permissions

The tool is available to the Operator access profile when tool access control is on. The modelobjects_evaluate tool uses your Pricefx permissions. You need read access to Model Objects. You can evaluate only the Model Objects that your user groups are allowed to view, at both the Model Object level and the Model Class level.

When you do not have access to a Model Object, the tool returns the same error as for a Model Object that does not exist. The error does not show whether a Model Object exists that you cannot access.

Parameters

Parameter

Required

Description

model_object

Yes

The typed ID of the Model Object, for example 42.MO. Use the typedId value that the modelobjects_search tool returns.

evaluation

Yes

The name of the evaluation, for example minimal_mapping. Use one of the names in the evaluations list that the modelobjects_search tool returns for the Model Object.

parameters

No

The parameter values for the evaluation, keyed by parameter name. The expectedParameters output field lists the parameter names and the type of value to give. The values are described in the Parameter Value Types table on this page.

Default: No parameters.

run

No

false returns only the parameters that the evaluation expects and does not run the evaluation. true runs the evaluation with the values in parameters.

Default: false.

Parameter Value Types

The expectedParameters output field describes the value to give for each parameter. For the input types in this table, the field shows the description. For any other input type, the field shows the name of the Pricefx input type.

Pricefx Input Type

Value to Give

DMDIMFILTER

Text: one value of the dimension.

DMFIELD

Text: a field name.

DMFIELDS

A list of field names.

DMSOURCE

Text: a Datamart as DM.<name> or a Data Source as DMDS.<name>.

DMFILTERBUILDER

A Pricefx filter, for example {"_constructor": "AdvancedCriteria", "operator": "and", "criteria": [{"fieldName": "Country", "operator": "equals", "value": "France"}]}.

INTEGERUSERENTRY

A whole number.

BOOLEANUSERENTRY

true or false.

Output

The modelobjects_evaluate tool returns an object with the following fields. A field without a value is left out of the output.

Field

Description

typedId

The typed ID of the evaluated Model Object.

status

The status of the Model Object: READY, DRAFT, CALCULATING, ERROR, or INVALID.

step

The calculation step from which the tool runs the evaluation. The evaluation uses the results of the steps up to this step.

evaluation

The name of the evaluation.

logic

The name of the logic that the evaluation runs.

expectedParameters

The parameters that the evaluation expects in this Model Object, keyed by parameter name, with the type of value to give.

parameters

The parameter values that you gave.

warnings

The warnings and alerts that the evaluation raised. Each entry starts with the name of the result, for example Margin: Low margin. An alert also contains its alert type. Present only when the evaluation ran.

results

The results of the evaluation, in the order the logic returns them. Each result has the fields in the Evaluation Result Fields table on this page. Present only when the evaluation ran.

message

How the given parameters compare with the expected parameters, and what to do next. For a Model Object with a status other than READY, the message also explains which step the evaluation used and what action to suggest.

Evaluation Result Fields

Field

Description

name

The name of the result in the logic.

label

The label of the result in Pricefx.

group

The group that the result belongs to, for example Segment.

format

The format of the value, for example PERCENT.

value

The value that the logic calculated. A table result contains only columns (the column names in order), columnFormats (the format of each column), and entries (the rows, one object per row).

warnings

The warnings that the logic raised for this result.

Behavior and Limitations

  • The modelobjects_evaluate tool works in two calls. The first call, with run set to false, returns the parameters that the evaluation expects. The second call, with run set to true and values in parameters, runs the evaluation.

  • The modelobjects_evaluate tool takes the evaluation by name and finds its logic in the Model Class. The AI assistant cannot choose a different logic.

  • For a Model Object with the status READY or DRAFT, the tool runs the evaluation from the current step.

  • For a Model Object with the status ERROR or CALCULATING, the tool runs the evaluation from the step before the current step.

  • A Model Object with the status INVALID cannot be evaluated.

  • A Model Object whose first step has the status ERROR or CALCULATING cannot be evaluated, because nothing is calculated yet.

  • A Model Object with the status DRAFT is calculated up to its current step only. The evaluation can miss results that later steps calculate. The message field suggests calculating the Model Object further.

  • When you leave out an expected parameter, the logic of the evaluation decides what happens, for example it uses a default value. The message field lists the parameters that you did not give.

  • Some inputs of the logic are hidden. The expectedParameters field does not list hidden inputs, and the tool does not accept values for them.

  • The values in results are in the units of the model, which are not always prices. Check the result labels and formats before you convert a value.

  • The modelobjects_evaluate tool works with every Model Class, for example Negotiation Guidance.

  • The modelobjects_evaluate tool does not read the tables or the inputs of a Model Object.

Errors

Situation

Error Message

model_object is not a typed ID such as 42.MO

String should match pattern '^\d+\.MO$'

The Model Object does not exist, or you do not have access to it

The Model Object X was not found

The Model Class of the Model Object does not exist, or you do not have access to it

The Model Class X was not found

The current step of the Model Object is not a step of its Model Class

The Model Object X cannot be evaluated: its current step Y is not a step of its Model Class Z.

The Model Object has the status INVALID

The Model Object X cannot be evaluated: its status is INVALID.

The first step of the Model Object has the status ERROR or CALCULATING

The Model Object X cannot be evaluated: its first step Y is Z, so nothing is calculated yet.

The Model Class has no evaluation with the given name

The Model Object X has no evaluation called Y. Its evaluations are: Z.

parameters contains a name that the evaluation does not expect

Unknown parameters for X: Y. Expected parameters: Z.

The logic of the evaluation fails

The evaluation X failed: Y. Z

Pricefx rejects the request for another reason

The backend refused the request: X

info In the last two rows, Y is the error message from the logic. Z explains the status of the Model Object, and when the evaluation ran, it also lists the expected parameters.