Functionality

Introduction to Functionality

menu Business logic > Functionality

Using the Functionality screen, you can develop and test the application's business logic that cannot be modeled. This business logic not only comprises traditional business rules  but also the logic to control the user interfaces, process flows and messages.

The functionality screen consists of six tabs:

• Control procedures - Define the business logic. See 1. Create a control procedure.

• Template - Templates contain the actual source code for the business logic. See 2. Add a template.

• Assigning - For statically assigned business logic, you can assign a template to the various program objects. Parameter values can be specified for every assignment. See 3. Assign a template.

• Result - This is where the program objects that use the template are (re)generated and can be applied. You can also perform a static code analysis of the generated program objects. See 4. Apply the functionality.

• Unit tests - The place to create, maintain and run unit tests. See 5. Run unit tests.

• Code review - The code review is based on the live code of the control procedure. See 6. Complete the control procedure.

• Validation - This tab shows validation messages regarding the selected business logic.

Functionality

Definitions

Control procedures

A control procedure is a placeholder for a specific piece of business logic. The control procedure describes the business logic, defines where and how it is applied, and shows the development, test and review status of the functionality.

Templates

Functionality is written in the form of code templates, based on the functional description which has been drawn up when modeling the application logic. A control procedure always contains one or more templates.

The code in templates with which the application logic is developed is dependent on the platform that the end product uses. The information available when performing the logic (the context), and the possibilities for each logic concept are almost identical for each platform.

Some points of attention:

• The code groups are often identical to the logic concepts as discussed in this manual. However, it may occur that certain logic concepts are included in different code groups.
• Examples have been worked out in this chapter, in which the end product makes use of a platform that supports Transact-SQL. The way in which the execution context is read out and in which the values are set may differ on the various platforms. However, the information that contains the execution context and the possibilities for the application of logic are practically the same for each platform.

Program objects and items

Every logic concept results in one or more program objects in the end product, which are generated by the Software Factory. When using Transact-SQL for your business logic, these program objects result in stored procedures (for most concepts), triggers (for events), and functions on the database, which are executed by the application tier and user interfaces.

A program object contains one or more program object items. The header and footer items are provided by the Software Factory. The items containing business logic correspond to the custom code templates.

A program object for the project table default concept will look like this:

/* Header, generated by the Software Factory */

create procedure def_project
(
   @default_mode       tinyint,             /* 0 = add, 1 = update */
   @import_mode        tinyint,             /* 0 = regular, 1 = import */
   @cursor_from_col_id varchar(255),        /* trigger column */
   @cursor_to_col_id   varchar(255) output, /* focus column */

   /* column values */
   @project_id         project_id output,
   @project_desc       description output,
   @finished           no_yes output,
   @finished_date      date output,
   @insert_user        user_name output,
   @insert_date_time   date_time output,
   @update_user        user_name output,
   @update_date_time   date_time output
)
as
begin

  /* Business logic to fill finished date when finished is checked */
  
  if @finished = 1 and @finished_date is null
  begin
    set @finished_date = getdate();
  end

  /* Business logic to fill trace columns */

  if @default_mode = 0 /* New record */
  begin
    set @insert_user = dbo.tsf_original_login();
    set @insert_date_time = getdate();
  end
  
  set @update_user = dbo.tsf_original_login()
  set update_date_time = getdate();

/* Footer, generated by the Software Factory */

end

When are program objects generated

If a program object is in some way affected, the generated code is set as 'stale' to indicate it needs to be generated again. For example, in case of new, updated, or deleted assignments, or new, updated, or deleted parameter values.

This is checked during the definition generation and code (group) generation. If a program object does not contain any code, it will always be generated. Once the program object code is generated, it is no longer considered 'stale'.

The Code stale field is set automatically, but its state is visible in the menu Models > Model content > tab Program objects > group Generation.

note

If you are using the Fully controlled strategy in a Control procedure, you need to set generated_code_stale to 1 manually in the code to ensure the program object's code is generated again. In that case, however, using the Staged strategy instead is probably more suitable for the Control procedure.

Example (to be adapted to suit your own situation):

update prog_object
set generated_code_stale = 1
where model_id = @model_id
  and branch_id = @branch_id
  and prog_object_id = [Prog object(s)]
  and generated_code_stale = 0

