Set up the Data Integrity Agent

The Data Integrity Agent allows you to run your tests on a local or remote system.

To set up the Tosca Data Integrity Agent, perform the following actions:

• Download and install the Data Integrity Agent.

• Set up JDBC drivers.

• Customize the Data Integrity Agent.

• Run multiple Data Integrity Agents if needed.

• Secure the Data Integrity Agent if needed.

Prerequisites

Before you install the Data Integrity Agent, consider the following prerequisites:

• You can run the Data Integrity Agent on Windows or Unix/Linux.

• You must have Java Runtime Environment (JRE) version 1.8 or later.

• By default, the Data Integrity Agent uses port 80 for HTTP and port 443 for HTTPS.
  You can specify a different port after the installation (see chapter "Specify your own port").

Install the Data Integrity Agent

Install on Windows

To install the Data Integrity Agent on Windows, follow the steps below:

1. Download the installation package Tosca Data Integrity Agent Package <version> from the Tricentis Support Portal.

2. Double-click the installer file ToscaDataIntegrityAgentInstaller<version>.msi to install.

3. Follow the steps of the setup dialog to finish the installation.

4. To start the Data Integrity Agent, run the file Tricentis.DataIntegrity.Agent.exe.

Install on Linux

To install and start the Data Integrity Agent on Linux, follow the steps below:

1. Download the installation package Tosca Data Integrity Agent Package <version> from the Tricentis Support Portal.

2. Extract the content of the archive ToscaDataIntegrityAgentInstaller.<version>-Linux.x64.tar.
   There is no setup dialog in Linux. Where you extract the archive determines the <InstallationDirectory> in all further steps of the agent setup.

3. Start the agent with the command sudo ./Start_Tricentis.DataIntegrity.Agent.sh.

Tosca Data Integrity Agent Diagnostics

With Tosca Data Integrity Agent Diagnostics, you can help improve the agent by sending anonymous usage data to Tricentis. Diagnostics doesn't transmit any user data, it only tracks which features of the Data Integrity Agent you use.

By default, Diagnostics is enabled. If you don't want to send anonymous usage data, you can disable this setting. For information on our privacy policy, see the Tricentis privacy policy.

To disable Diagnostics, follow the steps below:

1. Go to C:\Program Files\TRICENTIS\Tricentis Tosca Data Integrity Agent on Windows, or <InstallationDirectory>/Agent/ on Linux.

2. Open the file appsettings.json.

3. Scroll to the Diagnostics section.

4. Set EnableApplicationInsights to false.

Set up JDBC drivers

The Data Integrity Agent connects to any data source via Java Database Connectivity (JDBC).

To do so, the Data Integrity Agent loads the required JDBC driver when it starts. The corresponding class name of the driver is specified in the TestStep (see chapter "JDBC connection").

To add a JDBC driver, follow the steps below:

1. Make sure that the Data Integrity Agent is not running.

2. Add the JAR files of the JDBC driver to the jdbcDrivers folder:

   • On Windows, this folder is located at C:\Program Files\TRICENTIS\Tricentis Tosca Data Integrity Agent.

   • On Linux, this folder is located at <InstallationDirectory>/Agent/.

3. Start the Data Integrity Agent to load the new JDBC driver.

Customize the Data Integrity Agent

You can change the default log directory, port, and certificate of the Data Integrity Agent. If you want to run multiple Data Integrity Agents on a single machine, you can assign a unique name to each agent.

Specify your own log directory

When you start the Data Integrity Agent, you can see the default log path in the command prompt.

If you want to specify your own log path, follow the steps below:

1. Go to C:\Program Files\TRICENTIS\Tricentis Tosca Data Integrity Agent on Windows, or <InstallationDirectory>/Agent/ on Linux.

2. Open the file appsettings.json.

3. Scroll to the Logs section.

4. Change the default path of Directory to the path that you want to use.

Specify your own port

If you want to specify your own port, follow the steps below:

1. Go to C:\Program Files\TRICENTIS\Tricentis Tosca Data Integrity Agent on Windows, or <InstallationDirectory>/Agent/ on Linux.

2. Open the file appsettings.json.

3. Change either the Http or the Https port number, depending on which protocol you use.

   If you don't want to use an HTTP or HTTPS port, delete the whole Endpoints section.

Specify your own certificate

