Calling REST Services from DMN
Blog: Method & Style (Bruce Silver)
One of the basic principles of DMN is that decision services are stateless, meaning that given the same set of input data values, the service output will always be the same. But sometimes it is convenient to break that rule with tool-specific extensions. For example, in Trisotech Decision Modeler the FEEL built-in functions Today and Now, which return the current date and date/time, respectively, break the rule. If you wanted to strictly comply with DMN you would need to define those as input data and, if necessary, look up the values before executing the DMN service. But often it’s more convenient to break the rule and just use these functions within your DMN model.
A less well-known example is the ability to call a REST service in a BKM. Since this introduces new data into the decision model at runtime, it breaks the stateless principle. But if you are ok with that, it opens up a wider world of possibilities for a single decision service.
In Trisotech Decision Modeler, an expression language code value of “O” (for Operation) in the upper left of the BKM boxed expression indicates a REST service call. (Normally, the code is “F”, for FEEL.) In this post we’ll see how to use it in a DMN decision model.
To start with, you need to include a specification of the service interface in your model’s Operation Library, shown on the DMN ribbon.
There are two ways of getting it there. One is by importing an OpenAPI (also called Swagger) file or OData file, as you see in the diagram above. These are json-based service interface specifications obtained from the REST service provider. The other is by using a Trisotech connector. Trisotech’s Connector Library is a beta feature currently available only to select customers. Contact Trisotech for more information.
We’ll illustrate both of them in a simple decision model using geolocation services. Suppose you’re traveling, just arrived at your hotel. You’re hungry, but not sure what’s nearby or even where you are exactly. Here is a DMN model that lists restaurants close to your hotel, using two different geolocation APIs. The DRD is shown below:
It has a single input data element, which is my IP address. You could call a service for this as well, but I just went to myip.com and got the answer immediately. (If you do this yourself, make sure you are not using a VPN.) The decision my Location uses the ipstack Geolocation connector in the Trisotech Connector Library.
You just drag the connector onto the DRD, and it appears as the BKM Standard IP Lookup. In the Operations Library it looks like this:
The interface ipstack API exposes a single operation, Standard IP Lookup. Clicking the pencil on the operation reveals its details:
Trisotech automatically converts the output datatype Geolocation Information to a FEEL datatype in the DMN/Data Type tab. In this case we are just interested in my location specified as latitude and longitude, which are components of this type. The BKM Standard IP Lookup appears like this:
The code “O” indicates a REST operation. For these the BKM is a context, with values of context entries Interface and Operation selected from those available in the Operations Library. The input parameters IP Address and language are taken from the operation details. The decision My Location invokes this BKM and then combines the returned latitude and longitude in a single comma-delimited string.
To get the restaurants nearby, we use a second geolocation provider, here.com, which exposes a couple different services. We will use the Discovery service, which lists places near a specified location. We imported the OpenAPI spec for this service, and it too resides in our Operations Library. The interface Here API exposes an operation called Discover with the details shown below.
The input at is the location string latitude and longitude, limit is the count of nearby places returned, and q is the type of place of interest. The boxed expression for the BKM has the same format we saw before:
The decision restaurants near me is a context that first invokes the BKM and then extracts the information of interest in the final result box. It uses the my Location value returned from ipstack in the query.
When I go to myip.com I get “66.214.44.6″, so that’s our input data. We can now go to Execution/Test and run the model.
Now I have a list of 10 restaurants near me. Let’s eat!
One thing I forgot to mention: Each of these services requires an authorization credential from the service provider, either an api key or OAuth. In this case, I obtained a free api key from each provider. When you execute the service, Trisotech asks you to specify an identity, your name along with the api key.
In this snippet we haven’t used any decision rules, but it illustrates how information gathered from one or more REST services could be used within the context of a more complex decision. Once you obtain the OpenAPI file for a service, it’s easy to do!
Leave a Comment
You must be logged in to post a comment.