It is not necessary to empty prog_object_generated_code.

Prefilters for control procedures

menu Business logic > Functionality > tab Control procedure

To get a better overview of the control procedures, the following prefilters are available:

• - Control procedures in development. This prefilter does not show the disapproved control procedures.
• - Control procedures that need to be reviewed.
• - Disapproved control procedures assigned to you.
• - All control procedures developed by you.
• - Hide control procedures that have already been generated.
• - Hide inactive control procedures.

Adding functionality

The step-by-step plan for creating functionality is discussed in the following paragraphs.

For a better overview, the following rules apply:

• Tab Control procedure: When a control procedure is created or edited, the name of the developer will automatically be filled in the Developer field.
• Tab Templates: When a control procedure is in development or in review, and you are not the responsible developer, templates are shown in red.
• Control procedure- or template code for inactive control procedures is shown in grey.

1. Create a control procedure

A new control procedure can be created in the Control procedure tab.

Before you start:

• Check out the Control procedure guidelines.
• As long as the control procedure has not been completed, you can roll back the changes you made. See: Abandon changes in a control procedure.
• When a control procedure is created or edited, the name of the developer is automatically entered in the Developer field. If any questions arise about the development, this directs to the right developer.

To create a control procedure:

menu Business logic > Functionality > tab Control procedure

1. In field Assignment, indicate how this procedure should be assigned: 'Static' or via 'SQL'. It is possible to switch the assignment type of a control procedure: static to dynamic (control procedure code will be added) or dynamic to static (static assignments will be added).

2. If Assignment is 'SQL', you can select a generation Strategy:

   • Delete: All objects generated by this control procedure will be dropped during the Generate definition process and then re-created by the control procedure.
   • Fully controlled: All objects generated by this control procedure will not be dropped during the Generate definition process. This strategy means the developer has to manage all the objects generated by this control procedure. So, previously generated and outdated objects need to be deleted by code, if necessary. See also When are program objects generated.
   • Staged: All objects generated by this control procedure will be either updated, inserted, or deleted based on the object data. If any data has changed, the object will be updated. If no corresponding object is found, a new object will be created. If an object is found but no corresponding data is present, the object will be deleted.

notes on the default strategy

The Staged strategy is recommended because of all its advantages, such as performance and IO.
This strategy uses temporary tables similar to the program object tables but much smaller. The Software Factory will identify and apply changes between the temporary tables and the actual program object tables. Records are only inserted, updated, or deleted as needed. This makes the process more efficient than deleting and recreating all program objects.

• For new SQL-typed control procedures, the default strategy is Staged.
• If you change the assignment to 'SQL' (using the task Switch assignment to SQL ), the strategy will also be automatically set to Staged. The generated SQL code will automatically use the correct staging tables.
• Existing SQL-typed control procedures from before the 2021.3 Thinkwise Platform release have been assigned Delete as the strategy.

Settings for a control procedure

2. Add a template

menu Business logic > Functionality > tab Templates

Most procedures have one template for weaving. Hence, the template ID and description can be copied as default from the control procedure. The sequence number determines the default sequence of the program objects. These can still be changed for each program object at a later date.

The source code is subsequently defined in the Code tab of the form.

Adding code to the Template tab

You can write the code directly in the Template tab. It will be displayed as usual with an editor, such as Notepad++ or SQL Server Management Studio. If you prefer to work directly in the editor, you can click on the button next to the code template. A linked editor will open. Changes to the file are automatically reported back to the Software Factory.

When the control procedures or templates are modified, the history is stored in the Software Factory. Several tasks are available to compare these templates and control procedures with the history. It is also recorded when a template is modified and when the source code was last generated.

See also: Control procedure guidelines.

Parameters

A template can have parameters. These are placed in square brackets (e.g., [COL_ID]). When assigning a template to a program object, the parameter is provided with one or more values. If a parameter has more than one value, the line of code containing the parameter will be repeated as many times as there are values.

if @[col_1] = 1 /* checkbox is checked */
begin
  set @[col_2]_mand = 1 /* mandatory */
end
else
begin
  set @[col_2]_type = 2 /* hidden */
end

A parameter value can also be empty and by checking the Ignore if empty check box for the parameter, it can be determined that the source code line, containing the parameter, is not included in the end product.

note

