hvrdefinitionimport

Usage

hvrdefinitionimport [-Rurl] [-cchn] [-lloc] [-ttbl] hub impjsonfile

Description

Command hvrdefinitionimport loads definition changes to a hub. Definition change is a change to a HVR object on a hub, such as a channel, location, location group, table, table group, action. For example, a definition change may include adding/modifying/replacing/deleting a channel (location, location group, table, table group, action). The definition change is supplied in a JSON file (impjsonfile). The JSON file may include one or more definition changes.

The JSON file can either be created using command hvrdefinitionexport or it can be compiled manually provided it conforms to the JSON prototypes used in HVR.

For example, the following is a sample JSON file exported using command hvrdefinitionexport that adds tables to a channel (the 'add_tables' definition change):

'Add tables' definition change

{
  "export_header": {
      "creator": "icuser",
      "hvr_version": "6.0.1/2",
      "api_version": "v0",
      "description": "Exported with UI",
      "tstamp": "2021-03-06T14:04:33.886Z",
      "original_hub": "hvr_hub",
      "type": "definition_changes"
  },
  "changes": [
   {
       "add_tables": {
           "channel": "test_test",
           "tables": {
               "warehouse": {
               "base_name": "warehouse",
               "table_group": "GENERAL",
               "cols": {
                   "w_id": {
                       "sequence": 1,
                       "key": 1,
                       "data_type": "number",
                       "attributes": {
                           "prec": 4,
                           "nullable": false
                       }
                   },
                   "w_ytd": {
                       "sequence": 2,
                       "data_type": "number",
                       "attributes": {
                           "prec": 12,
                           "scale": 2,
                           "nullable": true
                       }
                   },
                   "w_name": {
                       "sequence": 4,
                       "data_type": "varchar2",
                       "attributes": {
                           "bytelen": 10,
                           "charlen": 10,
                           "encoding": "UTF-8",
                           "nullable": true
                       }
                    },
                 }
              }
           }
        }
     }
  ]
}

The following is a manually compiled JSON file (based on the HVR JSON prototypes) that modifies location properties (the 'modify_loc_props' definition change):

'Modify location properties' definition change

{ changes : [
    {
        modify_loc_props : {
            loc : myloc
            props : {
                Class : oracle
                Oracle_Home : /oracle/1220
                Capture_Method : DIRECT
                Oracle_SID : HVR1220
                Description : Oracle source location
            }
         }
      }
   ]
}

Command hvrdefinitionimport corresponds to the Import Channel Definitions, Import Location Definitions, Import Table Definitions, and Import Definition Changes options in the User Interface.

Options

This section describes the options available for command hvrdefinitionimport.

