5 Relationship Discovery and Relationship Rules

This chapter introduces how to utilize the relationship rules for the relationship discovery including the relationship discovery process. It also provides the information about the relationships rules and how to define and register the relationship rules.

5.1 Relationship Discovery

The relationship discovery feature of the relationship management provides the ability to identify and extract key relationships in the inbound messages from the OHMPI applications or the upstream integral applications. The relationship discovery feature is built upon the standard open architecture. The business and processing logic for discovering relationships is determined by the relationship rules. The relationship rule is completely definitive and pluggable. Users can define and create custom relationship rules according to the specific business requirements.

The policies, process and business logic for automating relationship discovery are too dynamic to manage effectively as applications in many situations. The definitive relationship rules can help users develop more agile relationship management solutions.

The relationship rule is literally a business rule. The business rule as a statement that defines or constrains some aspect of the business; a business rule is intended to assert business structure or to control or influence the business's behavior. The relationship rule is to externalize the relationship management process logic. The relationship rule is executed by the standard relationship management rule engine.

Figure 5-1 illustrates relationship discovery process dataflow by the relationship rules and tasks.

Figure 5-1 Relationship Discovery Process Dataflow

Description of ''Figure 5-1 Relationship Discovery Process Dataflow''

5.1.1 Integrating with Relationship Rules

The relationship discovery process is triggered when you execute the following relationship management REST APIs:

Create a relationship from a single source or target entity by using configured relationship rules.
- entity: The name of the source or target entity type.
- request body: The attributes of the source or target entity.
```
POST /resources/relationships/entities/{entity}
{ "entity resource attributes" }
```
Create a relationship between the source entity and the target entity by using configured relationship rules.
- source: The name of the source entity type.
- target: The name of the target entity type.
- request body: The attributes of the source entity and target entity.
```
POST /resources/relationships/entities/{source}/{target}
{ "items": [{"source entity attributes"}, {"target entity attributes"}] }
```
Create a relationship from a single source or target entity by using configured relationship rules.
- entity: The name of the source or target entity type.
- request body: The attributes of the source or target entity.
```
POST /integration /relationships/entities/{entity}
{ "entity resource attributes" }
```
Create a relationship between the source entity and the target entity by using configured relationship rules.
- source: The name of the source entity type.
- target: The name of the target entity type.
- request body: The attributes of the source entity and target entity.
```
POST /integration/relationships/entities/{source}/{target}
{ "items": [{"source entity attributes"}, {"target entity attributes"}] }
```

For more information, see Oracle Healthcare Master Person Index Relationship Management REST APIs Reference Guide.

5.2 Relationship Rules

A relationship rule is as a set of the if-then statements. The if-then statements are the rules. A rule is composed of two parts: a condition and an action. When the condition is met, the action is executed. The if portion contains conditions. The inputs to a relationship rule engine are a collection of rules called a rule execution set and data objects. The outputs are determined by the inputs and may include the relationship and entity data objects with modifications.

Use relationship rules when the business logic and process workflow for creating relationships are:

Too dynamic to be managed at the pre-defined applications
Cannot be predefined and require customization

5.2.1 Rules Syntax

A rule is composed of the following elements:

A unique name
A description
A list of conditions
- A condition having the format: "source" ["operator" "target"]
- An operator between source and target can be: =, <>, <, >, <=, >=, in, like, between, exist, or between
  
  Note:
  =, <>, and exist are supported in this release.
- If a condition has only source, then operator is exists
- The value of source is the entity attribute in EPATH starting with the domain attribute name. For example:
  - "source" = "FirstName_St"
  - "source" = "Address.AddressLine1_StName"
- The value of target is also the entity attribute in EPATH starting with the domain attribute name or can be constant value of (text or numeric value) or an enumeration of values expressed as [value1, value2, and so on].
- AND or OR group condition
- A list of tasks
  - A task having the format: "TaskName" ["arg-1" "arg-2" ... "arg-N"]
  - TaskName is unique and has one-to-one map to groovy script class name