Before you start, note that the Data Integrity Agent only supports certificates without password encryption and in PFK format using Public Key Cryptography Standard (PKCS) 8.

If you want to specify your own certificate, follow the steps below:

1. Go to C:\Program Files\TRICENTIS\Tricentis Tosca Data Integrity Agent on Windows, or <InstallationDirectory>/Agent/ on Linux.

2. Open the file appsettings.json.

3. Scroll to the Certificate section.

4. Change the default Path to the path of the certificate that you want to use.

Run multiple Data Integrity Agents

You can run multiple Data Integrity Agents on a single machine. Every instance of the agent has to run on a different port. Each agent creates logs and error reports that you can check on the status page or in the folder. The folder has the same name as the agent.

To easily identify your agents, you can give them unique names. If you don't name your agents, you can always identify them by the port number. Tosca DI automatically appends the agent's host and it's port to the agent name as described in the example below.

To specify an agent name, follow the steps below:

1. Go to C:\Program Files\TRICENTIS\Tricentis Tosca Data Integrity Agent on Windows, or <InstallationDirectory>/Agent/ on Linux.

2. Open the file appsettings.json.

3. Under Agent, change the default name Agent to the name that you want to use.

In this example, you give your Data Integrity Agent a unique name: You change the default name Agent to TestAgent. The name of the host machine where the Data Integrity Agent runs is TRI-NB001. The HTTPS port you use is 443. Tosca DI automatically appends the name of host and the port. The full name of your agent is TestAgent_TRI-NB001_443.

Secure the Data Integrity Agent

If you have security concerns, for example if the agent is exposed on the internet or running on a remote machine, you can secure your Data Integrity Agent. In this case, only authenticated clients can communicate with it.

To do so, you have to configure the Data Integrity Agent and Tosca Commander to point to the same authentication service.

Prerequisites

Before you can configure security, make sure that you meet the following requirements:

• You have Tosca Server installed.

• You have set up Tricentis Authentication Service and Tricentis User Administration.

  Tricentis Authentication Service provides OAuth 2.0 as protocol for authorization.

  Tricentis User Administration allows users that want to communicate with the agent to create a personal access token. They have to provide this token from within Tosca Commander.

• If you want to use Tricentis Service Discovery to get the endpoint of your authentication service, make sure it's set up.

  Alternatively, you can configure the authentication endpoint directly without Service Discovery.

Configure the Data Integrity Agent

To configure security in the Data Integrity Agent, follow the steps below:

1. Go to C:\Program Files\TRICENTIS\Tricentis Tosca Data Integrity Agent on Windows, or <InstallationDirectory>/Agent/ on Linux.

2. Open the file appsettings.json.

3. Scroll to the Security section.

4. To enable security, set Deactivate to false.

5. Scroll to the Discovery section.

6. Change the ServiceDiscovery endpoint to the endpoint of your Tricentis Authentication Service.

   Alternatively, you can enter the endpoint of your authentication service as IssuerUri and set Discovery->Enabled to false.

The Data Integrity Agent is now set up to retrieve the Tricentis Authentication Service certificate and store it for the authentication of API calls.

Configure Tosca Commander

To configure security in Tosca Commander, follow the steps below:

1. Go to Settings->Tricentis Services and specify a valid endpoint address for Tricentis Services.

2. Open Tricentis User Administration and create a personal access token for the Data Integrity Agent.
   Copy and store the token to use it later.

3. In Tosca Commander, go to the object that you want the agent to run, such as a TestCase folder or TestCase.

4. Switch to the Test configuration tab.

5. Create a test configuration parameter (TCP) named DataIntegrityAccessToken.

6. As value of the TCP, enter the personal access token that you created in step 2.

You can't use the TCP DataIntegrityAccessToken in a reusable TestStepBlock. Authentication only works if you specify it directly in the TestStep or any parent level.

Tosca Commander is now set up to use the personal access token to retrieve a bearer token from Tricentis Authentication Service during test execution. It then sends the bearer token to the Data Integrity Agent. If the agent validates the bearer token, test execution can proceed.

Next steps

Now that you've set up the Data Integrity Agent, you can configure your Module depending on which tests you want to run:

• For Reconciliation tests, configure the Preview: Row by Row Comparison (DI Agent) Module .

• For database tests, configure the Preview: DB Expert module (DI Agent).