Synchronization to IAM

Introduction to synchronization to IAM

The Intelligent Application Manager (IAM) provides authorization, analysis, and user preferences for applications developed with the Software Factory, creating a personalized application for every user. Since the runtime components of the Thinkwise platform need to interpret the model from the Intelligent Application Manager, together with the authorization settings and user preferences, it is necessary to synchronize your project to IAM.

A project version is synchronized from the Software Factory to IAM by pushing the model from the Software Factory to IAM. You can synchronize the model directly or manually (by creating a synchronization script first). The synchronization is run via Indicium. Both options are available when you automate the synchronization via Indicium's API.

It is important to know that:

• All jobs are performed by Indicium. So, the synchronization will continue even if you close the Software Factory GUI.
• Since all jobs are performed by Indicium, it is possible to automate the synchronization process.
• All developers can track a job's progress. For example, if one developer starts the synchronization to IAM, another developer can see this in their Synchronization to IAM screen.

To synchronize a project version to IAM, two tasks are available:

• - Synchronize to IAM: synchronize directly into an IAM database.
• - Synchronize to disk: create a synchronization script to manually synchronize the model to, for example, a remote IAM server.

The Synchronization to IAM tab

Synchronization to IAM

Use this option to synchronize directly into an IAM database.

menu Deployment > Synchronization to IAM > tab Synchronization

1. Execute the Synchronize to IAM task.
2. At Target IAM, select the right IAM. These are set in the menu Maintenance > IAM configurations. The default Target IAM is selected automatically if you have not synchronized to an IAM target before. If you have synchronized before, the last selected target will be used as default.
3. To verify your synchronized model, make sure that the option Verify synchronization is checked.
4. In field Note, you can add the reason for synchronizing. The reason is also visible in the History tab.
5. Press Execute.

On synchronization, both tasks first check for unsolved validation messages and if any roles are present in the project version you want to synchronize. If no roles are present, create new roles or import them from (an upgraded) IAM using the Import roles task.

Synchronization to IAM

tip

To easily find the failed steps, select one of the generation steps on the right > navigate to the Start ribbon or the context menu > Prefilters > Status 'Failed'.

Synchronization to disk

Use this option to manually synchronize the model to, for example, a remote IAM server.

The file storage location for this process needs to be configured in IAM: menu Authorization > Applications. For more information, see Configure the file storage location.

To create a synchronization script for manually synchronizing the model:

menu Deployment > Synchronization to IAM > tab Synchronization

1. Execute the Synchronize to disk task.
2. To verify your synchronized model, make sure that the option Verify synchronization is checked.
3. In field Note, you can add the reason for synchronizing. The reason is also visible in the History tab.
4. Press Execute.

After a successful run, the script is written to the configured file storage location. A field containing the exact location appears on the screen. You can directly navigate to this file or folder .

tip

To easily find the failed steps, select one of the generation steps on the right > navigate to the Start ribbon or the context menu > Prefilters > Status 'Failed'.

Verify synchronization

menu Deployment > Synchronization to IAM > tab Synchronization

menu Deployment > Deployment package > tab Deployment package

Since the model is not locked, it can be changed during a synchronization or the creation of a deployment package. This could lead to errors when a change applies to an object that has already been synchronized. For example, when a table has been renamed, but the columns have already been synchronized with the old table name.

It is possible to verify the synchronized model during:

• - Synchronization to IAM.
• - Synchronization to disk.
• - Creating a deployment package.

When the model changes during synchronization, a warning is shown, for example:

"The model has changed during synchronization of INSIGHTS version 1.00 to IAM, using host localhost and database INSIGHTS_IAM. Check the verified results and consider re-synchronization when important changes were made."

Include modules into the synchronization

menu Deployment > Synchronization to IAM > tab Synchronization > tab Modules

If a project version contains any modules, a list of available modules will be shown. By checking the modules you can include or exclude them from synchronization.

The Roles tab shows all roles and the modules in which they are included. A checkmark in front of the role indicates if it will be synchronized.

Modules to synchronize to IAM

Post synchronization code

menu Deployment > Synchronization to IAM > tab Post synchronization code

It is possible to add arbitrary SQL code to a synchronisation run. This code will be executed after the synchronisation to IAM is finished. The current project_id and project_vrs_id are available as variables, as long as there are no "GO" statements encountered.

note

This code is different from the post synchronization code in the Deployment package screen.

An example of how to use the Post synchronization code

Use case: Create or replace an existing application

A typical use case of SQL scripts after synchronization is to use the synchronized project version to create or replace an application.

Writing these scripts is similar to dynamic model scripts but applies to the structure of the Intelligent Application Manager instead of the Software Factory. Since the Intelligent Application Manager uses a SQL Server database, the Transact-SQL dialect is used, regardless of the database platform used by the product being deployed.

warning

Please note that these scripts are subject to change. A new Thinkwise Platform version can result in procedure and data structure changes. Always consider the impact of periodic maintenance of these scripts compared to the benefits of automating these tasks.

You can use two variables, @project_id and @project_vrs_id, to refer to the project and version currently being deployed.

Furthermore, you can use the template variable '<@db_name,,>' in the post-deployment scripts. These are automatically replaced when using the Deployment Center. Note that this variable is unavailable for scripts that are executed directly after synchronization to IAM.

Script examples

When creating a new application, a database server must be configured, and the server ID must be used.

The following script determines the ID of a particular named server and stores it for later use. If the named server does not already exist, the server will be created.