Parameter	Description
`-apolicy`	Define rules for import. If the import contains a change that adds an object (such as a location or a channel) and that object already exists, the `policy` defines how to proceed. Valid values for the `policy` are: ABORT: Abort the import with an error. REPLACE: Replace the existing object with the new one from the import. RENAME`default`: Add the new object with a different name. The new name is derived from the original name with an ascending number appended, such as channel1, channel2, etc.
`-Aact_policy` `Since v6.1.0/26`	Define rules for action(s) when replacing a location or a channel during import. Valid values for the `act_policy` are: MERGE: Add the new action(s) from the import to the existing ones. REPLACE`default`: Replace all existing action(s) with the new one(s) from the import. If the import does not specify any actions for the replaced location or channel, the existing actions will not be changed.
`-cchn`	Import definition change(s) in channel `chn`. Value `chn` will override the channel name if specified in the definition change file `impjsonfile`. This option can only be applied to the child objects of channels (e.g. tables or location groups). Definition changes like add_table will be imported to channel chn, even if they were originally exported from a differently named channel. The option cannot be used to change the channel name of the add_channel definition change.
`-k`	Retain the old members of a location group. If the import contains a location group that already exists, this option will keep the old members of that location group and merge them with the new members specified in the import. If this option is not specified, the old members will be replaced.
`-L`	Promote the action to a location group if the import contains a channel action defined for a location that does not exist. A new location group will be created in this case. And, the name of this location group will consist the original location name in uppercase with the '_GROUP' suffix. If this option is not specified and if the import contains a non-existing channel action, the action will be discarded.
`-lloc`	Import definition change(s) to location `loc`. Value loc will override the location name if specified in the definition change file `impjsonfile`. This option can only be applied to the child objects of locations (e.g. location properties). Definition changes like add_loc_props will be imported to location loc, even if they were originally exported from a differently named location. This option cannot be used to change the location name of the add_loc definition change.
`-m`	Remove the location from the location group if an imported location group contains a location that does not exist in the hub to which the location group is imported. If this option is not specified, the import will fail with an error.
`-ttbl`	Import definition change(s) to table `tbl`. Value `tbl` will override the table name if specified in the definition change file `impjsonfile`. This option can only be applied to the child objects of tables (e.g. columns). Definition changes like add_cols will be imported to table `tbl`, even if they were originally exported from a differently named table. This option cannot be used to change the table name of the add_table definition change.
`-Rurl`	Remote hub server. Access the hub server running on a remote machine, via the REST interface. This option is required for remote CLI access. When using this option, command hvrlogin should be run first, for authentication.
`-r`	Add resilience to the import. All changes that replace an object will add that object if it does not exist. All changes that modify, rename or delete an object will be discarded if that object does not exist. Without resilience, the import will fail instead.
`-Vaccessmeth`	Handle classified data. @inputfile: Read transport encryption key stored in a inputfile. This can also be a path (relative or absolute) to this file. @prompt: Prompt a user to enter the transport key via keyboard.

Examples

This section provides examples of using the hvrdefinitionimport command.

Example 1. Add Channel

The following command adds a channel supplied in the add_channel.json file to a hub.

hvrdefinitionimport hvrhub add_channel.json

View the add_channel.json file

{ changes : [
    {
        add_channel : {
            channel : mychannel
            description : Test channel
        }
     }
  ]
}

Example 2. Define Policy for Import

The following command adds channel chn supplied in the add_channel.json file to a hub. If the channel chn already exists on a hub, the channel will be added with name appended by an ascending number (chn2).

hvrdefinitionimport -aRENAME hvr_hub import_channel.json

View the add_channel.json file

{ changes : [
    {        
        add_channel : {
            channel : chn   
            description : Test channel 
        }
     }
  ]
}

Example 3. Add Table to Channel

The following command adds table customer supplied in the add_table.json file to an existing channel mychannel. Option -c allows you to set the channel to import the table to, even if the add_tables definition change includes a reference to a different channel.

hvrdefinitionimport -cmychannel hvr_hub add_table.json

View the add_table.json file

{ changes : [
    {
        add_tables : {
            channel : mychannel2  
            tables : {
                customer : {
                    base_name :  customer1  
                    table_group :  GENERAL  
                    cols : {
                        c1_id : {
                            sequence : 1 
                            data_type :  number  
                            attributes : {
                                prec : 5 
                                nullable : true
                            }
                        } 
                        c1_last : {
                            sequence : 2
                            data_type : number
                            attributes : {
                                prec : 2
                                nullable : true
                            }
                        }
                    }
                }
            }
         }
      }
   ]
}

Example 4. Add Location Properties

The following command adds the location properties supplied in the add_loc_props.json file to an existing location myloc. Option -l allows you to set the location to add the location properties to, even if the add_loc_props definition change includes a reference to a different location.

hvrdefinitionimport -lmyloc hvrhub add_loc_props.json

View the add_loc_props.json file

{ changes: [

    {

        add_loc_props: {
            loc : myloc2
            props: {
                Capture_Method: SQL
                Oracle_Home: /distr/oracle/1210
                Oracle_SID: HVR1210
                Database_User: a_src
                Database_Password: mypassword
                Class: oracle
            }
         }
      }
   ]
}

Example 5. Add Columns to Table

