Versioning

In Intrexx, the various developmental stages of applications, processes and layouts can be versioned in two ways:

Semantic versioning: Assignment of a textual version number with metadata
Version management with Git (history)

Semantic versioning: Version number

The version number can be created and edited in the properties dialog of applications, processes and layouts. It is not created automatically but manually. This makes it easier to identify the version in use.

Open version manager

Opens a dialog where version numbers can be created and managed.

Version manager

Application / Process / Layout

The title of the current application, process or layout is also shown here.

Version column

If versions are already available, these will be listed here.

Details column

The details of the version selected in the left-hand column are shown here.

Remove version

Removes the version currently selected in the "Version" column.

Add version / Edit version / Copy version

Opens a dialog where a new version can be added or the currently selected version can be edited. When copying a version, the same dialog will open so that a new version number can be assigned before copying.

Version

In semantic versioning, version numbers are composed of three digits: Major, Minor and Patch. The format is always as follows: <Major Version>.<Minor Version>.<Patch Version>. Each digit is incremented as follows:

Major version

API-incompatible modifications are published
Minor version

New functions, which are compatible with the current API, are published
Patch version

Modifications consist of API-compatible bug fixes only

Pre-release version

With this setting, suffixes for pre-release versions can be attached to the version number.

Preview

A preview of the version number is shown here.

Details

Date

The version's date can be entered here. If you create a new version, the current date is entered automatically.

System requirements

Minimum Intrexx version

The corresponding Intrexx version can be selected here. You will find all Intrexx version numbers in the list. If you create a new version, the Intrexx version currently installed is entered automatically.

Other requirements

In this field, enter requirements such as database, applications, Connectors or recommended apps (e.g. Intrexx Share for plugins).

Multilingualism

Opens a dialog where the requirements can be entered in the different portal languages.

Description

A "changelog" can be written here. Enter the new or modified functions of this version here.

Multilingualism

Opens a dialog where the description can be entered in the different portal languages.

Restrict definition of version number

Application, process and layout developers have the ability to restrict the definition of version numbers by other users. This is done by opening the file "version.xml" in a text editor. The file is found here: Portal directory /internal/application/store/<GUID of the application / process / layout>;

<?xml version="1.0" encoding="UTF-8"?>
<v:versions xmlns:v="https://schemas.unitedplanet.de/intrexx/2016/versionmanager/versioninfo/" lock="false">
	<v:version guid="83F4893FA60DD288DD89C3240B5CA70B83E0ED7E" major="1" minor="0" patch="0" creationTime="1501153173848">
		<v:property name="date">2017-07-26T22:00:00Z</v:property>        
		<v:property name="minProductVersion">9400</v:property>        
		<v:property name="additionalRequirements">            
			<v:text>
				<v:item lang="de"/>
				<v:item lang="en"/>
			</v:text>
		</v:property>
		<v:property name="description">            
			<v:text>
				<v:item lang="de"/>                
				<v:item lang="en"/>            
			</v:text>        
		</v:property>    
	</v:version>
</v:versions>

Replace lock="false" with lock="true" and save the file.

<?xml version="1.0" encoding="UTF-8"?>
<v:versions xmlns:v="https://schemas.unitedplanet.de/intrexx/2016/versionmanager/versioninfo/" lock="true">

If a developer has restricted the definition of version numbers, a new version number can be defined based on the version last specified by the developer by adding an extension to this - this can be done by clicking on "Add version" in the version manager.

Extension

Enter the extension here.

Callables

The callables

$Portal.getApplicationVersionInformation("<appGuid>"))
$Portal.getWorkflowVersionInformation("<wfGuid>"))
$Portal.getLayoutVersionInformation("<layoutDirName>"))

are available for semantic versioning. This return an object with the type "de.uplanet.lucy.server.auxiliaries.versionmanager.VCVersionInfo". "VCVersionInfo" has the following methods:

getVersions(): List<VCVersionItem>
getCurrentVersion(): VCVersionItem

"VCVersionItem" has the following methods:

getMajorVersion(): int
getMinorVersion(): int
getPatchVersion(): int
getPreReleaseVersion(): String
getCustomVersion(): String
getDate(): Date
getMinProductVersion(): String
getAdditionalRequirements(): Map<String, String>
getDescriptions(): Map<String, String>
getFormattedVersion(): String

This means, the current version of an application can be displayed in the browser using Velocity, for example:

$Portal.getApplicationVersionInformation("<GUID der Applikation>").getCurrentVersion().getFormattedVersion()

Click here for more information.

History - Version management with Git

Create history

A history can be created in the following modules:

A Git repository forms the basis for the history. For each respective module, this is created in the following directory:

Applications module (Portal directory internal/application/store/<Application GUID>)
Processes module (Portal directory internal/workflow/<Process GUID>)
Design module (Portal directory internal/layout/xml/layouts/<Layout name>)

Each entry in the history corresponds to a commit in the Git repository. If you publish an application, process or layout via the File menu, a dialog will open where an entry in the history can be created with Git.

Publish with history

Here, you can see the dialog that opens when you publish an application. During the versioning process of applications or processes, the scripts they contain are also versioned.

Create entry in the application history / process history / layout history.

If this setting is activated, the latest change will be added to the history. This setting is not available if the "Always create history entry when publishing applications, workflows or layouts" options is activated in the options in the portal properties.

Comment

You can add a comment to document the latest change in the application. If a comment is not specified, the default comment from the language constant "COMMIT_DEFAULT_MESSAGE" in the default portal language used. Here is a guide on how to format commit comments.

Compare version currently open with the last entry in the application history

Opens a dialog where the changes in the application can be tracked.

Open version manager

Opens a dialog where the semantic version number can be edited.

Options / Publishing

In the Extras menu / Options, you can find the settings for publishing applications, processes and layouts with or without history under each respective module. Regardless of which option is selected here, the different publishing methods can also be selected from the respective File menu. Regardless of which option is selected here, the different publishing methods can also be selected from the respective File menu.

Default settings for publishing

Optimized publish

Only the pages that have been changed will be transformed for the web when you publish an application with this option. In general, the optimized publish is recommended.

Optimized publish with history

Here as well, only the pages that have been changed will be transformed. Additionally, when the application is published, a dialog will be shown where changes can be commented and an entry can be added to the application history.

Complete publish

When publishing an application, all objects are published. An application has to be published completely, if for example XSL files were exchanged on the server - e.g. after installing a patch that contains XSL files or when developing XSL files. In this case, all pages must be republished.

Complete publish with history

Here as well, every page will be transformed. Additionally, when the application is published, a dialog will be shown where changes can be commented and an entry can be added to the application history.

Allow application to be published despite error entries in the "Problems" area

When an application is opened, Intrexx checks it for errors. Corresponding notices are displayed in the Problems area. Warning entries are displayed as a notification. The application can still be published despite these. Error entries prevent the application from being published. However, you can allow the application to be published despite these by activating this setting.

This setting may not be available in future versions of Intrexx. The best approach is to always correct reported errors.

Regardless of which option is selected here, the different publishing methods for applications can also be selected from the File menu.

With processes and layouts, you will find the following settings in the "Publish" dialog:

Default settings for publishing

Public process / layout

The process or layout is published without history.

Publish process / layout with history

When publishing the process or layout, a dialog is displayed where changes can be commented and an entry can be created in the history.

Regardless of which option is selected here, the different publishing methods for processes or layout can also be selected from the File menu.

Publish regardless of the settings in Options

Regardless of which settings are active in Options for applications, processes or layouts, you can select the desired mode for each publication.

To do this, click on the small arrow to the right of the floppy disk symbol in the top left of the toolbar. This displays a menu in which you can select the following modes:

Optimized publish
Optimized publish with history
Complete publish
Complete publish with history

If you click directly on the floppy disk icon, the application (or process or layout) is published according to the settings in Options.

Portal properties / Options

In the Portal menu / Portal properties, you can specify that every time applications, processes and layouts are published, a new entry is created in the history. This option makes sense, for example, for live systems so that changes in the portal can be tracked. This applies to both user and system actions. When an action, which usually does not create a new history entry (e.g. Optimized publish), the user will receive a notification that a history entry is required. When an action, which usually does not create a new history entry (e.g. Optimized publish), the user will receive a notification that a history entry is required. Following this, the dialog for creating a new entry will open.

New entry in the history

A new history entry can be created in the following ways:

Applications - File menu
- Publish application
  - Optimized publish with history
  - Complete publish with history
- Create entry in application history
Processes - File menu
- Publish process with history
- Create entry in process history
Design - File menu
- Publish layout with history
- Create entry in layout history

New history entries are also created via user or system actions.

User actions

An entry is created under the following circumstances:

Every time an application, process or layout is published via the File menu and the setting Always create history entry when publishing applications, workflows or layouts is active. If a repository does not exist yet, this will be created here.
When an application, process or layout is published via the File menu and the setting Create entry in application history is active. The entry is created after publishing. This setting is hidden in the dialog, if the Portal property: "Always create history entry when publishing applications, workflows or layouts" is defined.
File menu / Create entry in history opens a dialog where an entry can be created if changes are found on the server which have not yet been added to the history.

