Skip to main content

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 IAM, together with the authorization settings and user preferences, it is necessary to synchronize your model to IAM.

A branch 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 branch to IAM, two tasks are available:

note

You can also synchronize the model for its state at a certain point in time. For more information, see synchronize an older model version.

tab Synchronization 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 task Synchronize to IAM Synchronize to IAM. The model and branch are preselected.

  2. Optional: you can synchronize your product to IAM with its own branch name. Select the checkbox Different branch name and enter a name in the field As branch. For example, your branch in the Software Factory is called 'MAIN' but is synchronized as 'ACC'.

note

If you synchronize your branch to IAM with a different branch name, you can view its original branch name in IAM. You can do this in menu Models > Model overview > tab Branches > tab Form.

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

  2. Recommended: to verify your model while synchronizing, select the checkbox Verify synchronization.

  3. In the field Note, you can add the reason for synchronizing. The reason is also visible in the History tab.

  4. Click Execute.

On synchronization, both tasks first check for unsolved validation messages and if any roles are present in the branch 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 Synchronization to IAM

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 hide or press ALT+F.

Synchronization to storage​

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

note

To synchronize an older model version, first create a branch from that particular moment in time and then synchronize that branch.

The file storage location for this process needs to be configured in IAM: menu Authorization > Applications > tab General settings > tab File storage locations. 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 task Synchronize to storage Synchronize to storage.

  2. Optional: you can synchronize your product to IAM with its own branch name. Select the checkbox Different branch name and enter a name in the field As branch. For example, your branch in the Software Factory is called 'MAIN' but is synchronized as 'ACC'.

note

If you synchronize your branch to IAM with a different branch name, you can view its original branch name in IAM. You can do this in menu Models > Model overview > tab Branches > tab Form.

  1. Recommended: to verify your model while synchronizing, select the checkbox Verify synchronization.

  2. In the field Note, you can add the reason for synchronizing. The reason is also visible in the History tab.

  3. Click 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 Copy copy to clipboard the path and paste it at the location where the files are available, for example, in the File Explorer or an Amazon S3 bucket.

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 hide or press ALT+F.

Verify synchronization​

menu Deployment > Synchronization to IAM > tab Synchronization

menu Deployment > Deployment package > tab Deployment package

Because the model is not locked, it can be changed during 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:

  • Run - Synchronization to IAM.
  • Write to storage - Synchronization to storage.
  • Run - Creating a deployment package.

Because of these additional checks, selecting this option will increase the synchronization time.

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

"The model has changed during synchronization of INSIGHTS branch 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 branch contains any modules, a list of available modules will be shown. By selecting or clearing the modules, you can include or exclude them from synchronization.

The Roles tab shows all roles and to which modules they belong. A checkbox before the role indicates if it is included in the synchronization.

note
  • Any roles that are not assigned to a module will always be deployed by default.
  • Clearing modules that were previously deployed will remove them from your application during the next deployment.

Modules Selected modules

Post synchronization code​

menu Deployment > Synchronization to IAM > tab Post synchronization code

It is possible to add arbitrary SQL code to a synchronization run. This code will be executed on IAM after the synchronization to IAM has been finished.

This code can, for example, respond to the tag mechanism in IAM in order to control what the code affects. Tags are available for users, user groups, tenants and applications. See: User tags, User group tags, Tenant tags, or Applications tags.

The current model_id and branch_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.

Post synchronization code 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 branch to create or replace an application.

Writing these scripts is similar to dynamic model scripts, but applies to the structure of IAM 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, @model_id and @branch_id, to refer to the model and branch 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 synchronizing to IAM.

Script: Create a new application​

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 model currently being deployed:

declare @current_gui_appl_id id
declare @current_branch_id branch_id

select top 1
   @current_gui_appl_id = gui_appl_id,
   @current_branch_id = branch_id
from gui_appl
where model_id = @model_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_branch_id = @branch_id
begin
    -- The existing model 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_model_id = @model_id,
        @from_branch_id = @current_branch_id,
        @from_gui_appl_id = @current_gui_appl_id,
        @to_model_id = @model_id,
        @to_branch_id = @branch_id,
        @insert_gui_appl = 1,
        @to_gui_appl_id = null,
        @copy_gui_appl_settings = 1,   
        @copy_gui_appl_transl = 1,
        @copy_gui_appl_iam_process_flow = 1,
        @copy_gui_appl_ini_parmtr_value = 1,
        @copy_gui_appl_web_connection = 1,
        @copy_gui_appl_email_provider = 1,
        @copy_gui_appl_file_storage = 1,
        @copy_gui_appl_oauth_server = 1,
        @copy_gui_appl_gai_provider = 1,
        @copy_gui_appl_printer = 1,
        @copy_gui_appl_tag = 1,
        @copy_deployment_module_settings = 1,
        @copy_gui_appl_authorization = 1,
        @copy_gui_appl_authorization_public = 1,
        @copy_pool_user_credentials = 1,
        @copy_usr_pref = 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 model_id  = @model_id
      and branch_id = @branch_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 model
    -- Create a new application
    insert into gui_appl
    (
        model_id,
        branch_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 
        @model_id,
        @branch_id,
        @model_id + '/' + @branch_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, branch p
    where s.server_id  = @server
      and p.model_id   = @model_id
      and p.branch_id  = @branch_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, execute 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
    @model_id = @model_id, 
    @branch_id = @branch_id, 
    @gui_appl_id = @gui_appl_id,
    @tenant_id = @default_tenant_id

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

if @current_branch_id is not null and @current_branch_id = @branch_id
begin
    -- Delete the previous version if present
    exec task_delete_branch
        @model_id = @model_id,
        @branch_id = @current_branch_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 IAM.

Synchronize an older model version​

In some circumstances, you may want to synchronize an older version of your model with IAM. For example, due to new features that have been added to your current model, which should not yet be deployed to your Production environment.

To synchronize an older model version to IAM:

  1. Create a new branch based on the desired point in time or a specific model version.
  2. Switch to the newly created branch if you have not already done this.
  3. Synchronize to IAM or to storage as usual. If you do not want to overwrite the IAM application based on your actual model version, synchronize your product with its own branch name.

Automate Synchronization to IAM​

See Automate deployment.

View the synchronization history​

menu Deployment > Synchronization to IAM > tab Synchronization > tab History

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

Synchronization history Synchronization history

Was this article helpful?