Procedure

1. In the directory that contains your Red Hat Process Automation Manager Spring Boot application, open the <BUSINESS-APPLICATION>-service/pom.xml file in a text editor or IDE, where <BUSINESS-APPLICATION> is the name of your Spring Boot project.

2. 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>

3. Add the following plug-in repository to the pluginRepositories element:

   Note

   If your pom.xml file does not have the pluginRepositories element, add it as well.

   <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.

Procedure

1. Navigate to the Software Downloads page in the Red Hat Customer Portal (login required), and select the following product and version from the drop-down options:

   • Product: Red Hat Process Automation Manager
   • Version: 7.10
2. Download Red Hat Process Automation Manager 7.10 Maven Repository (rhpam-7.10.0-maven-repository.zip).
3. Extract the downloaded archive.
4. Change to the ~/.m2/ directory and open the Maven settings.xml file in a text editor or integrated development environment (IDE).

5. Add the following lines to the <profiles> element of the Maven settings.xml file, where <MAVEN_REPOSITORY> is the path of the Maven repository that you downloaded. The format of <MAVEN_REPOSITORY> must be file://$PATH, for example file:///home/userX/rhpam-7.10.0.GA-maven-repository/maven-repository.

   <profile>
     <id>red-hat-enterprise-maven-repository</id>
     <repositories>
       <repository>
         <id>red-hat-enterprise-maven-repository</id>
         <url>MAVEN_REPOSITORY</url>
         <releases>
           <enabled>true</enabled>
         </releases>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
       </repository>
     </repositories>
     <pluginRepositories>
       <pluginRepository>
         <id>red-hat-enterprise-maven-repository</id>
         <url><MAVEN_REPOSITORY></url>
         <releases>
           <enabled>true</enabled>
         </releases>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
       </pluginRepository>
     </pluginRepositories>
   </profile>

6. Add the following lines to the <activeProfiles> element of the Maven settings.xml file and save the file.

   <activeProfile>red-hat-enterprise-maven-repository</activeProfile>

Procedure

1. In the directory that contains your Red Hat Process Automation Manager Spring Boot application, open the business-application-service/src/main/java/com/company/service/DefaultWebSecurityConfig.java file in a text editor or IDE.