System actions

For certain actions, the system will automatically create a new entry in the history, if the corresponding setting is active in the portal properties. If a repository has not been created yet, this will be created here. Each new entry receives a static English comment with the prefix "Intrexx:". The user, who is stored in the history entry, depends on the action (see below). The following system actions are supported:

Process

Activation/Deactivation of a process (User: Current user)
Layout

Definition of the default layout (User: Current user)
User management

Publishing of the User application when the schema is changed (User: Intrexx)
Script

publishAllApplications, publishAllProcesses (User: Intrexx)

Complete history

The following menus open a dialog where you can find the complete history:

For the current application: Application menu / Application history
For the current process: Process menu / Process history
For the current layout: Layout menu / Layout history

The search filters the list based on the search term entered. Comments, users and tags are searched through. Within tags, names, comments and users are search through.

"ID" column

The ID of a repository entry is generated automatically by Intrexx and displayed in the abbreviated form typical for Git.

"Comment" column

The comments entered when the application, process or layout was published are shown here.

"User" column

The user who created the last entry in the history is shown here.

"Date" column

The date when the history entry was created is shown here.

Open in Portal Manager

Opens the selected version in the corresponding module. In the Applications module, the currently opened application will be closed with this action. In the Processes and Design module, the selected entry will open in a new tab. This function is only available if the expert options have been activated. The server will not be changed with this action. If you want to use the selected state, then you need to publish the respective application, process or layout via the File menu.

If you publish a different state from the history, data could be lost, if for example the current state contains a data field that the previous state does not.

Manage tags

Entries with tags are marked with this symbol in the last column. If you have marked such an entry, click on " Manage tags" on the right. This opens a dialog where the tags for the selected entry can be managed.

Details

The tag name, the user, who created the tag, the creation date, and - where applicable - the comment are shown automatically here.

Delete tag

Removes the currently selected tag from the history.

Create tag

Opens a dialog where a new tag can be created.

Name

The name of the tag must be unique, meaning it may only appear once per history. Furthermore, the tag name must conform to Git. For example, it may not contain whitespace.

Comment

You can enter one comment for each tag. Click on "OK" to save the tag and close the dialog.

You will then be back in the "Manage tags" dialog. Click on "OK" to return to the history.

Load next 25 entries / Load all entries

When opening the dialog the last 25 entries of the history are loaded. Clicking "Load next 25 entries" or "Load all entries" loads the corresponding number of additional entries.

Refresh

Reloads the current state of the history from the server, e.g. if changes have been made that are not visible in the history. This situation occurs, e.g. if an application was published on the server but without an entry in the history. If this is the case, a corresponding notification is shown at the bottom of the dialog.

Advanced options

If the expert options have been activated in the current module, the Advanced options button will be available at the bottom of the dialog. The button opens a submenu from which all of the history entries can be deleted. The Git repository will also be deleted at the same time.

Individual history entries cannot be deleted.

Info text

Appears at the bottom in special situations, e.g. when there are changes on the server without an entry in the history.

Details

You will find the details in the lower part of the dialog. This displays the ID, user (QualifiedLoginName), date and comment from the currently selected entry.

Changes

Added, edited and deleted files for the currently selected entry are shown here.

"Type" column

The change type can be recognized from the symbol:

Added
View changes
deleted

"Path" column

The path of the modified file relative to the portal directory internal/application/store/<Application GUID> is shown here.

View changes

Opens a sub menu with the menu items "View changes in diff format" and "View changes in external tool".

View changes in diff format

Opens a dialog where the differences can be viewed in the diff format from Git.

Here, you can view the changes to the file in the diff format typical for Git. For binary files, e.g. images, it will only be shown that there are changes.

Lines of context

Lines of context are the lines that are output before and after the changed lines in the diff. In Git, the default value is 3. The number of lines of context can be modified here.

Reset settings

Resets the number of lines of context to the default value of 3. Click on "OK" to close the dialog again.

View changes in external tool

The file from the selected entry will be compared with the file from the previous entry in the external tool.

The external tool is only used for viewing. The external tool is only used for viewing.

View file history

Opens the change history in an additional window which functions analogously to the current dialog. Here, only the entries are shown where changes to the file were made.

Files

For the selected entry, all of the directories and files from the respective state will be shown in a tree structure. Files which have been deleted are not shown in the file tree. The following buttons are only available for files because only files, but not directories, are versioned in a Git repository.

View file

Opens a dialog where the content of the selected file is shown. Syntax highlighting is available for files ending with xml, js, vm, vmi, groovy or css. Image files with the png, jpg, jpeg or gif file extension are shown as an image.

