Creating Red Hat Decision Manager business applications with Spring Boot

Red Hat Decision Manager 7.2

Red Hat Customer Content Services

Abstract

This document describes how to create Red Hat Decision Manager business applications using Spring Boot starters.

Preface

As a developer, you can use Spring Boot starters through the business applications website to quickly create Red Hat Decision Manager business applications, configure those applications, and deploy them to an existing service or in the cloud.

Chapter 1. Red Hat Decision Manager business applications

Spring Framework is a Java platform that provides comprehensive infrastructure support for developing Java applications. Spring Boot is a lightweight framework based on Spring Boot starters. Spring Boot starters are pom.xml files that contain a set of dependency descriptors that you can include in your application.

Red Hat Decision Manager business applications are flexible, UI-agnostic logical groupings of individual services that provide certain business capabilities. Business applications are based on Spring Boot starters. They are usually deployed separately and can be versioned individually. A complete business application enables a domain to achieve specific business goals, for example order management or accommodation management.

On the business application website you can create a Process Automation Manager, Decision Manager, or Business Optimizer business application. After you create and configure your business application, you can deploy it to an existing service or to the cloud, through OpenShift.

Business applications can contain one or more of the following projects and more than one project of the same type:

  • Business assets (kjar): Contains business processes, rules, and forms and are easily imported into Decision Central.
  • Data model: Data model projects provide common data structures that are shared between the service projects and business assets projects. This enables proper encapsulation, promotes reuse, and reduces shortcuts. Each service project can expose its own public data model.
  • Service: A deployable project that provides the actual service with various capabilities. It includes the business logic that operates your business. In most cases, a service project includes business assets and data model projects. A business application can split services into smaller component service projects for better manageability.

Chapter 2. Creating a business application

You can use the business application website to quickly and easily create business applications using the Spring Boot framework. Doing this by-passes the need to install and configure Red Hat Decision Manager.

Procedure

  1. Enter the following URL in a web browser:

    https://start.jbpm.org
  2. Click Configure your business application.
  3. Click Decision Management and click Next.
  4. Enter a package and application name.
  5. From the Version menu, select Enterprise 7.2 and click Next.

    Note

    You must select Enterprise 7.2 to create a Red Hat Decision Manager business application.

  6. Select the project types that you want to include in your project. You can include more than one project type.

    • Business Assets: Contains business processes, rules, and forms and are easily imported into Decision Central. Select Dynamic Assets instead if you want to add adaptive and dynamic assets such as cases.
    • Data Model: Provides common data structures that are shared between the service projects and business assets projects. This enables proper encapsulation, promotes reuse, and reduces shortcuts. Each service project can expose its own public data model.
    • Service: Includes business logic that operates your business.
  7. Click Generate business application.

    The <business-application>.zip file downloads, where <business-application> is the name that you entered in the Application Name box.

  8. Unzip the <business-application>.zip file.
  9. Open the <business-application>/business-application-service/src/main/docker/settings.xml file in a text editor.
  10. Add the following repository to the repositories element:

    <repository>
      <id>jboss-enterprise-repository-group</id>
      <name>Red Hat JBoss Enterprise Maven Repository</name>
      <url>https://maven.repository.redhat.com/ga/</url>
      <layout>default</layout>
      <releases>
        <updatePolicy>never</updatePolicy>
      </releases>
      <snapshots>
        <updatePolicy>daily</updatePolicy>
      </snapshots>
    </repository>
  11. Add the following plug-in repository to the pluginRepositories element:

    <pluginRepository>
      <id>jboss-enterprise-repository-group</id>
      <name>Red Hat JBoss Enterprise Maven Repository</name>
      <url>https://maven.repository.redhat.com/ga/</url>
      <layout>default</layout>
      <releases>
        <updatePolicy>never</updatePolicy>
      </releases>
      <snapshots>
        <updatePolicy>daily</updatePolicy>
      </snapshots
    </pluginRepository>

    Doing this adds the productized Maven repository to your business application.

Chapter 3. Business application configuration

3.1. Business application authentication and authorization

By default, business applications are secured by protecting all REST endpoints (URLs that contain /rest/). In addition, business applications have two sets of log in credentials that allow users to connect to Decision Central in development mode: the user with the ID user and password user and the kieserver user (password kieserver1!).

Both authentication and authorization is based on Spring security. Alter this security configuration for all business applications used in production environments. You can make configuration changes in the <business-application>/<business-application>-services/src/main/java/com/company/service/DefaultWebSecurityConfig.java file:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;