To retrieve the username of the current application user, the Software Factory provides the tsf_user() and tsf_original_user() functions. See also User name.

This method is not supported by Crystal Reports/Crystal Clear, however. In this case the username has to be provided to the report by means of a parameter, filled using a default that uses the tsf_user() or tsf_original_user() function.

3. Assign the template

Templates can be assigned to one or more logic concepts in the Assigning tab.

• To add templates to your upgrade scripts, also read Model version specific upgrade scripts.

menu Business logic > Functionality > tab Assigning

The left column shows all the program objects available for the selected concept. After selecting a program object, the contents of the program object (program object items) are displayed on the bottom right.

1. Execute the Assign task to assign it to the program object.

Logic concepts can be disabled through the settings found in tables, tasks, reports and process actions. This applies for default, layout, context and process program objects.

Disabled concepts are displayed in italics. No code is generated for disabled logic concepts and they are not used in the end product. When assigning a template to a disabled concept, this concept will be automatically enabled.

Assigning control procedure templates

A template can be assigned to the same program object item more than once. To do this, the program object item ID of the existing assignment first has to be modified. This can be done in the list of program object items. Also, the sequence of the templates can be changed here by changing the sequence number.

If a template has parameters, these are automatically created on the Parameters tab. An icon on the tab indicates that there are still parameters without a value. If these are not automatically generated, they can still be generated with the Generate parameters task.

Parameter values required

note

When editing templates with an external editor, selecting a different template will disconnect the temporary file that is created from the Software Factory and add the message This file is disconnected to the top of the file. Trying to import template code containing this message will display an error:

4. Apply the functionality

If a new template has been woven or the template source code has been changed, the source code of the program objects has to be generated again. For an overview of the generated session variables, see Generated session variables.

menu Business logic > Functionality > tab Result

1. To re-generate the source code of the program objects, click Generate definition in the Result tab.

   Result tab page

   The following options are available:

   • Highlight item - check this box to mark the generated source code corresponding with the program object item. This shows which part of the source code is generated by which program object item (and hence, which template).

   • Open and Import buttons - with these buttons, you can easily modify an assigned template using an external editor and import the changes afterward. The advantage of editing generated program objects instead of code templates is that the program object body and parameters are available in the code.

     When importing a modified program object, a pop-up dialog clearly shows the changes.

     Import a program object

2. To deploy the generated program objects to the database, click Execute. The Software Factory parses the program object and updates the modified templates automatically.

5. Run Unit tests

menu Business logic > Functionality > tab Unit tests

Create, maintain and run unit tests. See the Unit tests manual.

6. Complete the control procedure

menu Business logic > Functionality > tab Control procedure

Depending on the settings, a code review is required or not to complete the control procedure:

If no code review is required:

Execute the Complete control procedure task to set the status to Completed. If a modification is made to the template or the control procedure, the control procedure will automatically revert to the status of Development.

If code review is required:

Execute the Ready for review task to set the status of the control procedure to Review.

:::Note If a control procedure is marked as Ready for review in both branch and origin, a merge conflict may arise. You can select only one to be merged. :::

The control procedure will show up in the Code review tab, ready to be reviewed. The review will be based on the live code of the control procedure. For more information on the review process, see the Code review manual.

Three tabs are available:

• Code review - an overview of all changed control procedures, also when they are still in development.
• Changes - an overview of every change since the last time the control procedures have been completed. Here you can see which templates are new, updated, or deleted.
• Comments - an overview of all comments on every change in the selected code review record.

note

If, for any reason, the control procedure needs more time in development, execute the task Set status to development to revert the status back to development.

Code review in Functionality

Development and review status

menu Business logic > Functionality

Icons in the Functionality screen indicate the development and review status of control procedures:

Icon	Description
	Currently in development by current developer
	Currently in development by another developer
	Ready for review, developed by current developer
	Ready for review, developed by another developer
	Changes are disapproved, in development by current developer
	Changes are disapproved, in development by another developer

Abandon changes in a control procedure

As long as a control procedure has not been completed, you can roll back the changes you made. It will then revert to the last time it was approved and completed.

For a control procedure with the Assignment setting 'Static', it is also possible to revert the assignments and parameters.

menu Business logic > Functionality > tab Control procedure

1. Select the control procedure you wish to revert.
2. Execute the task Abandon control procedure changes .