The following command adds column prod_id supplied in the add_cols.json file to an existing table mytbl. Option -t allows you to set the table to add the column to, even if the add_cols definition change includes a reference to a different table.

hvrdefinitionimport -tmytbl hvrhub add_cols.json

View the add_col.json file

{  changes:  [
    {

        add_cols: {
            channel : my_chan
            table : mytbl2
            cols : {
                prod_id: {
                    sequence: 5
                    data_type: number
                    attributes: {
                        prec: 10
                        nullable: false
                    }
                }
            } 
         }
      }
   ]
}

Example 6. Add Location Groups to Channel

The following command adds location groups supplied in the add_loc_group.json file. If a location group contains a location that does not exist on the hub to which the location group is added, option -m will remove the location from the location group.

hvrdefinitionimport -m hvrhub add_loc_group.json

View the add_loc_group.json file

{ changes : [
    {
        add_loc_group : {
            channel : mychannel 
            loc_group : MYGROUP 
            members: [ 
                a_src
                b_src
            ] 
         } 
      } 
   ] 
}

Example 7. Merge Location Group Members

The following command adds location members a_src and b_src to an existing location group SOURCE in channel mychannel. Option -k will keep the old members of the location group and merge them with the new location members specified in the add_loc_group definition change. If this option is not specified, the old members in the location group will be replaced.

hvrdefinitionimport -k hvr_hub merge_loc_members.json

View the merge_loc_members.json file

{ changes : [
    {
        add_loc_group : {
            channel : mychannel 
            loc_group : SOURCE 
            members: [ 
                a_src
                b_src 
            ] 
         } 
      }     
   ] 
}

Example 8. Add Action to Channel

The following command adds action Capture supplied in the add_action.json file to a channel. The add_channel_actions definition change refers to a location that does not exist. Option -L allows to promote the action to a location group. A new location group will be created for this. The name of this location group consists of the original location name in uppercase with the '_GROUP' suffix. If this option is not specified, the action will be discarded.

hvrdefinitionimport -L hvr_hub add_action.json

View the add_action.json file

{ changes : [
    {
        add_channel_actions : {
            channel : mychannel 
            actions: [
               { 
                 loc_scope : mylocation
                 table_scope : *
                 type : Capture

                 params : {}
               }

            ] 
         }
      }
   ]
}

Example 9. Replace Location with Resilience

The following command replaces location mychannel with the same name location having the properties supplied in the replace_loc.json file. Option -r adds resilience to the replace_loc definition change. If location mylocation does not exist, option -r will add it to the hub, without resilience, the import will fail.

hvrdefinitionimport -r hvr_hub replace_loc.json

View the replace_loc.json file

{ changes : [
    {
        replace_loc : {
            loc : mylocation
            props : {
                Class : oracle
                Oracle_Home : /oracle/1220
                Capture_Method : DIRECT
                Oracle_SID : HVR1220
                Description : Oracle source location
            }
         }
      }
   ]
}

Examples of JSON Files

Here are basic examples of changes to HVR objects that can be imported to a hub using the hvrdefinitionimport command. Note that each change type accepted corresponds to an API end-point of the REST definition interface.

Channels

Add channel

Add channel mychannel. This change type corresponds to the Add Channel API end-point.

{ changes : [

    {        
        add_channel : {
            channel : mychannel   
            description : Test channel 
        }
     }
  ]
}

Replace channel

Replace channel mychannel with a new channel having the specified description, location groups and locations. The new channel has the same name as the channel being replaced. This change type corresponds to the Replace Channel API end-point.

{ changes : [
   {
       replace_channel : {
           channel : mychannel3 
           description : My channel 
               loc_groups : { 
                   SOURCE : { 
                        members: [ 
                            src 
                        ] 
                   } 
                   TARGET : { 
                       members : [ 
                           tgt 
                       ] 
                   } 
               } 
          } 
      } 
   ] 
}

Modify channel

Modify channel mychannel to add a description. This change type corresponds to the Modify Channel API end-point.

