Skip to main content

Models and branches

Introduction to models and branches​

When multiple developers or teams work on different features of an application, they can make additional branches within a model for these features. Each feature can be developed separately in its own branch. When completed, it can be combined (merged) back into the model's origin branch. This way, a new feature can be developed and tested independently from the rest of the model.

It is also possible to merge a branch into a different branch than its origin branch. Whether we merge with the origin or with another branch, it always involves merging the changes from a source branch into a target branch. See also Merging

To fine-tune your development workflow, you can create multiple branches for multiple features:

Branching example containing two feature branches, a hotfix branch, and a sub-feature branch

Overview of models and branches​

menu Models > Model overview

  • The Models tab contains a list of all models in the Software Factory development environment. It allows you to create new models and branches.
  • The Branches tab contains a list of the MAIN branch and all other branches of the selected model. It allows you to add a new branch and modify the generic settings for these branches.
  • The Quality dashboard tab gives an overview of the overall quality of the selected model.

Select a model and branch on start-up​

Upon starting the Software Factory, you need to select the model or branch in which you want to work. By default, your most recent model and branch are selected. This can also be a model or branch you just created and continued working in.

If only one model and branch are available in the prefilters for My models/branches my models, the Software Factory will automatically start this model and branch. In that case, you can still switch to another model or branch.

See:

Switch to another model or branch​

To indicate which model and branch you are working in, a breadcrumb trail is available on every screen, displaying the model and branch.

Model/branch breadcrumb

If you want to work in another model or branch, it is possible to switch:

menu Models > Switch branch

  1. Select a Model.

  2. Select a Branch.

    tip

    If necessary, use the lookup to select a model or branch. If the model or branch you are looking for is not visible, deselect the My models/branches my models prefilter.

    See also Add a model or branch to 'My models/branches' prefilter and Remove a model or branch from 'My models/branches' prefilter.

  3. Confirm with Yes or No the message that all open documents will be closed. You can stop the confirmation message from appearing by choosing the option Always. To turn the message back on, see Registered user settings.

After switching to another model or branch, all open windows will be closed to prevent working in your previous model or branch.

The Software Factory keeps track of the model and branch you selected and will automatically select these again when you log in.

Add a model or branch to 'My models/branches' prefilter​

You can add models and branches to the prefilter My models/branches my models.

menu Models > Model overview > tab Models / tab Branches

  1. If necessary, deselect the prefilter My models/branches my models. Now, all available models and branches are visible.
  2. Select the model or branch you wish to add to the prefilter.
  3. Execute the task Add to 'My models/branches' add.
  4. Reselect the prefilter My models/branches my models. Now, the model and branch you added are still visible.

Remove a model or branch from 'My models/branches' prefilter​

You can remove models and branches from the prefilter My models/branches my models.

menu Models > Model overview > tab Models / tab Branches

  1. Select the model or branch you want to remove.
  2. Execute the task Remove from 'My models/branches' remove.

Branch diagram​

The branch diagram shows a graphical overview of the branches inside the model and how they interact.

menu Models > Model overview > tab Branch diagram

  • Archived branches are visible by default, and shown in grey. You can exclude them by executing the task Show/Hide archived branches show/hide.
  • Protected branches have a padlock icon . For more information, see Protect a branch.
note

Merges from a source branch into a different branch than the origin are not shown in the branch diagram.

For more information on managing branches, see this blog in the Thinkwise Community.

branch diagram An example of a branch diagram

Customize the branch diagram​

You can change the branch diagram settings in the following places:

  • Model-wide: menu Models > Model overview > Models > tab Model overview.
    The settings specified here apply to the entire model, with no distinction between who is logged into the Software Factory. However, if you have customized your settings, they will override the model-wide settings.
  • User-specific: menu Models > Model overview > tab Branch diagram > tab Settings.
    On this tab, you can customize your personal preferences. These settings are not displayed for other users. The same tab page is displayed in the menu Maintenance > Users > tab Branch diagram settings.

