Assess Operation Request and Response Elements

Node:assess-request

The root container node for an assess request. The assess request contains an optional config node and a mandatory global-instance node. The global-instance element may be generic or specific.

Node:config

Contains configuration settings for the rulebase session. There are five settings.

Example:

<typ:config>
  <typ:show-properties>true</typ:show-properties>
  <typ:show-events>true</typ:show-events>  
  <typ:show-silent>true</typ:show-silent>
  <typ:show-invisible>true</typ:show-invisible>
  <typ:resolve-indecision-relationships>true</typ:resolve-indecision-
       relationships>
</typ:config>
 

 

show-properties

This can be set to true or false. If it is true, custom properties of elements and attributes will be shown in decision reports, session-data and screens

show-events

This can be set to true or false. If it is true, any events will be returned in an assess response.

show-silent

This can be set to true or false. If it is true, any silent operators attached to rule premises will be ignored for decision reports, resulting in the rule branch underneath the silent operator being included in the decision report. If it is false or not specified, the decision report will be shown with the silent operator having its usual effect of hiding all proving attributes.

show-invisible

This can be set to true or false. If it is true, any invisible operators attached to rule premises will be ignored for decision reports, resulting in the premise being included in the decision report. If it is false or not specified, the decision report will be shown with the invisible operator having its usual effect of hiding the attribute to which it is attached.

resolve-indecision-relationships

This can be set to true or false. If it is true, for all Decision Reports for an Attribute which is Unknown (an Indecision Report) the Indecision Report will look below an unknown relationship, and report on attributes and relationships.

Normally a Decision report will stop at an Unknown Relationship.

 

Node:global-instance

The global-instance element represents the root node of the session data used to make an assessment and appears in both the Generic and Specific interfaces. In the generic format, the global instance has zero or more ‘entity’ nodes. However, in a specific format, the global instance has zero or more ‘entity-list’ nodes. The ‘entity’ and ‘entity-list’ node serves as a container for child instances of a common entity type.

In both the Generic and Specific use, the global instance element is named 'global-instance'

Example

<typ:global-instance>
...
</typ:global-instance>

Node:list-entity

A list of entities of a common type. This node is only present in the specific format. An list-entity contains instances of a particular entity (see Node:instance below). Each entity has a list element. For example a person entity would have a “list-person” element.

Example (Specific):

In the same example in the specific format there is a specific list-person element, which contains person instances.

<typ:list-person>
    <typ:person id="sue"/>
    <typ:person id="bobjr"/>
    <typ:person id="lilSue"/>
</typ:list-person>

Node:entity

A container for entity instances of a common type. This node is only present in the generic format.

<typ:entity id="person">
    <typ:person id="sue"/>
    <typ:person id="bobjr"/>
    <typ:person id="lilSue"/>
</typ:list-person>

attribute:id

The name of the entity

Node:instance

An instance of an entity. An entity instance can have attributes (Node:attribute), relationships (Node:relationships) and child entities (Node:entity)

In the specific format an entity will be specifically named. For example a entity toy will be an element <typ:toy id=”plane”>

attribute:id

The entity name identifying the unique identifier (name) of this type of entity.

Example:

the entity set "toys" below has a single instance with a label 'plane'. Entity instance has an attribute 'wings'

<typ:entity id="toy">
    <typ:instance id="plane">
        <typ:attribute id="wings">
            <typ:boolean-val>true</typ:boolean-val>
        </typ:attribute>
    </typ:instance>
</typ:entity>

Example (Specific):

<typ:list-toy>
    <typ:toy id="plane">
        <typ:wings>
           <typ:boolean-val>true</typ:boolean-val>
        </typ:wings>
    </typ:toy>
</typ:list-toy>

Node:attribute

An attribute element can be used to set an attribute value or configured to indicate it is an outcome to be determined. Configuring an attribute as an outcome can be done by specifying an attribute:outcome-style.

In the Specific model there is no attribute element. The element for an attribute (named for that attribute) serves to request a value (if the outcome-style is specified) or set the value. In the specific model, the attributes for attribute also exist on an attribute.

attribute:id

This is the requested attribute name

