dssdefinitionimport - DSS 6 | Data Source Solutions Documentation
Documentation: dssdefinitionimport - DSS 6 | Data Source Solutions Documentation
dssdefinitionimport
Usage
<b>dssdefinitionimport</b> [<b>-R</b><em>url</em>] [<b>-c</b><em>chn</em>] [<b>-l</b><em>loc</em>] [<b>-t</b><em>tbl</em>] <em>hub impjsonfile</em>
Description
Command dssdefinitionimport loads definition changes to a hub. Definition change is a change to a DSS 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 (<em>impjsonfile</em>). The JSON file may include one or more definition changes.
The JSON file can either be created using command dssdefinitionexport or it can be compiled manually provided it conforms to the JSON prototypes used in DSS.
For example, the following is a sample JSON file exported using command dssdefinitionexport that adds tables to a channel (the 'add_tables' definition change):
'Add tables' definition change
{
"export_header": {
"creator": "icuser",
"dss_version": "6.0.1/2",
"api_version": "v0",
"description": "Exported with UI",
"tstamp": "2021-03-06T14:04:33.886Z",
"original_hub": "dss_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 DSS 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 : DSS1220
Description : Oracle source location
}
}
}
]
}
Command dssdefinitionimport 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 dssdefinitionimport.
| 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 Valid values for the
|
-Aact_policySince v6.1.0/26 |
Define rules for action(s) when replacing a location or a channel during import.
Valid values for the
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 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 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 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 |
-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 dsslogin 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. |
|
Handle classified data.
|
Examples
This section provides examples of using the dssdefinitionimport command.
Example 1. Add Channel
The following command adds a channel supplied in the add_channel.json file to a hub.
dssdefinitionimport dsshub 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).
dssdefinitionimport -aRENAME dss_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 <b>-c</b> 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.
dssdefinitionimport -cmychannel dss_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 <b>-l</b> 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.
dssdefinitionimport -lmyloc dsshub 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: DSS1210
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 <b>-t</b> 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.
dssdefinitionimport -tmytbl dsshub 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 <b>-m</b> will remove the location from the location group.
dssdefinitionimport -m dsshub 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 <b>-k</b> 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.
dssdefinitionimport -k dss_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 <b>-L</b> 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.
dssdefinitionimport -L dss_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 <b>-r</b> adds resilience to the replace_loc definition change. If location mylocation does not exist, option <b>-r</b> will add it to the hub, without resilience, the import will fail.
dssdefinitionimport -r dss_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 : DSS1220
Description : Oracle source location
}
}
}
]
}
Examples of JSON Files
Here are basic examples of changes to DSS objects that can be imported to a hub using the dssdefinitionimport 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 : DSS1800
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 : DSS1220
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 : DSS1220
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: "{dss_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 : DSS_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"
}
}
]
}
}
]
}