Figure 5-2 illustrates the ruleset XSD schema.

Figure 5-2 RuleSet XSD Schema

Description of ''Figure 5-2 RuleSet XSD Schema''

5.2.2 RuleSet

A ruleset is a collection of rules. Each rule set can contain one rule or combine multiple rules. Each rule can have a single condition or multiple conditions grouped, each rule can include a single task or multiple tasks if the condition is satisfied.

The ruleset starts with RmRuleSet element in the ruleset XML file. Each ruleset XML file contains one or multiple rulesets. The following are the RmRuleSet attributes:

name: The unique name of the ruleset, the name needs to comply with the relationship management generic naming standard.
source: The name of the source entity type for the relationship type that this ruleset processes. It has to match the name of the source entity type in the RM ruleset table.
target: The name of the target entity type for the relationship type that this ruleset processes. It has to match the name of the target entity type in the RM ruleset table.
description: The description of the ruleset.

The rule starts with the rule element. The rule element contains the following attributes:

name: The unique name of the rule, the name needs to comply with the relationship management generic naming standard.
description: The description of the rule.

5.2.3 Condition Rules

You can define condition rules to use in conjunction with the operation rules described in Section 5.2.3.1, "Condition Operators". Conditional rules return either true or false. They only define a condition and not an action, so they must be used with other types of rules. Conditional rules use if, condition, and then statements in the following format:

<rule name="rule name" description="rule description" >
   <if>
      <condition>
      ...
      </condition>
      <then>
      …
      </then>
   </if>
</rule>

5.2.3.1 Condition Operators

The condition operators are used to evaluate values for condition rules. The following condition operators are predefined:

equal
not equal
exist
not exist
conditional OR
conditional AND

5.2.3.1.1 Equal

This operator evaluates whether the value of the specific attribute of the source entity is equal to the value of the specific attribute of the target source. This operator returns true if the conditions are matched; otherwise it returns false. The syntax for equal is:

<source name="attribute name of the source entity" op="=" target=" attribute name of the target entity" />

The parameters for equal are:

name: The qualified attribute name of the source entity in e-path
op: The predefined operator indicator (=)
target: The qualified attribute name of the target entity in e-path

The e-path starts with the attribute name of the primary object or the child object name following by a dot and the attribute name of the child object. For example, FirstName indicates the FirstName attribute of Patient, Address.AddressLine1 indicates the AddressLine attribute of Patient's Address child object. The attributes of the entity type and the name of the child object have to match what is defined in the metadata.

The following rule checks whether the value of the Id of the Patient's Provider equals to the value of the NPI Provider. They match, the operator returns true, and then the task of CreatePatientOfTask gets executed; otherwise the rule does nothing.

<rule name="rule name" description="rule description" >
   <if>
      <condition>
         <source name="Provider.Id" op="=" target="NPI" />
      </condition>
      <then>
         <task name="CreatePatientOfTask" arg1="Patient-Of " />
      </then>
   </if>
</rule>

5.2.3.1.2 Not Equal

This operator evaluates whether the value of the specific attribute of the source entity is not equal to the value of the specific attribute of the target source. This operator returns true if the conditions are matched; otherwise it returns false. The syntax for not equal is:

<source name="attribute name of the source entity" op="<>" target=" attribute name of the target entity" />

The parameters for not equal are:

name: The qualified attribute name of the source entity in e-path
op: The predefined operator indicator (<>)
target: The qualified attribute name of the target entity in e-path

The following rule checks whether the value of the Id of the Patient's Provider does not equal to the value of the NPI Provider. They do not match, the operator returns true, then the task of DeactivatePatientOfTask gets executed; otherwise the rule does nothing.

<rule name="rule name" description="rule description" >
   <if>
      <condition>
         <source name="Provider.Id" op="<>" target="NPI" />
      </condition>
      <then>
         <task name="DeactivatePatientOfTask" arg1="Patient-Of " />
      </then>
   </if>
