Instance

Introduction

In the runtime, an Entity takes shape in the form of an instance.

Take for example an application for managing a digital ticketing queue. The entity Customer has several Attributes, such as Name and BirthDate. There can be multiple customers in the queue, so there can also be multiple instances of the Customer entity.

The application only handles one queue at a time, so there is also an entity Queue, of which there is only one instance. This is called a "singleton".

Static and dynamic instances

Instances that are created at runtime (see below) are called dynamic instances. There are also static instances, these are created at design time in Encore. See Static instance.

Referring to instances

Properties of instances are accessed by the name of the corresponding entity. Following the example above, Queue.Length could refer to the length of the queue and Customer.BirthDate refers to the birth date of one of the people in the queue.

Accessing an instance of a singleton entity is easy, as there is only one. However, for non-singleton (a.k.a. multiton) entities, how do we know which instance to access?

For this, we use the concept of active vs inactive. Only active instances can be accessed. Singletons are always active, but each multiton entity can only have one active instance at a time.

Active instances - in logic

In your Logic (attribute value expressions, Decision tables, Business rules, Reusable Expressions, etc.), you always reason starting from "self" (in other words, the instance that you are setting a value for).

Based on this, you do not have control over which instances are active or inactive. You can refer to:

• Yourself (in the above example, if the attribute Customer.Age refers to Customer.BirthDate, then this is always the same Customer instance)
• Instances that you have a Relation with (whether these are active or not)
• Singletons (these are always active)
• Static instances
• And you can make use of Collection functions to access other instances

Active instances - in a flow

Within Flows, it is possible to control which instances are active in several ways:

• Instances created with the Service call type: AQ_Instance_Create are immediately active
• Existing instances can be activated with Service call type: AQ_ActivateInstance
• A repeat Flow can be used. This flow is run once for each specified instance. Within each iteration of the flow, the next instance is activated

You can also refer to:

• Instances that an active instance has a Relation with (whether these are active or not)
• Singletons (these are always active)
• Static instances
• And you can make use of Collection functions to access other instances

Active instances - on a page

Within a Page, it is possible to control which instances are active in several ways:

• New instances can be created for 1:1 Relations by adding that Relation to the page
• A Repeat container can be used. This container is displayed once for each specified instance. Within each iteration of the container, the next instance is activated
• The Container type: AQ_InstanceList can be used to display (specified) instances of a particular entity.

You can also refer to:

• Instances that are already active in the flow (see above)
• Instances that an active instance has a Relation with (whether these are active or not) by adding that Relation to the page
• Singletons (these are always active)

The two ways to refer to a static instance in a page or a container is through the use of a REPEAT expression, or a relation.

Managing instances

Several Service calls can be used to manage instances:

• Service call type: AQ_Instance_Create
• Service call type: AQ_Instance_Update
• Service call type: AQ_ActivateInstance
• Service call type: AQ_DeleteInstance