This document describes the requirements for the Topaz for Total Test and MongoDB Repository Server configuration. It is intended for people responsible for IT infrastructure.

Since the Topaz for Total Test Repository Server (Repository Server) is installed as part of CES, only additional installation of MongoDB is required to set up and run Repository Server.

The Topaz for Total Test Functional Test Eclipse plug-in is part of the Topaz for Total Test feature of the Topaz Workbench and its installation is described in the Topaz Workbench Installation and Configuration space.

The initial installation should be made as simple as possible. Therefore, it is recommended that MongoDB and Topaz for Total Test Repository Server be installed to the same machine and not enable authorization or SSL for the MongoDB communication. This is the simplest possible setup, which is often enough for a pilot project where time used on setup and configuration should be minimized. For installation and supported platforms for installation of the MongoDB, refer to the MongoDB website.

Topaz for Total Test Repository Server communication architecture

The Communication between Total Test clients, the Topaz for Total Test Repository Server and the z/OS Agent installed at the mainframe (part of the ECC installation on z/OS) is illustrated in the following figure. All communication channels can be configured to use encryption.

Hardware and software requirements

The Topaz for Total Test Repository Server is installed as part of CES, and the hardware and software requirements are described in Software and hardware requirements. The MongoDB server hardware depends on how many users that use it simultaneously, how many test scenarios and components that are put into the repository, and how many test scenarios and test suites that are to be scheduled. The server can be either a physical or a virtual machine. The requirements identified below are recommended, although smaller configurations and older versions of the required software and operating systems may work as well.

The Repository Server and the MongoDB server can be installed on the same machine or on different machines, and the MongoDB installation can consist of several servers in a replicate set for replicating data and have failover possibilities.

For more information on MongoDB, refer to the following sections:

• Installing-the-MongoDB-for-use-with-Topaz-for-Total-Test-Repository-Server.
• Configuring-MongoDB-for-use-with-Topaz-for-Total-Test-Repository-Server.

Minimum hardware and software requirements for MongoDB Server

Upgrading from version 4.x or 19.03.x to 20.06.x

The Repository Server will be upgraded as part of the CES upgrade.

There is no need for upgrading the MongoDB when installing a new Repository Server. Leave it as is and point to the current MongoDB server address when prompted by the CES installation process or in the application.properties file for the Repository server found in the CES installation directory.

If an upgrade of the MongoDB is required, refer to the MongoDB documentation.

Upgrading to 20.5 or Greater from Previous Releases

If you are upgrading to CES 20.5 or greater from a previous release, and have already setup the Topaz for Total Test repository server, then you must add all users to CES, and assign the Total Test admin or Total Test user role after upgrading. This is needed when CES has authentication enabled, and it is needed for CES authentication modes. To add a user and assign roles, navigate to the Administration->Security->Users tab and click Add in the Users table. Enter the User ID and assign the necessary roles to the user. For additional information, refer to the CES documentation regarding Security.

Total Test with LDAP integration is now set up within CES. Be aware that CES currently does not yet support the use of LDAP groups for mapping to user roles. As well, it does not yet support using a system user for binding and searching LDAP. These are features are planned for the 20.6.1 release.

When using LDAP without security, all users accessing Total Test are known as Guest and, therefore, unable to see updates to test artifacts committed by actual users.

Verify installation

After installing and starting the Topaz for Total Test Repository Server, you must verify that it has started. Open the installed CES and, from the CES home page, click the Topaz for Total Test product card. You should see Total Test dashboard.

A bootstrapping admin user is automatically created at first startup, when no other users have been created. Login with the userid: admin, and the password: 123456.

Set Up Total Test Users and Assign Roles

When CES is set up with authentication enabled, CES users must be added in order to access CES. To use Total Test, a user must be assigned to either the Total Test user role and/or the Total Test Admin role assigned. Refer to Security

Configuring the Topaz for Total Test Repository Server

The server must be updated with a valid server CES license, an administration user must be created, and the bootstrapping user should be deleted or at least have its password changed. Furthermore, the server must be configured with customer specific connections and environments that are used to access the mainframe.

User Permissions on mainframe

All users using Functional Test must have the RACF permissions setup at the mainframe in order to execute programs on the mainframe:

1. A valid userid/password at the mainframe.
2. Permission to access the USS file system and have read/write access to the Functional Test user home directory defined by Connections in the repository. Default path is /var/xatester.
3. Permissions to access the Functional Test sample datasets. This should point to the ECC sample library hlq.SLCXCNTL.

