Creation

Introduction to Creation

The Creation screen allows you to easily deploy a new or updated version of your application. Creating and deploying an application requires a number of steps that are explained in the following paragraphs.

It is important to know that:

• All jobs are performed by Indicium. So, generation, validation, etc., will continue even if you close the Software Factory GUI.
• Since all jobs are performed by Indicium, it is possible to automate the entire process.
• All developers can track a job's progress. For example, if one developer starts generating the definition of a branch, another developer can see this in their Creation screen. This behavior extends to the validation- and unit test tabs in various modelers, and to the Validation and Unit test screens that can be opened directly from the menu.

You can execute all steps at once or each step separately.

• Execute all creation steps

Create steps seperately:

• Generate definition

• Validate definition

• Generate source code

• Execute source code

• Run unit tests

• Run smoke tests.

Configure the file storage location for system flows

The platform's system flows for writing code files, program objects, the manifest, and the IAM synchronization script use process actions that need a file storage location.

Before creating your software, configure the file storage location path in IAM:

IAM > menu Authorization > Applications

1. Select your SQLSERVER_SF application in tab List.
2. Navigate to tab File storage locations.
3. In column File storage, select the file storage location generated_scripts_location.
4. Edit field Path or change the file storage type using the task Switch file storage location type .

If the file storage type is File system, you can use variables in the path. For example D:\files\%FileLocation%\file.txt, where %FileLocation% is: thinkwise\textfiles.

See also: Set a different subfolder for code files and program objects.

Set a different subfolder for code files and program objects

The default file storage location is set in IAM, in the menu Authorization > Applications > tab File storage locations. The default subfolders for writing code files and program objects to storage are:

• Code files - \Source_code\Groups