@Configuration("kieServerSecurity")
@EnableWebSecurity
public class DefaultWebSecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
        .csrf().disable()
        .authorizeRequests()
        .antMatchers("/rest/*").authenticated()
        .and()
        .httpBasic();
    }

    @Autowired
    public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
        auth.inMemoryAuthentication().withUser("user").password("user").roles("kie-server");
        auth.inMemoryAuthentication().withUser("kieserver").password("kieserver1!").roles("kie-server");
    }
}

3.2. Configuring the application.properties file

After you create your business application, you can configure several components through the application.properties file to customize your application.

Prerequisites

  • You have a <business-application>.zip file that you created using the business application website.

Procedure

  1. Unzip the <business-application>.zip file and navigate to the <business-application>/<business-application>-service/src/main/resources folder.
  2. Open the application.properties file in a text editor.
  3. Configure the host, port, and path for the REST endpoints, for example:

    server.address=localhost
    server.port=8090
    
    cxf.path=/rest
  4. Configure the Decision Server (kieserver) so that it can be more easily identified, for example:

    kieserver.serverId=<business-application>-service
    kieserver.serverName=<business-application>-service
    kieserver.location=http://localhost:8090/rest/server
    kieserver.controllers=http://localhost:8080/jbpm-console/rest/controller

    The following table lists the Decision Server parameters that you can configure in your business application:

    Table 3.1. kieserver parameters

    ParameterValuesDescription

    kieserver.serverId

    string

    The ID used to identify the business application when connecting to the Decision Manager controller.

    kieserver.serverName

    string

    The name used to identify the business application when connecting to the Decision Manager controller. Can be the same string used for the kieserver.serverId parameter.

    kieserver.location

    URL

    Used by other components that use the REST API to identify the location of this server. Do not use the location as defined by server.address and server.port.

    kieserver.controllers

    URLs

    A comma-separated list of controller URLs.

  5. If you selected Business Automation when you created your business application, specify which of the following components that you want to start at runtime:

    Table 3.2. kieserver capabilities parameters

    ParameterValuesDescription

    kieserver.drools.enabled

    true, false

    Enables or disables the Decision Manager component.

    kieserver.dmn.enabled

    true, false

    Enables or disables the Decision Model and Notation (DMN) component.

3.3. Configuring the business application with Red Hat Single Sign-On

You can use Red Hat Single Sign-On (RH SSO) to enable single sign-on between your services and to have a central place to configure and manage your users and roles.

Prerequisites

Procedure

  1. Download and install RH SSO. For instructions, see the Red Hat Single Sign-On Getting Started Guide.
  2. Configure RH SSO:

    1. Either use the default master realm or create a new realm.
    2. Create the springboot-app client and set the AccessType to public.
    3. Set a valid redirect URI and web origin according to your local setup, for example:

      • Valid redirect URIs: http://localhost:8090/*
      • Web origin: http://localhost:8090
    4. Create realm roles that are used in the application.
    5. Create users that are used in the application and assign roles to them.
  3. Add the following dependencies to the service project pom.xml file:

    <dependencyManagement>
      <dependencies>
        <dependency>
          <groupId>org.keycloak.bom</groupId>
          <artifactId>keycloak-adapter-bom</artifactId>
          <version>${version.org.keycloak}</version>
          <type>pom</type>
          <scope>import</scope>
        </dependency>
      </dependencies>
    </dependencyManagement>
    
      ....
    
    <dependency>
      <groupId>org.keycloak</groupId>
      <artifactId>keycloak-spring-boot-starter</artifactId>
    </dependency>
  4. Update the application.properties file:

    # keycloak security setup
    keycloak.auth-server-url=http://localhost:8100/auth
    keycloak.realm=master
    keycloak.resource=springboot-app
    keycloak.public-client=true
    keycloak.principal-attribute=preferred_username
    keycloak.enable-basic-auth=true
  5. Modify the DefaultWebSecurityConfig.java file to ensure that Spring Security works correctly with RH SSO:

    import org.keycloak.adapters.KeycloakConfigResolver;
    import org.keycloak.adapters.springboot.KeycloakSpringBootConfigResolver;
    import org.keycloak.adapters.springsecurity.authentication.KeycloakAuthenticationProvider;
    import org.keycloak.adapters.springsecurity.config.KeycloakWebSecurityConfigurerAdapter;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
    import org.springframework.security.config.annotation.web.builders.HttpSecurity;
    import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
    import org.springframework.security.core.authority.mapping.SimpleAuthorityMapper;
    import org.springframework.security.core.session.SessionRegistryImpl;
    import org.springframework.security.web.authentication.session.RegisterSessionAuthenticationStrategy;
    import org.springframework.security.web.authentication.session.SessionAuthenticationStrategy;
    
    @Configuration("kieServerSecurity")
    @EnableWebSecurity
    public class DefaultWebSecurityConfig extends KeycloakWebSecurityConfigurerAdapter {
    
        @Override
        protected void configure(HttpSecurity http) throws Exception {
            super.configure(http);
            http
            .csrf().disable()
            .authorizeRequests()
                .anyRequest().authenticated()
                .and()
            .httpBasic();
        }
    
        @Autowired
        public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
            KeycloakAuthenticationProvider keycloakAuthenticationProvider = keycloakAuthenticationProvider();
            SimpleAuthorityMapper mapper = new SimpleAuthorityMapper();
            mapper.setPrefix("");
            keycloakAuthenticationProvider.setGrantedAuthoritiesMapper(mapper);
            auth.authenticationProvider(keycloakAuthenticationProvider);
        }
    
        @Bean
        public KeycloakConfigResolver KeycloakConfigResolver() {
           return new KeycloakSpringBootConfigResolver();
        }
    
        @Override
        protected SessionAuthenticationStrategy sessionAuthenticationStrategy() {
            return new RegisterSessionAuthenticationStrategy(new SessionRegistryImpl());
        }
    }