The server address 'current_server' can be used to refer to the IAM database server.

The rdbms_type can take the values 0, 1, and 3 for SQL Server, DB2, and Oracle, respectively.

declare @server_id server_id
declare @db_name db_name = 'MY_PRODUCT' 

select top 1 
    @server_id = server_id
from server
where server_name = 'production'

if @server_id is null
begin
    insert into server
    (
        server_name,
        server_address,
        rdbms_type,
        insert_user,
        insert_date_time,
        update_user,
        update_date_time
    )
    values
    (
        'production',
        'current_server', 
        0,
        dbo.tsf_user(),
        sysdatetime(),
        dbo.tsf_user(),
        sysdatetime()
    )

    set @server_id = scope_identity()
end

Use the following SQL script to find the version id and application id of the most recent active application for the project currently being deployed:

declare @current_gui_appl_id id
declare @current_project_vrs_id project_vrs_id

select top 1
   @current_gui_appl_id = gui_appl_id,
   @current_project_vrs_id = project_vrs_id
from gui_appl
where project_id = @project_id
  and server_id = @server_id
  and active = 1
order by gui_appl_id desc

With the information described above, you can use a procedure to copy all settings from the existing application version to a new application version. This uses the task Copy application in IAM. If there is no previous application version, a new application is created:

declare @gui_appl_id id

if @current_gui_appl_id is not null and @current_project_vrs_id = @project_vrs_id
begin
    -- The existing project version is being redeployed
    set @gui_appl_id = @current_gui_appl_id
end
else if @current_gui_appl_id is not null
begin
    -- The existing application uses a previous version version. 
    -- Copy all settings
    exec task_create_gui_appl_from_gui_appl
        @from_project_id = @project_id,
        @from_project_vrs_id = @current_project_vrs_id,
        @from_gui_appl_id = @current_gui_appl_id,
        @to_project_id = @project_id,
        @to_project_vrs_id = @project_vrs_id,
        @insert_gui_appl = 1,
        @to_gui_appl_id = null,
        @copy_gui_appl_settings = 1,
        @copy_gui_appl_transl = 1,
        @copy_deployment_module_settings = 1,
        @copy_gui_appl_authorization = 1,
        @copy_gui_appl_ini_parmtr_value = 1,
        @copy_gui_appl_iam_process_flow = 1,
        @copy_gui_appl_file_storage = 1,
        @copy_gui_appl_oauth_server = 1,
        @copy_gui_appl_printer = 1,
        @copy_usr_gui_appl = 1,
        @copy_usr_grp_pref = 1,
        @copy_gui_appl_pref = 1

    -- Load the newly created application id
    select top 1 
        @gui_appl_id = gui_appl_id
    from gui_appl
    where project_id     = @project_id
      and project_vrs_id = @project_vrs_id
    order by gui_appl_id desc

    -- Inactivate previous version
    update gui_appl
    set active = 0
    where gui_appl_id = @current_gui_appl_id

    -- Activate new version
    update gui_appl
    set active = 1
    where gui_appl_id = @gui_appl_id
end
else
begin
    -- There is no (active) application for this project
    -- Create a new application
    insert into gui_appl
    (
        project_id,
        project_vrs_id,
        gui_appl_name,
        gui_appl_alias,
        server_id,
        db_name,
        active,
        icon,
        icon_data,
        order_no,
        insert_user,
        insert_date_time,
        update_user,
        update_date_time
    )
    select 
        @project_id,
        @project_vrs_id,
        @project_id + '/' + @project_vrs_id + '@' + s.server_name + ':<@db_name,,>',
        'my_product',
        s.server_id,
        '<@db_name,,>',
        1,
        p.icon,
        p.icon_data,
        10,
        dbo.tsf_user(),
        sysdatetime(),
        dbo.tsf_user(),
        sysdatetime()
    from server s, project_vrs p
    where s.server_id       = @server
      and p.project_id      = @project_id
      and p.project_vrs_id  = @project_vrs_id
end

To speed up the rollout of an application instance or an application for a new tenant, default user groups are available in the Software Factory. These are reusable, preconfigured user groups and role assignments. More information here.

To automatically apply the default user groups for the default tenant for your new application as follows, use the task Apply default authorization in IAM:

declare @default_tenant_id tenant_id

select 
    @default_tenant_id = tenant_id
from tenant
where default_tenant = 1

-- Assign the default user groups and corresponding roles to the default tenant
exec task_provision_default_authorization
    @project_id = @project_id, 
    @project_vrs_id = @project_vrs_id, 
    @gui_appl_id = @gui_appl_id,
    @tenant_id = @default_tenant_id

When new project versions are released regularly, it can be undesirable to keep data from previous versions indefinitely. You can use the post-synchronization scripts to clean up the previous version. Note that the variable @current_project_vrs_id was determined in an earlier step.

if @current_project_vrs_id is not null and @current_project_vrs_id = @project_vrs_id
begin
    -- Delete the previous version if present
    exec task_delete_project_vrs
        @project_id = @project_id,
        @project_vrs_id = @current_project_vrs_id
end

You can freely add scripts to automate even more actions in the post-synchronization phase.

tip

To gain more experience with the queries needed to automate particular actions, you can consult the database logs of the runtime components while performing manual tasks in the Intelligent Application Manager.

Automate Synchronization to IAM

See Automate deployment.

History

menu Deployment > Synchronization to IAM > tab History

The History tab page shows a list of all previous synchronizations.

Synchronization history