Edit the following branch diagram settings to modify how it is displayed:

  • Display versions from - Set a start date and time to the range of versions that should be displayed.
  • Display versions to - Set an end date and time to the range of versions that should be displayed.
  • Width between versions - Specify the number of pixels between each version circle in the branch diagram.

If you select a date range, the branch diagram will show the following:

  • First versions are always shown, regardless of whether they fall within the specified range. Without the first version, the creation logic of branches would be lost in the diagram.
  • Named or merged branch versions are only shown if they fall within the specified range.

Models​

Create a new model with a MAIN branch​

To create a model with a MAIN branch:

menu Models > Model overview > tab Models

  1. Execute the task Create model Add.

  2. Add a Model name and a Description.

  3. The Branch name is set to 'MAIN' by default. If you follow a different naming convention, you can change this field.

  4. If necessary, change the RDBMS Type. A model can only support one RDBMS type.

  5. Select Execute.

Create model Add a new model

The following configuration setting is retrieved from the Default configuration (menu Maintenance > Configuration).

After creating the MAIN branch, a job will be scheduled automatically to generate its definition. You can view this job in the menu Maintenance > Jobs.

Switch to a newly created model or branch​

After creating a new model or branch, answer the question if you want to switch to it. This prevents working in the wrong branch.

  • If you choose to switch, all open documents will be closed, and your session will be updated to the new model or branch. The Model overview screen will be reopened automatically with the new model/branch combination as the selected row.
  • If you do not switch, the Software Factory keeps all documents open in the context of the original model/branch combination. In addition, a new Model overview screen is opened with the new model/branch combination as the selected row.

To switch to the model or branch at a later moment, see Switch to another model or branch.

model switch Start working in the new model or not

Set model details​

After creating a new model, set more details:

menu Models > Model overview > tab Models > tab Model overview

  1. Select whether the model is a Base model. If it needs to be linked to new models by default, select Def. base model. Only the MAIN branch of a base model is automatically linked to a new model.

    Base models are models that are only used by other models. A base model contains the necessary details for the correct operation of a model, a supplement, or an addition, such as a standard theme or default translations. Also, Thinkstore models can be used as a base model inside your work model. For more information, see the chapter Base model.

  2. Select whether the model is a Work model.

A new model usually is a work model because you are going to develop it. When you create a new work model, the Software Factory will automatically link default base models to it. Only base model branches without origin or default base models will be linked.

tip

To hide a model, clear the checkbox Work model. Then it will no longer show in tasks for selecting a model or switching to another branch. It will also be hidden by prefilters on the screens.

  1. Windows GUI There are three fields available: Title 1, Title 2, and Title 3. You can enter any information into these fields, which will appear on the splash screen during startup, in the title header, in the list of applications, and on the About screen.

  2. The Notification email address is used for sending notifications to the development team about the start and finish of definition generation and source code generation. Make sure the notification settings are set in the Default configuration screen to receive emails.

Model overview Model settings

Rename a model​

Not available at the moment

At the moment, it is not possible to rename a model or branch because that would cause a loss of history.

Base models​

Base models are models that are only used by other models. A base model contains details that are necessary for the correct operation of a model, a supplement, or an addition, such as a standard theme or default translations. Also, Thinkstore models can be used as a base model inside your work model.

You can link only one branch of a base model to a branch of a work model.

menu Models > Model overview > tab Branches > tab Base models

This tab provides an overview of all base models and whether they are linked to this branch or not. If necessary, use prefilter Linked linked to view only the linked base models.

To link a branch of a base model to a branch of a work model:

  1. Select the base model.
  2. Execute task Link base model link.
note

If you do not want to use the current MAIN branch, execute task Select previous branch select previous.

When you link a base model branch to a work model branch, it needs to be generated to obtain the model of the base branch.

  1. To generate the definition immediately, reply Yes to the question "Do you want to generate the definition for model [MODEL NAME] > [BRANCH NAME] immediately?". You can also reply No, link other base model branches, and generate the definition after the last one with the task Generate definition generate definition.