2. To authorize requests for access by an authenticated user only if they have a specific role, edit the .antMatchers("/rest/*").authenticated().and() line in one of the following ways:

   • To authorize for a single role, edit the antMatchers method as shown in the following example, where <role> is the role that that the user must have for access:

     @Configuration("kieServerSecurity")
     @EnableWebSecurity
     public class DefaultWebSecurityConfig extends WebSecurityConfigurerAdapter {
     
         @Override
         protected void configure(HttpSecurity http) throws Exception {
             http
                 .cors().and().csrf().disable()
                 .authorizeRequests()
                     .antMatchers("/**").hasRole("<role>")
                     .anyRequest().authenticated()
                 .and().httpBasic()
                 .and().headers().frameOptions().disable();
         }
         ...

   • To authorize a user that has one of a range of roles, edit the antMatchers method as shown in the following example, where <role> and <role1> are each roles the user can have for access:

     @Configuration("kieServerSecurity")
     @EnableWebSecurity
     public class DefaultWebSecurityConfig extends WebSecurityConfigurerAdapter {
     
         @Override
         protected void configure(HttpSecurity http) throws Exception {
             http
                 .cors().and().csrf().disable()
                 .authorizeRequests()
                     .antMatchers("/**").hasAnyRole("<role>", "<role1")
                     .anyRequest().authenticated()
                 .and().httpBasic()
                 .and().headers().frameOptions().disable();
         }
         ...

Procedure

1. In the directory that contains your Red Hat Process Automation Manager Spring Boot application, open the business-application-service/src/main/java/com/company/service/DefaultWebSecurityConfig.java file in a text editor or integrated development environment (IDE).

2. Edit the .antMatchers method as shown in the following example:

       @Override
       protected void configure(HttpSecurity http) throws Exception {
   
                   http
                       .cors().and().csrf().disable()
                       .authorizeRequests()
                       .antMatchers("/*")
                           .permitAll()
                       .and().headers().frameOptions().disable();
   
       }

   The PermitAll method allows any and all requests for the specified URL pattern.

Procedure

1. Create the following class that extends the AnonymousAuthenticationFilter class:

   import org.springframework.security.authentication.AnonymousAuthenticationToken;
   import org.springframework.security.core.Authentication;
   import org.springframework.security.core.AuthenticationException;
   import org.springframework.security.core.GrantedAuthority;
   import org.springframework.security.core.authority.SimpleGrantedAuthority;
   import org.springframework.security.core.context.SecurityContextHolder;
   import org.springframework.security.web.authentication.AnonymousAuthenticationFilter;
   
   import javax.servlet.FilterChain;
   import javax.servlet.ServletException;
   import javax.servlet.ServletRequest;
   import javax.servlet.ServletResponse;
   import javax.servlet.http.HttpServletRequest;
   import java.io.IOException;
   import java.util.Arrays;
   import java.util.Collections;
   import java.util.List;
   
   public class <CLASS_NAME> extends AnonymousAuthenticationFilter {
       private static final Logger log = LoggerFactory.getLogger(<CLASS_NAME>.class);
   
       public AnonymousAuthFilter() {
           super("PROXY_AUTH_FILTER");
       }
   
       @Override
       public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
               throws IOException, ServletException {
   
           SecurityContextHolder.getContext().setAuthentication(createAuthentication((HttpServletRequest) req));
           log.info("SecurityContextHolder pre-auth user: {}",  SecurityContextHolder.getContext());
   
           if (log.isDebugEnabled()) {
               log.debug("Populated SecurityContextHolder with authenticated user: {}",
                       SecurityContextHolder.getContext().getAuthentication());
           }
   
           chain.doFilter(req, res);
       }
   
       @Override
       protected Authentication createAuthentication(final HttpServletRequest request)
               throws AuthenticationException {
   
           log.info("<ANONYMOUS_USER>");
   
   
           List<? extends GrantedAuthority> authorities = Collections
                   .unmodifiableList(Arrays.asList(new SimpleGrantedAuthority("<ROLE>")
                   ));
           return new AnonymousAuthenticationToken("ANONYMOUS", "<ANONYMOUS_USER>", authorities);
       }
   
   }

2. Replace the following variables:

   • Replace <CLASS_NAME> with a name for this class, for example AnonymousAuthFilter.
   • Replace <ANONYMOUS_USER> with a user ID, for example Service_Group.
   • Replace <ROLE> with the role that has the privileges that you want to give to <ANONYMOUS_USER>.

3. If you want to give <ANONYMOUS_USER> more than one role, add additional roles as shown in the following example:

   .unmodifiableList(Arrays.asList(new SimpleGrantedAuthority("<ROLE>")
   , new SimpleGrantedAuthority("<ROLE2>")

4. Add .anonymous().authenticationFilter(new <CLASS_NAME>()).and() to the business-application-service/src/main/java/com/company/service/DefaultWebSecurityConfig.java file, where <CLASS_NAME> is the name of the class that you created:

       @Override
       protected void configure(HttpSecurity http) throws Exception {
   
                   http
                       .anonymous().authenticationFilter(new <CLASS_NAME>()).and() // Override anonymousUser
                       .cors().and().csrf().disable()
                       .authorizeRequests()
                       .antMatchers("/*").permitAll()
                       .and().headers().frameOptions().disable();
   
       }

Procedure

1. Download and install RHSSO. For instructions, see the Red Hat Single Sign-On Getting Started Guide.

2. Configure RHSSO:

   1. Either use the default master realm or create a new realm.

      A realm manages a set of users, credentials, roles, and groups. A user belongs to and logs into a realm. Realms are isolated from one another and can only manage and authenticate the users that they control.

   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, as shown in the following 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 element and property to the Spring Boot project pom.xml file, where <KEYCLOAK_VERSION> is the version of Keycloak that you are using:

   <properties>
     <version.org.keycloak><KEYCLOAK_VERSION></version.org.keycloak>
   </properties>

4. Add the following dependencies to the Spring Boot 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>

5. In your Spring Boot project directory, open the business-application-service/src/main/resources/application.properties file and add the following lines:

   # 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

6. Modify the business-application-service/src/main/java/com/company/service/DefaultWebSecurityConfig.java file to ensure that Spring Security works correctly with RHSSO:

   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());
       }
   }

Procedure

1. Extract the Spring Boot project ZIP file and navigate to the <BUSINESS-APPLICATION>/<BUSINESS-APPLICATION>-service/src/main/resources folder, where <BUSINESS-APPLICATION> is the name of your Spring Boot project.
2. Open the application.properties file in a text editor.

3. Configure the host, port, and path for the REST endpoints, where <ADDRESS> is the server address and <PORT> is the server port:

   server.address=<ADDRESS>
   server.port=<PORT>
   cxf.path=/rest

   The following example adds the REST endpoint to the address localhost on port 8090.

   server.address=localhost
   server.port=8090
   cxf.path=/rest

Procedure

1. Extract the Spring Boot project ZIP file and navigate to the <BUSINESS-APPLICATION>/<BUSINESS-APPLICATION>-service/src/main/resources folder, where <BUSINESS-APPLICATION> is the name of your Spring Boot project.
2. Open the application.properties file in a text editor.

3. Configure the KIE Server parameters as shown in the following example:

   kieserver.serverId=<BUSINESS-APPLICATION>-service
   kieserver.serverName=<BUSINESS-APPLICATION>-service
   kieserver.location=http://localhost:8090/rest/server
   kieserver.controllers=http://localhost:8080/business-central/rest/controller

   The following table describes the KIE Server parameters that you can configure in your business project:

   Table 5.1. kieserver parameters

   Parameter	Values	Description
   kieserver.serverId	string	The ID used to identify the business application when connecting to the Process Automation Manager controller.
   kieserver.serverName	string	The name used to identify the business application when it connects to the Process Automation 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.

Procedure

1. In your Spring Boot project directory, open the business-application-service/src/main/resources/application.properties file.

2. Add the kieserver.kafka.enabled system property with value true:

   kieserver.kafka.enabled=true

Procedure

1. Extract the Spring Boot project ZIP file and navigate to the <BUSINESS-APPLICATION>/<BUSINESS-APPLICATION>-service/src/main/resources folder, where <BUSINESS-APPLICATION> is the name of your Spring Boot project.
2. Open the application.properties file in a text editor.

3. To set a component to start at runtime, set the value of the component to true.

   The following table lists the components that you can set to start at runtime:

   Table 5.2. kieserver capabilities parameters

   Parameter	Values	Description
   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.
   kieserver.jbpm.enabled	true, false	Enables or disables the Red Hat Process Automation Manager component.
   kieserver.jbpmui.enabled	true, false	Enables or disables the Red Hat Process Automation Manager UI component.
   kieserver.casemgmt.enabled	true, false	Enables or disables the case management component.

Procedure

1. Extract the Spring Boot project ZIP file and navigate to the <BUSINESS-APPLICATION>/<BUSINESS-APPLICATION>-service/src/main/resources folder, where <BUSINESS-APPLICATION> is the name of your Spring Boot project.
2. Open the application.properties file in a text editor.

3. To enable asynchronous execution, set the value of the jbpm.executor.enabled parameter to true, uncomment the other jbpm.executor parameters, and change the values as required, as shown in the following example:

   jbpm.executor.enabled=true
   jbpm.executor.retries=5
   jbpm.executor.interval=0
   jbpm.executor.threadPoolSize=1
   jbpm.executor.timeUnit=SECONDS

   The following table describes the executor parameters that you can configure in your business project:

   Table 5.3. Executor parameters

   Parameter	Values	Description
   jbpm.executor.enabled	true, false	Disables or enables the executor component.
   jbpm.executor.retries	integer	Specifies the number of retries if errors occur while a job is running.
   jbpm.executor.interval	integer	Specifies the length of time that the executor uses to synchronize with the database. The unit of time is specified by the jbpm.executor.timeUnit parameter. Disabled by default (value 0).
   jbpm.executor.threadPoolSize	integer	Specifies the thread pool size.
   jbpm.executor.timeUnit	string	Specifies the time unit used to calculate the interval that the executor uses to synchronize with the database. The value must be a valid constant of java.util.concurrent.TimeUnit. The default value is SECONDS.

Procedure

1. Create the quartz.properties file and add the following content:

   #============================================================================
   # Configure Main Scheduler Properties
   #============================================================================
   org.quartz.scheduler.instanceName = SpringBootScheduler
   org.quartz.scheduler.instanceId = AUTO
   org.quartz.scheduler.skipUpdateCheck=true
   org.quartz.scheduler.idleWaitTime=1000
   #============================================================================
   # Configure ThreadPool
   #============================================================================
   org.quartz.threadPool.class = org.quartz.simpl.SimpleThreadPool
   org.quartz.threadPool.threadCount = 5
   org.quartz.threadPool.threadPriority = 5
   #============================================================================
   # Configure JobStore
   #============================================================================
   org.quartz.jobStore.misfireThreshold = 60000
   org.quartz.jobStore.class=org.quartz.impl.jdbcjobstore.JobStoreCMT
   org.quartz.jobStore.driverDelegateClass=org.jbpm.process.core.timer.impl.quartz.DeploymentsAwareStdJDBCDelegate
   org.quartz.jobStore.useProperties=false
   org.quartz.jobStore.dataSource=myDS
   org.quartz.jobStore.nonManagedTXDataSource=notManagedDS
   org.quartz.jobStore.tablePrefix=QRTZ_
   org.quartz.jobStore.isClustered=true
   org.quartz.jobStore.clusterCheckinInterval = 5000
   #============================================================================
   # Configure Datasources
   #============================================================================
   org.quartz.dataSource.myDS.connectionProvider.class=org.jbpm.springboot.quartz.SpringConnectionProvider
   org.quartz.dataSource.myDS.dataSourceName=quartzDataSource
   org.quartz.dataSource.notManagedDS.connectionProvider.class=org.jbpm.springboot.quartz.SpringConnectionProvider
   org.quartz.dataSource.notManagedDS.dataSourceName=quartzNotManagedDataSource

   Note

   Data source names in the Quartz configuration file refer to Spring beans. The connection provider must be set to org.jbpm.springboot.quartz.SpringConnectionProvider to enable integration with Spring-based data sources.

2. To enable the Quartz clustered timers and set the path of the quartz.properties file that you created in the previous step, include the following properties in the <BUSINESS-APPLICATION>/<BUSINESS-APPLICATION>-service/src/main/resourcesapplication.properties file, where <BUSINESS-APPLICATION> is the name of your Spring Boot project.

   jbpm.quartz.enabled=true
   jbpm.quartz.configuration=quartz.properties

3. Create a managed and an unmanaged data source by adding the following content to the <BUSINESS-APPLICATION>/<BUSINESS-APPLICATION>-service/src/main/resources/application.properties file:

   # enable to use database as storage
   jbpm.quartz.db=true
   
   quartz.datasource.name=quartz
   quartz.datasource.username=sa
   quartz.datasource.password=sa
   quartz.datasource.url=jdbc:h2:./target/spring-boot-jbpm;MVCC=true
   quartz.datasource.driver-class-name=org.h2.Driver
   
   # used to configure connection pool
   quartz.datasource.dbcp2.maxTotal=15
   
   # used to initialize quartz schema
   quartz.datasource.initialization=true
   spring.datasource.schema=classpath*:<QUARTZ_TABLES_H2>.sql
   spring.datasource.initialization-mode=always

   In the preceding example, replace <QUARTZ_TABLES_H2> with the name of a Quartz H2 database schema script. The last three lines of the preceding configuration initialize the database schema.

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();
   }