</rule>

5.2.3.1.3 Exist

This operator evaluates whether the value of the specific attribute of the source entity or the target entity exists. This operator returns true if the conditions are matched; otherwise it returns false. The syntax for exist is:

<source name="attribute name of the source entity" />

<target name="attribute name of the target entity" />

The parameter for exist is:

name: The qualified attribute name of the source entity or the target entity in e-path.

The following rule checks whether the incoming message contains the value of the Doctor attribute of the Patient, the operator returns true, and then the task of PatientOfTask gets executed; otherwise the rule does nothing.

<rule name="rule name" description="rule description" >
   <if>
      <condition>
         <source name="Doctor" />
      </condition>
<then>
         <task name=" CreatePatientOfTaskByDoctorNode" arg1="Patient-Of" />
      </then>
   </if>
</rule>

5.2.3.1.4 Not Exist

This operator evaluates whether the value of the specific attribute of the source entity or the target entity does not exist. This operator returns true if the conditions are matched; otherwise it returns false. The syntax for not exist is:

<source name="attribute name of the source entity" op="not exists" />

<target name="attribute name of the target entity" op="not exists" />

The parameter for not exist is:

name: The qualified attribute name of the source entity or the target entity in e-path.

The following rule checks whether the incoming message does not contain the value of the Doctor attribute of the Patient, the operator returns true, and then the task of "PatientOfTask" gets executed; otherwise the rule does nothing.

<rule name="rule name" description="rule description" >
   <if>
      <condition>
         <source name="Doctor" op="not exists" />
      </condition>
      <then>
         <task name=" CreatePatientOfTaskByDoctorNode" arg1="Patient-Of" />
      </then>
   </if>
</rule>

5.2.3.1.5 Conditional OR

The conditional OR operation is performed on multiple condition operators. The multiple condition operators are grouped by OR and the condition operators are evaluated in order. This operator returns true if any of the condition operators results in true; otherwise it returns false. The syntax for conditional OR is:

<or>
    <!-- Condition Operator -->
    <source name="attribute name of the source entity" op="=" target=" attribute name of the target entity" />
    <source name="attribute name of the source entity" op="<>" target=" attribute name of the target entity" />
    <source name="attribute name of the source entity" />
    <target name="attribute name of the target entity" />
    …
</or>

The following rule checks whether the value of the NPI of the Patient's Provider equals to the value of the NPI Provider or whether the value of the Id of the Patient's Provider equals to the value of the NPI Provider either of them matches, the operator returns true, then the task of CreatePatientOfTask gets executed; otherwise the rule does nothing.

<rule name="rule name" description="rule description" >
   <if>
      <condition>
         <or>
            <source name="Provider.NPI" op="=" target="NPI" />
            <source name="ProviderId" op="=" target="NPI" />
         </or>
      </condition>
      <then>
         <task name="CreatePatientOfTask" arg1="Patient-Of " />
      </then>
   </if>
</rule>

5.2.3.1.6 Conditional AND

The conditional AND operation is performed on multiple condition operators. The multiple operators are grouped by AND and the condition operators are evaluated in order. This operator returns true if all the condition operators result in true; otherwise it returns false. The syntax for conditional AND is:

<and>
    <!-- Condition Operator -->
    <source name="attribute name of the source entity" op="=" target=" attribute name of the target entity" />
    <source name="attribute name of the source entity" op="<>" target=" attribute name of the target entity" />
    <source name="attribute name of the source entity" />
    <target name="attribute name of the target entity" />
    …
</and>

The following rule checks whether the value of the NPI of the Patient's Provider equals to the value of the NPI Provider and whether the value of the Id of the Patient's Provider equals to the value of the NPI Provider both of them matches, the operator returns true, then the task of CreatePatientOfTask gets executed; otherwise the rule does nothing.

