Compatibility

Publisher 5 is compatible with Blueriq Studio 11, 12, 13 & 14.

Installation

The installation of the Publisher entails the following:

• Deployment of the Publisher on an application server
• Creating the required databases
• 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:

1. The Publisher uses its own Home folder: 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=C:/Publisher5/publisher.home
2. Create folder for publisher configuration eg. C:/Publisher5/publisher.home (Windows) or /opt/publisher.home (Linux)
3. Copy the files from Publisher installation zip /publisher.home to created the configuration folder and change them following chapter Configuration.

Tomcat 9.x

• Create file TOMCAT_HOME/bin/setenv.bat or setenv.sh
• Copy-paste following line (change publisher.home location accordingly, note the folder has no end slash):

set "JAVA_OPTS=%JAVA_OPTS% -Dpublisher.home=C:/Publisher5/publisher.home"

JAVA_OPTS="$JAVA_OPTS -Dpublisher.home=/opt/publisher.home"

• Rename publisher-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 7.3

• Open JBOSS_HOME/bin/standalone.conf.bat or standalone.conf
• Copy-paste following line (change publisher.home location accordingly, note the folder has no end slash):
  
  

set "JAVA_OPTS=%JAVA_OPTS% -Dpublisher.home=C:/Publisher5/publisher.home"

JAVA_OPTS="$JAVA_OPTS -Dpublisher.home=/opt/publisher.home"

• Place publisher-xxx.war in JBOSS_HOME/standalone/deployments
• Start server and go to http://host:port/publisher. You should see a login screen

Websphere Liberty Core 21.0.0.x

• Create or open file WAS_HOME/usr/servers/defaultServer/jvm.options
• Copy-paste following line (change publisher.home location accordingly, note the folder has no end slash):
  
  

-Dpublisher.home=C:/Publisher5/publisher.home

-Dpublisher.home=/opt/publisher.home

• Open file WAS_HOME/usr/servers/defaultServer/server.xml
• Add tag: <httpSession idLength="28" />. Otherwise the log will show the error "Detected JSESSIONID with invalid length; expected length of 23, found 28" and you will not be able to login
• Add tag: <application id="Publisher" location="publisher-xxx.war" name="Publisher" context-root="publisher" />. Change name of war file accordingly.
• Place publisher-xxx.war in WAS_HOME/usr/servers/defaultServer/apps
• 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 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.

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 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 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 the Studio

The Publisher retrieves projects from Studio and then publishes them to other environments. Configure the location of the management service of the Studio so the Publisher can retrieve projects from it.

# Example: 
#studio.url= http://HOSTNAME:PORT/Studio/Server/Services/ManagementService
studio.url=STUDIO_URL
 
#studio.authentication=[BASIC|NTLM_CUSTOM|KERBEROS_CUSTOM]
studio.authentication=BASIC

Configuring the publisher database

Provide the details for the connection to the Publisher database that you created earlier.

#publisher.datasource.url: The URL on which to locate the database to connect to 
#publisher.datasource.driverclassname: The JDBC driver class to use to connect to the database 
#publisher.datasource.username: The username to use to connect to the database 
#publisher.datasource.password: The password to use to connect to the database 
 
#Example:
publisher.datasource.url=jdbc:oracle:thin:@oracle19C-proj:1521:publisher
publisher.datasource.driverclassname=oracle.jdbc.driver.OracleDriver
publisher.datasource.username=PUBLISHER_A
publisher.datasource.password=PUBLISHER_A

Configuring the environments

For each environment, configure the connection to the database that you created earlier. The example shows the configuration of two environments (TEST and ACC).

