Logic Service Overview

Background

The logic service was created for two main purposes:

1. To provide a mechanism for defining business rules in one place -- e.g., the definition of a "pediatric" patient.

2. To provide a unified method for retrieving data from OpenMRS -- i.e., instead of having to manage a dozen different method of accessing data from different places within the API, consumers of the logic service can go to one place to get anything from a patient's demographic attribute, one more observation(s), or the result of a complicated business rule calculation.

The logic service accomplishes these goals by defining a way in which business rules can be encapsulated within logic "rules" and by providing a mechanism for registering these rules under tokens.

Consumers of the logic service specify the token(s) to be evaluated and the patient (or cohort of patients) against which to evaluate the rule(s).  The logic service evaluates the rules associated with those tokens.  Rules can call other rules or read directly from data sources to fetch the data needed for their calculations.  Results are returned from the logic service (to the original requester) as logic results.

Definitions

• Data Source - a data source provides access to a set of data for consumption by logic rules.  Many data sources are built into OpenMRS, including person data source, observation data source, encounter data source, etc.  Each of these data sources exposes a set of keys that may be used to fetch data from the data source.  Data are returned in the form of logic results.

• Evaluation - in the logic service, evaluation is the act of evaluation a given rule or set of rules -- i.e., perform whatever calculations are needed and return a logic result.

• Index Date - when evaluating rules, an "index date" is used to represent "today's date."  This is done to allow rules to be calculated retrospectively without changing the rule itself.  For example, an AGE rule would return a result containing the patient's age; however, if the index date was set to 5-September-2008, then the rule would return the age as of that date.  By calculating the age based on the patient's date of birth and the index date (instead of today), the rule can be re-used in both use cases.  When an index date is not specified, the logic service will always default it to today's date.

• Key - data sources expose their data through a set of keys.  For example, the person data source provides keys like GENDER, BIRTHDATE, etc. which represent the types of results you can request from the data source.  Keys are used when reading data source from a data source.

• Logic Context - a logic context provides an evaluation context for evaluating rules.  The context contains information like the index date and the current cohort against which the rule(s) are being evaluated.  Having a context allows rules to be efficienctly applied across multiple patients.

• Parameters - extra information may be passed to rules through the use of parameters.  For example, a rule might need to know a reporting period (date range) or a special threshold value to calculate its result; such information can be passed through parameters during evaluation of the rule.

• Reading - rules are "evaluated" (often involving a calculation), while data are "read" from data sources.  We use the notion of "reading" to distinguish the data requests from data sources from requests for other tokens to be evaluated.  This is really only a concern for people that are manually constructing logic rules by writing their own classes, where they

• Registration - rules are registered within the logic service with a unique token.  Once registered, the rule becomes available to other rules and to consumers of the logic service through the assigned token.

• Logic Result - all data returned by the logic service are converted into a reliable and predictable form: a logic result.  The logic result looks much like a clinical observation, with a date and a value.  Results may represent a set of data or a single value and each individual result can link to an object (e.g., a result obtained after asking for LAST CD4 COUNT could link to the observation that represents the most recent CD4 COUNT result for the patient).  By coercing all results into this one format, it is easier for rules to be combined to form a complex & sophisticated hierarchy.

• Rule - a logic rule represents a single piece of logic within the service.  In some cases, rules simply fetch a piece of data from the database; in other cases, the rule might perform sophisticated calculations to determine its result.  Under the hood, a logic rule is a Java class that implements a specific LogicRule implementation which is largely implementing an eval() method through which the rule can be evaluated.  See the ?Logic Service Technical Overview for more technical details.

• Rule Provider - a rule provider providers one or more rules for OpenMRS.  In some cases, data sources act as a rule provider by registering their own rules.

• Token - a token is a unique string used to get to a rule.  A rule is tied to a token through registration.

• Token Tag - a tag is an arbitrary string connected to a token.  A token can have any number of tags associated with it.  Tags allow for arbitrary grouping and/or categorization of tokens.

How things work

For technical details about the logic service, refer to the ?Logic Service Technical Overview page.