Configure Scheduling Server

If you have multiple CES servers connected to the same MongoDB database, and use the servers for load balancing, you must specify which servers to use to periodically clean up the database. You must set up either the IP address or the domain name of the server in the Scheduling Server option. If the field is left empty or equal to localhost, then all CES servers will perform the clean up job once per day.

Configure data cleanup intervals

Over time test reports, files and audit logs will fill up the repository. Once a day, Functional Test looks for old items to delete. You can configure after how many days to delete these items. This is configured in the same place as the LDAP integration in previous section. These setting can be changed on the bottom of the page. It is also possible to select if backup versions should automatically be created when users make updating operations.

Set up JDBC Drivers for the Repository Server

If you plan to upload test scenarios that contain SQL Select steps from Topaz to the server and execute test scenarios from the server you will need to copy your Db2 JDBC driver jar file and Db2 license jar file to the CES server. Place them into folder:

• <CES data installation dir>\data\totaltest\jdbcdrivers (Windows default location: 
  C:\ProgramData\Compuware\CES\data)
• <CES data installation dir>/data/totaltest/jdbcdrivers (Linux)
• <CES data installation dir>/data/totaltest/jdbcdrivers (z/OS UNIX)

You will have to restart CES after copying the jar files.

Configuring connections

The Repository Server needs to be configured with information about customer specific environments and connections. An admin user configures these in the web front-end. The information is used by the server and the Eclipse client when invoking tests. A connection specifies the location and other properties of the host, while an environment uses a connection and specifies additional information such as Batch and CICS and default Db2 settings.

To add a new connection:

1. Login as an admin user and navigate to the Configuration > Connections section.
2. Click Add to the left and fill in the values on the right side.
3. Enter a label. Optionally enter an id, set the IP address of the server, and select operating system.
4. When the operating system is z/OS, set the port of the z/OS Agent (HCI port).
5. Select socket communication type is HCI or HCI-Encrypted. Only select different values if the z/OS Agent is version 1.4.1 or 2.0.0. It is recommended to use HCI-Encrypted for production setup.
6. Optionally set the high-level qualifier where Functional Test is installed. If left empty, then the default installation dataset will be used. This value is only used when testing whether a Connection has been setup correctly.
7. If the z/OS Agent is installed in an older version, then choose the version number instead of being NEWEST.
8. Setup an MQ provider—normally always Websphere MQ—and setup the default port for the queuemanager for executing CICS programs.
9. Database properties are used for JDBC connection from test scenarios that use SQL inside the test scenario. You have to specify the JDBC driver, the connection URL and a default data-base name. The database URI should not include the database name. Instead enter ${data-base} in the URI where the database name should be. Individual test cases can override the default database name and Functional Test will substitute the database name at runtime.
   1. For Db2 on z/OS, the uri is in the form jdbc:The following configuration parameters are only for FTP and FTPS:db2://<ip>:<port>/${database} and the driver is com.ibm.db2.jcc.DB2Driver.
   2. When Db2 is installed on z/OS, the database name is the Db2 location name that is de-fined during installation. All characters in Db2 location name must be uppercase characters. The location name can be found by executing the SQL statement at the server: SELECT CURRENT SERVER FROM SYSIBM.SYSDUMMY1.

10. The Dynamic JCL section allows you to specify, for the selected connection, the JCL jobcard and skeleton information and the TTTRunner load library to be used when executing Unit (Virtualized) tests using the Execution Context dialog when the Use Repository server option is set.

    This information is similar to the TotalTestConfiguration Project as described in topic "Using Functional Test without the Repository Server" in the Topaz Workbench Topaz for Total Test User Guide.

    1. Specify a Job card to be used for elements that don’t include a job card. If the JCL skeleton includes a job card, than that will be used. Here is a sample: 

       //${userId} JOB ('${accountingInfo}'),'NAME',NOTIFY=&SYSUID,CLASS=A,
       //        MSGCLASS=R,REGION=0M
    2. Specify the TTTRunner loadlib (hlq.SLCXLOAD) needed to execute Unit test.

    3. Specify the TTT Runner JCL needed to execute Unit test. You may copy the information from the TTTRUNNER.jcl created in the TotalTestConfiguration Project and modify it for the selected connection.

       The Job card and TTT Runner JCL entries don’t require admin privileges.

