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 , 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
• Add a model or branch to the 'My models/branches' prefilters
• Remove a model or branch from the 'My models/branches' prefilters.

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 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 .

menu Models > Model overview > tab Models / tab Branches

1. If necessary, deselect the prefilter My models/branches . 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' .
4. Reselect the prefilter My models/branches . 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 .

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' .

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 .
• 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.

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 .

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.

Add a new model

The following configuration settings are retrieved from the Default configuration (menu Maintenance > Configuration).

• Company name.
• Subname group, see Set a subname group for a branch.

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.

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.

3. 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 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.

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 .
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 and branch will be compressed and exported, excluding trace columns and non-default runtime configurations. You can download it via 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, like user-created controls or font faces.

To export base data:

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

1. Execute the task Export base data .
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 .
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, like user-created controls or font faces. You can recognize this situation when an import fails because of missing objects.

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 .
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.

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.

• To create a base model, see chapter Create a new model with a MAIN branch.
• For more information about base models for languages, see chapter Application languages.

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 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 .

note

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

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 .

More tasks are available:

• 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.

• 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.

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 .

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 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, 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 .
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

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.

This provides two additional possibilities compared to deleting a branch:

1. The branch remains visible in the Branch diagram.

2. The branch can be unarchived so that you can work in it again. This will restore all data as stored in the history tables based on the state of the branch just before it was archived. It is not possible to switch to an archived branch to work in it.

   If your database contains too much historical data, you can decide to delete the history from a specific point in time, for example, anything older than five years. It will then no longer be possible to unarchive a branch because its historical data cannot be re-inserted.

If neither of these possibilities are desired, you can choose delete the branch entirely.

It is not allowed to archive the MAIN branch or branches that are the origin of other branches that have not been archived.

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 . 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 .

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 .
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 .

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
  • Floating label strategy - Universal GUI Select a strategy for floating labels. See Floating labels strategy.
• 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).
• Smoke test
  • Mimic Windows GUI (classic) - Windows GUI This check is disabled by default. Enable it if you run a smoke test for the Windows GUI and want it to fail for prefilters with expression fields. See Prefilter with expression fields in smoke tests 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.

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:

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

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:

  

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

  

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 shows all model versions with a description.
• The prefilter Use upgrade logic shows all model versions where Use upgrade logic is checked.

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.

Platforms for a branch

Application languages

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

Setting
Thinkwise supported languages	Thinkwise supports a basic set of languages. New languages outside this set can be added in the Master data: Advanced menu (right-click on the Default menu): menu Master data > Model > Application languages Windows GUI Here, you can also 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: menu Models > Model overview > tab Branches > tab Base models - An overview of the languages in a branch is available in menu Models > Model overview > tab Branches > tab Application languages. - 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 their 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. The fallback language 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	Global translations are used for the login process in web applications, when a user's identity and application language are not yet known: IAM > menu Settings > Global translations

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 filegroups.

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.

Quality dashboard

menu Models > Model overview > tab Quality dashboard

In the Quality dashboard, you can monitor the quality of any active branch in this model. Select the branch you want to monitor on the tab Models. For more information, see: Quality dashboard.