External Functions

COMPASS Version 6.2, 6.3, 6.4 © General Re Corporation 2021 - 2026. All Rights Reserved (created: 2025-05-05 generated: 2026-07-10)

Introduction

COMPASS stores most of the knowledge used for the assessment of cases in databases. However there is a part of knowledge that is not represented in form of rules and objects but in form of mathematical calculations e.g. calculation of loadings from extra mortalities. Those calculations are realised as Java-Functions; called external functions in this document. GenRe’s versions of those functions are shipped with COMPASS as part of the file lib/externalFunctions.jar.

When there is the need to modify a GenRe calculation, this can be done by the customer by rewriting the corresponding calculation. The programmer responsible for the rewriting should read Data Types and Interfaces for the basic structure of an external function. Interfaces for existing External Functions describes the currently available interfaces for external functions.

Example: Creating a New External Function presents a step-by-step guide of how to create an external function based on an example; while Adaptation of Database deals with the integration of this external function into the existing environment. Finally Overview over existing External Functions describes some of GenRe’s external functions more in detail.

Data Types and Interfaces

This chapter explains the general data structures that are passed between the assessment logic (COMPASS) and an external function.

All classes and interfaces described in this chapter can be found in the file lib/compass.jar of the standard delivery.

An external function that is to be used by COMPASS is a Java-Class with a public constructor with no arguments. The class has to implement the interface com.cr.compass.external.ExternalOperator. This interface specifies only one method named evaluate:

com.cr.compass.external.ExternalValue evaluate (com.cr.compass.external.ExternalValue[] inargs) throws com.cr.compass.external.ExternalException;

It is the programmer’s job to create this class and to implement the evaluate method. The only exception that should be thrown by this method is com.cr.compass.external.ExternalException. This exception is to be used if the calculation ends abnormally.

The arguments and the return value of the evaluate method are implementations of the interface com.cr.compass.external.ExternalValue. As values can be numbers, Strings or IDs of selections, there are three interfaces that extend this interface. They are presented together with their method to access the wrapped value:

  • com.cr.compass.external.ExternalNumericValue
    The value-accessing method is double getValue();
    For convenience reasons this Interface has an implementing class called
    com.cr.compass.external.ExternalNumericValueImpl.

  • com.cr.compass.external.ExternalSelectionValue
    The value-accessing method is int getSelectionId();

  • com.cr.compass.external.ExternalStringValue
    The value-accessing method is String getValue();
    This interface is currently not used at all.

The return value for the evaluate method is currently in all cases an ExternalNumericValue. Programmers can use the class ExternalNumericValueImpl to create the object that should be returned by the evaluate method.

The input arguments for the evaluate method are passed as an array of ExternalValues: com.cr.compass.external.ExternalValue[ ]. Which arguments are passed, and what the return value should contain, is described in the Interfaces for existing External Functions.

Interfaces for existing External Functions

There are currently four types of external functions:

Each of these four types expects the arguments of the evaluate-method in a specific way/order. They are described in detail in the following subchapters. The ID of each External Function is important, as will be seen in Adaptation of Database.

EM/Loading from Height/Weight

ID of the External Function: 1003

Description:

Computes the extra mortality in percent (if Plan Type is Life) or loading in per cent (if Plan Type is IP) for a given age, gender, height, weight and a flag whether light groups should be considered.

Most insurance companies are replacing this function by the BMI-calculation of the extra mortality. See EM from BMI for the BMI calculations.

Input arguments in the following order:

Type Description

ExternalNumericValue

Age in years, e.g. 17.0

ExternalSelectionValue

Gender: 3 for female, 2 for male

ExternalNumericValue

Height in cm

ExternalNumericValue

Weight in kg

ExternalNumericValue (see comment below)

Group: is 0.0 for Normal groups, else Lighter Group

ExternalNumericValue (see comment below)

Plan Type: is 0.0 for IP (PHI), else Life

Comment for German version of COMPASS:
The 5th and 6th argument are not used, i.e. they are not passed to the External Function.

Return value:

Type Description

ExternalNumericValue

An extra mortality. A negative number means underweight, positive numbers overweight.