Procedure

1. Extract the Spring Boot project ZIP file and navigate to the <BUSINESS-APPLICATION>/<BUSINESS-APPLICATION>-service/src/main/resources folder, where <BUSINESS-APPLICATION> is the name of your Spring Boot project.
2. Open the application.properties file in a text editor.

3. Configure your Spring Boot project to use a MySQL or PostgreSQL, complete one of the following set of steps:

   1. To configure your business application to use a MySQL database, locate the following parameters in the application.properties file and change the values as shown:

      spring.datasource.username=jbpm
      spring.datasource.password=jbpm
      spring.datasource.url=jdbc:mysql://localhost:3306/jbpm
      spring.datasource.driver-class-name=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource
      
      spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect

   2. To configure your business application to use a PostgreSQL database, locate the following parameters in the application.properties file and change the values as shown:

      spring.datasource.username=jbpm
      spring.datasource.password=jbpm
      spring.datasource.url=jdbc:postgresql://localhost:5432/jbpm
      spring.datasource.driver-class-name=org.postgresql.xa.PGXADataSource
      
      spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

      Note

      To create a PostgreSQL schema that uses the bytea column type instead of the oid column type, set the value of the org.kie.persistence.postgresql.useBytea property to true:

      org.kie.persistence.postgresql.useBytea=true

