Integrating Red Hat Process Automation Manager with other products and components

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 then select the following product and version from the drop-down options:

   • Product: Process Automation Manager
   • Version: 7.12
2. Download Red Hat Process Automation Manager 7.12 Maven Repository (rhpam-7.12.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.12.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.

Procedure

1. Enter the following commands to determine whether your installation contains obsolete Red Hat Process Automation Manager features XML files:

   $ JBossFuse:karaf@root> feature:repo-list
   $ JBossFuse:karaf@root> feature:list

2. Enter the following command, where <FUSE_HOME> is the Fuse installation directory, to start the Red Hat Fuse console:

   $ ./<FUSE_HOME>/bin/fuse

3. Enter the following command, where <FEATURE_NAME> is the name of the feature that you want to uninstall, to uninstall features or applications that use obsolete features XML files:

   JBossFuse:karaf@root> features:uninstall <FEATURE_NAME>

   The following example shows how to remove features:

   JBossFuse:karaf@root> features:uninstall drools-module
   JBossFuse:karaf@root> features:uninstall jbpm
   JBossFuse:karaf@root> features:uninstall kie-ci

4. Search Karaf home for references to bundles that use drools, kie, or jbpm. The following example shows how to use grep to search for these components:

   karaf@root> list -t 0 -s | grep drools
   karaf@root> list -t 0 -s | grep kie
   karaf@root> list -t 0 -s | grep jbpm

   The example shows the output from these commands:

   250 │ Active   │  80 │ 7.19.0.201902201522          │ org.drools.canonical-model
   251 │ Active   │  80 │ 7.19.0.201902201522          │ org.drools.cdi
   252 │ Active   │  80 │ 7.19.0.201902201522          │ org.drools.compiler

5. Enter the following command, where BUNDLE_ID is a bundle ID returned in the search, to remove the bundles found in the previous step:

   karaf@root> osgi:uninstall BUNDLE_ID

6. Enter the following command to remove the obsolete drools-karaf-features URL:

   karaf@root> features:removeurl
    mvn:org.kie/kie-karaf-features/VERSION.Final-redhat-VERSION/xml/features

7. Restart Fuse.

Procedure

1. To configure the Maven repository, open the FUSE_HOME/etc/org.ops4j.pax.url.mvn.cfg file in a text editor.

2. Make sure that the https://maven.repository.redhat.com/ga/ repository is present in the org.ops4j.pax.url.mvn.repositories variable and add it if necessary.

   Note

   Separate entries in the org.ops4j.pax.url.mvn.repositories variable with a comma, space, and backslash (, \). The backslash forces a new line.

3. To start Fuse, enter the following command, where FUSE_HOME is the Fuse installation directory:

   $ ./FUSE_HOME/bin/fuse

4. To add a reference to the features file that contains installation prerequisites, enter the following command, where <FUSE_VERSION is the version of Fuse that you are installing:

   $ feature:repo-add mvn:org.jboss.fuse.features/rhba-features/<FUSE-VERSION>/xml/features

5. Enter the following command to add a reference to the Red Hat Process Automation Manager features XML file:

   $ JBossFuse:karaf@root> features:addurl mvn:org.kie/kie-karaf-features/VERSION/xml/features-fuse

   To see the current drools-karaf-features version, see the Red Hat Process Automation Manager 7 Supported Configurations page.

6. Enter the following command to install a feature provided by Red Hat Process Automation Manager features XML file. In this command, <FEATURE_NAME> is one of the features listed in Section 12.4, “Red Hat Process Automation Manager Karaf features”.

   JBossFuse:karaf@root> features:install <FEATURE_NAME>

7. Enter the following command to verify the installation:

   $ JBossFuse:karaf@root>feature:list

   Successfully installed features have the status started.

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 18.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 18.2, “Installing the RH-SSO client adapter for Business Central”.

   You must define roles used in 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.

   Note

   The RH-SSO server client uses one URL to a single business-central deployment. The following error message might be displayed if there are two or more deployment configurations:

   We are sorry…​ Invalid parameter: redirect_uri

   To resolve this error, append /* to the Valid Redirect URIs field in the client configuration.

   On the Configure page, go to Clients > kie > Settings, and append the Valid Redirect URIs field with /*, for example:

   http://localhost:8080/business-central/*

Procedure

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

   • Product: Red Hat Single Sign-On
   • Version: 7.5
2. Select the Patches tab.
3. Download Red Hat Single Sign-On 7.5 Client Adapter for EAP 7 (rh-sso-7.5.0-eap7-adapter.zip or the latest version).

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

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

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

7. Optional: If you want to use client roles, add the following system property:

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

   By default, the client resource name is kie. The client resource name must be the same as the client name that you used to configure the client in RH-SSO. If you want to use a custom client resource name, add the following system property:

     <property name="org.uberfire.ext.security.management.keycloak.resource" value="customClient"/>

   Replace customClient with the client resource name.

8. 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. To use client roles, set the client resource name that you used when configuring the client in RH-SSO.
   • 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 attribute for displaying the user name in the application. 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>

9. 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=undertow/application-security-domain=other:remove()
     /subsystem=undertow/application-security-domain=other:add(http-authentication-factory="keycloak-http-authentication")
     /subsystem=ejb3/application-security-domain=other:write-attribute(name=security-domain, value=KeycloakDomain)

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

   • 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:jboss:domain:undertow:12.0" ... >
     ...
       <application-security-domains>
         <application-security-domain name="other" http-authentication-factory="keycloak-http-authentication"/>
       </application-security-domains>

     <subsystem xmlns="urn:jboss:domain:ejb3:9.0">
     ...
       <application-security-domains>
           <application-security-domain name="other" security-domain="KeycloakDomain"/>
       </application-security-domains>

10. 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. The default name and location for this file is $EAP_HOME/kie-git.json.

3. Optional: In the EAP_HOME/standalone/configuration/standalone-full.xml file, under the <system-properties> tag, add the following system property:

   <property name="org.uberfire.ext.security.keycloak.keycloak-config-file" value="$EAP_HOME/kie-git.json"/>

   Replace the $EAP_HOME/kie-git.json value of the property with the absolute path or the class path (classpath:/EXAMPLE_PATH/kie-git.json) to the new JSON configuration file.

   Note

   If you do not set the org.uberfire.ext.security.keycloak.keycloak-config-file property, Red Hat Process Automation Manager reads the $EAP_HOME/kie-git.json file.

Procedure

1. In the RH-SSO Admin Console, open the security realm that you created in Chapter 16, 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.

   Note

   The RH-SSO server client uses one URL to a single KIE Server deployment. The following error message might be displayed if there are two or more deployment configurations:

   We are sorry…​ Invalid parameter: redirect_uri

   To resolve this error, append /* to the Valid Redirect URIs field in the client configuration.

   On the Configure page, go to Clients > kie-execution-server > Settings, and append the Valid Redirect URIs field with /*, for example:

   http://localhost:8080/kie-server/*

Procedure

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

   • Product: Red Hat Single Sign-On
   • Version: 7.5
2. Download Red Hat Single Sign-On 7.5 Client Adapter for JBoss EAP 7 (rh-sso-7.5.0-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 attribute for displaying the user name in the application. 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 17.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 KIE Server system property.

   For instructions about using org.kie.server.jbpm-kafka.ext.topics.* system properties to define topic names, see Chapter 22, 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. 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.
3. Select the business process and open the business process designer.
4. Add an intermediate throw event or an end event 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 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 KIE Server system property.

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

7. Add an input data item. Select the data object that you created as its type.
8. 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. Optional: Enter the following information. If you leave any of the fields empty, the process engine uses the default values for these fields.

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

   • Value Serializer class: The class that provides the value serializer. The default value is org.apache.kafka.common.serialization.StringSerializer. You can enter a different value if you want to 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. If you entered the name of a custom serializer class, complete the following additional configuration:

   1. Select the Settings → Deployments → Work Item Handlers tab.

   2. In the KafkaPublishMessages line, modify the Value field to add the classLoader parameter. For example, the initial value of this field can be the following string:

      new org.jbpm.process.workitem.kafka.KafkaWorkItemHandler("127.0.0.1:9092", "jbpm", "com.myspace.test.MyCustomSerializer", "com.myspace.test.MyCustomSerializer")

      In this example, change the value to the following string:

      new org.jbpm.process.workitem.kafka.KafkaWorkItemHandler("127.0.0.1:9092", "jbpm", "com.myspace.test.MyCustomSerializer", "com.myspace.test.MyCustomSerializer", classLoader)

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

Procedure

1. If you want to use a custom format for sending or receiving messages, implement and provide custom classes:

   1. Develop the source code for the classes:

      • To send messages, develop a class that implements the KafkaEventWriter interface

      • To receive messages, develop a class that implements the KafkaEventReader interface

        You can download the interface definitons from the GitHub repository.

   2. Provide the classes to your business application. For instructions, see Chapter 24, Providing a custom class to your business application in Business Central.

2. Set the following KIE Server system properties to set the custom writer or reader:

   • org.kie.server.jbpm-kafka.ext.eventWriterClass: the custom event writer class. Set this property to use a different format to send messages. If you want to use a custom format, set the property to the fully qualified name of your custom event writer class. If you want to use a raw JSON data format, set the property to org.kie.server.services.jbpm.kafka.RawJsonEventWriter.
   • org.kie.server.jbpm-kafka.ext.eventReaderClass: the custom event reader class. Set this property to use a different format to receive messages. If you want to use a custom format, set the property to the fully qualified name of your custom event reader class. If you want to use a raw JSON data format, set the property to org.kie.server.services.jbpm.kafka.RawJsonEventReader.

Procedure

1. Create the Java source code for the following classes:

   • ESInstanceViewTransformer: The transformer class. It provides index() and update() methods. Both of the methods take a view as a parameter and return an ESRequest object.

     When a process, case, task, or task operation instance is first created, the process engine calls the index() method. For subsequent changes related to the same instance, the process engine calls the update() method.

     You can create different ESInstanceViewTransformer implementations for different view types.

   • ESInstanceViewTransformerFactory: The transformer factory class. It returns an instance of the ESInstanceViewTransformer class for every view type.
2. In Business Central, enter your project and click the Settings → Dependencies tab.
3. Optional: Add any dependencies that your transformer classes require.
4. Click the Assets tab.

5. For each of the class source files, complete the following steps:

   1. Click Import Asset.
   2. In the Please select a file to upload field, select the location of the Java source file for the custom serializer class.
   3. Click Ok to upload the file.
6. For the KIE Server instance that runs the service, set the org.jbpm.event.emitters.elasticsearch.factory system property to the fully qualified class name of your implementation of ESInstanceViewTransformerFactory.