Creating and Activating Channels from CLI

This section contains instructions on how to use the command line interface (CLI) to create a channel, add locations, add actions and tables to the channel, create and run a refresh event, and activate replication in the channel. It also provides additional examples for configuring a HVR Agent with authentication, allowing anonymous access and access with user credentials.

For the purpose of this article, it is assumed that an HVR distribution is installed and a hub server is configured and running.

The article includes the following steps:

Create a source location
Create a target location
Create a channel
Add tables to the channel
Create and run a refresh event
Activate the channel
Additional configuration steps
- Configure HVR Agent allowing anonymous access
- Configure HVR Agent with username/password authentication

All HVR commands can be executed locally (on the same machine where the hub server is running) or remotely from another machine. When running the commands remotely, authorization is required. Otherwise, you can get the error F_JW0555: Refresh token invalid or expired.
To access a remote hub server with a specified user, run the hvrlogin command with -R and -u options. For example, hvrlogin -R http://myhost:12345 -u hvradmin.

Create a source location

This step includes creating a source location that connects directly to an Oracle database (without using an HVR Agent).

Create a JSON file (e.g. oracle.json) that defines a source location (e.g. oracle).

{
  "changes": [
    {
      "add_loc": {
        "props": {
          "Capture_Method": "DIRECT",
          "Class": "oracle",
          "Database_Password": "ora_pwd",
          "Database_User": "ora_user",
          "Oracle_Home": "/distr/oracle/1800",
          "Oracle_SID": "HVR1800"
         },
        "loc": "oracle"
      }
    }
  ]
}

Add the oracle location to the hub using the hvrdefinitionimport command.
```
hvrdefinitionimport -l oracle myhub oracle.json
```

Create a target location

This step includes creating a target location that connects directly to a PostgreSQL database (without using an HVR Agent).

Create a JSON file (e.g. postgres.json) that defines a target location (e.g. postgres).

{
  "changes": [
    {
      "add_loc": {
        "props": {
          "Class": "postgresql",
          "Database_Host": "localhost",
          "Database_Name": "pg_db",
          "Database_Password": "pg_pwd",
          "Database_Port": 11111,
          "Database_User": "pg_user"
         },
        "loc": "postgres"
      }
    }
  ]
}

Add the target location to the hub using the hvrdefinitionimport command.
```
hvrdefinitionimport -l postgres myhub postgres.json
```

Create a channel

This step includes:

creating channel mychn
adding location groups SOURCE and TARGET to the channel
adding locations oracle and postgres to the channel
defining action Capture for the SOURCE location group and action Integrate for the TARGET location group

Create a JSON file (e.g. mychn.json) that defines the channel.

{
  "changes": [
    {
      "add_channel": {
        "description": "Oracle to Postgres channel",
        "loc_groups": {
          "SOURCE": {
            "members": [
              "oracle"
            ]
          },
          "TARGET": {
            "members": [
              "postgres"
            ]
          }
        },
        "actions": [
          {
            "loc_scope": "SOURCE",
            "table_scope": "*",
            "type": "Capture",
            "params": {}
          },
          {
            "loc_scope": "TARGET",
            "table_scope": "*",
            "type": "Integrate",
            "params": {}
          }
        ],
        "channel": "mychn"
      }
    },
  ]
}

Add channel mychn to the hub using the hvrdefinitionimport command.
```
hvrdefinitionimport myhub mychn.json
```

Add tables to the channel

Add tables to the channel using the hvradapt command.

hvradapt -l oracle myhub mychn

Create and run a refresh event

This step assumes that no refresh has been done in the channel before. Run the hvrrefresh command to create a refresh event which, once started, will create the absent tables in the target location.

hvrrefresh -J integ -s -r oracle -l postgres -cbkr -gb -qrw myhub mychn

Activate the channel

Run the hvractivate command to start the refresh event from the previous step and activate replication in the channel. Once completed, the capture and integrate jobs will be running in the channel.

hvractivate -J cap -J refr -p2 myhub mychn