4. Save the application.properties file.

Procedure

1. Extract the <BUSINESS-APPLICATION>.zip file and navigate to the <BUSINESS-APPLICATION>/<BUSINESS-APPLICATION>-service/src/main/resources folder, where <BUSINESS-APPLICATION> is the name of your Spring Boot project.
2. Open the application.properties file in a text editor.

3. Locate the following parameters in the application.properties file and verify that they have the values shown:

   spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.H2Dialect
   spring.jpa.properties.hibernate.show_sql=false
   spring.jpa.properties.hibernate.hbm2ddl.auto=update
   spring.jpa.hibernate.naming.physical-strategy=org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl

4. If your business application has business automation capabilities, you can add entities to the entity manager factory by adding a comma-separated list of packages:

   spring.jpa.properties.entity-scan-packages=org.jbpm.springboot.samples.entities

   Business applications with business automation capabilities create an entity manager factory based on the persistence.xml file that comes with Red Hat Process Automation Manager. All entities found in the org.jbpm.springboot.samples.entities package are automatically added to the entity manager factory and used the same as any other JPA entity in the application.

Procedure

1. Add a customized entity manager JavaBean to your java class. The following example shows an entity manager Java Bean called auditEntityManager for a Java Persistence API (JPA) data source:

       @Bean(name = "auditEntityManager")
       @ConditionalOnMissingBean(name = "auditEntityManager")
       public LocalContainerEntityManagerFactoryBean entityManagerFactory(@Qualifier("jpaAuditDataSource") DataSource dataSource, JpaProperties jpaProperties) {
           return EntityManagerFactoryHelper.create(applicationContext,
                                                    dataSource,
                                                    jpaProperties,
                                                    "custom-persistent-unit",
                                                    "classpath:/META-INF/persistence.xml");
       }

   The auditEntityManager becomes an implicit context parameter when the parameters are resolved during MVFLEX Expression Language (MVEL) evaluation.

2. Add the following marshalling stragegy to the kie-deployment-descriptor.xml file:

    <marshalling-strategy>
       <resolver>mvel</resolver>
       <identifier>new org.drools.persistence.jpa.marshaller.JPAPlaceholderResolverStrategy(auditEntityManager)
       </identifier>
       <parameters/>
       </marshalling-strategy>

Procedure

1. Extract the <BUSINESS-APPLICATION>.zip file and navigate to the <BUSINESS-APPLICATION>/<BUSINESS-APPLICATION>-service folder, where <BUSINESS-APPLICATION> is the name of your Spring Boot project.
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.2.6</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

Procedure

1. Navigate to the <BUSINESS-APPLICATION>/<BUSINESS-APPLICATION>-service folder.