{ changes : [
    {
        modify_channel : {
            channel : mychannel 
            description : Test channel 
        } 
     } 
  ]
}

Delete channel

Delete channel mychannel. This change type corresponds to the Delete Channel API end-point.

{ changes : [
    {
         delete_channel : {
             channel : mychannel 
         }
      }
   ]
}

Locations

Add location

Add new location myloc with the specified location properties. This change type corresponds to the Add Location API end-point.

{ changes : [
    {
        add_loc : {
            loc : myloc
            props : {
                Class : oracle
                Oracle_Home : /oracle/1800
                Capture_Method : DIRECT
                Oracle_SID : HVR1800
                Description : Oracle source location
            }
         }
      }
   ]
}

Replace location

Replace location myloc and all its properties with a new location having the specified location properties. The new location has the same name as the location being replaced. This change type corresponds to the Replace Location API end-point.

{ changes : [
    {
        replace_loc : {
            loc : myloc
            props : {
                Class : oracle
                Oracle_Home : /oracle/1220
                Capture_Method : DIRECT
                Oracle_SID : HVR1220
                Description : Oracle source location
            }
         }
      }
   ]
}

Delete location

Delete location myloc. This change type corresponds to the Delete Location API end-point.

{ changes : [
    {
        delete_loc : {
            loc : myloc 
        }
     }
  ]
}

Add location properties

Add the specified properties to location myloc. This change type corresponds to the Modify Location Properties API end-point.

{ changes : [
    {
        add_loc_props : {
            loc : myloc
            props : {
                Database_User : user_src 
                Database_Password : mypassword 
                Class : oracle 
            }
         }
      }
   ]
}

Modify location properties

Modify the properties of location myloc. Only the specified properties will be replaced. This change type corresponds to the Modify Location Properties API end-point.

{ changes : [
    {
        modify_loc_props : {
            loc : myloc
            props : {
                Class : oracle
                Oracle_Home : /oracle/1220
                Capture_Method : DIRECT
                Oracle_SID : HVR1220
                Description : Oracle source location
            }
         }
      }
   ]
}

Delete location properties

Delete location property Description of location myloc. This change type corresponds to the Delete Location Property API end-point.

{ changes : [
    {
        delete_loc_props : {
            loc : myloc
            props : [
                Description
            ]
        }
     }

  ]
}

Location Group

Add location group

Add locationg roup MYGROUP to channel mychannel. This change type corresponds to the Add Location Group API end-point.

{ changes : [
    {
        add_loc_group : {
            channel : mychannel 
            loc_group : MYGROUP 

                members: [ 
                    r_src 
                ] 
        } 
     } 
  ] 
}

Replace location group

Replace location group MYGROUP with a new location group having members src1 and src2. This change type corresponds to the Add or Replace Location Group API end-point.

{ changes : [
    {
        replace_loc_group : {
            channel : mychannel 
            loc_group : MYGROUP 
                members: [ 
                    src1 
                    src2 
                ] 
        } 
     }
  ] 
}

Delete location group

Delete location group MYGROUP. This change type corresponds to the Delete Location Group API end-point.

{ changes : [
    {
        delete_loc_group : {
            channel : mychannel
            loc_group : MYGROUP
        }
     }
  ] 
}

Add location group members

Add locations src1 and src2 to location group MYGROUP. This change type corresponds to the Add Location Group Members API end-point.

{ changes : [
    {
        add_loc_group_members : {
            channel : mychannel 
            loc_group : MYGROUP 
                members: [ 
                    src1 
                    src2 
                ] 
        } 
     }
  ] 
}

Replace location group member list

Replace the member list of location group MYGROUP with location members src1 and src2. This change type corresponds to the Replace Location Group Member List API end-point.

{ changes : [
    {
        replace_loc_group_member_list : {
            channel : mychannel 
            loc_group : MYGROUP
                members: [ 
                    src1 
                    src2 
                ] 
         } 
      }
   ] 
}

Delete location group members