• Program objects - \Source_code\Program_objects.

  For example, the standard code file Functions will be written to the File storage location + \Source_code\Groups\060_Functions.sql (the code file's relative path).

If you want to use other subfolders than the default, you can specify those for code files in the Software Factory, in the menu Models > Model content > tab Code files > tab List > tab Code file > field File specification.

Execute all creation steps

By executing all creation steps, you do not need to run each step separately. Consult the next chapters in this manual for more detailed information about each creation step.

menu Deployment > Creation > tab Generate definition

1. Execute the Execute all creation steps task.

2. In the popup, select your source for data migration and upgrade. For more detailled information, see Generate definition.

3. Select your Next action: Continue creation or Review mapping and click Execute.

   If you selected Continue creation:

4. Optionally, enter a model Version name. This name identifies the model version and is shown in the manifest and deployment package folder.

5. In field Execute, select whether you want to run:

   • Complete - all steps are selected, deselecting a step is not possible.
   • Selected - all steps are selected, you can deselect the steps you do not want to execute.
   • Selected (start with none) - none of the steps are selected, you can select the steps you want to execute.

6. Define for each step whether it should be executed and, when applicable, what the error handling should be.

7. For the source code, you can define the Upgrade method (Full or Smart).

8. Select Execute.

   Settings for executing all creation steps

1. Generate definition

If you choose to run each Creation step separately, you start with generating the definition.

note

If configured, a notification email is sent to the notification email address set in Model overview at the start and finish of this step.

In this step, your branch is generated and marked as a moment in time (in model_vrs).

menu Deployment > Creation > tab Generate definition

1. Execute the Generate definition task.

2. In the pop-up, select your source for data migration and upgrade. Two selection methods are available:

   • Obtain from database - If necessary, select a Runtime configuration.
   • Specific model version - Select a Source branch and a Source model version.

   This pop-up will not be presented the first time a definition is generated, i.e. when no source branch and model version have been specified yet.

3. Select the Next action:

   • Continue creation - The Generate definition process will be started.
   • Review mapping - The Data migration screen will be opened to review the mapping.

Set source for data migration and upgrade.

When the generation has finished, the application model is composed and extended using the defined generic concepts (for example, for trace functionality and logging), and the platform-specific definition is created. The generation strategy is set in the control procedures.

Generation definition

When are generated objects deleted

All generated objects will be deleted unless they are still referenced by other model objects in the following cases:

• They are copied from a base model and no longer present in the base model.
• They are generated by control procedures with generation strategy Delete. See Create a control procedure.
• The Generated checkbox is selected (available in a form's Trace info for a limited set of objects, such as tables, columns, domains, tasks, reports, and screen types).

This ensures that all generated model objects can be referenced as menu items, diagrams, look-up references, variants, etc. It maintains the integrity between roles and model objects and prevents problems.

Errors while generating the definition

If an error occurs during the generation of the definition, the generation will halt and you are prompted with various options to either continue or abort code execution. This choice may also be made by a different developer than the developer initiating the definition generation.

• Retry executing the generation step. This option can be chosen when the occurred error is fixed in the meanwhile.
• Skip the generation step and continue with the next generation step.
• Abort the definition generation completely.

tip

To find the failed steps:

1. Select one of the steps in the right-hand pane.
2. Navigate to the Start tab in the ribbon or open the context menu.
3. Select Prefilters > Failed or press ALT+F.

2. Validate definition

After the generation, the definition must be validated.

menu Deployment > Creation > tab Validate definition

• Execute all validations.
• Execute the validation for the selected group.
• Executes the selected validation.

It is important to resolve all Error and Validation messages before generating the source code. If this requires modifications to the model, you need to generate the definition again.

See Validation for more information about the validation.

3. Generate source code

After the definition has been generated and validated, the actual source code can be generated.

note

If configured, a notification email is sent to the notification email address set in Model overview at the start and finish of this step.

menu Deployment > Creation > tab Generate source code

1. Select Generate source code .

2. Select an Upgrade method.

3. If you want to write Code files to storage, select the checkbox. The code files are by default written to the \Source_code\Groups folder. A field containing the exact location appears on the screen. Click to navigate to this folder. The code in the storage is not used when executing code files on the database from this screen. Changes to the code files in storage have no effect.

4. If you want to write Program objects to storage, check the box. The program objects are by default written to the \Source_code\Program_objects folder. A field containing the exact location appears on the screen. Click to navigate to this folder.

note

To deviate from the default subfolders for code files or program objects, see Set a different subfolder for code files and program objects.

5. Select Execute.

Generate source code

The source code is generated. To provide insight into the progress, each code group shows the number of program objects it contains.

The generated code is stored in the Software Factory. Errors will be logged in the menu Maintenance > Jobs > Generate source code.

tip

To find the failed steps:

1. Select one of the steps in the right-hand pane.
2. Navigate to the Start tab in the ribbon or open the context menu.
3. Select Prefilters > Failed or press ALT+F.

Generated source code with folders for code files and program objects

Generation method

There are two options for generating the code, depending on the situation.

note

For cherry-pick execution of specific pieces of logic, use the Functionality modeler or the Code overview screen.

Full

This option is desired when the end product database still has to be created or still has to be brought in line with the model, and the end product database does not correspond with a previous version of the model.

The program code of all the objects is assembled. Subsequently, all program objects are used to compile the code files.

note

All the database objects that are not defined in the model, for example, indexes and procedures, are removed.

Smart

With this option, only modified objects are reapplied to the database. However, this option can only be used when the end product database is the same as the previous version of the model. This is often the case when upgrading a production version. The smart way of generating significantly speeds up the upgrading process, because unmodified objects are not rebuilt.

The program code of all the objects is assembled. An analysis is performed to determine which program objects are actually used during the compilation of the code files.

The condition for performing the analysis is that the program objects of the previous version of the model are available and compiled to code. This is because the analysis looks among other things at the modified code in program objects.

note

On any Software Factory prior to the 2023.1: If you perform a smart upgrade, make sure that the previous version is fully generated. For example, generated objects may have been deleted during the implementation of a branch. These then appear as newly installed objects during the difference analysis.

4. Execute source code

When all source code is generated, it must be deployed to the database. This is done in the Execute source code step. The model version will be recorded in the sf_model_info table and thus used for creating and upgrading code files (creating and upgrading databases).

warning

Make a backup of your end-product before executing this step.

You can execute the source code in several ways.

menu Deployment > Creation > tab Execute source code

• Connect - Select a runtime configuration. The server and database of this runtime configuration will be used to create or upgrade the database and deploy the business logic code. Use this task also to reconnect to a different runtime configuration.
  The connection remains available until a new Generate definition or Source code job has been started for this branch or if a timeout of 5 minutes has been reached. You can also close the connection manually .
  The default selection of code files to be executed may vary depending on whether or not the database exists and the current versioning information stored in the database. You can change the default selection by selecting or clearing the checkboxes, or with the tasks Select all code files and Deselect all code files .

  • The db code file is selected automatically if the database does not yet exist.
  • The create code file is selected automatically if the database does not exist or is empty. For example, when you connect to a manually created database on Azure SQL Database.
  • The upgrade code file is selected automatically if the database exists and the product information in this database indicates that an upgrade is required.

• Execute selected code files - As long as the connection to the database is available, you can select and execute code files.

• Execute all code files - Only available if the connection to the database has not yet been established. Select a runtime configuration. The server and database of this runtime configuration will be used to create or upgrade the database and deploy the business logic code.
  No further input is asked, and all the code files are executed directly on the runtime configuration.

Execute source code

When all code has been executed and/or compiled, your end-product is ready for use.

note

On any Software Factory prior to the 2023.1: After the database has been created, no more data model modifications should be done in the current project version. You will have to make a new version.

Errors while executing source code

menu Deployment > Creation > tab Execute source code

The log in this tab shows the errors together with the run query.

While the source code is being executed, only the last error is shown. After the job completes, the full log is shown with all errors and informative messages.

You are prompted with various options to either continue or abort code execution. This choice may also be made by a different developer than the one initiating the code execution.

• Ignore the error and continue the current code file execution.
• Skip the code file and continue with the next code file.
• Abort the execution completely.

Error in executing source code

Upgrade an existing database

When the structure of a table is changed, the old table will be renamed and a new table will be created. The upgrade script ensures that the data is migrated from the renamed table to the new table. Lastly, the (now superfluous) renamed table is deleted. Next, the business functionality is immediately reapplied.

When an existing database is upgraded, it is possible that not all data conforms to the (new) checks and constraints. To check the database, the base model SQLSERVER_VERIFICATION, DB2_VERIFICATION or ORACLE_VERIFICATION can be linked. After having carried out all of the steps again, an extra code file with controls will have been generated, which can be executed on the database.

5. Run unit tests

After an upgrade, you can run all unit tests as a regression test, to ensure that further changes have not broken any units that were already tested.

menu Deployment > Creation > tab Run unit tests

You can run the unit tests in two ways. In both scenarios, you are first prompted to select a runtime configuration. The server and database of this runtime configuration will be used to run the unit tests on.

• Execute all unit tests.
• Execute the selected unit tests.

Unit tests as a regression test

6. Run smoke tests

After an upgrade, you can run all smoke tests to ensure that there are no simple failures in the model that were missed.

menu Deployment > Creation > tab Run smoke tests

You can run the smoke tests in two ways:

• Start smoke test - Run the full smoke test. If you execute this task you are prompted to select a runtime configuration. The server and database of this runtime configuration are used to run the smoke test.
• Re-run selected smoke test step(s) - Run the selected single test steps again.

Executing smoke tests

Creation job overview

An overview of all Creation jobs for all models and branches is available in the Log menu.

menu Maintenance > Jobs > tab Job

The following prefilters are available:

• - View only active jobs. Deselect to see the completed and failed jobs.
• - View only jobs that have been executed by you.
• - View only jobs for your models.

To cancel or abort a job:

• Click to cancel a queued or active job.
• Click to abort a job. Only abort a job if Indicium is no longer running it, for example, due to a restart. By aborting the job, you inform Indicium that it is no longer running and therefore new jobs can be started.

Example: two active jobs for two models, and one queued job

Inspect errors in a job

To inspect errors that occurred in a job:

menu Maintenance > Jobs > tab Job

1. Deselect the Active jobs prefilter. Now, the completed and failed jobs are visible.
2. In the job overview, select the failed job. Its errors are available in a separate log tab or the job's output tab.

Errors in a job are available in a separate tab

Automate the Creation process

See Automate deployment.

Limit database authorization with a tag

By default, a grant .. on .. public line is added after DLL statements in logic, such as the creation of tables, user-defined data types, views and stored procedures.

To suppress this line, you need to add a tag to a model:

Advanced menu > Model management > Models > tab Model tags > tab Model tags

1. Select the Model for which you want to suppress grant .. on .. public.
2. In field Tag, add tag NO_GRANT_TO_PUBLIC.
3. Generate the model's definition to activate the tag.

Now, the grant .. on .. public line will no longer be added to the logic within the context of your model.

warning

This affects database authorization for functionality and upgrades for the entire model.

Tag: NO_GRANT_TO_PUBLIC

Troubleshoot the Creation process

Indicium error

If Indicium throws an error about creating a folder for a job in the creation or synchronization process, the file storage location probably has not been configured.

See Configure the file storage location