Additional configuration steps

The following examples demonstrate how to configure an HVR Agent for a remote location. In the first case, the authentication for HVR Agent is configured to allow anonymous access from a specific hub system. In the second case, an agent user is created with the AgentAdmin permissions that will be used to access the HVR Agent. For more information, see Configuring HVR Agent.

Configure HVR Agent allowing anonymous access

On the location where an HVR Agent is installed and configured, start the HVR Agent service by running the hvragentlistener command.
```
hvragentlistener -d <em>port_number</em>
```
Get the agent client public certificate by running the hvragentlistener command. Copy the value of the Agent_Client_Public_Certificate property from the command output.
```
hvrreposconfig -R http://myhost:12345
```

Modify the Only_From_Client_Public_Certificates agent property to allow anonymous authentication using the hvragentconfig command.

hvragentconfig -h myhub -r http://agenthost:11111 -S Anonymous_Access='{"allow":"true"}' Only_From_Client_Public_Certificates='{"http://myhost:12345":"<em>copied value of the Agent_Client_Public_Certificate</em>"}' Setup_Mode_Timed_Until=

Create a JSON file (e.g. sqlserver.json) that defines the location.

{
  "changes": [
    {
      "add_loc": {
        "props": {
          "Agent_Host": "myhost",
          "Agent_Port": 12345,
          "Capture_Method": "DIRECT",
          "Class": "sqlserver",
          "Database_Name": "mydatabase",
          "Database_Password": "mypasswd",
          "Database_User": "myuser",
          "Log_Truncater": "CAP_JOB",
          "SqlServer_Server": "LT-SERVER",
          "Supplemental_Logging": "CDCTAB_ARTICLE"
        },
        "loc": "sqlserver"
      }
    }
  ]
}

Run the hvrdefinitionimport command to add the sqlserver location to the hub.
```
hvrdefinitionimport -l sqlserver myhub sqlserver.json
```

Configure HVR Agent with username/password authentication

On the location where an HVR Agent is installed and configured, start the HVR Agent service using the hvragentlistener command. The first time the HVR Agent service is started on this port, it will be in setup mode.
```
hvragentlistener -d <em>port_number</em>
```
Run the hvragentuserconfig command to create an AgentAdmin user. You will be prompted to type a password for the user.
This step is optional, but having at least one AgentAdmin user gives the possibility to re-configure the HVR Agent when not in setup mode.
```
hvragentuserconfig -h myhub -r http://agenthost:11111 -S -c hvradmin
```
Create an agent user for a location. You will be prompted to type a password for the user. The authentication to the HVR Agent will be done by using a username and password, network traffic will be encrypted using the agent client public certificate from the hub.
```
hvragentuserconfig -h myhub -r http://agenthost:11111 -S -c agentuser
```

Modify the User_Access agent property to allow username/password authentication.

hvragentconfig -h myhub -r http://agenthost:11111 -S User_Access='{"agentuser":{"level":"AgentAdmin"}}' Setup_Mode_Timed_Until=

Create a JSON file (e.g. snowflake.json) that defines the location (e.g. snowflake).

{
  "changes": [
    {
      "add_loc": {
        "props": {
          "Agent_Host": "http://myhost",
          "Agent_Password": "mypasswd",
          "Agent_Port": 11111,
          "Agent_User": "agentuser",
          "Class": "snowflake",
          "Database_Host": "hvr_partner.west-europe.azure.snowflakecomputing.com",
          "Database_Name": "myhub",
          "Database_Password": "mypasswd",
          "Database_Port": 123,
          "Database_Schema": "hvrschema",
          "Database_User": "dbuser",
          "ODBC_Driver": "SnowflakeDSIIDriver",
          "Snowflake_Role": "public",
          "Snowflake_Warehouse": "hvrware"
        },
        "loc": "snowflake"
      }
    }
  ]
}

Run the hvrdefinitionimport command to add the snowflake location to the hub.
```
hvrdefinitionimport -l snowflake myhub snowflake.json
```