attribute:outcome-style

This is the default outcome-style to use whether known or unknown. The outcome style attribute can be “attribute only” (no decision report, just the value), “base-attributes” (a decision reports showing the relevant attributes, but only the base level ones, and “decision-report” a full decision report.

attribute:known-outcome-style

This is the outcome style to use when the attribute is known, and overrides the default style specified in outcome-style. This attribute takes the same values as outcome-style.

attribute:unknown-outcome-style

This is the outcome style to use when the attribute is unknown or uncertain, and overrides the default style specified in outcome-style. This attribute takes the same values as outcome-style.

 

Example – Configuring an attribute outcome:

In the generic and specific examples below, we are requesting an attribute called parentsSatisfy from the global instance.

<typ:global-instance>
    <typ:attribute id="parentsSatisfy"
        outcome-style="decision-report" />

</typ:global-instance>

Example – Configuring an attribute outcome (Specific):

<typ:global-instance>
    <typ:parentsSatisfy outcome-style="decision-report"/>
</typ:global-instance>

Example – Setting an attribute value:

This sets the value of the Boolean attribute wings to value of 'false'

<typ:attribute id="wings">
    <typ:boolean-val>false</typ:boolean-val>
</typ:attribute>

Example – Setting an attribute value (Specific):

This sets the value of the Boolean attribute wings to value of 'false'

<typ: wings>
    <typ:boolean-val>false</typ:boolean-val>
</typ: wings>

Node:boolean-val

A boolean value: the text of this node must be "true" or "false".

Node:date-val

A date value: the text of this node must be a valid date in yyyy-mm-dd format (<year>-<month as two digit number>-<day of month>)

Node:datetime-val

A date and time value: the text of this node must be a valid date in yyyy-mm-ddThh:mm:ss format (<year>-<month as two digit number>-<day of month>’T’hh:mm:ss)

Node:time-val

A time-of-day value: the text of this node must be a valid date hh:mm:ss format (<hours 0-23>:<minutes>:<seconds>)

Node:number-val

A number value: the text of this node must be a valid number. The number-val element is used for all numeric values including currency.

Node:text-val

A text value: supports any arbitrary string.

Node:unknown-val

This empty node indicates that the attribute has an unknown value. You never have to set this attribute. If you want the value of an attribute to be unknown, then do not set a value, or leave the attribute out entirely as the default value for an attribute is unknown.

Example:

this wings attribute has an unknown value. This could also be indicated by leaving the value out of the XML altogether.

<typ:attribute id="wings"/>

Node:uncertain-val

This empty node indicates that the attribute has an uncertain value. You can set this element to indicate that a particular attribute is uncertain.

Example:

this wings attribute has an uncertain value

<typ:attribute id="wings">
    <typ:uncertain-val/>
</typ:attribute>

Node:change-point

Change points can be used to indicate a changing value over time.

Change-point:date

This indicates the date at which the value specified within the change point takes effect.

Example:

In this example, the happiness of the people changes from being unknown before 1 January 2007 to false on 1 January, and then changes to true on 28 February 2007.

<people_happy type=”boolean”>
  <unknown-val/>
  <change-point date="2007-01-01">
    <boolean-val>false</boolean-val>
  </change-point>
  <change-point date="2007-02-28">
    <boolean-val>true</boolean-val>
  </change-point>
</people_happy>

Node:relationship

This element represents a reference relationship between one entity instance and one or more entity instances. This element is also used to request the value (the targets) of an inferred relationship (also known as a ‘relationship outcome’). In the Specific model there is no relationship element. The element for an relationship (named for that relationship) serves to request a value (if the outcome-style is specified) or set the value.

Example – Configuring a Relationship Outcome:

In the generic and specific examples below, we are requesting a relationship called qualifying_claimants from the global instance.

<typ:global-instance>
    ...
        <typ:relationship id="qualifying_claimants" outcome-style="decision-report" />
</typ:global-instance>

Example – Configuring a Relationship Outcome (Specific):

<typ:global>
    ...
        <typ:relationships>
           <typ:qualifying_claimants" outcome-style="decision-report"/>
        </typ:relationships>
</typ:global>

The relationship node has one or more target elements (see Node:target) that represents the entities at the other end of the relationship. In the specific format a relationship will be represented by an element with a name matching the name of the relationship.

attribute:id

is the name of the relationship. In specific format this attribute is not needed and does not exist.

 

Example – Specifying a relationship’s targets:

The relationship below is called children and the target is bobjr (who must be declared as an entity instance in the global instance.

<typ:relationship id="children">
    <typ:target instance-id="bobjr" />
</typ:relationship>

Example- Specifying a relationship’s targets (Specific):

<typ:relationships>
    <typ:children>
        <typ:target instance-id="bobjr" />
    </typ:children>
</typ:relationships>

attribute:state

the state of the relationship.

attribute:inferred

this attribute is a Boolean value and it indicates if the relationship was inferred. This attribute is populated by the Oracle Determination Server and it is returned in the response.

attribute:outcome-style

this is the default outcome-style to use whether known or unknown. The outcome style attribute can be “attribute only” (no decision report, just the value), “base-attributes” (a decision reports showing the relevant attributes, but only the base level ones, and “decision-report” a full decision report.

attribute:known-outcome-style

this is the outcome style to use when the attribute is known, and overrides the default style specified in outcome-style. This attribute takes the same values as outcome-style.

attribute:unknown-outcome-style

this is the outcome style to use when the attribute is unknown or uncertain, and overrides the default style specified in outcome-style. This attribute takes the same values as outcome-style.

Node:target

This sub-node of relationship represents the entities at the other end of the relationship.

attribute:entity-id

Is a reference to the target entity instance. entity-id is an XSD:ID and so must unique and must match an entities id attribute (see Node:entity).

Example:

The target below can refer to any entity in the session-data. There must be an entity with an id=”bob-jrr”

<typ:target instance-id="bobjr" />  
<!—refers to ... -->
<typ:entity id="bobjr" >
...
</typ:entity>

Node:properties

This is a list of custom properties and can exist within a screen, screen control, attribute, or entity.

Custom properties are set in Oracle Policy Modeling, and are only displayed if show-properties is set to true in the Node:config  section of the assess.

A properties list will have one or more property items in it.

Node:decision-report

A Decision Report is a sub-element of an attribute, and provides information on how the value of an attribute was derived (or why it is unknown). A Decision Report appears when a request for an attribute value is made, and the outcome-style attribute is set to anything except "value-only" (see Node:attribute )

A Decision Report is populated by Oracle Determinations Server and only ever appears in the Response. You do not create Decision Reports in an attribute in a request. A Decision Report contains Node:attribute-decision-node and relationship-node elements (see Node:relationship-node). The sub-elements are contributing attributes and relationships to the value of the attribute.

Attribute:report-style: the report style indicates the report style and will be the style requested in the attribute-outcome. Valid values are “decision-report” and “base-attributes”

Example:

<typ:global-instance>
    <typ:attribute id="parentsSatisfy" outcome-style="decision-
         report" />

    ...

this is requesting the value for the attribute "parentsSatisfy" but the returned value will be the attribute (if known), and a Decision Report.

The response below is the attribute “parentsSatisfy”. We can tell that the boolean value is known. Below the value is the beginning of the Decision Report element (line 3).

1  <typ:attribute id="parentsSatisfy" type="boolean">
2    <typ:boolean-val>true</typ:boolean-val>
3    <typ:decision-report report-style="decision-report">
4      <typ:attribute-node id="childSatisfies"
5           instance-id="bob" entity-id="person" attribute-id="dn:0"
6           text="" type="boolean">
7        <typ:boolean-val>true</typ:boolean-val>
8        <typ:attribute-node attribute-id="condition"
9             instance-id="bobjr" entity-id="person" attribute-id="dn:1"
10            text="" type="boolean">
11           <typ:boolean-val>true</typ:boolean-val>
12         <typ:attribute-node attribute-id="wings"
13              instance-id="plane" entity-id="toy" attribute-id="dn:2"
14              text="" type="boolean">
15           <typ:boolean-val>true</typ:boolean-val>
16         </typ:attribute-node>
17         <typ:attribute-node attribute-id="wings"
18              instance-id="tip-truck" entity-id="toy" attribute-id="dn:3"
19              text="" type="boolean">
20           <typ:boolean-val>true</typ:boolean-val>
21         </typ:attribute-node>
22       </typ:attribute-node>
23    </typ:attribute-node>
24  </typ:decision-report> 25 </typ:attribute>

 

Node:attribute-node

This sub-node of decision-report (see Node:decision-report ) represents a contributing attribute to the Decision Report. It Indicates an attribute of an entity. An attribute-node can contain other attribute-node and relationship-node (see Node: relationship-node), if the attribute is itself inferenced from other attributes. The entire inferencing structure for a decision-report is called a decision tree.

attribute:id

A unique identifier for this decision node. This is useful when an attribute-node occurs more than once in a decision-report. Rather than print the entire attribute-node again a reference will be made to the first appearance of the attribute decision-node.

Example:

In the example below, the second time the attribute node “dn:0” appears its contents is replaced by an “already-proven” element. Note that the id of both occurrences has the same id (dn:0) to make it easier to reference the original appearance of the attribute-decision-node

<typ:attribute-node attribute-id="childSatisfies"
     entity-id="person" instance-id="bob" id="dn:0">
     ...
     <!—- this may contain a large complicated decision tree -->
</typ:attribute-node>
...

<typ:attribute-node attribute-id="childSatisfies"
     entity-id="person" instance-id="bob" id="dn:0">
  <typ:already-proven>See above dn:0</typ: already-proven>
</typ:attribute-decision-node>

 

attribute:entity-id

The type of entity to which the attribute belongs

attribute:instance-id

The unique identifier for the entity to which the attribute belongs

attribute:hypothetical-instance

Indicates whether the instance to which the entity belongs was explicitly created or implicitly created by the engine in order to resolve unknown relationships.

attribute:attribute-id

Name of the attribute

attribute:type

The type of attribute. It will be one of "boolean", "text", "number", "currency" or "date".

attribute:text

The text associated with the attribute. This will usually be something like “child is not satisfied” (if false) or “child is satisfied” (if true).

attribute:inferred

This attribute is a Boolean value and it indicates if the relationship was inferred. This attribute is populated by the Oracle Determination Server and it is returned in the response.

attribute:start-relevance

This is a Time Based Reasoning feature. It indicates when an attribute-node is only relevant for a particular time period. The start-relevance attribute indicates the start of the period on which this attributes value is relevant to the goal. The absence of this attribute means that this attribute is relevant from the earliest possible date.

attribute:end-relevance

This is a Time Based Reasoning feature. The end-relevance attribute indicates the date at which the attribute value ceases to be relevant to the goal. The absence of this attribute means that this attribute is relevant until the latest possible date.

Node:relationship-node

This sub-node of relationship represents an unresolved relationship. A relationship-node will only occur in a decision report where an attribute value is not known (an in-decision report). A relationship-node and an attribute-node can contain other attribute-node and relationship-node. But on if the configuration element resolve-indecision-relationships is set to true (see Node:config). This is because normally, the engine decision trees stop when they reach an unresolved relationship, making it the last element in a decision tree.

attribute:id

A unique identifier for this decision node. For more information on how an id is used (see Node:attribute-decision-node)

attribute:relationship-id

The name of the relationship

attribute:source-entity-id

The source entity for the relationship

attribute:source-instance-id

The source entity instance for the relationship

attribute:hypothetical-instance

Indicates whether the instance to which the entity belongs was explicitly created or implicitly created by the engine in order to resolve unknown relationships.

attribute:target-entity-id

The target entity for the other end of the relationship

attribute:state

The state of the relationship. Because a relationship-node only occurs in a decision report if it is unknown, the state should always be “unknown”

attribute:inferred

Indicates whether the relationship is inferred.

attribute:start-relevance

This is a Time Based Reasoning feature. It indicates when a relationship-node is only relevant for a particular time period. The start-relevance attribute indicates the start of the period on which this relationship is relevant to the goal. The absence of this attribute means that this relationship is relevant from the earliest possible date.

attribute:end-relevance

This is a Time Based Reasoning feature. The end-relevance attribute indicates the date at which the relationship ceases to be relevant to the goal. The absence of this attribute means that this relationship is relevant until the latest possible date.

Example:

In the example below we can see that the attribute-node “condition” is unknown because the relationship “plays-with” between a person and toy is unknown (line 4).

1  <typ:attribute-node attribute-id="condition"
2       entity-id="person" id="dn:2" text="" type="boolean">
3      <typ:unknown-val/>
4      <typ:relationship-node id="dn:3"
5           relationship-id="plays-with" state="unknown" target="toy">
6          <typ:attribute-node attribute-id="wings"
7               entity-id="toy" id="dn:4" text="" type="boolean">
8              <typ:unknown-val/>
9          </typ:attribute-node>
10     </typ:relationship-node>
11 </typ:attribute-node>

Node:events

The events element can contain one or more event elements (see Node:event). This element will occur in the response when an assess operation has triggered either a standard event, or an "error". If an error event has been triggered, then the Oracle Determinations Server will always return a SOAP Fault. The errors will be in the body of the SOAP Fault  (see: Node:config show-events).

Example:

In this example, the SOAP Fault contains an error message, that a value passed in a request was -3.0. In this case the error was generated because the number is expected to be greater than 0.

1  <SOAP-ENV:Fault>
2    <faultcode>SOAP-ENV:Client</faultcode>
3    <faultstring>The Rulebase generated an error event</faultstring>
4    <detail>
5      <typ:error-response>
6        <typ:code>assess.request.event.error</typ:code>
7        <typ:message>The Rulebase generated
8             an error event</typ:message>
9        <typ:events>
10          <typ:event instance-id="my-attribute-holder" name="error">
11             <typ:message>"The event-field is negative" </typ:message>
12             <typ:decision-report report-style="base-attributes">
13               <typ:attribute-node   attribute-id="event_field"
15                    instance-id="my-attribute-holder"
16                    entity-id="attrholder" id="dn:0"
17                    text="Attrholder's event-field is -3.0."
18                    type="number">
19                    <typ:number-val>-3.0</typ:number-val>
20              </typ:attribute-node>
21            </typ:decision-report>
22          </typ:event>
23        </typ:events>
24      </typ:error-response>
25    </detail>
26  </SOAP-ENV:Fault>

Node:event  

When the Oracle Determinations Server returns an event (see Node:events) an event element is generated. An event element can represent either a standard event, or an "error".

Any event defined in the Rulebase with the name error, when the event is triggered, will be returned in a SOAP:Fault.  Error events will result in SOAP errors regardless of the “show-events” setting in the assessment configuration.

All other events are returned only when show-events is set to true.

An event will have a message sub-element, containing the text of the event message. It will also have a decision report, giving a decision tree of the cause of the event (see Node:decision-report).

attribute:name

This is the name of the event. Currently supported events in Oracle Determinations Server are "error" and "warning" events, so the name will be either of these.

attribute:instance-id

When an event is associated with a particular entity instance. The entity-id attribute will contain as XSD:IDREF to that entity.

Example:

In the example below. a Warning event has been generated in a response.

1   <typ:events>
2     <typ:event entity-id="my-attribute-holder" name="Warning">
3       <typ:message>"The event-field is more than 100"</typ:message>
4       <typ:decision-report report-style="base-attributes">
5         <typ:attribute-node
6              attribute-id="event_field"
7              instance-id="my-attribute-holder"
8              entity-id="attrholder" id="dn:0"
9              text="Attrholder's event-field is 102.0." type="number">
10          <typ:number-val>102.0</typ:number-val>
11        </typ:attribute-node>
12        <typ:attribute-node attribute-id="boolean_field"
13             instance-id="my-attribute-holder"
14             entity-id="attrholder" id="dn:1"
15             text="Attrholder's boolean-field is true."
16             type="boolean">
17             <typ:boolean-val>true</typ:boolean-val>
18        </typ:attribute-node>
19      </typ:decision-report>
20    </typ:event>
21  </events>

 

See also:

Example: Assess Request xml

Example: Assess Response xml