View file history

Displays the history for the selected file. Afterwards, the comparison can be made. The comparison can also be made via the menu item Compare with last entry of application history and Compare with entry of application history. The currently opened state can also be compared to the last state of a history entry in the dialog where the history entry can be created. The same applies to processes and layouts.

Compare versions

Compare

After selecting a history entry for comparison, a dialog will open where another history entry can be searched for and selected. It is also possible to select two entries at once, which will then display a dialog with the differences between the two versions.

If you only selected one entry, you will find the following information here:

The search filters the list based on the search term entered. Comments, users and tags are searched through. Within tags, names, comments and users are search through.

ID column

Displays the ID of the repository entry.

Comment column

Displays the comments that were entered when the application, process or layout was published.

User column

The user who created the last entry in the history is shown here.

Date column

The date when the history entry was created is shown here.

Select the version for comparison. When you click on "OK", the differences between the two versions will be displayed.

"Type" column

The change type can be recognized from the symbol:

Added
View changes
deleted

"Path" column

The path of the modified file relative to the portal directory internal/application/store/<Application GUID> is shown here.

View changes

Opens the following submenu:

View changes in diff format

Opens a dialog where the differences can be viewed in the diff format from Git.
View changes in external tool

The file from the selected entry will be compared with the file from the previous entry in the external tool.

The external tool is only used for viewing. The external tool is only used for viewing.
Furthermore, the state which should be compared needs to be open in the Portal Manager.

This sub menu is only available if the expert options have been activated. Changed files will be marked in the list with a *. Changes to the selected files can be merged interactively between the currently opened version and the selected history entry. Furthermore, the version which should be compared needs to be open in the Portal Manager. Only changes to files from the currently opened version in the local working directory can be applied. The selected file will be compared in the external tool using the two-window view.

All changes in this area are carried out under own respsonsibility. Support cannot be provided for the editing of files and the resulting consequences. The action allows you to directly edit files and should therefore only be performed by users with the required specialized knowledge. Validate files in current working directory With this action, changes to the selected files can be completely reset from the currently opened version to a different, selected history entry.

Reset changes

This action is only available if the expert options have been activated. Furthermore, the version which should be compared needs to be open in the Portal Manager. Changed files will be marked in the list with a *. This action is only available if the expert options have been activated. Furthermore, the version which should be compared needs to be open in the Portal Manager.

All changes in this area are carried out under own respsonsibility. Support cannot be provided for the editing of files and the resulting consequences. The action allows you to directly edit files and should therefore only be performed by users with the required specialized knowledge. Validate files in current working directory With this action, changes to the selected files can be completely reset from the currently opened version to a different, selected history entry.

Validate files in current working directory

Opens a dialog where the files from applications, processes and layouts can be validated.

Changes to files may not be compatible with the patch level of the current portal. Please note: The patch level of individual files cannot be modified and may cause errors.

Hide system files

This option filters the table. System files are files that are normally generated automatically by the system, e.g. when creating a new application or when publishing an existing one.

"History" area

In the "Applications", "Processes" and "Design" modules, you will find the "History" tab at the bottom. The complete history of the current application, process or layout is shown here.

Open detailed history

Opens a dialog where the entire history is shown. The entry selected on the tab is preselected.

Load next 25 entries / Load all entries

When the area is opened, the last 25 history entries are loaded. Clicking "Load next 25 entries" or "Load all entries" loads the corresponding number of additional entries.

Refresh

Reloads the history from the server. The view is automatically refreshed after the following actions:

Publish by a user
Publish during the execution of certain actions
1. Processes: Action Activate/deactivate process
2. Design: Define as default layout
Create entry in history
Import, if the imported object is currently open in the Portal Manager and a new entry was created in the history during the import
When deleting applications, processes or layouts
When deleting all entries in this history

Use tags

History entries can be marked as important using tags; this makes the specific entry easier to find. A tag is often used to denote a new version. In principle, every entry which is important to the Development can be marked with a tag. Intrexx automatically connects with Intrexx version number to tags in the history. If, for example, a new application version number is created and the application is then published, a tag with this version number is created for this commit.

Tags for the history of applications, processes and layouts can be created in the dialog which displays the complete history. Any number of tags can be added to a history entry. Tags can also be deleted. Every tag is constructed as follows:

Name
User (QualifiedLoginName) - is automated in the "User" module. This is composed of the username and domain.
Date
Comment (optional)

