The Publisher is a standalone web application for publishing Studio projects across different environments.

For a complete description of the functionality of the Publisher see the documentation.

System Requirements

The system requirements for the publisher are as follows:

Product	Free memory (minimum)	Free memory (advised) *	Free disk space	Recommended CPU **
Publisher	512 MB	2 GB	1 GB	Intel Xeon X5650 or better

* The memory usage of both the Studio client and server is strongly correlated to the size of the projects and the number of (open) branches. These numbers suffice for a simple project.
** The recommended CPU is the CPU recommended in production environments.

On this page:

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 mechanism: spring.config.additional-location. The location of spring.config.additional-location has to be supplied to the Publisher web application. This can be achieved by passing it as a property on the application server startup: -Dspring.config.additional-location=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 Configuration.

Tomcat 10.1.x

Place a supported JDBC driver that matches the database that you use in the TOMCAT_HOME/lib folder. See Configuring JDBC database drivers
Create file TOMCAT_HOME/bin/setenv.bat or setenv.sh
Copy-paste the following line (change spring.config.additional-location location accordingly, note the folder must have an end slash):

Windows

set "JAVA_OPTS=%JAVA_OPTS% -Dspring.config.additional-location=file:///C:/publisher_8_config_location/"

Linux

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

JBoss EAP 8.0

Make sure that a supported JDBC driver that matches the database that you use has been added to JBoss EAP. See Configuring JDBC database drivers
Open JBOSS_HOME/bin/standalone.conf.bat or standalone.conf
Copy-paste the following line (change spring.config.additional-location location accordingly, note the folder must have an end slash):

Windows

set "JAVA_OPTS=%JAVA_OPTS% -Dspring.config.additional-location=file:///C:/publisher_8_config_location/"

Linux

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

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.

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

The configuration of the Publisher consists of setting the properties in the publisher.properties, 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 spring.config.additional-location folder.

Publisher settings (publisher.properties)

The publisher.properties file, residing in the spring.config.additional-location 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.

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

#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

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

#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:@oracle23c-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).

#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

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.

#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

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.

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.

# 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

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.

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`

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

Note that the group names of the transitions (publisher_<transition>) have to correspond with the transition name that you defined in publisher.properties.

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.

You are advised to create separate users and roles with limited access to specific Encore repositories, do not make any Publisher group Encore Administrator!

Accessing the Publisher web application

Start the server and go to http://host:port/publisher. You should see a login screen

Installing Publisher 8