The sky is the limit! And there are much more IPv6 addresses than stars in the universe!
Authors @Amel Ben Othmane, @Jean Louis Ardoint
Introduction
Starting with IBM Cloud Pak for Business Automation 25.0.0, it becomes easier to extend Automation Decision Services, ADS, with web services or REST APIs, using an external library and storing access URLs or credentials as decision runtime metadata.
In this tutorial, we will extend the ADS rule language with a way to retrieve the country that corresponds to an IP address, to enable decisions that can depend on user location, for example for access control, security or fraud detection, or any use case that requires the access to an external service during a decision execution.
Prerequisites
Before starting, make sure you have the following installed or configured:
Setting Up the external library
In ADS, an external library is a wrapper around one or more Java libraries (see ADS documentation). It allows you to enrich your data model and extend the rule language with custom types and functions. Those functions and types are provided through a business vocabulary generated by a provided maven plugin.
In this tutorial, the external library will include a call to a web service. For such a call, you will need to access URLs or credentials that may change frequently, or depend on the execution environment, for example, in a test or production environment. Those information may be stored as runtime decision metadata, which can be modified using ADS runtime REST API.
Getting the Java library
This tutorial uses a Java library that calls a web service to retrieve the country corresponding to an IP address, see IP Geolocalisation REST API. The code for this library is provided in a Git repository https://github.com/DecisionsDev/ads-web-service-call. You can directly clone this repository or download the source as a zip file and unzip it.
Once unzipped, you should get a project with the following structure:
Explore the IPAPIRequest class, which provides methods to lookup IP addresses using the IP external API. In the code, in the case the URL of the service is not set, there is a fallback code. This permits to run the decision from ADS designer, where runtime metadata cannot be modified.
You can compile and deploy the resulting jar file to the Maven artifact repository. First, you need to declare the artifact repository in settings.xml.
Then go to the IPGeoLoc directory and run the following command:
mvn deploy -s ../settings.xml
It will compile the source and test files, run the tests, package the archive, and deploy it to the Maven repository.
Annotations
The Java library code is already annotated. Here are some explanations of ADS annotations. Those annotations can be put directly on Java types or members or external annotation files can be used if the Javs source cannot be modified.
To annotate your source code, you must declare a dependency on the annotations JAR file provided with ADS and deployed to your Maven repository manager (see the pom.xml file under the IPGeoLoc folder).
There are 3 levels of visibility that can be used for a Java type or member from a library, from the most technical part to the business oriented rule language:
-
Visible from the BOM to XOM extension code: all public Java types or members from the library can be accessed in the BOM to XOM extension code.
-
Visible from the Advanced Rule Language(ARL) code: types and members that are in the BOM file of an external library can be used in ARL code in ADS. Typically, such code can be written only in task model i.e. in initial/final actions of a ruleflow tasks or in the rule selection part of a rule task. By default, all public types or members in the library are imported in the BOM. This may be restricted by changing the filter in the pom.xml file of the external library, or by annotating the Java types or members with @NotBusiness.
-
Visible from the Business Rule Language: types and members that are verbalized, i.e. have a verbalization in the voc file can be used in business rule language. By default, all BOM types and attributes are verbalized. Methods may be verbalized, depending on the importMethods parameter in the pom.xml file. The types, attributes and methods that are verbalized may be restricted by using the @NotVerbalized annotation.
Note: members that are using array of array as type or parameters are never verbalized.
Generating external library POM
ADS provides a Maven archetype that you can use to generate a Maven POM file that will be used to build the external library. Go to the ads-web-service-call directory and run the following command:
mvn archetype:generate \
-DarchetypeGroupId=com.ibm.decision \
-DarchetypeArtifactId=maven-archetype-external-library \
-DarchetypeVersion=16.0.3 \
-DgroupId=org.ipgeoloc \
-DartifactId=IPGeoLocExtLib \
-Dversion=1.0.0 \
-Ddependencies=org.ipgeoloc:IPGeoLoc:1.0.0 \
-Dlocales=en_US \
-DimportMethods=true\
-B -s settings.xml
This will generate an external library folder named IPGeoLocExtLib with a ready-to-use POM file. It contains configuration details to build the external library, for example, the dependency on the IPGeoLoc Java library.
The resulting project structure is as follows:
Note: An issue exists in ADS 25.0.0. The plugin part of pom.xml that contains maven-dependency-plugin should be erased manually.
Building the external library
Generating the library files
To build your external library, change directory to IPGeoLocExtLib run the following command:
mvn clean install -s ../settings.xml
This will and generate the following directories and files:
Editing vocabulary and annotations
You may look at the markdown file to check if all the types and methods are represented as you expect. If you are not satisfied with the external library files you can edit manually the vocabulary, add external annotations or add custom BOM types and members. This last option will be presented in the next section.
For example, you can manually edit the vocabulary by adding a reference/bom/model_en_US.voc file with this content:
#org.ipgeoloc.IPAPIRequest
org.ipgeoloc.IPAPIRequest#concept.label =
org.ipgeoloc.IPAPIRequest.ip2Country(java.lang.String)#phrase.navigation = find country from {0}
By putting an empty content for a label, we are removing the type IPAPIRequest from the vocabulary.
Using B2X extension code to access metadata
Decision service metadata are attached to a decision service archive. They may be retrieved at runtime (See the documentation). In order to access those metadata in the external library, you need to access ADS engine function by adding custom BOM types and members. For that you need to add a BOM-to-XOM (B2X) mapping file under the reference folder of the external library and define a custom bom and vocabulary. Hence, the project structure at this step should look as follows:
In extension.b2xa, add the following ARL code. For more information on the ARL language, see ARL syntax.
<b2x:translation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.ilog.com/JRules/1.2/Translation ilog/rules/schemas/1_2/b2x.xsd"
xmlns:b2x="http://schemas.ilog.com/JRules/1.2/Translation">
<class>
<businessName>utility.RemoteCallSupport</businessName>
<executionName>void</executionName>
<method>
<name>initRemoteCallURL</name>
<body language="arl"><![CDATA[
com.fasterxml.jackson.databind.JsonNode metadata =
(com.fasterxml.jackson.databind.JsonNode)runContext.getMetadata().get("ipgeoloc");
java.lang.String url = metadata != null ? metadata.textValue() : null;
note("Found url :" + url);
org.ipgeoloc.IPAPIRequest.setURL(url);
]]></body>
</method>
</class>
</b2x:translation>
Metadata can be accessed as a Jackson ObjectNode. Within the metadata, you may access the remote service URL using:
metadata.at("http://ip-api.com/json/").toString();
In the BOM extension, you can provide the following BOM method:
class RemoteCallSupport
{
static void initRemoteCallURL();
}
Open the model_en_US.voc under the reference folder. Add the following custom verbalization:
# utility.RemoteCallSupport
utility.RemoteCallSupport#concept.label =
utility.RemoteCallSupport.initRemoteCallURL()#phrase.action = initialize service URL
After those steps, you can run again the following command:
mvn clean install -s ../settings.xml
Deploying the external library
If you are satisfied with your external library content you can deploy it by running mvn deploy -s ../settings.xml. It will deploy the library JARs and any dependencies listed in the project’s POM file that are not already present in the target repository.
Note: If you deploy manually the library jars to your maven repository, make sure you add the corresponding pom.xml and deploy all dependencies.
Authoring a decision that uses the external library
Importing the external library in ADS
To import the external library, walk through steps described here. The coordinates of the IPGeoLocExtLib library are as follows:
After successfully importing the IPGeoLocExtLib library, you can navigate to it to explore its content as shown in the following screenshot and then use it within ADS.
Using the external library in a decision service
Now you will create a decision service that call this IPGeoLocExtLib external library in ADS:
-
Create a new decision service.
-
Inside this decision service, create a new decision model.
-
Click the Dependencies tab.
-
Click Add +.
-
Select IPGeoLocExtLib and click OK. Now, you can use the library in the decision service.
-
Go back to your decision model:
-
Rename the input node to IP address.
-
Click on the decision node, rename the decision node to Country
-
Click on Logic, click + to create a new Business Rule
-
Edit the rule as follows :
set decision to find country from ’IP address’;
Executing the decision
Running the decision in ADS designer
-
Click on the Run tab, click add test data set +.
-
Enter the IP address 131.132.0.0. This will trigger the fallback code, as the runtime metadata is not accessible in ADS designer.
-
Click Run, you should have "Canada" as output.
-
Try a different IP address that does not begin with 131.132. You will get the expected error url not initialized in the error message in JSON.
Deploying the decision to ADS runtime
-
In the breadcrumb, click the decision service name.
-
Click on Decision Operations tab, create a new operation for the decision model.
-
Click on Share changes on the top right and share all your changes.
-
Click on the View History tab and create a new version from the last commit.
-
Click on the Deploy tab , expand the version you created and click Deploy
The decision service is built, and a Decision Service Archive(DSA) is pushed to the embedded runtime space storage. Now you can modify the metadata associated with the deployed decision. You will need the decision ID that can be copied from this page.
Storing remote call information as decision service metadata
Decision service metadata are attached to a decision service archive (see Decision service metadata for more details).
To be able to modify the metadata of the decision service, you need permission to Manage deployed decision services, see user permission documentation.
You can create or update the metadata of a decision service archive using Decision runtime API. The operation to add metadata is :
PUT /deploymentSpaces/{deploymentSpaceId}/decisions/{decisionId}/metadata
The deploymentSpaceID is embedded when deploying from ADS designer. The decisionId can be retrieved from the deploy page (see previous section).
You may now add the IP Geolocation API URL using the REST endpoint with the following input:
{
"map": {
"ipgeoloc" : {
"name": "ipgeoloc",
"kind": " ENCRYPTED",
"readOnly": false,
"value": { "URL": "http://ip-api.com/json/"
}
}
}
}
The runtime periodically checks for metadata changes and updates its decision cache. As a consequence, if you update the metadata, you will have to wait several minutes before an execution will get the new values.
Executing the decision service
Once you have added the metadata of the IP Geolocation service to the decision archive, you can execute it as Executing decision services.
You can try it with different IP addresses, as it was done in ADS designer. It should work now for all IP addresses.
Conclusion
By wrapping Java code and REST APIs into an ADS-compatible external library you can seamlessly integrate external data and logic into ADS decision models.
You can reuse this pattern to enrich ADS with external APIs for advanced use cases such as fraud detection, compliance checks, or dynamic pricing.