2. Enter one of the following commands:

   Table 7.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!.

Procedure

1. Navigate to the <BUSINESS-APPLICATION>/<BUSINESS-APPLICATION>-service folder, where <BUSINESS-APPLICATION> is the name of your Spring Boot project.

2. Enter one of the following commands:

   Table 7.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 Process Automation Manager controller and is visible in Menu → Deploy → Execution Servers in Business Central.

1. Log in to the RH-SSO Admin Console and open the realm that you want to add a user to.

2. Click the Users menu item under the Manage section.

   An empty user list appears on the Users page.

3. Click the Add User button on the empty user list to start creating your new user.

   The Add User page opens.

4. On the Add User page, enter the user information and click Save.
5. Click the Credentials tab and create a password.

6. Assign the new user one of the roles that allows access to Red Hat Process Automation Manager. For example, assign the admin role to access Business Central or assign the kie-server role to access KIE Server.

   Note

   For projects that deploy from Business Central on OpenShift, create an RH-SSO user called mavenuser without any role assigned, then add this user to the BUSINESS_CENTRAL_MAVEN_USERNAME and BUSINESS_CENTRAL_MAVEN_PASSWORD in your OpenShift template.

7. Define the roles as realm roles in the Realm Roles tab under the Roles section.

   Alternatively, for roles used in Business Central, you can define the roles as client roles for the kie client. For instructions about configuring the kie client, see Section 16.1, “Creating the Business Central client for RH-SSO”. To use client roles, you must also configure additional settings for Business Central, as described in Section 16.2, “Installing the RH-SSO client adapter for Business Central”.

   You must define roles used in the KIE Server as realm roles.

8. Click the Role Mappings tab on the Users page to assign roles.

Procedure

1. Enter http://localhost:8180/auth/admin in a web browser to open the RH-SSO Admin Console and log in using the admin credentials that you created while installing RH-SSO.

   Note

   If you are configuring RH-SSO with Red Hat OpenShift Container Platform, enter the URL that is exposed by the RH-SSO routes. Your OpenShift administrator can provide this URL if necessary.

   When you login for the first time, you can set up the initial user on the new user registration form.

2. In the RH-SSO Admin Console, click the Realm Settings menu item.

3. On the Realm Settings page, click Add Realm.

   The Add realm page opens.

4. On the Add realm page, provide a name for the realm and click Create.

5. Click the Clients menu item and click Create.

   The Add Client page opens.

6. On the Add Client page, provide the required information to create a new client for your realm. For example:

   • Client ID: kie
   • Client protocol: openid-connect

   • Root URL: http://localhost:8080/business-central

     Note

     If you are configuring RH-SSO with Red Hat OpenShift Container Platform, enter the URL that is exposed by the KIE Server routes. Your OpenShift administrator can provide this URL if necessary.

7. Click Save to save your changes.

   After you create a new client, its Access Type is set to public by default. Change it to confidential.

   The RH-SSO server is now configured with a realm with a client for Business Central applications and running and listening for HTTP connections at localhost:8180. This realm provides different users, roles, and sessions for Business Central applications.

Procedure

1. Navigate to the Software Downloads page in the Red Hat Customer Portal (login required), and select the product and version from the drop-down options:

   • Product: Red Hat Single Sign-On
   • Version: 7.4
2. Download Red Hat Single Sign-on 7.4 Client Adapter for JBoss EAP 7 (rh-sso-7.4.3-eap7-adapter.zip or the latest version).

3. Extract and install the adapter zip file. For installation instructions, see the "JBoss EAP Adapter" section of the Red Hat Single Sign On Securing Applications and Services Guide.

   Note

   Install the adapter with the -Dserver.config=standalone-full.xml property.

4. Navigate to the EAP_HOME/standalone/configuration directory in your Red Hat JBoss EAP installation and open the standalone-full.xml file in a text editor.

5. Add the system properties listed in the following example to <system-properties>:

   <system-properties>
     <property name="org.jbpm.workbench.kie_server.keycloak" value="true"/>
     <property name="org.uberfire.ext.security.management.api.userManagementServices" value="KCAdapterUserManagementService"/>
     <property name="org.uberfire.ext.security.management.keycloak.authServer" value="http://localhost:8180/auth"/>
   </system-properties>

   If you want to use client roles, also add the following system property:

     <property name="org.uberfire.ext.security.management.keycloak.use-resource-role-mappings" value="true"/>