More tasks are available:

  • unlink Unlink base model - To unlink a base model branch from a work model branch. Note that components of the base model will be removed from the work model during generation. Only components that are no longer in use are removed. It might take multiple generations before all components are cleaned up.
warning

Never unlink the base models SQLSERVER_DB, DB2_DB or ORACLE_DB from a work model. These base models are required for versioning and executing code.

  • import Merge base models into work models - To import the base models for the selected work model without generating. This is an expert function that can be used for testing new features from a base model in a work model.

Export and import models​

Export a model​

You can export your own work and base models. By exporting a model, you can share it between different environments. This is a fast and easy way to enrich your models.

Exporting a model only makes sense if it has a branch (a model without a branch is empty).

To export a model:

menu Models > Model overview > tab Models

  1. Execute the task Export model Export.
  2. Enter a Model and Branch name.
  3. Select Execute.
  4. Select a folder and, if necessary, change the name. The default name contains the date and time of the export, the model, and the branch name. Note that .dat is the only allowed extension for importing a model.
  5. Select Save.

The entire model, its base data, and branch are compressed and exported, excluding trace columns and non-default runtime configurations. You can download the export in the pop-up.

Export base data​

Export base data if the model you want to export uses base data which is not present in the receiving Software Factory.

note

Usually, you do not need to export base data because the base data is already present in the exported model.

To export base data:

menu Advanced > Master data > Software Factory > Export base data

  1. Execute the task Export base data Export.
  2. Select a folder and, if necessary, change the name. The default name is 'base_data.dat'. Note that .dat is the only allowed extension for importing a model.
  3. Select Save.

Import a model​

You can import an exported model into another model or even into another Software Factory. This can be done into a model without a branch or into a new model that does not yet exist. You can also merge imported model data with an existing model to update an existing branch. This ensures that the contents of the target branch are completely overwritten to match the exported model exactly.

note

You can only import a model into another Software Factory if the platform version is the same as the Software Factory from which the model was exported. The only allowed extension is .dat.

To import a model:

menu Models > Model overview > tab Models

  1. Check if it is necessary to import base data before importing the model. See Import base data.
  2. Execute the task Import model import.
  3. Select the File path of the .dat file you wish to import.
  4. If necessary, change the Model and Branch name.
  5. Select Execute.

The model will be decompressed and imported. Trace columns will be filled with the user name 'Imported' and the current system date and time.

Import base data​

Import base data if the model you want to import uses base data which is not present in the receiving Software Factory.

note

Usually, you do not need to import base data because the base data is already present in the exported model.

You can recognize this situation when an import fails because of missing objects.

Import model error Example of a domain which cannot be imported because of a missing user-created datatype

To import base data:

menu Advanced > Master data > Software Factory > Import base data

  1. Execute the task Import base data import.
  2. Select the File path of the .dat file you wish to import.
  3. Select Execute.
  4. Import the model again, now that the required base data is present. See Import a model.
note

Base data may be overwritten when upgrading platform versions.

Branches​

Create a new branch​

A branch is created within a model. The origin is tagged with the current point in time, and the branch is copied from that point in time.

menu Models > Model overview > tab Branches > tab List

  1. Execute the task Create branch create branch.

  2. Select the Origin branch you want to base your new branch on.

  3. Select the point in time you want to base your new branch on:

    • Current point in time - Based on the current branch, as it is now.
    • Specific point in time - Based on an earlier point in time, for example, yesterday at 9 AM.
    • Select model version - Based on how the branch was at a certain point in time. See Model versions.

  4. Enter a New branch name.

  5. If necessary, select a folder (Branch folder) and the database (Branch database name).

Create branch Create a new branch

note

Only the creator of the branch has access to the active runtime configuration. All other users can activate the runtime configuration for this branch in the menu Maintenance > Users. Select the user, open the tab Runtime configurations, and find the corresponding runtime configuration.

Protect a branch​

Branch protection prevents the archiving or deletion of a branch. It safeguards branches with indefinite lifespans. Branches named MAIN, RELEASE, and DEVELOP are automatically protected. A branch will also automatically become protected when used as an origin for another branch. You can remove its protected status once all its branches are archived and fully deleted. For other branches, you can manually add or remove protection as needed.

