TDM Installation and Initial Configuration

This document describes the installation guidelines and the initial configuration activities requires for a new TDM installation or an upgrade of a TDM 7.x version to the current version.

TDM Installation - Prerequisites

Linux Installation

The following components must be installed as a prerequisite:

  • Fabric Server - Fabric 7.1 and above. see here.
  • PostgreSQL DB - The TDM DB tables are created on a PostgreSQL DB. PostgreSQL v9.6 or v13 versions are certified. For more details, see here.

Docker Installation

Click here to open the TDM 8.0 Docker Installation document.

Import the TDM Library

Both TDM layers - backend and frontend - are included in the TDM library from v7.6 onwards. Download the TDM Library from the download links, import and deploy it.

Click here for instructions how to import and deploy the TDM Library.

TDM Web Application

Import the updated TDM LU to Fabric project and deploy it to Fabric. Use the Import All option to import the TDM Portal (self-service) code (stored in the web sub folder) into the TDM LU. The deployment of the TDM LU also deploys the TDM Portal to Fabric and adds it to the web applications in your Fabric web framework.

Click for more information about Fabric Web Framework.

Create the TDM PostgreSQL DB (in case of new installation)

  • From TDM 7.6 onwards TDM creates of the TDM DB objects by the TDM LU's deploy flow:

    • Creates the TDM DB tables, sequences, views and functions.

    Notes:

    • You must set the BUILD_TDMDB Global to true and the POSTGRESQL_ADMIN interface to be active to create the TDM DB by the TDM deploy flow.
    • You must create the TDM database and user in advance. The database and user names must be aligned with the TDM interface. You can run the TDMDBCreateRoleAndDB flow (located in the TDM LU) to create the TDMDB database and tdm user (role) in the postgreSQL DB.

Upgrade the TDM PostgreSQL DB (if not a new installation)

  • Soft deploy the TDM LU to Fabric debug server. Before the deploy, verify that the TDM interface is updated with the TDM DB connection details.

  • Run the RunTDMDBUpgradeScripts flow. Populate the current version and the target version input parameters. Set the target version parameter to 8.0. For example:

    • CURRENT_TDM_VERSION = 7.6.
    • TARGET_TDM_VERSION = 8.0.
  • Note that the version’s list is set in TDMDBUpgradeScripts actor (imported from the TDM Library).

Create K2masking Keyspace in Cassandra

The k2masking keyspace is needed for a TDM implementation in order to support masking or sequence handling. The k2masking keyspace is automatically created by the the TDM LU's deploy.flow upon the deployment of the TDM LU to Fabric. Alternatively, you can run the masking-create-cache-table.flow from the library of Broadway examples or run the create_masking_cache_table.sql of the TDM Library to create the K2masking keyspace if needed.

Click for more information about sequence handling.

Add Permission Groups Mapping to the TDM

The TDM Portal application is pre-integrated with Fabric Web Framework. The user logs in to the Fabric Web Framework and Fabric authenticates the user. The TDM Portal gets the user id and the user's Fabric roles from the user's session and identifies the user type (Permission Group) by their Fabric roles.

The mapping of each Fabric role to a TDM Permission Group is done by the Permission Groups Mapping TDM window and is kept in permission_groups_mapping TDM DB table.

After installing the TDM, the admin user must log in to the TDM Portal, open the Permission Groups Mapping window and define the Permission Group mapping of each user's group (= Fabric role). This process is done in order to enable the TDM users to work properly on the TDM Portal, based on their Permission Groups.

Update the TDM APIDOC (Optional)

The TDM APIDOC html file is located in the TDM folder (imported from the TDM library) in Fabric project:

\TDM\web\TDM\apidoc

The TDM APIDOC describes all the Web Services in the Fabric project including the TDM Web Services imported from the TDM Library.

The below steps should be followed if a new APIDOC is generated to include project custom APIs:

  1. Import the following objects from the updated TDM library:

    • TDM_APIDOC_JSON interface (local file interface)- this interface contains the location of the TDM APIDOC JSON file.
    • buildTdmApiJSON Broadway flow.
  2. Edit the TDM_APIDOC_JSON interface or define the TDM_APIDOC directory under C:\k2view\ local directory.

  3. Deploy Fabric project's Web Services to the local debug server.

  4. Edit the buildTdmApiJSON flow: edit the port in the path input parameter of the HttpJson actor.

  5. Run buildTdmApiJSON Broadway flow to create a JSON under the local directory of TDM_APIDOC_JSON interface. Populate the current TDM version in the TDM Version input parameter. For example, TDM 8.0. This version is added to the generated APIDOC.

  6. Open the Swagger editor using the following URL: https://editor.swagger.io/.

  7. In the Swagger Editor:

    • Click File > Import File and select the TDM_APIDOC.json generated by the Broadway flow.
    • Click Generate Client > html to download a zip file with the HTML file to your working station.
  8. Open the TDM folder in the Fabric project: right-click the TDM LU > Open Folder. A File Explorer window opens.

  9. Navigate the File Explorer window and move to \TDM\web\TDM\apidoc sub-directory.

  10. Extract the zip file and copy the generated HTML file under the \TDM\web\TDM\apidoc sub-directory.

  11. Open the TDM Portal and click the API Doc tab. Verify that the API doc is displayed properly.