3.4. Configuring business application user group providers

With Red Hat Decision Manager, you can manage human-centric activities. To provide integration with user and group repositories, you can use two KIE API entry points:

  • UserGroupCallback: Responsible for verifying whether a user or group exists and for collecting groups for a specific user
  • UserInfo: Responsible for collecting additional information about users and groups, for example email addresses and preferred language

You can configure both of these components by providing alternative code, either code provided out of the box or custom developed code.

For the UserGroupCallback component, retain the default implementation because it is based on the security context of the application. For this reason, it does not matter which backend store is used for authentication and authorisation (for example, RH-SSO). It will be automatically used as a source of information for collecting user and group information.

The UserInfo component is a separate component because it collects more advanced information.

Prerequisites

  • You have a <business-application>.zip file that you created using the business application website and that contains a business automation project.

Procedure

  1. To provide an alternative implementation of UserGroupCallback, add the following code to the Application class or a separate class annotated with @Configuration:

    @Bean(name = "userGroupCallback")
    public UserGroupCallback userGroupCallback(IdentityProvider identityProvider) throws IOException {
        return new MyCustomUserGroupCallback(identityProvider);
    }
  2. To provide an alternative implementation of UserInfo, add the following code to the Application class or a separate class annotated with @Configuration:

    @Bean(name = "userInfo")
    public UserInfo userInfo() throws IOException {
        return new MyCustomUserInfo();
    }

3.5. Enabling Swagger documentation

You can enable Swagger-based documentation for all endpoints available in the service project of your Red Hat Decision Manager business application.

Prerequisites

Procedure

  1. Unzip the <business-application>.zip file and navigate to the <business-application>/<business-application>-service folder.
  2. Open the service project pom.xml file in a text editor.
  3. Add the following dependencies to the service project pom.xml file and save the file.

    <dependency>
      <groupId>org.apache.cxf</groupId>
      <artifactId>cxf-rt-rs-service-description-swagger</artifactId>
      <version>3.1.11</version>
    </dependency>
    <dependency>
      <groupId>io.swagger</groupId>
      <artifactId>swagger-jaxrs</artifactId>
      <version>1.5.15</version>
      <exclusions>
        <exclusion>
          <groupId>javax.ws.rs</groupId>
          <artifactId>jsr311-api</artifactId>
        </exclusion>
      </exclusions>
    </dependency>
  4. To enable the Swagger UI (optional), add the following dependency to the pom.xml file and save the file.

    <dependency>
      <groupId>org.webjars</groupId>
      <artifactId>swagger-ui</artifactId>
      <version>2.2.10</version>
    </dependency>
  5. Open the <business-application>/<business-application>-service/src/main/resources/application.properties file in a text editor.
  6. Add the following line to the application.properties file to enable Swagger support:

    kieserver.swagger.enabled=true

After you start the business application, you can view the Swagger document at http://localhost:8090/rest/swagger.json. The complete set of endpoints is available at http://localhost:8090/rest/api-docs/?url=../swagger.json.

Chapter 4. Business application execution

