Skip to content

Querying Existing Instances

The Query Existing Instances rule action searches the instances your tenant already holds outside the current case, and makes what it finds available to the rest of the rule. Use it to react to data that lives elsewhere, for example to warn that a person with the same name has been onboarded before.

The action reads approved instances and the values they were approved with. A value that exists only in an open case, including the case the rule runs in, is invisible to it.

Writing the query

The query is a RuLa expression that assigns to QUERY:

QUERY.ontology := 'Person'
QUERY.roles := ['AccountHolder']
QUERY.match := {'last_name': '%Lovelace%'}
QUERY.retrieve := ['first_name', 'email_address', 'works_with.first_name']
QUERY.max_results := 50
  • ontology searches only instances of that ontology.
  • roles (new in Atfinity 17) searches only instances that hold one of those roles in an approved case.
  • match compares information against a value. {'key': 'value'} requires the two to be equal, and {'key': '%value%'} requires the information to contain the value. Only plain information can be matched, so a relationship, a structure and a nested key are all rejected.
  • retrieve names the information to read back from each match.
  • max_results (new in Atfinity 17) caps how many matches you get, defaults to 1000 and accepts 10000 at most.

When the query names an ontology, a key that it and the queried roles do not have stops the rule and names the key, so a typo fails loudly instead of quietly returning nothing. When the query names no ontology, a key from any ontology is accepted.

Reading the result

RESULT.instances holds one entry per match and RESULT.number_of_matches holds how many matches there were, so a rule assigns them like any other value:

p.namesakes := RESULT.instances
p.number_of_namesakes := RESULT.number_of_matches

What each retrieved key holds depends on its information type:

[
    {
        'first_name': 'Ada',
        'email_address': [{'__name': 'Work', 'email_value': 'ada@example.com'}],
        'works_with': {'db_id': 41, 'first_name': 'Grace'}
    }
]
  • plain information: its value, or an empty string when the instance has none
  • a structure (new in Atfinity 17): a list of its occurrences, each carrying its members under their own keys and its occurrence name under __name
  • a relationship: the id it stores as text, so a Single Instance Relationship reads '41' and a Multiple Instance Relationship reads '[41,57]'

Info

New in Atfinity 17.

Writing a relationship and an information key together, as works_with.first_name, reads that information from the instances the relationship points at. A Single Instance Relationship gives you one dictionary, and an empty one when it points at no instance. A Multiple Instance Relationship gives you a list of dictionaries, in the order the instances are stored. Each dictionary holds the related instance's id under db_id, so a later rule can tell two related instances apart.

A structure key works the same way, so works_with.email_address gives you the occurrences of the related instance.

A relationship can point at instances of more than one ontology, and an ontology that does not define the information you asked for reads as an empty string, or as an empty list when its own ontology makes that key a structure. Each related instance answers with the shape its own ontology gives the key, so a key that is a structure on one ontology and a plain information on another returns occurrences for the first and a value for the second.

One step is as far as this goes. works_with.employer.name is rejected, and so is an occurrence index such as email_address[0].email_value. Retrieve works_with.employer or email_address instead, and pick the entry you want in the rule.