#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
#database.NAME.url: The URL on which to locate the database to connect to (only used when database.jndi has not been set)
#database.NAME.driverclassname: The JDBC driver class to use to connect to the database (only used when database.jndi has not been set)
#database.NAME.username: The username to use to connect to the database (only used when database.jndi has not been set)
#database.NAME.password: The password to use to connect to the database (only used when database.jndi has not been set)
#database.NAME.requires_approval: Indicates if the environment needs approval of an approver before the publish takes place. Default = true.
#database.NAME.uncommitted_allowed: Indicates if uncommitted changes (the tip revision) can be published to this environment. Default = false.
#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:
database.TEST.jndi=
database.TEST.url=jdbc:oracle:thin:@oracle19c-proj:1521:PublisherEnvTest
database.TEST.driverclassname=oracle.jdbc.driver.OracleDriver
database.TEST.username=Test
database.TEST.password=Test
database.TEST.sortvalue=1
 
database.ACC.url=jdbc:sqlserver://localhost:1433;databaseName=PublisherEnvAcc;instance=SQLEXPRESS
database.ACC.driverclassname=com.microsoft.sqlserver.jdbc.SQLServerDriver
database.ACC.username=Acc
database.ACC.password=Acc
database.ACC.uncommitted_allowed=false
database.ACC.requires_approval=true
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 environments (TEST and ACC).

#artifactory.NAME.url: The URL on which to locate the Artifactory server
#artifactory.NAME.repository: The repository in Artifactory where the models are stored
#artifactory.NAME.username: The username to use to connect to the Artifactory server
#artifactory.NAME.password: The password to use to connect to the Artifactory server
#artifactory.NAME.requires_approval: Indicates if the environment needs approval of an approver before the publish takes place. Default = true.
#artifactory.NAME.uncommitted_allowed: Indicates if uncommitted changes (the tip revision) can be published to this environment. Default = false.
#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:
artifactory.TEST.url=http://artifactory.mycompany.com/artifactory
artifactory.TEST.repository=publisher-models-test-local
artifactory.TEST.username=Test
artifactory.TEST.password=Test
artifactory.TEST.sortvalue=1
 
artifactory.ACC.url=http://artifactory.mycompany.com/artifactory
artifactory.ACC.repository=publisher-models-acc-local
artifactory.ACC.username=Acc
artifactory.ACC.password=Acc
artifactory.ACC.uncommitted_allowed=false
artifactory.ACC.requires_approval=true
artifactory.ACC.sortvalue=2

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.

#transition.NAME.from=<source environment>
#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 database names or the value studio.

transition.studioTEST.from=studio
transition.studioTEST.to=TEST
 
transition.TESTACC.from=TEST
transition.TESTACC.to=ACC

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.

oauth2.client-id=... (please specify the <client id>)
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 (publisher.hibernate.properties)

The publisher.hibernate.properties needs to be configured as follows. If the file does not exist, create it in the spring.config.additional-location folder. 

# In case of connecting to an Oracle database server:
hibernate.dialect=org.hibernate.dialect.Oracle10gDialect

# In case of connecting to an MS SQL database server:
hibernate.dialect=org.hibernate.dialect.SQLServer2012Dialect

Logging (logback.xml)

By default, the Publisher logs to the file publisher.log in the spring.config.additional-location folder. Logback is used for the logging configuration. You can override the default logging configuration by adding a logback.xml to the spring.config.additional-location folder. Below is an example.

<configuration>
	<appender name="FILE" class="ch.qos.logback.core.FileAppender">
		<file>${publisher.home}/publisher.log</file>
		<encoder>
			<pattern>%d{dd-mm-yyyy HH:mm:ss.SSS} %-5level %40.40logger{40} - %msg%n </pattern>
		</encoder>
	</appender>
	<root level="info">
		<appender-ref ref="FILE" />
	</root>
	<!-- Limit the org.springframework category to WARN as its DEBUG is verbose -->
	<logger name="org.springframework" level="WARN" />
	<logger name="org.hibernate" level="WARN" />
	<logger name="org.apache.http" level="WARN" />
</configuration>

Publisher users

Users for the Publisher are defined in Studio and use Studio groups to define their role. The table below gives an overview of different Publisher roles and the groups in Studio associated with this role.

Define a user that can execute a publish action

To define a user that can execute a publish action, create a user in Studio 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:

1. publisher
2. publisher_studioTEST
3. publisher_TESTACC

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.