Entity enrichment

An entity that is defined in the business model can have attributes that are enriched from an external source.

A data provider to be used in the enrichment of an entity must be defined in the business model. The enrichment of an attribute must also be defined in the business model by using a rule-like statement. An enrichment statement includes the name of the data provider and the attributes to be returned. For example, the following statement defines the attributes latitude and longitude of the entity type airport, which are to be enriched by using the weather provider data provider.

an airport is enriched by the weather provider,
   given
      the latitude from the latitude of this airport,
      the longitude from the longitude of this airport,
   setting
      the temperature to the temperature of this weather provider,
      the wind speed to the wind speed of this weather provider,
      the precipitation to the precipitation of this weather provider.

The business model must include the following definition of the airport entity:

an airport is a business entity identified by an IATA code with
   a latitude (a number),
   a longitude (a number),
   a precipitation level (a number),
   a wind speed (a number),
   a temperature (a number).

The data provider is defined by specifying a name, the required attributes, and the returned data.

a weather provider is a data provider, 
   accepts
      a latitude (a number),
      a longitude (a number),
   returns
      a temperature (a number),
      a wind speed  (a number),
      a precipitation  (a number).

When an agent requests the value of temperature, wind speed, or precipitation of the airport entity the runtime calls the associated weather provider. The values of the returned attributes are cached by default during a transaction. The values can be cached for longer than a single transaction to reduce the cost of repeated calls to the data provider.

Note: A single entity can be enriched by multiple providers. One or more input values can be specified, which can be any attribute of the entity, including attributes of attributes. You cannot enrich a single attribute with more than one data provider.

When you implement the data provider, you use the Data Provider Extension wizard to create a dedicated DataProvider API class. The DataProvider class provides the getConceptFactory method to return complex attribute values. The default implementation uses the @DataProviderDescriptor annotation to bind the implementation to the provider name that is defined in the business model statements.

The DataProvider implementation is deployed into an extension project that is part of the solution. A complete solution must contain one implementation for each provider that is named in the business model enrichment statements. And each data provider name must be unique within the solution.

The following figure shows how the enrichment of data is defined in the business model. The runtime resolves and loads a data provider implementation when an agent requires an enriched attribute value (by referring to the attribute in a rule, for example). The grid caches and shares the data between transactions.