Special values are:
• 998 is return code for "no existing table"
• 997 is return code for "height not found in table"
• 999 no extra mortality for extreme underweight or overweight

EM from BMI

ID of the External Function: 1005

Description:

Computes the extra mortality for most benefits, a given age, gender, BMI and a flag whether light groups should be considered. For Disability benefits a waiting period can be considered in the calculation.

Input arguments in the following order:

Type Description

ExternalNumericValue

Age in years, e.g. 17.0

ExternalSelectionValue

Gender: 3 for female, 2 for male

ExternalNumericValue

Unused (was: Measure system: 0.0 for "imperial", 1.0 for "metric"; see remark below)

ExternalNumericValue

Unused (was Height; in cm or feet, depending on 3rd argument; see remark below)

ExternalNumericValue

Unused (was Height2; 0.0 or inches, depending on 3rd argument; see remark below)

ExternalNumericValue

Unused (was Weight; in cm or stones, depending on 3rd argument; see remark below)

ExternalNumericValue

Unused (was Height2; 0.0 or pounds, depending on 3rd argument; see remark below)

ExternalNumericValue

BMI

ExternalNumericValue

Group: is 0.0 for Normal groups, else Lighter Group

ExternalSelectionValue

Benefit-Type
0=Life
1=Pension Annuity
2=WOP own
3=CI
4=Hospital and Surgery
5=IP any
6=ADB
7=not assigned
8=WOP any
9=LTC
10=IP own
11=DMM
12=IP ADL
13=IP own/similar
14=WOP ADL
15=WOP own/similar
16=TPD own
17=TPD own/similar
18=TPD any
19=TPD ADL
20=Savings
21=BE
22=Debility
23=AI
24=Surgery (Korea)
25=Outpatient (Korea)
26=Implants/Transplants (Israel)
27=Special Medication (Israel)

ExternalNumericValue

Waiting period, in weeks

Remark:
Input arguments described as “Unused” contain default values, and should therefore not be used for the Extra Mortality calculation in your External Function. They remain in the interface for compatibility reasons with older versions of COMPASS.

Return value:

Type Description

ExternalNumericValue

Extra mortality in percent.
Special values are:
951 virtual CMO
994 Postpone (defer) 6 months
995 Decline
997 invalid data(e.g. negative waiting period)
998 GPR (General Practitioners Report)
999 refer for individual consideration

Remark:
Not all implementations of this External Function do return all of the above special values. See EM from BMI for a detailed list of return-Values for each of the deployed BMI-calculations.

EM from Hypertonia

ID of the External Function: 1004

There are two implementations of this external function. Both are presented here, and the old one should not be used any longer.

Old Implementation

Description:

Computes an extra mortality for Life based on age, gender, systolic and diastolic blood pressure.

Input arguments in the following order:

Type Description

ExternalNumericValue

Age in years, e.g. 17.0

ExternalSelectionValue

Gender: 3 for female, 2 for male

ExternalNumericValue

Systolic pressure in mmHg (millimetres of mercury)

ExternalNumericValue

Diastolic pressure in mmHg (millimetres of mercury)

Return value:

Header 1 Header 2

Type

Description

ExternalNumericValue

Extra mortality in per cent.
Special values:
• 997 error in measurement
• 998 GPR (General Practitioners Report)
• 999 individual consideration

New Implementation

Description:

Computes an extra mortality based on age, gender, systolic and diastolic blood pressure and benefit (+ waiting period).

Input arguments in the following order:

Type Description

ExternalNumericValue

Age in years, e.g. 17.0

ExternalSelectionValue

Gender: 3 for female, 2 for male

ExternalNumericValue

Systolic pressure in mmHg (millimetres of mercury)

ExternalNumericValue

Diastolic pressure in mmHg (millimetres of mercury)

ExternalSelectionValue

Benefit-Type (see EM from BMI for details)

ExternalNumericValue

Weeks of waiting period, e.g. “4” for “4 weeks”

Return value:

Type Description

ExternalNumericValue

Extra mortality in percent.

Special values:
• 900 General Error
• 994 postpone (not used)
• 997 error in measurement
• 998 GPR, Refer or CMO (General Practitioners Report)
• 999 Decline

