Feature Specific Extensions
External Client Integration
OIPA may be integrated with external systems that can provide client information. The external client integration feature provides support to:
- Display external client data on the OIPA Role screen.
- Attach external clients to OIPA policies.
Rules Configuration
This section describes how to configure business rules to implement the OIPA external client functionality.
- 1.Make sure that External Client Plan security is enabled (checked) in the Rules Palette Plan Page Security.
- Using the Rules Palette Admin Explorer, add codes for new external roles to the AsCodeRole code set in the AsCode table—navigate to Administration | Code Names. If using the OIPA client search option, also add codes for external client types to the AsCodeClientType code set. The table below shows sample values for both codes:
Code Name Code Value Short Description Long Description System Indicator AsCodeRole 71 External Custom Agent External Custom Agent Unchecked AsCodeRole 72 External Agent External Agent Unchecked AsCodeClientType 06 External Client External Client Unchecked - If needed, insert authorizations for the ExternalClient page to be able to see the ExternalClientDetail popup page that is used to view the details of the external client.
- For the ExternalClientDetailsScreen rule, create a company-level override to configure which external client role codes and fields are associated with each defined external role. The information in the rule is used:
- To validate a set of keys identifying a client in the external system; the keys are returned when a new external role is created.
- To configure the External Client Detail popup page, which is used to view and, in some cases, to edit external client details on the Policy or Segment role page.
The external client fields configured by the rule may be classified as following:
- Key fields that identify a client in an external system. They are retrieved from an external system when a new external role is created, and stored in the AsExternalClient/AsExternalClientField tables in the OIPA database. Later, they are used as keys in requests to an external system whenever OIPA needs to obtain external client data. The key fields are indicated by a "No" value in the ExternalSource tag, which has its KEY attribute set to "Yes". When a new external role is created, OIPA validates returned key values for a selected external client against this rule to make sure keys are not empty.
- OIPA-specific fields that are configured and exist in the OIPA application only. They are stored in the OIPA database. Values for these types of fields can be entered and modified on the External Client Detail popup page. The OIPA-specific external client fields are indicated by a "No" value in the ExternalSource tag, which has its KEY attribute set to "No" (default value) in the ExternalClientDetailsScreen rule.
- External fields that are always returned from an external system and never stored in the OIPA database. They are indicated by a "Yes" value in the ExternalSource tag in the ExternalClientDetailsScreen rule. Fields of this type can be displayed on the External Client Detail popup page, but cannot be modified.
Example:
<ExternalClientDetailScreen> <Client ROLECODE="71"> <Fields> <Field> <Name>CLID</Name> <Display>External ID</Display> <DataType>Text</DataType> <ExternalSource KEY="Yes">No</ExternalSource> </Field> <Field> <Name>Address</Name> <Display>Address</Display> <DataType>Text</DataType> <ExternalSource>Yes</ExternalSource> </Field> <Field> <Name>PaymentMethod</Name> <Display>Methods</Display> <DataType>Combo</DataType> <Query TYPE="SQL">SELECT CodeValue,LongDescription FROM AsCode … </Query> <DefaultValue>01</DefaultValue> <ExternalSource>No</ExternalSource> </Field> </Fields> </Client> . . . </ExternalClientDetailScreen> |
For the PolicyScreen rule or Segment rule (for segment roles):
- Create a plan-level override.
- Add external client roles to the configuration.
- Identify the name of a class that implements the IExternalClientRowRetriever interface that must be called to retrieve a row of external client data from an external system.
<Role NAME="External Agent" EXTERNAL="Yes"> <ExternalClientRowRetriever>com.adminserver.externalClient.ExternalClientRows </ExternalClientRowRetriever> <RoleCode>72</RoleCode> <RoleCount>2</RoleCount> <RolePercent>100</RolePercent> <ClientType>06</ClientType> </Role> |
For an implementation that uses the OIPA client search screen, the ClientSearchScreen rule needs to include configuration of the client search screen for the defined external client types. The name of a class that implements the IExternalClientSearch interface should be specified using the ExternalClientSearchRetriever tag.
Example:
<Client TYPECODE="06" EXTERNAL="Yes"> <ExternalClientSearchRetriever>com.adminserver.externalClient.ExternalClientSearch </ExternalClientSearchRetriever> <Search> <Fields> <Field> <Name>LastName</Name> <Display>Last Name</Display> <DataType>Text</DataType> </Field> <Field> <Name>FirstName</Name> <Display>First Name</Display> <DataType>Text</DataType> </Field> </Fields> </Search> <Results DEFAULTRESULTS="Yes"> . . . </Client> |
If the Custom screen option is implemented, the role configuration in the Policy or SegmentName rule must include the CustomScreen tag with the name of a class that implements the IExternalClientSearchScreen interface. See the bolded information in the configuration below.
<Role NAME="External Custom Agent" EXTERNAL="Yes"> <ExternalClientRowRetriever>com.adminserver.externalClient.ExternalClientRows </ExternalClientRowRetriever> <CustomScreen>com.adminserver.externalClient.CustomScreen</CustomScreen> <RoleCode>71</RoleCode> <RoleCount>2</RoleCount> <RolePercent>100</RolePercent> </Role> In the ClientScreen business rule, make sure to include the Client configuration for the newly added external clientType. |
Implementing Java Interfaces
In addition to the business rule configuration, integration with an external client system requires implementation of several OIPA interfaces by a Java developer. The external classes that implement the interfaces described in this section should be deployed in a shared library, as with other extension classes. Please refer to the OIPA Deployment Installation instructions for your particular application server for information on how to configure shared libraries.
Retrieving a Row of External Client Data
The IExternalClientRowRetriever interface should be implemented to retrieve client data from an external system. The returned data are then displayed as a row in the role summary table on the OIPA Role screen. The same interface is also used to retrieve external client information displayed on the External Client Detail screen. The name of the implementation class (or the name of the Spring bean if the implementation class is registered as a Spring component) should be specified for each external role in the business rules as described in the Rules Configuration section above.
/** •Interface to retrieve a row of external client data. It is used to retrieve external •client data displayed in the role summary table Also, used to display external data •on the edit external client details popup screen •(for the fields marked with ExternalSource tag set to Yes) */ public interface IExternalClientRowRetriever { /** •Retrieves a row of external client data. Besides returning values to match •the columnDcl list, the implementation may return value a named "ClientName" •that will be used to display name of the client •@param keyVariableDclList •list of keys that identify external client •@param columnDclList •list of columnDcl objects that defines returned values •@param locale •current user locale •@return */ public List <VariableDcl> retrieveRow( List <VariableDcl> keyVariableDclList, List <ColumnDcl> columnDclList, Locale locale ) throws ExternalClientException; } |
The retrieveRow method of the IExternalClientRowRetriever interface has the following parameters:
- A list of VariableDcl objects containing data to identify a client in an external system. This contains keys that have been retrieved from an external system when a client has been selected. The key data are stored in the OIPA database in the AsExternalClient/AsExternalClientField tables and used when a client needs to be identified in the external system. A VariableDcl object is a POJO (Plain Old Java Object) bean with the following properties:
String variableName; String dataType; Object value; String currencyCode; The values of the dataType property are listed below: "01", //Date "02", //Text "03", //Integer "04", //Float |
The object type of the value property should match the type of the VariableDcl instance. The currencyCode property should be set for the currency values.
- A list of ColumnDcl objects describing what values should be returned from the method. The list consists of columns configured in the RoleScreen business rule (for the role view), as described in the Rules Configuration section above, that have the Group attribute set to either CLIENT or CLIENTFIELD. A ColumnDcl object is a POJO bean that has the following properties, which areimportant in the context of the retrieveRow method:
private String dataType; private String name; The dataType property may have the following values: public static final String DATATYPE_Date = "Date"; public static final String DATATYPE_Money = "Money"; public static final String DATATYPE_Integer = "Integer"; public static final String DATATYPE_Decimal = "Decimal"; public static final String DATATYPE_Percent = "Percent"; public static final String DATATYPE_Text = "Text"; |
The locale of the current user can be used to localize returned values if required.
The retrieveRow method retrieves a list of VariableDcl objects that represents search results in an external client system based on the key values passed in the first parameter. The elements in the list should match the elements requested in the second parameter of the method. Additionally, the method may add a VariableDcl object with the name "ClientName" to the list. This value is used by OIPA to display the client name in the left side navigation bar on the role screen.
In case of failure, the method may throw an instance of the ExternalClientException exception class, derived from the Exception class, that has the following constructors:
public class ExternalClientException extends Exception { public ExternalClientException( String message ){. . . public ExternalClientException( Throwable cause ) {. . . public ExternalClientException( String message, Throwable cause ) {. . . Here is a simple example of the interface implementation: @Component @Scope("singleton") public class ExternalClientRows implements IExternalClientRowRetriever { public List <VariableDcl> retrieveRow( List <VariableDcl> keyVariableDclList, List <ColumnDcl> columnDclList, Locale locale ) throws ExternalClientException { if( keyVariableDclList == null || keyVariableDclList.size() != 1 ) { throw new ExternalClientException( "Missing or redundant keys" ); } VariableDcl keyVarDcl = keyVariableDclList.get( 0 ); int key = TypeHelperUtl.getInt( keyVarDcl.getValue() ); ExClientDcl exClientDcl = ExClientDal.findClients(key); if( exClientDcl == null ) { throw new ExternalClientException( "Could not find an external client:" + key ); } List <VariableDcl> results = new ArrayList <VariableDcl>(); for( ColumnDcl columnDcl : columnDclList ) { String value = ""; if( "Name".equalsIgnoreCase( columnDcl.getName() ) ) { value = exClientDcl.getLastName() + ", " + exClientDcl.getFirstName(); } else if( "LastName".equalsIgnoreCase( columnDcl.getName() ) ) { value = exClientDcl.getLastName(); } else if( "FirstName".equalsIgnoreCase( columnDcl.getName() ) ) { value = exClientDcl.getFirstName(); } else if( "Address".equalsIgnoreCase( columnDcl.getName() ) ) { value = exClientDcl.getAddress(); } else if( "TaxId".equalsIgnoreCase( columnDcl.getName() ) ) { value = exClientDcl.getTaxId(); } VariableDcl varDcl = new VariableDcl( columnDcl.getName(), value, FieldDataType.TEXT.getTypeCode() ); results.add( varDcl ); } VariableDcl varDcl = new VariableDcl( "ClientName", exClientDcl.getLastName() + ", " + exClientDcl.getFirstName(), FieldDataType.TEXT.getTypeCode() ); results.add( varDcl ); return results; } } |
Retrieving External Client Search Results
The IExternalClientSearch interface should be implemented for external roles that are configured to use the OIPA client search tab on the Role screen, which is used to attach external clients to OIPA policies. This interface provides a method to query an external system using a set of search criteria. The search criteria, and the columns of search results returned, are configured similarly to the search configuration for clients stored in the OIPA system. The name of the implementation class (or the name of the Spring bean if the implementation class is registered as a Spring component) should be specified for each external role in the business rules as described in the Rules Configuration section above.
/** •Interface to retrieve results of an external client search. This interface is •implemented when using OIPA client search screen to retrieve results of •the external client search */ public interface IExternalClientSearch { /** •Returns client rows found by an external search for the given search criteria • •list of criteria for external client search collected on •the OIPA client search screen •@param columnDclList •list of columnDcl objects that defines returned values •@param pageNumber •page number of the search results •@param pageSize •size of the page of the search results •@param locale •current user locale •@return */ public RowDataListDcl <ExternalClientSearchRowDcl> retrieveClientSearchResults( List <IFieldDataDcl> criteriaFieldDataDclList, List <ColumnDcl> columnDclList, Integer pageNumber, Integer pageSize, Locale locale ) throws ExternalClientException; } |
The retrieveClientSearchResults method of the IExternalClientSearch interface has the following parameters:
- A list of search criteria represented by objects that implement the IFieldDataDcl interface. The following methods of the interface are the most important in the context of the external client search:
public interface IFieldDataDcl { /** * Gets the value of the field */ public Object getValue(); /** * Gets the fieldName value */ public String getFieldName(); /** * Returns the value associated with the column: DateValue */ public Date getDateValue(); /** * Returns the value associated with the column: FieldTypeCode */ public String getFieldTypeCode(); /** * Returns the value associated with the column: FloatValue */ public Double getFloatValue(); /** * Returns the value associated with the column: IntValue */ public Integer getIntValue(); /** * Returns the value associated with the column: TextValue */ public String getTextValue(); /** * Returns the currencyCode */ public String getCurrencyCode(); . . . } The values of the fieldTypeCode property are the same as the type values for the VariableDcl objects: "01", //Date "02", //Text "03", //Integer "04", //Float |
The developer must extract search criteria name/value pairs from the list, and pass them on to an external system search call.
- A list of ColumnDcl objects describing what values should be returned from the method. The list consists of columns configured in the ClientSearchScreen business rule as described in the Rules Configuration section above.
Note: The next two parameters can be used only if an external system supports paginated search. Otherwise, all external rows found by the search may be returned. This could affect the external search performance.
- Page number of the search results.
- The size of the search result page.
- The locale of the current user, which could be used to localize the returned values if desired.
The retrieveClientSearchResults method retrieves a list of ExternalClientSearchRowDcl objects. The list contains the search results from the external client system that satisfy the search criteria specified. The elements in the list should match the elements requested in the second parameter of the method. The returned list is of type RowDataListDcl. Besides a list of objects, this list also contains the total number of rows of search results. The total number of rows may be different from the number of rows returned if the external system supports pagination of search results.
public class RowDataListDcl <T> extends ArrayList <T> {
public int getTotalRowCount()
. . .
The ExternalClientSearchRowDcl objects returned in the list represent individual rows of search results. The ExternalClientSearchRowDcl class has the following properties that are important in the context of an external client search:
public class ExternalClientSearchRowDcl extends RowDcl { /** * List of external client keys that identify client in an external system */ List <VariableDcl> externalKeyVariableDclList; /** * Client name */ String clientName; . . . public class RowDcl { List <CellDcl> rowData; . . . |
The externalKeyVariableDclList list should be populated with the keys that identify rows of data in an external system. When an external client is chosen by a user to map to an external role, the key data will be stored in the OIPA database. Later, it may be used to retrieve the external client information. The clientName property may be set so that it can be used in OIPA to display a selected client name. The rowData property is used to display client data in the search result table. Each CellDcl object represents a value that will be displayed in a single cell in the search result table. The type of a CellDcl object should match the type of a corresponding ColumnDcl object in the list passed in as the second parameter of the method. This is shown in the following table:
ColumnDcl Type | CellDcl Type/Constructor | |
---|---|---|
Money | MoneyCellDcl( Double data, CurrencyDcl currencyDcl) | |
Date | DateCellDcl( Date data) | |
Integer | IntegerCellDcl( Integer data) | |
Percent | PercentCellDcl( Double data) | |
Decimal | DecimalCellDcl( Double data) | |
Text | TextCellDcl( String data) |
For money values, an instance of the CurrencyDcl class may be created using the following constructor:
public CurrencyDcl( String currencyCode, String currencyName, Integer displayRoundPlaces, Integer currencyRoundPlaces, String currencyRoundMethod ) |
In case of a failure, the method may throw an instance of the ExternalClientException exception class.
Here is a simple example of the interface implementation:
public class ExternalClientSearch implements IExternalClientSearch { /* * An exmaple implementation that always returns a single client * regardless of search criteria. It also ignores a list of * columns **/ public RowDataListDcl <ExternalClientSearchRowDcl> retrieveClientSearchResults( List <IFieldDataDcl> criteriaFieldDataDclList, List <ColumnDcl> columnDclList, Integer pageNumber, Integer pageSize, Locale locale ) throws ExternalClientException { RowDataListDcl <ExternalClientSearchRowDcl> results = new RowDataListDcl <ExternalClientSearchRowDcl>(); ExternalClientSearchRowDcl rowDcl = new ExternalClientSearchRowDcl(); rowDcl.getRowData().add( new TextCellDcl( "LastName, FirstName" ) ); rowDcl.getRowData().add( new TextCellDcl( "123-23-8970") ); rowDcl.getRowData().add( new TextCellDcl( "100 Street Town, PA 19003" ) ); rowDcl.setClientName( "LastName, FirstName" ); List <VariableDcl> varDclList = new ArrayList <VariableDcl>(); VariableDcl varDcl = new VariableDcl( "CLID", "12345", FieldDataType.TEXT.getTypeCode(), null ); varDclList.add( varDcl ); rowDcl.setExternalKeyVariableDclList( varDclList ); results.add( rowDcl ); results.setTotalRowCount( 1 ); return results; } } |
Implementing Custom External Client Search Page
The IExternalClientSearchScreen interface should be implemented for external roles that are configured to use a custom Client Search screen included on the OIPA Role screen. This interface provides methods for OIPA to find an external page html, retrieve an external client selection made on the custom screen, and map it to an external role. OIPA does not make any assumptions regarding the custom search screen, but simply includes it within the OIPA Role screen. Then it requests the selection from the custom screen through the interface. The name of the implementation class (or the name of the Spring bean if the implementation class is registered as a Spring component) should be specified for each external role in the business rules as described in the Rules Configuration section above.
/** •Interface is required to implement custom client search screen. This is a stateful •interface. An instance of an object that implements this interface is created •and kept in the role page bean (request scope) maintaining the state •of the current search for a user */ public interface IExternalClientSearchScreen { /** •Returns URL to an external HTML page include. The include file should be deployed •on a web server and accessible through HTTP. •@return */ public String getScreenUrl(); /** •Retrieves the current selection of an external client search screen. •The state of the search is maintained by storing an instance of •this object in the role page bean •@return */ public ExternalClientSearchRowDcl retrieveSelection() throws ExternalClientException; } |
The getScreenUrl method of the interface returns a URL to HTML page that will be included in the tab normally occupied by the client search on the OIPA Role screen. The custom HTML page include should be deployed as a web application and available to the OIPA system through HTTP protocol.
Here is a simple example of the interface implementation:
public class CustomScreen implements IExternalClientSearchScreen { public CustomScreen() { super(); } public String getScreenUrl() { return "http://localhost:8080/includes/ExternalClientSearch.txt"; } |
Developing a Custom Page
The OIPA role page, both for policy and segment roles, may be configured to include a custom client search page allowing OIPA customers to customize external client search to satisfy business requirements that can't be satisfied with the standard configurable OIPA client search. It has been discussed in the previous sections how to configure business rules and create a Java implementation of the IExternalClientSearchScreen interface. This section will discuss how to create a html page that will be included on the Client Search tab of the OIPA Role screen.
Typically, a custom search html page should display a set of search criteria and a table with search results that allows the selection of a single row of results before the user clicks the "Add" button to create a role mapped to the selected external client. Please note, the "Add" buttons belongs to the OIPA role page and not the custom include subpage. On row selection, a call back function externalInterfaceCallback(var interfaceName, var externalClientSearchRowDcl ) shall be invoked from the javascript. The callback function has two arguments, interfaceName shall be a string with a value 'externalClient' and externalClientSearchRowDcl is the selected ExternalClientSearchRowDcl record.
Below is an example of the IexternalClientSearchScreen interface implementation.
public class CustomScreen implements IExternalClientSearchScreen { public CustomScreen() { super(); } public String getScreenUrl() { return "http://localhost:8080/includes/ExternalClientSearch.txt"; } public String getTitleCustom() { return "Custom Screen"; } public String getTitleCustomContent() { return "External Client Search"; } } The custom search html page may look like this. This custom html page should be deployed in a web server.. |
<table> <tr id="row1"> <td> </td> <td><button onclick="onSelectionEvent(rowDcl)"> Select</button></td> </tr> </table> <script type="text/javascript"> function onSelectionEvent(rowDcl) { externalInterfaceCallback('externalClient', rowDcl); } </script> |