TDM Installation and Initial Configuration

This document describes the installation guidelines and the initial configuration activities requires for a new TDM installation or an upgrade of a TDM 7.x version to the current version.

TDM Installation - Prerequisites

Linux Installation

The following components must be installed as a prerequisite:

  • Fabric Server - Fabric 7.1 and above. see here.
  • PostgreSQL DB - The TDM DB tables are created on a PostgreSQL DB. PostgreSQL v9.6 or v13 versions are certified. For more details, see here.

Docker Installation

Click here to open the TDM 8.0 Docker Installation document.

Import the TDM Library

Both TDM layers - backend and frontend - are included in the TDM library from v7.6 onwards. Download the TDM Library from the download links, import and deploy it.

Click here for instructions how to import and deploy the TDM Library.

TDM Web Application

Import the updated TDM LU to Fabric project and deploy it to Fabric. Use the Import All option to import the TDM Portal (self-service) code (stored in the web sub folder) into the TDM LU. The deployment of the TDM LU also deploys the TDM Portal to Fabric and adds it to the web applications in your Fabric web framework.

Click for more information about Fabric Web Framework.

Create the TDM PostgreSQL DB (in case of new installation)

  • From TDM 7.6 onwards TDM creates of the TDM DB objects by the TDM LU's deploy flow:

    • Creates the TDM DB tables, sequences, views and functions.

    Notes:

    • You must set the BUILD_TDMDB Global to true and the POSTGRESQL_ADMIN interface to be active to create the TDM DB by the TDM deploy flow.
    • You must create the TDM database and user in advance. The database and user names must be aligned with the TDM interface. You can run the TDMDBCreateRoleAndDB flow (located in the TDM LU) to create the TDMDB database and tdm user (role) in the postgreSQL DB.

Upgrade the TDM PostgreSQL DB (if not a new installation)

  • Soft deploy the TDM LU to Fabric debug server. Before the deploy, verify that the TDM interface is updated with the TDM DB connection details.

  • Run the RunTDMDBUpgradeScripts flow. Populate the current version and the target version input parameters. Set the target version parameter to 8.0. For example:

    • CURRENT_TDM_VERSION = 7.6.
    • TARGET_TDM_VERSION = 8.0.
  • Note that the version’s list is set in TDMDBUpgradeScripts actor (imported from the TDM Library).

Create K2masking Keyspace in Cassandra

The k2masking keyspace is needed for a TDM implementation in order to support masking or sequence handling. The k2masking keyspace is automatically created by the the TDM LU's deploy.flow upon the deployment of the TDM LU to Fabric. Alternatively, you can run the masking-create-cache-table.flow from the library of Broadway examples or run the create_masking_cache_table.sql of the TDM Library to create the K2masking keyspace if needed.

Click for more information about sequence handling.

Add Permission Groups Mapping to the TDM

The TDM Portal application is pre-integrated with Fabric Web Framework. The user logs in to the Fabric Web Framework and Fabric authenticates the user. The TDM Portal gets the user id and the user's Fabric roles from the user's session and identifies the user type (Permission Group) by their Fabric roles.

The mapping of each Fabric role to a TDM Permission Group is done by the Permission Groups Mapping TDM window and is kept in permission_groups_mapping TDM DB table.

After installing the TDM, the admin user must log in to the TDM Portal, open the Permission Groups Mapping window and define the Permission Group mapping of each user's group (= Fabric role). This process is done in order to enable the TDM users to work properly on the TDM Portal, based on their Permission Groups.

Update the TDM APIDOC (Optional)

The TDM APIDOC html file is located in the TDM folder (imported from the TDM library) in Fabric project:

\TDM\web\TDM\apidoc

The TDM APIDOC describes all the Web Services in the Fabric project including the TDM Web Services imported from the TDM Library.

The below steps should be followed if a new APIDOC is generated to include project custom APIs:

  1. Import the following objects from the updated TDM library:

    • TDM_APIDOC_JSON interface (local file interface)- this interface contains the location of the TDM APIDOC JSON file.
    • buildTdmApiJSON Broadway flow.
  2. Edit the TDM_APIDOC_JSON interface or define the TDM_APIDOC directory under C:\k2view\ local directory.

  3. Deploy Fabric project's Web Services to the local debug server.

  4. Edit the buildTdmApiJSON flow: edit the port in the path input parameter of the HttpJson actor.

  5. Run buildTdmApiJSON Broadway flow to create a JSON under the local directory of TDM_APIDOC_JSON interface. Populate the current TDM version in the TDM Version input parameter. For example, TDM 8.0. This version is added to the generated APIDOC.

  6. Open the Swagger editor using the following URL: https://editor.swagger.io/.

  7. In the Swagger Editor:

    • Click File > Import File and select the TDM_APIDOC.json generated by the Broadway flow.
    • Click Generate Client > html to download a zip file with the HTML file to your working station.
  8. Open the TDM folder in the Fabric project: right-click the TDM LU > Open Folder. A File Explorer window opens.

  9. Navigate the File Explorer window and move to \TDM\web\TDM\apidoc sub-directory.

  10. Extract the zip file and copy the generated HTML file under the \TDM\web\TDM\apidoc sub-directory.

  11. Open the TDM Portal and click the API Doc tab. Verify that the API doc is displayed properly.