6. Add the RH-SSO subsystem configuration. For example:

   <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
    <secure-deployment name="business-central.war">
      <realm>demo</realm>
      <realm-public-key>MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCrVrCuTtArbgaZzL1hvh0xtL5mc7o0NqPVnYXkLvgcwiC3BjLGw1tGEGoJaXDuSaRllobm53JBhjx33UNv+5z/UMG4kytBWxheNVKnL6GgqlNabMaFfPLPCF8kAgKnsi79NMo+n6KnSY8YeUmec/p2vjO2NjsSAVcWEQMVhJ31LwIDAQAB</realm-public-key>
      <auth-server-url>http://localhost:8180/auth</auth-server-url>
      <ssl-required>external</ssl-required>
      <enable-basic-auth>true</enable-basic-auth>
      <resource>kie</resource>
      <credential name="secret">759514d0-dbb1-46ba-b7e7-ff76e63c6891</credential>
      <principal-attribute>preferred_username</principal-attribute>
    </secure-deployment>
   </subsystem>

   In this example:

   • secure-deployment name is the name of your application’s WAR file.
   • realm is the name of the realm that you created for the applications to use.
   • realm-public-key is the public key of the realm you created. You can find the key in the Keys tab in the Realm settings page of the realm you created in the RH-SSO Admin Console. If you do not provide a value for realm-public-key, the server retrieves it automatically.
   • auth-server-url is the URL for the RH-SSO authentication server.
   • enable-basic-auth is the setting to enable basic authentication mechanism, so that the clients can use both token-based and basic authentication approaches to perform the requests.
   • resource is the name for the client that you created.
   • credential name is the secret key for the client you created. You can find the key in the Credentials tab on the Clients page of the RH-SSO Admin Console.

   • principal-attribute is the login name of the user. If you do not provide this value, your User Id is displayed in the application instead of your user name.

     Note

     The RH-SSO server converts the user names to lower case. Therefore, after integration with RH-SSO, your user name will appear in lower case in Red Hat Process Automation Manager. If you have user names in upper case hard coded in business processes, the application might not be able to identify the upper case user.

     If you want to use client roles, also add the following setting under <secure-deployment>:

     <use-resource-role-mappings>true</use-resource-role-mappings>

7. The Elytron subsystem provides a built-in policy provider based on JACC specification. To enable the JACC manually in the standalone.xml or in the file where Elytron is installed, do any of the following tasks:

   • To create the policy provider, enter the following commands in the management command-line interface (CLI) of Red Hat JBoss EAP:

     /subsystem=elytron/policy=jacc:add(jacc-policy={})
     /subsystem=undertow/application-security-domain=other:remove
     /subsystem=undertow/application-security-domain=other:add(http-authentication-factory=keycloak-http-authentication,enable-jacc=true)

     For more information about management CLI of Red Hat JBoss EAP, see the Management CLI Guide.

   • Navigate to the EAP_HOME/standalone/configuration directory in your Red Hat JBoss EAP installation. Locate the Elytron and undertow subsystem configurations in the standalone.xml and standalone-full.xml files and enable JACC. For example:

     <subsystem xmlns="urn:wildfly:elytron:4.0" ...>
     ......
      <policy name="jacc"><jacc-policy/></policy>
     </subsystem>

     <subsystem xmlns="urn:jboss:domain:undertow:7.0" ...>
     ......
      <application-security-domains>
         <application-security-domain name="other" http-authentication-factory="keycloak-http-authentication" enable-jacc="true"/>
      </application-security-domains>
     </subsystem>

8. Navigate to EAP_HOME/bin/ and enter the following command to start the Red Hat JBoss EAP server:

   ./standalone.sh -c standalone-full.xml

Procedure

1. Generate a JSON configuration file:

   1. Navigate to the RH-SSO Admin Console located at http://localhost:8180/auth/admin.
   2. Click Clients.

   3. Create a new client with the following settings:

      • Set Client ID as kie-git.
      • Set Access Type as confidential.
      • Disable the Standard Flow Enabled option.
      • Enable the Direct Access Grants Enabled option.
      
   4. Click Save.
   5. Click the Installation tab at the top of the client configuration screen and choose Keycloak OIDC JSON as a Format Option.
   6. Click Download.
2. Move the downloaded JSON file to an accessible directory in the server’s file system or add it to the application class path.

3. Specify the correct RH-SSO login module in the EAP_HOME/standalone/configuration/standalone-full.xml file. By default, the security domain in Red Hat Process Automation Manager is set to other. Replace the default values of the login-module in this security domain with the values in the following example:

   <security-domain name="other" cache-type="default">
     <authentication>
       <login-module code="org.keycloak.adapters.jaas.DirectAccessGrantsLoginModule" flag="required">
         <module-option name="keycloak-config-file" value="$EAP_HOME/kie-git.json"/>
       </login-module>
     </authentication>
   </security-domain>

4. The JSON file specified in the module-option element contains a client used for securing the remote services. Replace the $EAP_HOME/kie-git.json value of the module-option element with the absolute path or the class path (classpath:/EXAMPLE_PATH/kie-git.json) to this JSON configuration file.

   At this point, all users authenticated through the RH-SSO server can clone internal GIT repositories. In the following command, change USER_NAME to a RH-SSO user, for example admin:

   git clone ssh://USER_NAME@localhost:8001/system

Procedure

1. In the RH-SSO Admin Console, open the security realm that you created in Chapter 14, Installing and configuring RH-SSO.

2. Click Clients and click Create.

   The Add Client page opens.