11. The optional code coverage daemon can be the host itself or another server and is only used when tests are executed with the Code Coverage option enabled. The Collector file directory must be the same directory that the daemon is started with and it must be accessible through FTP in order for Functional Test to retrieve the code coverage files. It is possible to use the Repository Server to host the collector daemon. In this case, Topaz for Total Test can be setup to get the files through HTTP, and the address for the Repository Server must be set.

    Important! The IBM Debug tool cannot resolve symbolic links, requiring you to write the fully qualified path starting with the z/OS system ID. For example, /XA00/var/xatester/CC.

12. When complete, click Create.
13. Select the connection and click Test Connection.

The following configuration parameters are only for FTP and FTPS. This is necessary only if you are using the old z/OS Agent for Xatester.

1. If HCI or HCI-Encrypted is not selected as Communication Type, when File transferring is set to FTP by default. This can be changed to FTPS. Optionally, set the code page and encoding used at the host. Also set the USS home directory to use by Functional Test for transferring files. Default value is /var/xatester and must be the same value as the z/OS Agent is configured with.
2. Enter a Service account user ID for FTP if automatic cleanup of old files should be enabled. You will be asked about password when creating the connection. The password will be strongly encrypted and saved in the repository. The password can be changed later on by clicking the "Set password" button at the Service account userid field.
3. If users are not allowed to use FTP, then select Use Service account for all FTP access. Then the service account credentials will be used for uploading and downloading files for test cases and the users do not need permission for FTP.
4. Set the Max request size. Default is 4096. This value is used at runtime to ensure that executing test cases can be handled at the z/OS Agent. This value will also be checked when testing the connection, and the correct value can be found here.

Testing a connection

The best way to ensure that an installation is setup correctly is to use the Test Connection button. This will check nearly all settings for executing and testing Batch programs. Click Test Connection, enter your host credentials, and wait some seconds to see the test report. If any errors occur, there is a description of the error that should guide you in what is wrong with the setup.

The first time the Test Connection is run, it will automatically define a Batch environment and add the XARISCAL demo program to the repository, and then also try to execute it in the last step of the tests.

Configuring environments

To add a new environment:

1. Navigate to Configuration > Environments.
2. Click Add, and enter the information in the Environment Details panel.
3. Choose the environment: should be Batch or CICS. Depending on what is chosen, different options become available.
4. For both Batch and CICS, default Db2 plan and ID can be entered, as well as the call mechanism for CICS, the CICS applid. All these values are default values for components in the environment. The default values can be overridden by a system and by the component itself.
5. You can select an existing environment and use those values to create a new one. Click the Edit toggle to go to edit mode. And then, click either Update to update an existing adapter or Create new to create a new one.

Setting up systems

A system specifies the default source and load libraries, and also the Db2 settings for a group of components and optionally the JCL that should be used for all components. It also specifies a number of valid environments to select. A component can refer to a system, and thus, inherit the definitions from the system.

Complete the following steps to setup a system that represents the Functional Test sample programs.

1. Navigate to Component repository > Systems.
2. Click Add, and enter Functional Test samples as label.
3. Select a Batch environment.
4. Fill in hlq.SLCXLOAD for main load library and hlq.SLCXCNTL for main source library, where hlq should be replaced with high level qualifier of the z/OS Agent.
5. Click Create New.

Adding and executing a component

The Topaz for Total Test Functional Test z/OS installation comes with a number of sample programs. The XARISCAL program is a simple program for testing and verifying that the configuration is functioning as expected.

Complete the following steps to add a component to the repository:

1. Navigate to Component repository > Components.
2. Click Add.
3. In the Component field, enter XARISCAL.
4. Select the Functional Test sample system just created. This will automatically select the environment allowed for the system.
5. In the Data structure area, click Extract data definition, then click OK in the popup dialog.
6. Accept the default settings.
7. Verify that the program looks like the screens presented below in Connection Details. The Environment details screen will be different.
8. Click Create.
9. To execute the component, click Goto execute.

Checklist

Check that you have set up all of the following tasks:

1. Installed MongoDB and optionally configured authentication and SSL.
2. Installed Topaz for Total Test Repository Server as part of CES.
3. Installed server certificate from MongoDB server.
4. Set up connections and environments.
5. Added a component.

6. Executed a component.