Skip to main content

Functionality

Introduction to Functionality​

Using the Functionality screen, you can develop and test the business logic of the application 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 components:

  • Control procedures - The definition of the business logic.

  • Template - Templates contain the actual source code for the business logic.

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

  • Result - This is where the program objects, which make use of the template, are (re)generated and can be applied. You can also perform a static code analysis of the generated program objects.

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

  • Process tests - Here you can create test cases for your business logic. See test cases.

  • Validation - This tab shows any 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 Transaction 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) and triggers (for events) 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_user();
set @insert_date_time = getdate();
end

set @update_user = dbo.tsf_user();
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 regenerated. 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 Projects > Full model > 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 regenerated. 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 project_id = @project_id
and project_vrs_id = @project_vrs_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:

  • In development - Control procedures in development. This prefilter will not show the disapproved control procedures.
  • To review - Control procedures that need to be reviewed.
  • Disapproved - Disapproved control procedures assigned to you.
  • Developed by me - All control procedures developed by you.
  • Hide generated - Hide control procedures that have already been generated.
  • Hide inactive - 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​

menu Business logic > Functionality > tab Control procedure

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

See also: Control procedure guidelines.

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

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.

Control procedure 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

The code can be written directly in the Template tab and will be displayed as is usual with an editor such as Notepad++ or SQL Server Management Studio. If the preference is to work directly in the editor itself, 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. After the development is finished, the control procedure should receive the status Completed. This is done by calling the Complete control procedure task. It must be indicated in the pop-up what must be included in the change log.

If subsequently a modification is made to the template or the control procedure, the control procedure will automatically revert back to the status of Development.

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.

caution

To retrieve the username of the current application user, the Software Factory provides the tsf_user() function.

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() function.

3. Assign the template​

menu Business logic > Functionality > tab Assigning

Templates can be assigned to one or more logic concepts in the Assigning tab page. 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. By using the arrow down button, the template can be woven into 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 regenerated. For an overview of the generated session variables, see Generated session variables.

menu Business logic > Functionality > tab Result

  1. To regenerate the source code of the program objects, click the Generate code button in the Result tab page.

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

  1. The generated program objects can subsequently be deployed to the database by clicking the Execute button. After clicking Execute, the Software Factory parses the program object and updates the modified templates automatically.

5. Complete the control procedure​

menu Business logic > Functionality > tab Control procedure

After creating or modifying business logic, the control procedure can be marked for review using the Ready for review task.

Ready for review task

This will set the status of the control procedure to Review and create a changelog record. The code changelogs, including the code changes, can be found in the Code changelog tab page.

If for any reason the control procedure needs more time in development the task Set status to development can be used to revert the status back to development.

Changelog tab page

Any changes made to the code, while the status of the control procedure is set to review, will directly be pushed to the changelog and a changelog update message will be added in the comments tab page.

The control procedure will show up in the Code review screen, ready to be reviewed. Any code changes made between now and when the review is completed will automatically be pushed to the changelog.

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 versions. The difference is that they do not contain the project_id, project_vrs_id, and control_proc_id columns, because they are always in the context of one project version/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 nameData typeNullablePKDefault
prog_object_idvarchar(1000)NoX
prog_object_type_idvarchar(100)
tab_idvarchar(100)
task_idvarchar(100)
report_idvarchar(100)
process_flow_idvarchar(100)
process_action_idvarchar(100)
subroutine_idvarchar(100)
code_file_idvarchar(200)
order_noint
prog_object_file_specvarchar(1000)
prog_object_statustinyintNo0

Table #prog_object_parmtr

Column nameData typeNullablePKDefault
prog_object_idvarchar(1000)NoX
parmtr_idvarchar(1000)No
parmtr_valuenvarchar(4000)
order_nointNo
no_line_when_emptybitNo0

Table #prog_object_item

Column nameData typeNullablePKDefault
prog_object_idvarchar(1000)NoX
prog_object_item_idvarchar(1000)NoX
order_nointNo
template_idvarchar(100)No

Table #prog_object_item_parmtr

Column nameData typeNullablePKDefault
prog_object_idvarchar(1000)NoX
prog_object_item_idvarchar(1000)NoX
parmtr_idvarchar(1000)No
parmtr_valuenvarchar(4000)
order_nointNo
no_line_when_emptybitNo0