<rule name="rule name" description="rule description" >
   <if>
      <condition>
         <and>
            <source name="Provider.NPI" op="=" target="NPI" />
            <source name="ProviderId" op="=" target="NPI" />
         </and>
      </condition>
      <then>
         <task name="CreatePatientOfTask" arg1="Patient-Of " />
      </then>
   </if>
</rule>

The conditional AND and conditional OR operators can be combined together and create more complicated conditions. The two samples of syntax for combining conditional AND and conditional OR operators are listed below:

<rule name="rule name" description="rule description" >
   <if>
      <condition>
         <and>
            …
            <or>
            …
            </or>
            …
         </and>
      </condition>
      <then>
         <task name="CreatePatientOfTask" arg1="Patient-Of " />
      </then>
   </if>
</rule>

<rule name="rule name" description="rule description" >
   <if>
      <condition>
         <or>
            …
            <and>
            …
            </and>
            …
         </or>
      </condition>
      <then>
         <task name="CreatePatientOfTask" arg1="Patient-Of " />
      </then>
   </if>
</rule>

5.2.4 Relationship Management Task Interface

package oracle.hsgbu.ohmpi.rm.rules.task;

import oracle.hsgbu.ohmpi.rm.rules.service.RmTaskException;

/**
* RmTaskInterface Interface
* @author <author_name>
*/public interface RmTaskInterface {
/**
* Execute the task
* @param context RmTaskContext
* @throws RmTaskException
*/
 void execute(RmTaskContext context) throws RmTaskException;            }

5.2.5 Registering Relationship Rulesets

This section explains how to register the relationship rulesets and the relationship management tasks. To do so, perform the following steps:

Define and create rules and ruleset. For information, see Section 5.2.5.1, "Defining and Creating Rules and Ruleset".
Design and implement the relationship management task interface in groovy script. For information, see Section 5.2.5.2, "Designing and Implementing the Relationship Management Task Interface in Groovy Script".
Register the ruleset. For information, see Section 5.2.5.3, "Registering Ruleset".
Register the relationship management task. For information, see Section 5.2.5.4, "Registering Relationship Management Task".

5.2.5.1 Defining and Creating Rules and Ruleset

Create a rule and ruleset, in a text or XML editor, based on the rule and ruleset syntaxes respectively.

The following is a sample CreatePatientOfRuleset.xml ruleset:

<?xml version="1.0" encoding="UTF-8"?>
<RmRules xmlns="http://www.w3.org"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.w3.org rules.xsd" >
   <RmRuleSet name=" CreatePatientOfRuleset "
         source="Patient"
         target="Provider "
         description="a sample ruleset" >
      <rule name="CreatePatientOfRule" description="a sample rule" >
       <if>
        <condition>
         <source name="Provider.Id" op="=" target="NPI" />
        </condition>
        <then>
         <task name="CreatePatientOfTask" arg1="Patient-Of " />
        </then>
       </if>
      </rule>
   </RmRuleSet>
</RmRules>

Register the ruleset.

For information, see Section 5.2.5.3, "Registering Ruleset".

Registering the ruleset using the management REST APIs or the RM data manager validates the syntax of the ruleset.

5.2.5.2 Designing and Implementing the Relationship Management Task Interface in Groovy Script

After you create the ruleset, you must design and implement the RM task which is referred by the ruleset. The RM task is the implementation of RmTaskInterface in groovy. The RM project creates a skeleton custom RM task. You can implement your business logic based on the business use cases. Perform the following steps to implement the RM Task interface:

In the Projects panel, expand the Source Packages of OHMPI Relationship Management Custom Rm Task.

Open the CustomRmTaskImpl.groovy file in the NetBeans editor.

The following appears:

/*----------------------------------------------------------------*
* Copyright (c) 2010 Oracle Corporation, Redwood Shores, CA, USA *
*                  All rights reserved.                          *
*----------------------------------------------------------------*/
package oracle.hsgbu.ohmpi.rm.rules.task;