Abandon changes in a control procedure

Managing code generation with staging tables

Code generation during the Generate definition, Generate code groups, and Generate source code processes can be managed with several strategies. This chapter describes the Staged strategy.

The Staged strategy manages the mutations of the program object and program object item tables by temporary tables. It looks to see if anything is new, changed, or removed. This strategy will fit most SQL-typed control procedures.

It uses temporary program object tables to insert, update and/or delete program objects. The Software Factory creates these temporary tables, and the developer can use them. In SQL-typed control procedures, the developer can insert data into the temporary tables, and the Software Factory processes the data.

Note:

• The temporary tables are almost equal to the permanent model versions. The difference is that they do not contain the model_id, branch_id, and control_proc_id columns, because they are always in the context of one branch/control procedure.
• The selected and prog_object_generated_code columns for program objects are not present as these are not handled in the Generating definition process but in the Generate source code process.

The created temporary tables have the following table structure:

Table #prog_object

Column name	Data type	Nullable	PK	Default
prog_object_id	varchar(1000)	No	X
prog_object_type_id	varchar(100)
tab_id	varchar(100)
task_id	varchar(100)
report_id	varchar(100)
process_flow_id	varchar(100)
process_action_id	varchar(100)
subroutine_id	varchar(100)
code_file_id	varchar(200)
order_no	int
prog_object_file_spec	varchar(1000)
prog_object_status	tinyint	No		0

Table #prog_object_parmtr

Column name	Data type	Nullable	PK	Default
prog_object_id	varchar(1000)	No	X
parmtr_id	varchar(1000)	No
parmtr_value	nvarchar(4000)
order_no	int	No
no_line_when_empty	bit	No		0

Table #prog_object_item

Column name	Data type	Nullable	PK	Default
prog_object_id	varchar(1000)	No	X
prog_object_item_id	varchar(1000)	No	X
order_no	int	No
template_id	varchar(100)	No

Table #prog_object_item_parmtr

Column name	Data type	Nullable	PK	Default
prog_object_id	varchar(1000)	No	X
prog_object_item_id	varchar(1000)	No	X
parmtr_id	varchar(1000)	No
parmtr_value	nvarchar(4000)
order_no	int	No
no_line_when_empty	bit	No		0

Model version specific upgrade scripts

It is possible to add templates to your upgrade scripts when upgrading to a new model version. This can be useful when, for example, a data correction is necessary during a specific part of the upgrade process.

note

Use the Data migration functionality for simple scenarios, where records are moved from one table to another or columns are filled using default values.

To add templates to the upgrade:

menu Business logic > Functionality

1. Create a control procedure with code group Upgrade.

2. The Assigning tab lists the program objects that will be run before, during, and after the Upgrade code file for each available model version, as well as a program object for every model version. Here, assign your templates to the Upgrade program objects. See 3. Assign the template. The code will be weaved into the correct position and executed during the next upgrade.

   You can place custom scripts in various stages of the upgrade process. The stage depends on the program object to which a template is assigned:

   Program object	Stage
   ug_before_upgrade_from_[x]	Before any upgrade code from model version [x] has been executed.
   ug_during_upgrade_from_[x]	After the data migration from model version [x] has been done but before the old tables are dropped.
   ug_after_upgrade_from_[x]	After the old tables from model version [x] have been dropped when upgrading.

   Model version [x] in the program object name corresponds to the configured source model version. Because of this, the template will only affect this specific upgrade.

   If a code needs to be run before, during, or after every single upgrade, you can use one of the following program objects instead:

   Program object	Stage
   ug_before_upgrade_always	Before any upgrade code has been executed.
   ug_during_upgrade_always	After the data migration has been done but before the old tables are dropped.
   ug_after_upgrade_always	After the old tables have been dropped.

   When using a template during the upgrade, you can refer to the old tables using __[tab_id]__.

note

If no model version specific program objects are available, make sure the model version is marked to use upgrade logic:

1. Navigate to menu Models > Model overview > tab Branches > tab Model versions.
2. Select the Use upgrade logic checkbox. See also Use upgrade logic. To keep the list of upgrade program objects manageable, clear this option again for older model versions.
3. Using upgrade logic also requires a model version to have a Description which will be used in the name of the generated program objects.

Model version specific upgrade scripts