Compatibility
Publisher 8 is compatible with Blueriq Encore 17.
Installation
The installation of the Publisher entails the following:
- Deployment of the Publisher on an application server
- Creating the required databases and/or Artifactory repositories
- Configuring the Publisher and the users
Deployment of the Publisher web application
The Publisher is a web application that needs to be deployed to a Java application server. The following steps outline the process:
- The Publisher uses the Spring Cloud configuration location mechanismrmechanism:
Include Page |
---|
| _PublisherConfigLocation |
---|
| _PublisherConfigLocation |
---|
|
. The location of Include Page |
---|
| _PublisherConfigLocation |
---|
| _PublisherConfigLocation |
---|
|
has to be supplied to the Publisher web application. This can be achieved by passing it as a property on the application server startup: -D Include Page |
---|
| _PublisherConfigLocation |
---|
| _PublisherConfigLocation |
---|
|
=file:///C:/publisher_8_config_location/
- Create folder for publisher configuration eg.
C:/publisher_8_config_location
(Windows) or /opt/publisher_8_config_location
(Linux) - Copy the files from Publisher installation zip
/config.location
to the created configuration folder and change them following chapter Installing Publisher 8 [Editor].
Tomcat 10.1.x
- Place a supported JDBC driver that matches the database that you use in the TOMCAT_HOME/lib folder.
- Create file Create file TOMCAT_HOME/bin/setenv.bat or setenv.sh
- Copy-paste the following line (change
Include Page |
---|
| _PublisherConfigLocation |
---|
| _PublisherConfigLocation |
---|
|
location accordingly, note the folder must have an end slash):
Code Block |
---|
|
set "JAVA_OPTS=%JAVA_OPTS% -Dspring.config.additional-location=file:///C:/publisher_8_config_location/" |
Code Block |
---|
|
JAVA_OPTS="$JAVA_OPTS -Dspring.config.additional-location=file:///opt/publisher_8_config_location/" |
- Rename blueriq-publisher-application-xxx.war to publisher.war and place in TOMCAT_HOME/webapps
- Start server and go to http://host:port/publisher. You should see a login screen
JBoss EAP 8.0
- Make sure that a supported JDBC driver that matches the database that you use has been added to JBoss EAP.
- Open Open JBOSS_HOME/bin/standalone.conf.bat or standalone.conf
- Copy-paste the following line (change
Include Page |
---|
| _PublisherConfigLocation |
---|
| _PublisherConfigLocation |
---|
|
location accordingly, note the folder must have an end slash):
Code Block |
---|
|
set "JAVA_OPTS=%JAVA_OPTS% -Dspring.config.additional-location=file:///C:/publisher_8_config_location/" |
Code Block |
---|
|
JAVA_OPTS="$JAVA_OPTS -Dspring.config.additional-location=file:///opt/publisher_8_config_location/" |
- Place blueriq-publisher-application-xxx.war in JBOSS_HOME/standalone/deployments
- Start server and go to http://host:port/publisher. You should see a login screen
Creating the required databases
You need to create a database for the Publisher itself, as well as a database for each (database) environment that the Publisher needs to be able to publish to. For instance, a DTAP street requires a Publisher database as well as a database for the T (Test), A (Acceptance) and P (Production) environment and possibly one or more Artifactory environments.
UI Text Box |
---|
|
On the D (Development) environment it is advised that the Runtime has a direct connection to Encore, so projects from Encore can be run directly on the Runtime, without the need to use the Publisher. See overview. |
Creating the Publisher database
Create a new database and execute the scripts present in the Publisher installation zip /dbscripts/publisher
to create the database tables for the Publisher in the new database.
Creating an environment database
Create a new database and execute the scripts present in the Publisher installation zip /dbscripts/publisher-client
for each (database) environment that you need to be able to publish to. It is possible to use entirely different database servers for each environment database.
Configuration Anchor |
---|
| Configuration |
---|
| Configuration |
---|
|
The configuration of the Publisher consists of setting the properties in the
Include Page |
---|
| _PublisherProperties |
---|
| _PublisherProperties |
---|
|
, creating the required users and optionally configuring other database, Artifactory and logging settings.
Publisher license
The license.aql
file needs to be placed in the
Include Page |
---|
| _PublisherConfigLocation |
---|
| _PublisherConfigLocation |
---|
|
folder.
Publisher settings (
Include Page |
---|
| _PublisherProperties |
---|
| _PublisherProperties |
---|
|
)
The
Include Page |
---|
| _PublisherProperties |
---|
| _PublisherProperties |
---|
|
file, residing in the
Include Page |
---|
| _PublisherConfigLocation |
---|
| _PublisherConfigLocation |
---|
|
folder, contains the configuration for the Publisher. The following properties need to be set.
Location of Encore
The Publisher retrieves projects from Encore (formerly known as Studio) and then publishes them to other environments. Configure the location of the management service of Encore so the Publisher can retrieve projects from it.
Code Block |
---|
|
# Example:
#blueriq.publisher.studio.url= http://HOSTNAME:PORT/Studio/Server/Services/ManagementService
blueriq.publisher.studio.url=STUDIO_URL
#blueriq.publisher.studio.authentication=[BASIC]
# Beware that since Blueriq 16, only BASIC is supported. Use user federation in Keycloak instead for more advanced scenarios
blueriq.publisher.studio.authentication=BASIC |
Configuring the publisher database
Provide the details for the connection to the Publisher database that you created earlier.
Code Block |
---|
|
#blueriq.publisher.datasource.url: The URL on which to locate the database to connect to
#blueriq.publisher.datasource.driverclassname: The JDBC driver class to use to connect to the database
#blueriq.publisher.datasource.username: The username to use to connect to the database
#blueriq.publisher.datasource.password: The password to use to connect to the database
#Example:
blueriq.publisher.datasource.url=jdbc:oracle:thin:@oracle19c-proj:1521:publisher
blueriq.publisher.datasource.driverclassname=oracle.jdbc.driver.OracleDriver
blueriq.publisher.datasource.username=PUBLISHER_A
blueriq.publisher.datasource.password=PUBLISHER_A |
Info |
---|
title | Note about SQL Server configuration |
---|
|
When you configure a SQL Server (MS SQL) database please note that the connection string should contain 'encrypt=false' explicitly if you don't want to use a secure connection. Example: jdbc:sqlserver://<host>:<port>;databseName=<database name>;encrypt=false |
Configuring the environments
For each (database) environment, configure the connection to the database that you created earlier. The example shows the configuration of two database environments (TEST and ACC).
Code Block |
---|
|
#blueriq.publisher.env.database.NAME.jndi: if set, the publisher client will look up the datasource through JNDI, otherwise it will create the datasource itself and use the other database connection properties below
#blueriq.publisher.env.database.NAME.url: The URL on which to locate the database to connect to (only used when database.jndi has not been set)
#blueriq.publisher.env.database.NAME.driverclassname: The JDBC driver class to use to connect to the database (only used when database.jndi has not been set)
#blueriq.publisher.env.database.NAME.username: The username to use to connect to the database (only used when database.jndi has not been set)
#blueriq.publisher.env.database.NAME.password: The password to use to connect to the database (only used when database.jndi has not been set)
#blueriq.publisher.env.database.NAME.requires_approval: Indicates if the environment needs approval of an approver before the publish takes place. Default = true.
#blueriq.publisher.env.database.NAME.uncommitted_allowed: Indicates if uncommitted changes (the tip revision) can be published to this environment. Default = false.
#blueriq.publisher.env.database.NAME.sortvalue: An optional integer which is used to define the order in which the environments are listed in the Publisher frontend, lower values are listed before higher values. If no sortvalue is specified, environments are sorted by NAME (case insensitive).
#Note that the NAME is the name used for your environment.
#Example:
blueriq.publisher.env.database.TEST.jndi=
blueriq.publisher.env.database.TEST.url=jdbc:oracle:thin:@oracle19c-proj:1521:PublisherEnvTest
blueriq.publisher.env.database.TEST.driverclassname=oracle.jdbc.driver.OracleDriver
blueriq.publisher.env.database.TEST.username=Test
blueriq.publisher.env.database.TEST.password=Test
blueriq.publisher.env.database.TEST.sortvalue=1
blueriq.publisher.env.database.ACC.url=jdbc:sqlserver://localhost:1433;databaseName=PublisherEnvAcc;instance=SQLEXPRESS
blueriq.publisher.env.database.ACC.driverclassname=com.microsoft.sqlserver.jdbc.SQLServerDriver
blueriq.publisher.env.database.ACC.username=Acc
blueriq.publisher.env.database.ACC.password=Acc
blueriq.publisher.env.database.ACC.uncommitted_allowed=false
blueriq.publisher.env.database.ACC.requires_approval=true
blueriq.publisher.env.database.ACC.sortvalue=2 |
Since Publisher 4.1 it is also possible to configure an environment which uses Artifactory PRO as a datasource. The example below shows the configuration of two Artifactory environments (TEST and ACC).
Code Block |
---|
|
#blueriq.publisher.env.artifactory.NAME.url: The URL on which to locate the Artifactory server
#blueriq.publisher.env.artifactory.NAME.repository: The repository in Artifactory where the models are stored
#blueriq.publisher.env.artifactory.NAME.username: The username to use to connect to the Artifactory server
#blueriq.publisher.env.artifactory.NAME.password: The password to use to connect to the Artifactory server
#blueriq.publisher.env.artifactory.NAME.requires_approval: Indicates if the environment needs approval of an approver before the publish takes place. Default = true.
#blueriq.publisher.env.artifactory.NAME.uncommitted_allowed: Indicates if uncommitted changes (the tip revision) can be published to this environment. Default = false.
#blueriq.publisher.env.artifactory.NAME.sortvalue: An optional integer which is used to define the order in which the environments are listed in the Publisher frontend, lower values are listed before higher values. If no sortvalue is specified, environments are sorted by NAME (case insensitive).
#Note that the NAME is the name used for your environment.
#Example:
blueriq.publisher.env.artifactory.TEST.url=http://artifactory.mycompany.com/artifactory
blueriq.publisher.env.artifactory.TEST.repository=publisher-models-test-local
blueriq.publisher.env.artifactory.TEST.username=Test
blueriq.publisher.env.artifactory.TEST.password=Test
blueriq.publisher.env.artifactory.TEST.sortvalue=1
blueriq.publisher.env.artifactory.ACC.url=http://artifactory.mycompany.com/artifactory
blueriq.publisher.env.artifactory.ACC.repository=publisher-models-acc-local
blueriq.publisher.env.artifactory.ACC.username=Acc
blueriq.publisher.env.artifactory.ACC.password=Acc
blueriq.publisher.env.artifactory.ACC.uncommitted_allowed=false
blueriq.publisher.env.artifactory.ACC.requires_approval=true
blueriq.publisher.env.artifactory.ACC.sortvalue=2 |
Note |
---|
Once you start publishing, the name of the environment is stored (in the database and/or Artifactory). Because the Publisher client depends on the stored environment names, renaming an environment might have unforeseen implications for you. |
Transitions
A transition defines a path from one environment to another. A publish action can only be executed on a defined transition, eg. to publish from Studio to TEST, the transition from Studio to Test needs to be defined.
Code Block |
---|
|
#blueriq.publisher.env.transition.NAME.from=<source environment>
#blueriq.publisher.env.transition.NAME.to=<destination environment>
#The NAME field is an arbitrary name for the transition. The source environment and destination environment must be either one of the defined environment names or the value studio.
blueriq.publisher.env.transition.studioTEST.from=studio
blueriq.publisher.env.transition.studioTEST.to=TEST
blueriq.publisher.env.transition.TESTACC.from=TEST
blueriq.publisher.env.transition.TESTACC.to=ACC |
Note |
---|
To create a transition from Encore, the environment name 'studio' has always to be written entirely in lower case. Other environments may contain capitals but they have to match the exact environment name. The transition name (the name after transition.<name> ) must match case sensitive to the groups in Encore. |
OAuth2 Client Credentials
In order to use the Publisher it needs the following configuration. Otherwise the Publisher will give an error when starting up. These properties are relevant when using the Publisher REST API.
Code Block |
---|
blueriq.publisher.rest.v1.oauth2.client-id=... (please specify the <client id>)
blueriq.publisher.rest.v1.oauth2.secret=... (please specify the <client secret>) |
Since Publisher 4.1 the password mechanism has changed. Please refer to Publisher 4.1 Upgrade Instructions.
Hibernate settings
The Hibernate properties can be set globally and can be overridden for the Publisher main datasource and database environments.
Code Block |
---|
|
# Global Hibernate settings
blueriq.publisher.hibernate.hbm2ddl.auto=validate
# Publisher main datasource
blueriq.publisher.datasource.hibernate.show_sql=true
blueriq.publisher.datasource.hibernate.format_sql=true
# Database environment 'TEST'
blueriq.publisher.env.database.TEST.hibernate.show_sql=true |
Note |
---|
You are advised to keep hibernate.hbm2ddl.auto on validate . Create and update any database tables using the respective SQL scripts from the Publisher installation zip. |
Logging (logback-spring.xml)
By default, the Publisher only logs to the console. Logging to file can be enabled by setting the property logging.file.name
. Logback is used for the logging configuration. You can override the default logging configuration by creating a logback-spring.xml
file and setting the property logging.config
to point to it. Below is an example.
Code Block |
---|
language | xml |
---|
title | logback-spring.xml |
---|
|
<configuration>
<!-- Bind Spring environment property to local LogBack property -->
<springProperty name="logFile" source="logging.file.name"/>
<property name="LOG_PATTERN" value="%d{dd-MM-yyyy HH:mm:ss.SSS} %-5level %40.40logger{40} - %msg%n"/>
<if condition='isDefined("logFile")'>
<then>
<appender name="FILE" class="ch.qos.logback.core.FileAppender">
<file>${logFile}</file>
<encoder>
<pattern>${LOG_PATTERN}</pattern>
</encoder>
</appender>
</then>
</if>
<if condition='isDefined("logFile")'>
<then>
<root level="INFO">
<appender-ref ref="FILE"/>
</root>
</then>
</if>
</configuration> |
Publisher users
Users for the Publisher are defined in Encore (actually the underlying Keycloak) and use Encore groups to define their role. The table below gives an overview of different Publisher roles and the groups in Studio associated with this role.
Publisher role | Studio group |
---|
publisher | publisher and one or more publisher_<transition> groups |
approver | approver and one or more approver_<transition> groups |
investigator | Investigator |
administrator | PublisherAdministrator |
UI Text Box |
---|
|
The publisher, approver and Investigator group need Login privileges. All other groups do not need any privileges. Furthermore, the publisher and approver group need repository and branch access to the repositories that they need to publish projects from. |
Define a user that can execute a publish action
To define a user that can execute a publish action, create a user in Encore and associate this user with the publisher group, as well as each group that corresponds to a transition that this user needs to execute publish actions on. For example, user Paul needs to publish from Studio to TEST and from TEST to ACC. Then the user Paul has three groups in Studio:
- publisher
- publisher_studioTEST
- publisher_TESTACC
UI Text Box |
---|
|
Note that the group names of the transitions (publisher_<transition>) have to correspond with the transition name that you defined in Include Page |
---|
| _PublisherProperties |
---|
| _PublisherProperties |
---|
| . |
Investigator
The investigator is a special role to check on the history of publish actions.
PublisherAdministrator
PublisherAdministrator users are both publisher
and approver
and can even approve their own published projects. This is different from a user that has both the publisher
and approver
role, as that user still will not be able to approve its own published projects.
Note |
---|
You are advised to create separate users and roles with limited access to specific Encore repositories, do not make any Publisher group Encore Administrator! |