The name of the tag must be unique, meaning it may only appear once per history. Furthermore, the tag name must conform to Git - for example, it may not contain whitespace. Rules for tag names can be found here. Optionally, each tag can be commented on. If no comment is defined, the comment stays empty. A tag is created automatically upon publishing, if the semantic version number has been changed. The tag name corresponds to the semantic version number and if necessary, a suffix is added to prevent duplicate entries.

Information about current state

You can see which version is currently open in the respective modules in the following places:

Applications - On the workspace if the application node is selected.
Processes - On the Process tab and in the Details dialog together with the shortened Git ID and date.
On the Layout tab and in the Details dialog with the shortened Git ID and date.

External tools

External tools can also be used when versioning with Git, these can be integrated here.

Misc

Applications, processes and layouts can be saved locally using the File menu. A locally saved application does not contain Git information. The same applies to locally saved processes and layouts. If you open a locally saved object in the corresponding module, you can view the history of the object if an application, process with the same GUID or layout with the same directory name has been published on the server.

Git configuration files

Configuration files are created when a Git repository is created. Depending on the object type (application, process, layout), not every configuration file is required.

.gitattributes

This file contains the definitions for line endings for different file types.
.gitignore

This file contains directories and files that should not be versioned.

Import / Export

When importing or exporting applications, processes or layouts, you can set how to proceed with version management.

Import

The dialog for version management is available in the import dialog by clicking on "Version management".

"Options" tab

If the setting "Create history entry when publishing" is active, an entry in the history will be created when the import is performed. Under "Comment" the entry "Import" can be replace by your own comment. Here is a guide on how to format commit comments.

"History" tab

History in the export

All history entries contained in the export are listed here. In the list you can find the ID of the corresponding entry, the comment, the user, who created the entry, and the date, when the record was created.

History on the server

All history entries for the import object, which are currently on the portal server for the import object, are listed here.

Compare export with the newest entry in the history on the server

Opens a dialog where the export can be compared with the newest entry in the history on the server. This action is only available if both the export and the server contain a history for the import object.

In the import dialog information about the version can be opened by clicking on "Version information".

The version number and the date are shown here. Under "System requirements" the minimum version of Intrexx that is required to implement the object is shown.

Export

In the export dialog the version management can be opened by clicking on "Version management".

Here the ID, the comment, the user, who caused the record in the history and the date, when the record was created, are shown. Furthermore you will be informed in the lower area of the dialog if changes have been made that are not yet visible in the history.

Also in the export dialog information about the version can be opened by clicking on "Version information".

The version number and the date are shown here. Under "System requirements" the minimum version of Intrexx that is required for the use of the export object is shown.

Options - History

The history options are available via the main menu "Extras / Options / General".

To view and merge changes in the History, you can enter paths to external tools here. The tools need to be installed on the same server where the Portal Manager is. Tools that can compare and merge two files in a two-window view are supported. The program path must support parameters for the file paths to be compared. To do this, the placeholders ${file1} and ${file2} can be used in the program path. ${file1} stands for the file that is taken as the basis for the comparison, ${file2} stands for the file for which the comparison is made. The placeholders are optional. If they are not specified, then they are attached programmatically to the program path.

The external tool is only used for viewing. Changes to files will not be applied.

Use external tool for viewing changes in the history

With this setting, a path to an external tool for viewing the changes can be entered.

Examples:

WinMerge (Windows)

"C:\Program Files (x86)\WinMerge\WinMergeU.exe" /wl /wr ${file1} ${file2}
KDiff3 (Windows)

"C:\Program Files\KDiff3\kdiff3.exe" ${file1} ${file2}
KDiff3 (Linux)

kdiff3 ${file1} ${file2}
KDiff3 (Mac)

/Applications/kdiff3.app/Contents/MacOS/kdiff3 ${file1} ${file2}
OpenDiff (Mac)

/usr/bin/opendiff ${file1} ${file2}

Select

Opens a dialog where the tool can be selected.

Double-clicking on change opens external tool

Means that changes can be double-clicked on to view them in the history. If this option is not activated, the change will be shown in Diff format.

Use external tool for merging changes in the history

With this setting, a path to an external tool for merging the changes can be entered.

Examples:

WinMerge (Windows)

"C:\Program Files (x86)\WinMerge\WinMergeU.exe" /wr ${file1} ${file2}
KDiff3 (Windows)

"C:\Program Files\KDiff3\kdiff3.exe" ${file1} ${file2}
KDiff3 (Linux)

kdiff3 ${file1} ${file2}
KDiff3 (Mac)

/Applications/kdiff3.app/Contents/MacOS/kdiff3 ${file1} ${file2}
OpenDiff (Mac)

/usr/bin/opendiff ${file1} ${file2}