You can recognize a protected branch by the padlock icon in the Branch diagram.

warning

Deleting a model still leads to the removal of all its associated branches.

To add protection to a branch:

Models > Model Overview > tab Branch

  1. Select the branch you want to protect.
  2. Go to the tab Form.
  3. Select the checkbox Protected.

Clear this checkbox when you intend to archive or delete a branch.

Rename a branch​

At the moment, it is not possible to rename a model or branch because that would cause a loss of history.

Delete a branch​

When deleting a branch, all underlying data and then the branch itself will be removed. Any related merge session to this branch will no longer be executable.

tip

Instead of deleting a branch entirely, you can also choose to archive the branch.

Revert a branch​

In some situations, you may want to revert a branch:

  • Without a merge session: if something went wrong in a branch and you want to make a fresh start, you can revert the branch to, for example, yesterday.
  • After a merge session: when you completed a merge session and the result is undesired, you can undo the merge session by reverting the branch. For example, when resolved conflicts do not turn out as intended. When executing a merge session, two model versions will be created in the target branch to indicate the moments before and after.

model versions Model versions, before and after a merge

Reverting a branch to an earlier point in time will simply undo any changes done to the model:

menu Models > Model overview > tab Branches > tab List / tab Model versions

  1. Execute the task Revert branch revert.
  2. If necessary, change the Model and Branch you wish to revert.
  3. Select whether you want to revert to a Specific point in time or a Specific model version.
  4. Select whether you want to revert to the branch immediately or review the changes first.

Reviewing the changes first will take you to a merge session that shows all the actions that will be taken as if the reversal was initiated in a branch. This type of one-sided merge session will never have conflicts.

revert a branch Revert a branch

Set branch details​

Branch details​

menu Models > Model overview > tab Branches > tab Form

  • Database storage location - You can divide the database into separate files and store them on separate drives. For example, you can store invoices on the SSD and customer data on the HDD. You can mark these storage locations for a table or index to retrieve data faster.
    • Table storage
    • Index storage
  • Data migration and upgrade
    • Source branch and Source model version - Shown here for informational purposes only. They can be changed in menu Data > Data migration > tab Tables with the task Set source for data migration and upgrade set source. They can also be changed in the Creation process, when generating the definition or executing all creation steps.
  • Merging
    • Origin branch and Origin model version - Shown here for informational purposes only. They indicate from which branch and model version the specified branch originates. This information serves as input for a merge session when the specified branch is being merged again.

Correct foreign key casing​

Because incorrect casing may cause problems in the user interfaces or in the Indicium service tier, a task is available to correct the casing, if necessary.

menu Models > Model overview > tab Branches > tab List

  1. Execute the task Correct foreign key casing Correct foreign key casing.

Locate an invalid XML character​

Some characters, such as the 0x0A linefeed character, can cause problems when serializing the model to XML. These (control) characters, which are often not displayed, can be located using this task.

menu Models > Model overview > tab Branches > tab List

  1. Execute the task Locate invalid XML character locate invalid xml character.
  2. If you already know which table to scan for invalid characters, enter the Table name. Leave it blank to scan all tables.

Retrieve the number of rows​

You can query the number of rows for all tables in an end-product database. This number is stored in the NO_OF_ROWS table tag and can be used to automatically enrich the model. For example, by changing the look-up control or screen type of an entity based on the number of rows in the database, to optimize the performance or user experience.

menu Models > Model overview > tab Branches > tab List

  1. Execute the task Retrieve number of rows retrieve number of rows.

Model settings for a branch​

For each branch, you can add or change model settings. When you merge a branch to it's MAIN branch, these settings will be included.