3. On the Add Client page, provide the required information to create a KIE Server client for your realm, then click Save. For example:

   • Client ID: kie-execution-server
   • Root URL: http://localhost:8080/kie-server

   • Client protocol: openid-connect

     Note

     If you are configuring RH-SSO with Red Hat OpenShift Container Platform, enter the URL that is exposed by the KIE Server routes. Your OpenShift administrator can provide this URL if necessary.

4. The new client Access Type is set to public by default. Change it to confidential and click Save again.
5. Navigate to the Credentials tab and copy the secret key. The secret key is required to configure the kie-execution-server client.

Procedure

1. Navigate to the Software Downloads page in the Red Hat Customer Portal (login required), and select the product and version from the drop-down options:

   • Product: Red Hat Single Sign-On
   • Version: 7.4
2. Download Red Hat Single Sign-on 7.4 Client Adapter for JBoss EAP 7 (rh-sso-7.4.3-eap7-adapter.zip or the latest version).
3. Extract and install the adapter zip file. For installation instructions, see the "JBoss EAP Adapter" section of the Red Hat Single Sign On Securing Applications and Services Guide.
4. Go to EAP_HOME/standalone/configuration and open the standalone-full.xml file.
5. Delete the <single-sign-on/> element from both of the files.
6. Navigate to EAP_HOME/standalone/configuration directory in your Red Hat JBoss EAP installation and edit the standalone-full.xml file to add the RH-SSO subsystem configuration. For example:

7. Navigate to EAP_HOME/standalone/configuration in your Red Hat JBoss EAP installation and edit the standalone-full.xml file to add the RH-SSO subsystem configuration. For example:

   <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
     <secure-deployment name="kie-server.war">
        <realm>demo</realm>
        <realm-public-key>MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCrVrCuTtArbgaZzL1hvh0xtL5mc7o0NqPVnYXkLvgcwiC3BjLGw1tGEGoJaXDuSaRllobm53JBhjx33UNv+5z/UMG4kytBWxheNVKnL6GgqlNabMaFfPLPCF8kAgKnsi79NMo+n6KnSY8YeUmec/p2vjO2NjsSAVcWEQMVhJ31LwIDAQAB</realm-public-key>
        <auth-server-url>http://localhost:8180/auth</auth-server-url>
        <ssl-required>external</ssl-required>
        <resource>kie-execution-server</resource>
        <enable-basic-auth>true</enable-basic-auth>
        <credential name="secret">03c2b267-7f64-4647-8566-572be673f5fa</credential>
        <principal-attribute>preferred_username</principal-attribute>
     </secure-deployment>
   </subsystem>
   
   <system-properties>
     <property name="org.kie.server.sync.deploy" value="false"/>
   </system-properties>

   In this example:

   • secure-deployment name is the name of your application WAR file.
   • realm is the name of the realm that you created for the applications to use.
   • realm-public-key is the public key of the realm you created. You can find the key in the Keys tab in the Realm settings page of the realm you created in the RH-SSO Admin Console. If you do not provide a value for this public key, the server retrieves it automatically.
   • auth-server-url is the URL for the RH-SSO authentication server.
   • resource is the name for the server client that you created.
   • enable-basic-auth is the setting to enable basic authentication mechanism, so that the clients can use both token-based and basic authentication approaches to perform the requests.
   • credential name is the secret key of the server client you created. You can find the key in the Credentials tab on the Clients page of the RH-SSO Admin Console.
   • principal-attribute is the login name of the user. If you do not provide this value, your User Id is displayed in the application instead of your user name.
8. Save your configuration changes.

9. Use the following command to restart the Red Hat JBoss EAP server and run KIE Server.

   EXEC_SERVER_HOME/bin/standalone.sh -c standalone-full.xml -Dorg.kie.server.id=<ID> -Dorg.kie.server.user=<USER> -Dorg.kie.server.pwd=<PWD> -Dorg.kie.server.location=<LOCATION_URL> -Dorg.kie.server.controller=<CONTROLLER_URL> -Dorg.kie.server.controller.user=<CONTROLLER_USER> -Dorg.kie.server.controller.pwd=<CONTOLLER_PASSWORD>

   For example:

   EXEC_SERVER_HOME/bin/standalone.sh -c standalone-full.xml -Dorg.kie.server.id=kieserver1 -Dorg.kie.server.user=kieserver -Dorg.kie.server.pwd=password -Dorg.kie.server.location=http://localhost:8080/kie-server/services/rest/server -Dorg.kie.server.controller=http://localhost:8080/business-central/rest/controller -Dorg.kie.server.controller.user=kiecontroller -Dorg.kie.server.controller.pwd=password

10. When KIE Server is running, enter the following command to check the server status, where <KIE_SERVER_USER> is a user with the kie-server role and <PASSWORD> is the password for that user:

    curl http://<KIE_SERVER_USER>:<PASSWORD>@localhost:8080/kie-server/services/rest/server/

Procedure

1. To configure Business Central to manage KIE Server using tokens:

   1. Set the org.kie.server.token property.

   2. Make sure that the org.kie.server.user and org.kie.server.pwd properties are not set.

      Red Hat Process Automation Manager will then use the Authorization: Bearer $TOKEN authentication method.