Conversion of EM to loading/age increase

ID of the External Function: 1001 (loading); 1002 (age increase)

Description:
This function converts a given extra mortality (specified as total mortality) to either an age increase in years or a loading in per mille. Apart from the mortality the result depends on the requested result type, the age, insurance period, premium payment period, gender and the type of Life insurance.

Input arguments in the following order:

Type Description

ExternalSelectionValue

Type of request result

For German systems: (Rückgewähr (RG) = premium refund)
0= keine Umrechnung
1= Umrechnung in Zuschlag; keine RG, keine Staffelung
2= Umrechnung in Zuschlag; mit RG, keine Staffelung
3= Umrechnung in Alterserhöhung
4= Umrechnung in Zuschlag; keine RG, Staffelung 1/4
5= Umrechnung in Zuschlag; keine RG, Staffelung 1/6
6= Umrechnung in Zuschlag; keine RG, Staffelung 1/10
7= Umrechnung in Zuschlag; mit RG, Staffelung 1/4
8= Umrechnung in Zuschlag; mit RG, Staffelung 1/6
9= Umrechnung in Zuschlag; mit RG, Staffelung 1/10

For non-German systems:
0= no conversion
1= conversion to loading
3= conversion to age increase

ExternalNumericValue

Age in years, e.g. 17.0

ExternalNumericValue

Insurance period in years

ExternalNumericValue

Premium payment period in years

ExternalSelectionValue

Gender: 3 for female, 2 for male

ExternalNumericValue

Total mortality in per cent e.g. 125.0 means 25% extra mortality

ExternalSelectionValue

Type of Life Insurance:
0 = Whole Life (Todesfall)
2 = (Termfix)
3 = Endowment (gemischte Versicherung)
4 = Unit linked Life Insurance (Fondsgebundene Versicherung)
8 = Term Insurance (Risikoversicherung)
9 = (Vermögenswirksame-Leistung Versicherung)
10 = Decreasing term insurance
Type 2 and 9 only for German systems!
No calculation for Type 4 and 9

Return value:

Type Description

ExternalNumericValue

Age increase in years, if ExternalSelectionValue is 3
Loading in per mille, otherwise
Special values:
997 error (invalid input parameters, ExternalSelectionValue is 4 or 9, etc.)

Example: Creating a New External Function

Each of the functions described in the previous chapter can be replaced by a function written by the customer. The following steps have to be performed.

In the example steps below the functionality described in EM from Hypertonia (calculate an extra mortality based on age, gender and blood pressure values) is to be replaced by a new calculation.

Step1: Create and implement a Java-class for the new external function
Assuming the new class is to be called com.mycompany.compass.Hypertonia.java

Create the file; then edit the file according to the following outline:

package com.mycompany.compass;
import com.cr.compass.external.*:
public class Hypertonia implements ExternalOperator {

// the public constructor
public Hypertonia() {}

// the mandatory evaluate method
public ExternalValue evaluate(ExternalValue[] inargs) throws ExternalException {
   ExternalNumericValue nvAge   = (ExternalNumericValue) inargs[0];
   ExternalSelectionValue svSex = (ExternalSelectionValue) inargs[1];
   ExternalNumericValue nvSyst  = (ExternalNumericValue) inargs[2];
   ExternalNumericValue nvDiast = (ExternalNumericValue) inargs[3];

   boolean male  = svSex.getSelectionId() == 2 ? true : false;
   int age       = (new Double(nvAge.getValue())).intValue();
   int systolic  = (new Double(nvSystolic.getValue())).intValue();
   int diastolic = (new Double(nvDiastolic.getValue())).intValue();

   ExternalNumericValueImpl numVal = null;
   try {
      double result = doTheCalculation(age, male, systolic, diastolic);
      numVal = new ExternalNumericValueImpl (result);
   } catch (Exception e) {
      throw new ExternalException(e);
   }
   return (numVal);
}


// the method that does the new calculation based on the input parameters
public double doTheCalculation(int anAge, boolean isMale, int aSyst, int aDiast) throws ExternalException {
   // here goes the code
   …
}
}