import oracle.hsgbu.ohmpi.rm.data.AttributeType;
import oracle.hsgbu.ohmpi.rm.data.EntityType;
import oracle.hsgbu.ohmpi.rm.data.RelationshipType;
import oracle.hsgbu.ohmpi.rm.data.KeyValue;
import oracle.hsgbu.ohmpi.rm.data.EntityAttribute;
import oracle.hsgbu.ohmpi.rm.data.Entity;
import oracle.hsgbu.ohmpi.rm.data.RelationshipAttribute;
import oracle.hsgbu.ohmpi.rm.data.Relationship;
import oracle.hsgbu.ohmpi.rm.rules.task.RmTaskContext;
import oracle.hsgbu.ohmpi.rm.rules.task.RmTaskInterface;
import oracle.hsgbu.ohmpi.rm.rules.task.RmTaskMetaData;
import oracle.hsgbu.ohmpi.rm.rules.task.RmTaskService;
import oracle.hsgbu.ohmpi.rm.rules.service.data.DataObject;
import oracle.hsgbu.ohmpi.rm.rules.service.data.RmDataObject;
import oracle.hsgbu.ohmpi.rm.rules.service.data.EntityDataObject;
import oracle.hsgbu.ohmpi.rm.rules.service.data.LiteralDataObject;
import oracle.hsgbu.ohmpi.rm.rules.service.RmTaskException;

/**
* Custom Implementation of RmTaskInterface
* @author oracle
*/
class CustomRmRaskImpl implements RmTaskInterface {

public void execute(RmTaskContext context)
   throws RmTaskException {
   RmTaskMetaData rmMetadata = context.getRmTaskMetaData();
   RmTaskService rmService = context.getRmTaskService();
   EntityDataObject sourceData = context.getSourceData();
   EntityDataObject targetData = context.getTargetData();
   RmDataObject rmData = context.getRmData();

print "Custom implementation of groovy task"
  }
}

Implement your business logic.

Note:
Make sure that there is no syntax error.
Save the file.
Register the Rm groovy task.

For information, see Section 5.2.5.4, "Registering Relationship Management Task".

5.2.5.3 Registering Ruleset

Define the relationship task business and processing logic.
Define the relationship rules and combine rules in a ruleset.

You create the relationship ruleset xml file. For example, CreatePatientOfRuleset.xml.
Register the relationship ruleset either using the relationship management REST API or the relationship management data manager by assigning the unique ruleset name.

To use the relationship management REST API, follow these steps:
1. Create the relationship ruleset using the management REST API:
```
POST /management/rulesets/{ruleset}
```
  For example,
```
POST /management/rulesets/CreatePatientOfRuleset
{"name": " CreatePatientOfRuleset",
"description":"ruleset for creating Patient-Of relationship",
"source":"Patient"
"target": "IndProvider"}
```
2. Upload the relationship ruleset XML file using the management REST API:
```
PUT /management/rulesets/{ruleset}files
```
  For example,
```
PUT/management/rulesets/CreatePatientOfRuleset/files
CreatePatientOfRuleset.xml
```

5.2.5.4 Registering Relationship Management Task

Define the relationship task business and processing logic.
Implement the relationship task interface in groovy script.

Create the relationship task interface implementation file name with .groovy extension file name. For example, CreatePatientOfTaskImpl.groovy.
Register the relationship task interface implementation either using the relationship management REST API or the relationship management data manager by assigning the unique task name for the relationship task.

To use the relationship management REST API, perform the following steps:
1. Register the custom relationship event policy using the management REST API:
```
POST /management/tasks/{task}
```
  For example,
```
POST /management/tasks/CreatePatientOfTask
{"name": "CreatePatientOfTask "}
```
2. Upload the relationship task implementation script groovy file using the management REST API:
```
PUT /management/tasks/{task}files
```
  For example,
```
PUT/management/tasks/CreatePatientOfTask/files
CreatePatientOfTaskImpl.groovy
```