2. To use the REST API using the token-based authentication:

   1. Set the org.kie.server.controller.token property.
   2. Make sure that the org.kie.server.controller.user and org.kie.server.controller.pwd properties are not set.

Procedure

1. In the RH-SSO Admin Console, click the Clients menu item and click Create to create a new client.

   The Add Client page opens.

2. On the Add Client page, provide the required information to create a new client for your realm. For example:

   • Client ID: kie-remote
   • Client protocol: openid-connect
3. Click Save to save your changes.

4. Change the token settings in Realm Settings:

   1. In the RH-SSO Admin Console, click the Realm Settings menu item.
   2. Click the Tokens tab.

   3. Change the value for Access Token Lifespan to 15 minutes.

      This gives you enough time to get a token and invoke the service before it expires.

   4. Click Save to save your changes.

5. After a public client for your remote clients is created, you can now obtain the token by making an HTTP request to the RH-SSO server’s token endpoint using:

   RESULT=`curl --data "grant_type=password&client_id=kie-remote&username=admin&password=password" http://localhost:8180/auth/realms/demo/protocol/openid-connect/token`

   The user in this command is a Business Central RH-SSO user. For more information, see Section 15.1, “Adding Red Hat Process Automation Manager users”.

6. To view the token obtained from the RH-SSO server, use the following command:

   TOKEN=`echo $RESULT | sed 's/.*access_token":"//g' | sed 's/".*//g'`

Procedure

1. Open the project that contains your business process in Business Central.
2. Create a data object defining the data that the message will contain. For instructions about creating data objects, see Designing business processes using BPMN models.
3. Select the business process and open the business process designer.
4. Add a start event, an intermediate catch event, or a boundary event (attached to a human task) of the type message.
5. Open the properties of the event.

6. In the Message field, select New and then enter the name of the message. This name must be the same as the name of the topic from which the event is to receive Kafka messages, or else must be defined in an org.kie.server.jbpm-kafka.ext.topics.broker-topic-name system property of the KIE Server.

   For instructions about using org.kie.server.jbpm-kafka.ext.topics.* system properties to define topic names, see Chapter 20, Configuring a KIE Server to send and receive Kafka messages from the process.

7. Add an output data item. Select the data object that you created as its type.
8. Save the business process.

Procedure

1. Open the project that contains your business process in Business Central.

2. Add the work item handler that is required for message-sending events:

   1. Select the Settings → Deployments → Work Item Handlers tab.
   2. Click Add Work Item Handler.

   3. Enter the following values in the new empty line:

      • Name: Send Task
      • Value : new org.jbpm.bpmn2.handler.SendTaskHandler()
      • Resolver type: MVEL
3. Create a data object defining the data that the message must contain. For instructions about creating data objects, see Designing business processes using BPMN models.
4. Select the business process and open the business process designer.
5. Add an intermediate throw event or an end event of the type message.
6. Open the properties of the event.

7. In the Message field, select New and then enter the name of the message. This name must be the same as the name of the topic to which the event is to send Kafka messages, or else must be defined in an org.kie.server.jbpm-kafka.ext.topics.broker-topic-name system property of the KIE Server.

   For instructions about using org.kie.server.jbpm-kafka.ext.topics.* system properties to define topic names, see Chapter 20, Configuring a KIE Server to send and receive Kafka messages from the process.

8. Add an input data item. Select the data object that you created as its type.
9. Save the business process.

Procedure

1. In the Business Central administrative settings menu, as the administrative user, select Custom Tasks Administration.
2. Ensure that KafkaPublishMessages is set to On.
3. In Business Central, select Menu → Design → Projects and then click the space name and the project name.
4. Select the Settings → Custom Tasks tab.
5. In the KafkaPublishMessages line, click Install.

6. Enter the following information:

   • Bootstrap Servers: The host and port of the Kafka broker, for example, localhost:9092. You can use a comma-separated list of multiple host:port pairs.
   • Client ID: An identifier string to pass to the broker when making requests. Red Hat AMQ Streams uses this string for logging.
   • Key Serializer class: The class that provides the key serializer. You can use the standard serializer class name: org.apache.kafka.common.serialization.StringSerializer. Alternatively you can use your own custom serializer class.

   • Value Serializer class: The class that provides the value serializer. You can use the standard serializer class name: org.apache.kafka.common.serialization.StringSerializer. Alternatively you can use your own custom serializer class.

     In any of these fields, you can enter an env[property] value. In this case, the process engine reads the setting from a system property at runtime. For example, you can set Client ID to env[application.client.id] and then, before running the process service, set the client ID value in the application.client.id system property.

7. Select the Assets tab.
8. Select the business process and open the business process designer.
9. Add the KafkaPublishMessages custom task, available under Custom Tasks in the BPMN modeler palette.
10. In the properties of the custom task, open the data assignments.
11. Assign the Key, Topic, and Value inputs to define the message.