Create a shortcut in the Runtime

Shortcuts can be used for starting a project with specific settings with a user friendly URL. A shortcut refers to a project that is available in the Runtime. The following chapter describes how to create a shortcut.

For security reasons we advise you to only use shortcuts in a production environment. This can be enabled via the blueriq.production.shortcuts-only in application.properties.

Create a shortcut

There are multiple ways to configure a shortcut.

Properties

You can configure a shortcut via the application.properties file. This file is located in your

spring.config.additional-location

directory. The properties contain the name of the shortcut

application.properties

### Shortcuts - Shortcuts can be started via the URL: http://YOURSERVER:PORT/ROOT/server/start/SHOTCUTNAME ###
blueriq.production.shortcuts-only = false
blueriq.shortcut.ChildSupport.flow = Start
blueriq.shortcut.ChildSupport.languageCode = en-GB
blueriq.shortcut.ChildSupport.project = export-Kinderbijslag
blueriq.shortcut.ChildSupport.theme = forms
blueriq.shortcut.ChildSupport.ui = mvc
blueriq.shortcut.ChildSupport.version = 0.0-Wetwijziging
blueriq.shortcut.ChildSupport.dynamicVersion = true
blueriq.shortcut.ChildSupport.privateAccess = false
blueriq.shortcut.ChildSupport.securityEnabled = true

Dynamic shortcuts

When the dynamicVersion property is set to true, the version property is ignored, and the version of the project to be used is looked up by comparing the version of the Container type: AQ_Dashboard_ProjectWidget or Service call type: AQ_StartProject to the version of the project of the current session. If so, that version will be used, otherwise the version set with the version property will be used.

Development dashboard

You can configure a shortcut, and its test paths, via the settings menu of the dashboard

Select Settings
Select Shortcuts properties
Press the add (or delete) button
When adding a card will appear to add a new shortcut
Enter a shortcut name
Enter the necessary data
Click 'Save'
You can now test your shortcut with the following URL: http://HOSTNAME:PORT/runtime/server/start/SHORTCUTNAME

Test Paths

Test Paths is a feature for development to test multi-repository applications. These are applications that span multiple projects, which communicate using one of the following services and/or containers:

For instance you have an application which start with project A that shows a dashboard, which opens project B, which starts an external flow in project C, etc. When you are developing your application, you sometimes need to change only one project in the whole application chain. Test Paths allow you to only branch that specific project and test your application with that specific branch, without having to resort to branching every project in the application, changing shortcuts etc.

The following presentation explains this in more detail.

Test Paths only work when the Runtime is in development mode, as this is a development feature, which makes testing changes to a project in an application chain easier.

Usage

The first step is making the runtime aware of the fact that a Test Path exists. You do this by adding the Test Paths to a shortcut, in the form <name> = <version>:

application.properties

blueriq.shortcut.ChildSupport.testPaths.feature1 = 0.0-FeatureBranch1
blueriq.shortcut.ChildSupport.testPaths.feature2 = 0.0-FeatureBranch2

This indicates that when the project is started with Test Path feature1, the project should use 0.0-FeatureBranch1 instead of the version indicated by blueriq.shortcut.ChildSupport.version.

If any Test Paths are configured, the development dashboard will display a selector for the Test Paths:

Selecting a Test Path will result in the following behavior:

When the selected Test Path is defined for the shortcut, the corresponding version of the project is started instead of the default version.
When the selected Test Path is not defined for the shortcut, the default version of the project is started.
When the selected Test Path is defined, but the corresponding version doesn't exist in the project, an error is returned.

The selected Test Path will be propagated through the entire application. This means that even if the current shortcut has not defined the Test Path (and therefore uses the default version), it will still pass it on because the Test Path may be defined on project further downstream.

The Test Path names, e.g. feature1 in the previous example, are identifiers that are limited to alphanumeric characters and underscores. Choose Test Path names that describe the feature you are testing.

It is possible to use a Test Path when calling a Blueriq REST-service. To do this, add a header with key X-Blueriq-Test-Path and for value the name of your Test Path.

Cleaning up

When a feature is done and the corresponding branch is merged, the Test Path is not automatically deleted. As a maintainer of the shortcuts, you should remove Test Paths for these versions manually.
This way, the list of Test Paths to choose from will remain restricted to features that are still under development.

A note on StartControllers

Blueriq has the Old Start Controller and the new API Start Controller which is used by external themes. Both StartControllers support the Test Path feature in the following way:

	Old Start Controller	API Start Controller
Entrypoint	/runtime/server/start	/runtime/server/api/v2/start
Test Path support in start project endpoint
Test Path support in start shortcut endpoint
Test Path override from start in shortcuts
Test Path override from start in projectreference
Test Path support in default project

Note that for overriding a Test Path in a project reference, you can simply select another version, so there is no need to override it. The same holds for the default project, which is the fallback project when you do not specify anything (including Test Path).

When working with shortcuts for the AQ_StartProject service, you need to think of security. On a production server you set the runtime to blueriq.production.shortcuts-only=true so that end users can not start any flows directly themselves. As you need to create a shortcut for the application to be started, you do not want that end users could guess the shortcut name and start the flow themselves. For this reason, you should set the property blueriq.shortcut.[name].privateAccess=true for the shortcuts that are only used for the AQ_StartProject service, and which are not directly started by end users.

It is possible to leave the version of the application out of the URL or shortcut, in which case the latest version of the application is started.

The latest version is determined as follows:

first the major version is compared
then the minor version
then the branch name

Example: 0.0-Wetwijziging

Major version: 0
Minor version: 0
Branch name: Wetwijziging

Since for all studio exports the major and minor version always are equal to 0, only the branch name is the discriminating factor. It is sorted in ascending order, meaning that a branch name starting with 'z' is considered later as a branch name starting with 'a'. In order to make effective use of this mechanism, we advice to use branch names which start with numbers, e.g. 001_4_FeatureBranch.

It is possible to leave the name of the application out of the URL or shortcut, in which case the default application is started.

The default application is determined by the Runtime, as being the shortcut that has the name 'default'.

Only one default application should be created as multiple defaults could lead to unexpected behavior or errors.

Other spaces

Page tree