You are viewing the documentation for Blueriq 17. Documentation for other versions is available in our documentation directory.
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
### 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
- Container type: AQ_Dashboard_ProjectWidget
- Service call type: AQ_StartProject
- Container type: AQ_ExternalFlow
- Service call type: AQ_RestServiceClient
- Service call type: AQ_SoapServiceClient
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>:
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.