menu Models > Model overview > tab Branches > tab Model settings

  • General
    • Multiple live versions - select to allow more model versions. By default, only one model version can have the status 'Production'.
  • Form
  • Task
    • Enable for empty subject - To enable the table task when no records are present on the screen. Adjusting this setting afterward will not change the existing rows. It will only affect the default value for new rows.
  • Report
    • Enable for empty subject - To enable the table report when no records are present on the screen. Adjusting this setting afterward will not change the existing rows. It will only affect the default value for new rows.
  • Data
    • Use domains - Enabled by default. When you disable it, all tables will use standard data types instead of the user-defined data types for the domains. Disable it when, for example, you wish to use SQL Data Synchronization to synchronize data between Azure databases since this tool cannot process user-defined data types. If you change this option, all tables need to be rebuilt. They will automatically be set to status 'changed' and added to the data conversion (and therefore to the upgrade script).
  • Prefilter
    • Lenient prefilter queries - This checkbox is deactivated by default and should remain so. When deactivated, Indicium can optimize prefilter queries and performance. Only use this setting temporarily if you have a lot of prefilter queries that do not yet use the alias t1. Change those queries as soon as possible, then deactivate the setting again. See Prefilter type for more information.

Floating labels strategy​

Universal GUI

For the Form component, the Software Factory allows separate specifications for Label width (px) and Field width (px) in the Model settings.

However, these specifications do not work well for input controls in the Universal GUI that use floating labels. Instead of placing a label in front of the input control, floating labels are placed inside the input control. When a value is entered, the label floats to the top inside the input control.

floating label Example of a floating label

You can configure per model whether the label width should be ignored for or included into the input control. Only forms and parameter pop-ups will be affected by this setting. The CHECKBOX and LABEL control types will never be affected as they do not use floating labels.

menu Models > Model overview > tab Branches > tab Model settings

  1. Select an option for the Floating labels strategy:

    • Ignore the label width - Only the field width is used.
    • Include the label width - Default. The label width and the field width will be added up to determine the size of the input controls.

Example

Given the following form configuration in the Software Factory:

Floating labels strategy

The Windows and Web GUIs that do not use floating labels will display the form as follows:

Floating labels strategy

The orange color on top indicates the full form element width including the label. The green color underneath the fields indicates only the input field widths.

For the Universal GUI:

  • If the Floating labels strategy is set to Include the label width, the form with floating labels will be displayed as follows:

    Floating labels strategy

  • If the Floating labels strategy is set to Ignore the label width, the form will be displayed as follows:

    Floating labels strategy

note

Large labels may get too little space when they are used as floating labels in small input fields.

Branch as model version​

Tag a branch as model version​

menu Models > Model overview > tab Branches > tab Model versions

You can tag a branch at a certain point in time as a model version. This model version can be used for upgrades or branching and merging.

The column Model version type indicates whether model versions have been added by a process such as merging or archiving. Model version descriptions that have been added by a process cannot be changed, except for descriptions of model versions added by the Creation process.

Model version status​

menu Models > Model overview > tab Branches > tab Model versions

The column Status indicates the stage or environment of the branch.

The following statuses are available:

  • Test - When the development phase is completed, the branch can be tested.
  • Acceptance - During the acceptance phase, users can become acquainted with the system and detect any final errors.
  • Production - When the system is accepted, it is put into production. The branch can no longer be modified once it is put into production.

Make a model version available for upgrade logic​

menu Models > Model overview > tab Branches > tab Model versions

To make a model version available for upgrade logic, select the checkbox Use upgrade logic and add a Description. See Version specific upgrade scripts.

  • The prefilter Named versions Named versions shows all model versions with a description.
  • The prefilter Use upgrade logic Use upgrade logic shows all model versions where Use upgrade logic is checked.

model versions Model versions

Set a platform for a branch​

menu Models > Model overview > tab Branches > tab Platforms

For each branch, you can select a platform (Windows and Universal), the default menu, and default theme.

platform Platforms for a branch

Application languages​

In the Software Factory, languages can be set at different levels.

Thinkwise supported languages​

Thinkwise supports a basic set of languages. To add more languages:

menu Advanced > Master data > Model > Application languages

  1. Add a new language.
  2. Windows GUI Set a flag icon, visible for the user when they select a language from the ribbon.

