Hyperon Runtime Rest

Using Hyperon Runtime REST

This short tutorial will guide you through the process of running Hyperon Runtime REST as a docker image and invoking parameter/function/domain element.

Prerequisites

In order to run examples from this article you will need:

Setting up a docker images

 

The tutorial will be based on our motor insurance demo. It consists of the insurance web application, Hyperon Studio, and Hyperon Runtime REST modules. There is a docker-compose.yml file that makes the whole application easy to run. Just download a project from GitHub, open terminal in that directory, and run the following command:

docker-compose up

 If you look closely inside the docker-compose.yml file, you will see that Hyperon Runtime REST docker image needs three additional properties to be passed to run properly:

  • mpp.database.url : JDBC url to Hyperon's database
  • mpp.database.username : Hyperon's database username
  • mpp.database.password : Hyperon's database password

If you want to connect to other database types such asOracle, Postgres, or MsSQL, then you must build your own docker image and provide your database driver. Here's a Docker file example that copies custom database driver and runs Runtime REST application: 

FROM hyperonio/runtime-rest:latest 
ARG DRIVER_JAR=dbDriver.jar
COPY ${DRIVER_JAR} driver.jar
ENTRYPOINT["java","-Dloader.path=driver.jar","-jar","/hyperon-runtime-rest.jar"]

 When everything is set up correctly, Hyperon Studio should be available at localhost:38080/hyperon/app. Use credentials:

User: admin

Password: admin

to log in. Moto insurance demo app will be available at localhost:48080/demo. Last but not least, Hyperon Runtime REST app, that interests us most, should be available at localhost:8081

 

Getting parameter value

 

We will be using parameter examples from this article. Let's get the value of a demo.motor.coverage.position parameter for the "BI" coverage code. Here's the request we're going to use:

 
{  
 "ctx": {    
  "properties": [      
    {        
     "key":"coverage.code",        
     "value":"BI"      
    }    
   ]  
 },  
 "elements": [    
  {      
   "code":"demo.motor.coverage.position",      
   "type":"PARAMETER"    
  }  
 ]
}

It consists of 2 main parts: ctx and elements.The former represents the input values we want to pass to Hyperon. We can pass there simple as well as complex objects. The latter is a list of Hyperon elements to invoke.

 

When we send this request to the localhost:8081/api/execution/invoke url, we should receive the following response: 

 
[  
  {    
   "element": {      
    "code":"demo.motor.coverage.position",      
    "type":"PARAMETER",      
    "attributeCode":null,      
    "profileCode":null    
    },    
   "resultValue": [      
    {        
     "fields": [          
      {           
       "key": "position",           
       "value": 1          
      }        
     ]      
    }    
   ]  
  }
]

We receive a list of executed Hyperon elements with corresponding values. 

 

Let's see how the response will look like if more than one row will be returned from the parameter. In this example, we are going to use the demo.motor.dict.vehicle.available Makes parameter. Here's the request:

{  
 "ctx": {    
  "properties": [      
   {        
    "key":"quote.vehicle.productionYear",        
    "value":1972      
   },
   {        
    "key":"coverage.code",        
    "value": "BI"      
   }     
  ]  
 },  
 "elements": [    
  {      
   "code":"demo.motor.dict.vehicle.availableMakes",      
   "type":"PARAMETER"    
  },   
  {      
   "code": "demo.motor.coverage.position",      
   "type":"PARAMETER"    
  }  
 ]
}

Besides a new parameter code and context property, you can see how to invoke more than one Hyperon element in a single JSON request.Let’s see the response: 

[  
 {   
  "element": {     
   "code": "demo.motor.coverage.position",     
   "type": "PARAMETER",      
   "attributeCode": null,     
   "profileCode": null    
  },   
  "resultValue": [      
   {       
    "fields": [          
     {           
      "key": "position",           
      "value": 1          
     }        
    ]      
   }    
  ]  
 },{   
  "element": {     
  "code": "demo.motor.dict.vehicle.availableMakes",     
  "type": "PARAMETER",     
  "attributeCode": null,     
  "profileCode": null    
 },   
 "resultValue": [      
  {       
   "fields": [          
    {           
     "key": "make",           
     "value": "STAR"          
    },{           
     "key": "make_id",           
     "value": 722          
    }        
   ]      
  },{       
   "fields": [          
    {           
     "key": "make",           
     "value": "TRABANT"          
    },{           
     "key": "make_id",           
     "value": 221          
    }        
   ]      
  },{       
   "fields": [          
    {           
     "key": "make",           
     "value": "UAZ"          
    },{           
     "key": "make_id",           
     "value": 315          
    }        
   ]      
  },{       
   "fields": [          
    {           
     "key": "make",           
     "value": "WARTBURG"          
    },{           
     "key": "make_id",           
     "value": 230          
    }        
   ]      
  }    
 ]  
]

As we see, each element has its own JSON section in returned array. What’s more, each row in the parameter's matrix corresponds to one complex element in the resultValue array.

 

Calling function

 

Similar to the previous section, we will be using function examples from this article. Let's get the computed value of the demo.insurance.calcpremium functionHere's the request we're going to use:

{  
 "ctx": {    
  "properties": [      
   {        
    "key":"policy.premiumPerDay",        
    "value":200      
   },{        
    "key":"policy.startDate",        
    "value": "2017-01-01"      
   },{        
    "key":"policy.endDate",        
    "value":"2017-01-03"      
   }    
  ]  
 },  
 "elements": [    
  {      
   "code":"demo.insurance.calcpremium",      
   "type":"FUNCTION"    
  }  
 ]
}

It's basically the same request as the one used in the parameter section. However, we pass here three context key-value pairs instead of one. Here's the response we should get by calling the localhost:8081/api/execution/invoke endpoint:

[  
 {    
  "element": {      
    "code":"demo.insurance.calcpremium",      
    "type":"FUNCTION",      
    "attributeCode":null,      
    "profileCode":null    
  },    
  "resultValue": 600.0  
 }
]

Again, the same response format as in the parameter's.

 

 

Accessing domain attributes

Last but not least, let's see how to access domain attributes through invoke API. We'll be using examples from this article. Let's see how to evaluate a position attribute of a coverage BI domain element: 

{  
 "ctx": {    
  "properties": [      
   {        
    "key":"coverage.code",       
    "value":"COLL"      
   }    
  ]  
 },  
 "elements": [    
  {      
   "profileCode":"DEMO",      
   "code":"/PLANS[FULL]/COVERAGES[BI]/",      
   "attributeCode":"POSITION",      
   "type":"DOMAIN_OBJECT"    
  }  
 ]
}

The main difference between domain element and parameter/function is the presence of 2 additional attributes: profileCode and attributeCode,which names are self-describing. Let's look at the response:

[  
 {    
  "element": {      
   "code":"/PLANS[FULL]/COVERAGES[BI]/",      
   "type":"DOMAIN_OBJECT",      
   "attributeCode":"POSITION",      
   "profileCode":"DEMO"    
  },    
  "resultValue": [      
   {        
    "fields": [          
     {           
      "key": "position",           
      "value": 8          
     }        
    ]      
   }    
  ]  
 }
]

As we see, the response format is the same as in the parameter/function section.

 

Summary

Congratulations! You know how to invoke parameter/function/domain attribute through Hyperon Runtime REST invoke API. If you want to learn more or discover other available endpoints, there is a Runtime REST swagger online documentation available at: http://localhost:8081/swagger-ui.html.