Delete location group members src1 and src2 from location group MYGROUP. This change type corresponds to the Delete Location Group Member API end-point.

{ changes : [
    {
        delete_loc_group_members : {
            channel : mychannel 
            loc_group : MYGROUP 
                members: [ 
                    src1 
                    src2 
                ] 
        } 
     }
  ] 
}

Tables

Add table

Add table customer to channel channel. This change type corresponds to the Add Table API end-point.

{ changes : [
    {
        add_tables : {
            channel : channel  
            tables : {
                customer : {
                    base_name :  customer1  
                    table_group :  GENERAL  
                    cols : {
                        c1_id : {
                            sequence : 1 
                            data_type :  number  
                            attributes : {
                                prec : 5 
                                nullable : true
                            }
                        } 
                        c1_last : {
                            sequence : 2
                            data_type : number
                            attributes : {
                                prec : 2
                                nullable : true
                            }
                        }
                    }
                }
            }
         }
      }
   ]
}

Replace table

Replace table customer with a new table having the specified table definition. This change type corresponds to the Replace Table API end-point.

{ changes : [
    {
        replace_tables : {
            channel : mychannel  
            tables : {
                customer : {
                    base_name :  customer1  
                    table_group :  MYGROUP
                    cols : {
                        customer_id : {
                            sequence : 1 
                            data_type :  number  
                            attributes : {
                                prec : 3 
                                nullable : true
                            }
                        } 
                        customer_last : {
                            sequence : 3
                            data_type : number
                            attributes : {
                                prec : 3
                                nullable : true
                            }
                        }
                    }
                }  
            }
         }
      }
   ]
}

Modify table

Modify table customer to change its table group to TEST_GROUP. This change type corresponds to the Modify Table API end-point.

{ changes : [  
    {        
        modify_table : {     
            channel :  mychannel 
            table : customer
            base_name : customer 
            table_group : TEST_GROUP  
        }      
     } 
   ]
}

Delete tables

Delete tables customer1 and customer2. This change type corresponds to the Delete Table API end-point.

{
    changes : [
        {
            delete_tables : {
                channel : mychannel
                tables : [
                    customer1
                    customer2
                ]
            }
        }
    ]
}

Columns

Add columns

Add columns customer_id and customer_name to table customer. This change type corresponds to the Add Columns API end-point.

{ changes : [
    {
        add_cols : {
            channel : mychannel  
            table : customer
                cols : {
                    customer_id : {
                        sequence : 2 
                        data_type :  number  
                        attributes : {
                            prec : 3 
                            nullable : true
                        }
                    } 
                    customer_name : {
                        sequence : 5
                        data_type : varchar2
                        attributes : {
                            bytelen : 10 
                            charlen : 10 
                            encoding: WINDOWS-1252
                            nullable : true
                        }
                    }
                }
            }
        }
    ]
}

Replace column list

Replace all the current columns of table customer in channel mychannel with columns cust_id and cust_name having the specified properties. This change type corresponds to the Replace Columns List API end-point.

{ changes : [
    {
        replace_col_list : {
            channel : mychannel  
            table : customer
                cols : {
                    cust_id : {
                        sequence : 6 
                        data_type : integer
                        attributes : {
                            prec : 3 
                            nullable : true
                        }
                    } 
                    cust_name : {
                        sequence : 7
                        data_type : varchar2
                        attributes : {
                            bytelen : 12 
                            charlen : 12 
                            encoding: WINDOWS-1252
                            nullable : true
                        }
                    }
                }
            }
        }
    ]
}

Delete columns

Delete columns customer_id and customer_name from table customer. This change type corresponds to the Delete Columns API end-point.

{ changes : [ 
    { 
        delete_cols : { 
            channel : mychannel 
            table : customer 
            cols : [ 
                customer_id 
                customer_name
            ]
        } 
     } 
  ]
}

Actions

Add location actions

Add actions Capture and Integrate to location myloc. This change type corresponds to the Add Location Actions API end-point.