Application languages for a branch​

  • For all Thinkwise-supported languages, a base model with GUI translations is available in the menu Models > Model overview > tab Branches > tab Base models.
  • An overview of the languages in a branch is available in the menu Models > Model overview > tab Branches > tab Application languages.

The following rules apply:

  • Translation objects are generated for all application-specific terms and need to be translated in every specified language.
  • To add a new language, link its corresponding base model. See chapter Base models.
  • All GUI labels and messages are added and translated for all linked Thinkwise-supported languages.
  • Translations for database errors and warnings are available in a base model for English, German, and Dutch (DB2_MSG_TRANSL, ORACLE_MSG_TRANSL, SQLSERVER_MSG_TRANSL). Each supported database platform contains its own errors. Only base models with the same database platform as the work model will be shown.

Fallback language​

Universal GUI

The fallback language is applied when a user uses a language that is not available for the application. It can replace the selected language when starting the application via IAM and when starting the application directly on the Software Factory. A language can, for example, be available if the application is started via IAM but not if it is started directly on the Software Factory. In that case, the fallback language is used in the Software Factory.

  • To set the fallback language for a branch: menu Models > Model overview > tab Branches > tab Model settings > tab Model settings
  • To set the default fallback language for a new model: menu Maintenance > Configuration

Login language​

IAM > menu Settings > Global translations

Global translations are used for the login process in web applications, when a user's identity and application language are not yet known

Database storage location for a branch​

menu Models > Model overview > tab Branches > tab Database storage locations

For SQL Server, the file locations for the database can be set here. When empty, the default server settings are used. For more information, see Database files and file groups.

Printer for a branch​

menu Models > Model overview > tab Branches > tab General settings > tab Printers

Here, you can configure and edit the available printers.

Runtime configurations​

You can create different runtime configurations for development, test, acceptance, or production environments. Each runtime configuration contains information on how to launch the end product. You can vary per runtime configuration, for example, which email providers or file storage locations you use. For more information, see runtime configurations.

Branch maintenance​

Archive and unarchive a branch​

Archiving a branch will delete all its operational data. This reduces the database size of the Software Factory and increases performance. The branch record and model version information is retained, which makes it different from deleting a branch entirely. Note the following:

  • It is not possible to switch to an archived branch to work in it.
  • It is not allowed to archive the MAIN branch or branches that are the origin of other branches that have not been archived.

Archiving differs in two ways from deleting a branch:

  • The branch remains visible in the Branch diagram.
  • The branch can be unarchived so you can work in it again. This restores all data as stored in the history tables based on the state of the branch just before it was archived.

If you do not want these possibilities, you can choose to delete the branch.

note

If your database contains too much historical data, you can decide to delete the history data of all branches that no longer exist. See also Clean up archived branches.

To archive or unarchive a branch:

menu Models > Model overview > tab Branches > tab List / tab Model versions

  • To archive a branch, execute the task Archive branch archive a branch.
  • To unarchive a branch, execute the task Unarchive branch unarchive a branch.

Clean up model history data​

Over time, the database can grow in size due to a growing list of deleted and archived models and branches, and their history data. To prevent problems with storage, backup, and restoration, you can clean up the history data.

To clean up these history data manually:

menu Advanced > Master data > Software Factory

  1. In the menu, select the task Clean up model history clean up model history.
  2. Optional. Select the checkbox Delete archived branches. Archived branches cannot be unarchived if you delete them.
  3. Select the Specific model and Specific branch for which you want to clean up the deleted branches and models.

Clean up archived branches​

A system flow is available to automatically clean up archived branches and their history that exceed a retention period. Archived branches cannot be unarchived if you delete them.

To configure this retention period for archived branches:

menu Maintenance > Configuration

  1. Select the Archived branch retention. The default value is 60 days.
tip

You can set up custom schedules for applications in IAM: menu Authorization > Applications (SQLSERVER_SF) > General settings > Scheduled system flows for the system flow system_flow_clean_archived_branch_history. See System flow schedules.

Was this article helpful?