Step2: Compile
Compile the created java file and make sure that compass.jar is in the classpath. compass.jar contains the package com.cr.compass.external that was imported by the new class.

Step3: Test
Before integration tests with COMPASS are done, the calculation core should be tested on its own.

For tests within COMPASS the following actions have to be performed.

  • Include the new class in the compass server classpath (either include the directory or package the class file to a jar)

  • Modify the COMPASS database so that your implementation of the external function will be used. See Adaptation of Database.

  • Set-up a test case that uses the external function during the assessment.

  • Verify the results by viewing the created result or the log. You can also use System.out.println debugging or use a logging framework to log what happened in your function.

Adaptation of Database

Compass comprises a utility that sets the class name of an EXTERNAL object. Calling the main method of the class com.cr.compass.maintenance.util.plugin.ModifyExternalStringMicroAttribute starts the utility. This class requires three attributes:

  1. a valid systemID; valid entries are defined in config/server/compass.properties.

  2. the ID of an EXTERNAL object (see chapter 3 for the corresponding ID)

  3. the class name to be linked to this EXTERNAL object.

A call of this class could look as follows:

java -classpath %cpath% com.cr.compass.maintenance.util.plugin.ModifyExternalStringMicroAttribute SystemCustomer 1003 com.customer.compass.HeightWeightExtramortality

This call modifies the class related to the External Function with ID 1003 (see EM/Loading from Height/Weight). The value is set to com.customer.compass.HeightWeightExtramortality. The value is modified for the system SystemCustomer.

When COMPASS is restarted, the assessment will be done using the new External Function.

Overview over existing External Functions

For each of the External Function Interfaces described in Interfaces for existing External Functions COMPASS includes one or more calculations when shipped. The available calculations are described in the subchapters. For details about each calculation, please contact the COMPASS hotline.

EM/Loading from Height/Weight

COMPASS includes two calculations for this extra mortality. They are old GenRe calculations based on the height and weight of a person, but not using the BMI. They are included for compatibility reasons in COMPASS 4. New customers will most likely to go for the calculation using the BMI, as described in EM from BMI. One of the classes does the calculation as optimised for the German market, the other as it was recommended for non-German markets. The class names are

com.cr.compass.externalfunction.heightweight.HeightWeightExtramortality

and

com.cr.compass.externalfunction.heightweight.HeightWeightExtramortalityGerman

EM from BMI

COMPASS includes four calculations for this extra mortality. They replace the old GenRe calculation based on the height and weight of a person. We present all four of them here, giving a brief description for each calculation. The class names are

  • com.cr.compass.swissre.bmi.ExtraMortalityForBMI
    Based on the current Swiss Re tables (2005)
    Special return-value: 999

  • com.cr.compass.externalfunction.bmi.ExtraMortalityForBMI
    Based on the CLUE 3 (GenRe) calculation
    Special return-values: 995 and 999

  • com.cr.compass.dom4.bmi.ExtraMortalityForBMI
    Based on the DOM 4 (GenRe) calculation
    Special return-values: 998 and 999

  • com.cr.compass.clue4.bmi.ExtraMortalityForBMI
    Based on the CLUE 4 (GenRe) calculation
    Special return-values: 994, 995, 997, 998 and 999

EM from hypertonia

COMPASS includes calculations for the old and the new implementation of this function, see EM from BMI.

For the old implementation described in Old Implementation there is only one calculation for the extra mortality. It resembles the calculation included in CLUE (CLUE 3 and CLUE 4). The class name for this calculation is

com.cr.compass.externalfunction.hypertonia.Hypertonia

For the new implementation described in New Implementation there are currently two calculations for the extra mortality.

The following one is used to resemble the CLUE 4 calculation; its class name is

com.cr.compass.clue4.hypertonia.Hypertonia

The following one is used to resemble the DOM 4 calculation; its class name is

com.cr.compass.dom4.hypertonia.Hypertonia

Conversion of EM to loading/age increase

COMPASS includes only one conversion of an extra mortality to a loading or age increase. For non-German markets the conversion has less options than for the German market, where the conversion into a loading can be differentiated by premium refund, or grading. The class name for this conversion-calculation is

com.cr.compass.externalfunction.emconversion.EMOperator