By default, business applications contain a single runnable project, the service project. You can run the service project on Windows or Linux, in standalone or development (managed) mode. Standalone mode enables you to start your application without additional requirements. Applications started in development mode require Decision Central to be available as the Decision Manager controller.

4.1. Running business applications in standalone mode

Standalone (unmanaged) mode enables you to start your business application without additional requirements.

Prerequisites

  • You have a <business-application>.zip file that you created using the business applications website.
  • The business application is configured.

Procedure

  1. Navigate to the <business-application>/<business-application>-service folder.
  2. Enter one of the following commands:

    Table 4.1. Standalone launch options

    Command

    Description

    ./launch.sh clean install

    Launches in standalone mode on Linux or Unix.

    ./launch.bat clean install

    Launches in standalone mode on Windows.

    ./launch.sh clean install -Pmysql

    Launches in standalone mode on Linux or Unix if you have configured the application with a MySQL database.

    ./launch.bat clean install -Pmysql

    Launches in standalone mode on Windows if you have configured the application with a MySQL database.

    ./launch.sh clean install -Ppostgres

    Launches in standalone mode on Linux or Unix if you have configured the application with a postgreSQL database.

    ./launch.bat clean install -Ppostgres

    Launches in standalone mode on Windows if you have configured the application with a PostgreSQL database.

    The clean install argument directs Maven to build a fresh installation. The projects are then built in the following order:

    • Data model
    • Business assets
    • Service

      The first time that you run the script, it might take a while to build the project because all dependencies of the project are downloaded. At the end of the build, the application starts.

  3. Enter the following command to access your business application:

    http://localhost:8090/
  4. Enter the credentials user/user or kieserver/kieserver1!.

4.2. Running business applications in development mode

Development (managed) mode enables developers to work on a Red Hat Decision Manager business application business assets project and dynamically deploy changes to the business application without the need to restart it. In addition, development mode provides a complete monitoring environment for business automation capabilities, for example process instances, tasks, and jobs.

Prerequisites

  • You have a <business-application>.zip file that contains a business assets project, that you created using the business applications website.
  • You configured the business application.
  • Decision Central is installed and running.

Procedure

  1. Navigate to the <business-application>/<business-application>-service folder.
  2. Enter one of the following commands:

    Table 4.2. Managed launch options

    Command

    Description

    ./launch-dev.sh clean install

    Launches in development mode on Linux or Unix.

    ./launch-dev.bat clean install

    Launches in development mode on Windows.

    ./launch-dev.sh clean install -Pmysql

    Launches in development mode on Linux or Unix if you have configured the application with a MySQL database.

    ./launch-dev.bat clean install -Pmysql

    Launches in development mode on Windows if you have configured the application with a MySQL database.

    ./launch-dev.sh clean install -Ppostgres

    Launches in development mode on Linux or Unix if you have configured the application with a postgreSQL database.

    ./launch-dev.bat clean install -Ppostgres

    Launches in development mode on Windows if you have configured the application with a PostgreSQL database.

    The clean install argument directs Maven to build a fresh installation. The projects are then built in the following order:

    • Data model
    • Business assets
    • Service

      The first time that you run the script, it might take a while to build the project because all dependencies of the project are downloaded. At the end of the build, the application starts.

  3. Enter the following command to access your business application:

    http://localhost:8090/
  4. Enter the credentials user/user or kieserver/kieserver1!. After the business application starts, it connects to the Decision Manager controller and is visible in MenuDeployExecution Servers in Decision Central.

Chapter 5. Importing business assets projects into and deploying from Decision Central

You can import a business assets project that is part of a Red Hat Decision Manager business application into Decision Central and then deploy that project to a business application.

Prerequistes

  • You have a business application project running in development mode.
  • Red Hat Decision Manager Decision Central is installed.

Procedure

  1. Navigate to the <business-application>/<business-application>-kjar folder.
  2. Execute the following following commands to initialize the Git repository for your project:

    $ git init
    $ git add -A
    $ git commit -m "Initial project structure"
  3. Log in to Decision Central and go to MenuDesignProjects.
  4. Select Import Project and enter following URL:

     file:///<business-application-path>/<business-application-name>-kjar
  5. Click Import and confirm the project to be imported.
  6. After the business assets project is imported into Decision Central, open the project and click Add Assets to add assets such as rules and decision tables to your business assets project.
  7. Click Deploy on your project page to deploy your project to a running business application.
  8. To verify the deployment, go to MenuDeployExecution Servers.

Appendix A. Versioning information

Documentation last updated on Wednesday, March 27, 2019.

Legal Notice

Copyright © 2019 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.