{ changes : [
    {
        add_loc_actions : {
            loc : myloc
            actions : [
                {
                    type : Capture 
                }    

                {
                    type : Integrate
                    params : {    
                        Resilient : true    
                   }   
               }
           ]
        }
     }
  ]
}

Replace location actions list

Replace the action list of location myloc with the specified action list. This change type corresponds to the Replace Location Actions List API end-point.

{ changes : [
    {
        replace_loc_action_list : {
            loc : myloc  
            actions : [
                {
                    type : Capture
                    params : {
                        IgnoreSessionName : admin
                    }  
                }
                {
                    type : Integrate
                    params : {  
                        Resilient : true
                    }
                }
            ]
         }
      }
   ]
}

Delete location actions

Delete actions Capture and Integrate from location myloc. This change type corresponds to the Delete Location Actions API end-point.

{ changes  : [
    {
        delete_loc_actions : {
            loc : myloc  
            actions : [
                {
                    type : Capture
                    params : {}
                }
                {
                    type : Integrate
                    params : {}
                }
           ]
        }
     }
  ]
}

Add channel actions

Add actions Capture and ColumnProperties to channel mychannel. This change type corresponds to the Add Channel Actions API end-point.

{ changes : [
    {
      add_channel_actions : {
        channel : mychannel 
        actions: [
          { 
            loc_scope : SOURCE
            table_scope : *
            type : Capture
            params : {}
          }
          {
            loc_scope : TARGET
            table_scope : *
            type : ColumnProperties
            params : {
              Datatype: datetime
              Extra: 1
              IntegrateExpression: "{hvr_cap_tstamp}"
              Name: capture_timestamp
            }
          }
        ]
      }
    }
  ]
}

Replace channel action list

Replace the existing actions in channel mychannel with the specified actions Capture and Integrate. This change type corresponds to the Replace Channel Action List API end-point.

{ changes : [
    {
      replace_channel_action_list : {
        channel : mychannel 
        actions: [
          { 
            loc_scope : SOURCE
            table_scope : *
            type : Capture
            params : {
              IgnoreSessionName : admin
            }
          }
          {
            loc_scope : TARGET
            table_scope : *
            type : Integrate
            params : {
              Resilient : SILENT
            }
          } 
        ]
      }
    }
  ]
}

Delete channel actions

Delete actions Capture and Integrate from channel mychannel. This change type corresponds to the Delete Channel Actions API end-point.

{ changes : [
    {
      delete_channel_actions : {
        channel : mychannel 
        actions: [
          { 
            loc_scope : SOURCE
            table_scope : *
            type : Capture
            params : {
              IgnoreSessionName : admin
            }
          }
          {
            loc_scope : TARGET
            table_scope : *
            type : Integrate
            params : {
              Resilient : SILENT
            }
          } 
        ] 
      }
    }
  ]
}

Add hub actions

Add action Scheduling to a hub. This change type corresponds to the Add Hub Actions API end-point.

{ changes : [
    {
        add_hub_actions : {
            actions : [
                {
                    type : Scheduling 
                    params : {
                        LatencySLA : "30" 
                        TimeContext : "5 12 1 1 1"
                    }
                }
           ]
        }
     }
  ]
}

Replace hub action list

Replace the current actions defined on a hub with new actions Scheduling and Environment. This change type corresponds to the Replace Hub Actions List API end-point.

{ changes : [
    {
        replace_hub_action_list : {
            actions : [
                {
                    type : Scheduling
                    params : {
                        LatencySLA : "5" 
                    }
                }
                {
                    type : Environment 
                    params : {
                        Name : HVR_SORT_ROW_LIMIT 
                        Value : "20"
                    }                 
                }
            ]
         }
      }
   ]
}

Delete hub actions

Delete action Scheduling defined on a hub. This change type corresponds to the Delete Hub Actions API end-point.

{ changes : [
    {
        delete_hub_actions : {
            actions : [
                {
                    type : Scheduling 
                    params : {
                        LatencySLA : "30"
                    }
                }
            ]
         }
      }
   ]
}