Compatibility
Publisher 4 is compatible with Blueriq Studio 9, 10 and 11.
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:
- 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:/Publisher4/publisher.home - Create folder for publisher configuration eg. C:/Publisher4/publisher.home (Windows) or /opt/publisher.home (Linux)
- Copy the files from Publisher installation zip /publisher.home to created the configuration folder and change them following chapter Configuration.
Tomcat 8.x
- Create file TOMCAT_HOME/bin/setenv.bat or setenv.sh
- Copy-paste following line (change publisher.home location accordingly, note the folder without end slash):
Windows
set "JAVA_OPTS=%JAVA_OPTS% -Dpublisher.home=C:/Publisher4/publisher.home"
Linux
JAVA_OPTS="$JAVA_OPTS -Dpublisher.home=/opt/publisher.home"
- Rename publisher-xxx.war to publisher.war and place in TOMCAT_HOME/webapps
JBoss EAP 6.4
- Open JBOSS_HOME/bin/standalone.conf.bat or standalone.conf
- Copy-paste following line (change publisher.home location accordingly, note the folder without end slash):
Windows
set "JAVA_OPTS=%JAVA_OPTS% -Dpublisher.home=C:/Publisher4/publisher.home"
Linux
JAVA_OPTS="$JAVA_OPTS -Dpublisher.home=/opt/publisher.home"
- Place publisher-xxx.war in JBOSS_HOME/standalone/deployments
Websphere Liberty Core 16.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 without end slash):
Windows
-Dpublisher.home=C:/Publisher4/publisher.home
Linux
-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
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.
On the D (Development) environment it is advised that the Runtime has a direct connection to the Studio, so projects from the Studio can be run directly on the Runtime, without the need to use the Publisher. See overview.
Creating the Publisher database
Execute the scripts present in the Publisher installation zip /dbscripts/publisher to create the database for the Publisher.
Creating an environment database
Execute the scripts present in the Publisher installation zip /dbscripts/publisher-client for each environment that you need to be able to publish to.
Configuration
The configuration of the Publisher consists of configuring the settings in the publisher.properties, creating the required users and optionally configure other database and logging settings.
Publisher settings (publisher.properties)
The publisher.properties file, residing in the spring.config.additional-location folder, contains the configuration for the Publisher. The following settings need to be configured.
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 of 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 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:@oracle10-proj:1521:projects 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 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 #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 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 environements are listed in the GUI, 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:@oracle10-proj:1521:projects 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=PublisherDB;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 shows the configuration of two environments (TEST and ACC).
#artifactory.NAME.url: The URL on which to locate Artifactory #artifactory.NAME.repository: The repository in Artifactory where the models are stored #artifactory.NAME.username: The username to use to connect to Artifactory #artifactory.NAME.password: The password to use to connect to Artifactory #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 GUI, 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
To create a transition from studio, the environment name 'studio' has always to be written entirely in lower case. Other environments may contain capitals but they have to match the name as defined in database.
The transition name (the name after transition.<name>) must match case sensitive to the groups in studio.
Oauth2 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 Oracle: hibernate.dialect=org.hibernate.dialect.Oracle10gDialect # In case of MS SQL: hibernate.dialect=org.hibernate.dialect.SQLServer2012Dialect
Logging (logback.xml)
By default, the Publisher logs to 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.
logback.xml
<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.
| 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 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:
- 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.
Accessing the Publisher web application
- Start the server and go to http://host:port/publisher. You should see a login screen
Overview
Content Tools