Tools -> Incorta Command Line Interface (CLI)
About the Incorta Command Line Interface (CLI)
The CLI for Incorta is available on an Incorta node with the Analytics Service running. Written in Python, the CLI is available from Bash shell and takes advantage of Python's available modules for managing HTTP requests.
incorta.py
The CLI python file is incorta.py
. The default location of:
/<IINCORTA_INSTALLATION_PATH>/IncortaNode/bin/incorta.py`
login
To use the CLI, you must first establish a web user session. Typically, you store the session credentials in a local shell variable. To create a session, use the CLI login
command.
The login
command requires the following arguments:
Argument | Definition |
---|---|
url | Required. The login URL of the Analytics Service. |
tenant | Required. The name of the tenant. |
username | Required. The username of the user. |
password | Required. The password of the user. |
verify | Optional. Use to verify the TLS/SSL certificate. If the certificate is self-signed, verification will fail. |
Here is an example over HTTP:
session=`python incorta.py login http://<url>:8080/incorta tenant username password`echo $session
The default port for the Analytics Service over HTTP is 8080.
Here is an example over HTTPs:
session=`python incorta.py login https://<url>:8443/incorta tenant username password`echo $session
CLI Commands
Here are the available commands:
- login
- logout
- list_schemas
logout
Use the logout
command to terminate the current web user session. The logout
command requires the following arguments:
Argument | Description |
---|---|
session | The current web user session. Often this is a reference to a local shell variable, $session . |
Example:
python incorta.py logout $session
list_schemas
Use the list_schemas
command to lists all the schemas that the user session has View access rights to. The list_schemas
command requires the following arguments:
Argument | Description |
---|---|
session | The current web user session. Often this is a reference to a local shell variable, $session . |
Example:
python incorta.py list_schemas $session
Argument | Definition |
---|---|
session | The current logged in session. |
export_schemas
Use the export_schemas
command to export a schema as a ZIP
file. The export_schemas
command requires the following arguments:
Argument | Description |
---|---|
package_output_path | This is the path and filename for the exported schema or schemas. |
schema | The name of the schema or a space separate list of schema names. |
session | The current web user session. Often this is a reference to a local shell variable, $session . |
Example:
python incorta.py export_schemas $session /tmp/schemas_HR_and_SALES.zip HR SALES
import_schemas
Imports schemas from a file.
Argument | Description |
---|---|
package_path | The path to the package being imported. |
session | The current web user session. Often this is a reference to a local shell variable, $session . |
Example:
python incorta.py import_schemas $session /tmp/schemas_HR_and_SALES.zip
export_alerts
Use the export_alerts
command to export user alerts to a ZIP
file.
Argument | Description |
---|---|
session | The current web user session. Often this is a reference to a local shell variable, $session . |
package_output_path | The destination path for the exported data alert(s). Each user can export one or more of their own alerts separated by space. Super Users can export alerts for other users, using their login name as in the following format: <USER_LOGINNAME>:<ALERT_NAME> . Names are case-sensitive. If a name includes a space, enclose it in quotes. |
Here is an example of exporting alerts for multiple users:
python incorta.py export_alert $session /tmp/export_alert.zip user1:alert1, user2:alert2
import_alerts
Use the import_alerts
command to import alerts to the current tenant of the web user session.
Argument | Description |
---|---|
session | The current web user session. Often this is a reference to a local shell variable, $session . |
package_path | The source path of the package to be imported. |
overwrite | Overwrites existing items [true / false]. The default is false. |
Here is an example that imports new user alerts.
python incorta.py import_alerts $session /tmp/user1_alerts.zip
Here is an example that replaces existing user alerts.
python incorta.py import_alerts $session /tmp/user2_alerts.zip true
revoke_group_access
Use the revoke_group_access
command to remove access rights for a group for a specific entity type such as a physical schema, business schema, folder, or dashboard.
Argument | Description |
---|---|
entity_type | The type of entity to which the access is granted. |
entity_name | The name of the <entity_type> instance that the group would access. |
group_name | The group name. |
session | The current web user session. Often this is a reference to a local shell variable, $session . |
Usage
python incorta.py revoke_user_access $session group_name entity_type entity_name
Examples
Here is an example to revoke access to the group grp_Sales
on the sch_Sales
folder :
python incorta.py revoke_user_access $session grp_Sales schema "sch_Sales"
Here is an example to revoke access to the group grp_Sales
for the Finance
folder :
python incorta.py revoke_user_access $session grp_Sales folder "Finance"
Here is an example to revoke access to the group grp_Sales
for the Revenue by Countries
dashboard:
python incorta.py revoke_user_access $session grp_Sales dashboard "Revenue by Countries"
revoke_user_access
Use the revoke_user_access
command to remove access rights to a user for a specific entity type such as a physical schema, business schema, folder, or dashboard.
Argument | Description |
---|---|
entity_type | The type of entity to which the access is granted. |
entity_name | The name of the <entity_type> instance that the group would access. |
user_name | The user name. |
session | The current web user session. Often this is a reference to a local shell variable, $session . |
Usage
python incorta.py revoke_user_access $session user_name entity_type entity_name
Examples
Here is an example to revoke access to the user user_1
on the sch_Sales
folder :
python incorta.py revoke_user_access $session `user_1` schema "sch_Sales"
Here is an example to revoke access to the user user_1
for the Finance
folder :
python incorta.py revoke_user_access $session user_1 folder "Finance"
Here is an example to revoke access to the user user_1
for the Revenue by Countries
dashboard:
python incorta.py revoke_user_access $session user_1 dashboard "Revenue by Countries"
list_groups
Lists the available groups. Use the following command to list the available groups.
Argument | Description |
---|---|
session | The current session ID. |
Example:
python incorta.py list_groups $session
assign_role_to_group
Grants roles to newly created groups. Use the following command to assign a role to a group.
Argument | Description |
---|---|
role_name | The role name to be assigned to the group. |
group name | The name of the group to which the role is assigned. |
session | The current web user session. Often this is a reference to a local shell variable, $session . |
Example:
python incorta.py assign_role_to_group $session "grp_Admin" "Schema Manager"
sync_directory
Synchronizes the system users and groups, along with their assignments. The process requires a zip file containing three CSV files; users.csv, groups.csv, and user-groups.csv. This property can be used by Super User users to check the status of synchronized rows; those that succeeded and those that failed.
Argument | Description |
---|---|
archive_path | The path containing three CSV files; users.csv, groups.csv, and user-groups.csv. A sample of each file is provided in the tables below. |
full_sync (optional) | The default value for this parameter is set to “false”. If set to “true”, the users and groups assignments get flushed before the import. Existing users and groups get updated regardless of the value for this option. |
autoGenerateGroup | When set to "false", this setting will only purge and reload user group assignments for existing groups that match 1:1 with the source system groups. No new groups from source system will be imported. Any manually created groups within Incorta will remain untouched. When set to "true", this setting will purge and reload all groups and user group assignments from source system, while retaining any manually created groups in Incorta. |
session | The current web user session. Often this is a reference to a local shell variable, $session . |
File Content for groups.csv
Parameter | Notes |
---|---|
Name | Refers to the group name. This column is mandatory. |
Description | Refers to the group description. This column is mandatory, but it can be left blank. |
Type | Refers to the group type. This column is optional, and values are case-sensitive. Possible values are: Internal, SSO, LDAP |
External ID | This column is optional. It is required only if the type is LDAP when it holds the value of the “Group Distinguished Name”. |
File Content for users.csv
Parameter | Notes |
---|---|
Login Name | This column is mandatory and unique. |
Email | This column is mandatory and unique. |
Display Name | This column is mandatory. |
Language | This column is mandatory, but it can take a blank value. |
Country | This column is mandatory, but it can take a blank value. |
Timezone | This column is mandatory, but it can take a blank value. |
Calendar | This column is mandatory, but it can take a blank value. |
Type | This column contains the user type and it is optional. Values are case-sensitive. Possible values are: Internal, SSO, LDAP |
External Id | This column is optional. It is required only if the user type is “LDAP”, holding the value of the “User Distinguished Name”. |
Notes:
If a field name contains a comma, place the field name between double quotes.
The CSV files should not contain unnecessary spaces.
The column order matters.
Here is an example that synchronizes users and groups, along with their assignments with an SSO or an LDAP directory:
python incorta.py sync_directory $session directory.zip
Here is an example to replace the existing users and/or groups:
python incorta.py sync_directory $session directory.zip true
Command: load_schema
Loads a schema or table. To load a schema:
python incorta.py load_schema $session SALES
To load a table:
python incorta.py load_schema $session SALES Customers
Argument | Description |
---|---|
schema name | The name of the schema to be loaded. Schema names are case sensitive. |
table name | The table name within the schema to be loaded. Table names are case sensitive. |
session | The current web user session. Often this is a reference to a local shell variable, $session . |
Command: load_schema_incremental
Loads the schemas from a file.
Use the following command to load a schema incrementally.
python incorta.py load_schema_incremental $session SALES
Argument | Description |
---|---|
schema name | Refers to the schema to be loaded. Names are case sensitive. |
session | The current web user session. Often this is a reference to a local shell variable, $session . |
Command: load_schema_from_snapshot
Loads the schemas. Use the following command to load a schema from a snapshot.
python incorta.py load_schema_from_snapshot $session SALES
Argument | Description |
---|---|
schema name | Refers to the schema to be loaded. Names are case sensitive. |
session | The current web user session. Often this is a reference to a local shell variable, $session . |
Command: export_session_variables
Exports session variables. Use the following command to export session variables.
python incorta.py export_session_variables $session
demo_sales_and_hr.zip SV1 SV2
Argument | Description |
---|---|
export_session_variables | <session> <package_output_path> <SV_1> <SV_2 ...> |
package_output_path | The destination path of the exported package. |
session_variable | The session variable names separated by spaces. Names are case sensitive. |
session | The current web user session. Often this is a reference to a local shell variable, $session . |
Command: import_session_variables
Imports session variables to the current tenant. Use the following command to import session variables.
python incorta.py import_session_variables
$session demo_sales_and_hr.zip true
Argument | Description |
---|---|
import_session_variables | <session> <package_path> <overwrite> |
package_path | |
overwrite | |
session | The current web user session. Often this is a reference to a local shell variable, $session . |
Command: export_dashboards
Exports schemas to an Incorta package. Dashboards can be exported with or without bookmarks. Use the following command to export dashboards.
python incorta.py export_dashboards
$session “/folder/subfolder/*” “/folder/dashboard” “dashboard_on_root_folder”
Argument | Description |
---|---|
export_dashboards | <session> <package_output_path> “/path/to/dashboard/” “/another/path/*”... |
package_output_path | |
dashboard path | |
session | The current web user session. Often this is a reference to a local shell variable, $session . |
Command: export_dashboards_no_bookmarks
Exports dashboards without bookmarks.
Administrators can use the CLI to export dashboards while ignoring bookmarks. This ensures that bookmarks created in the production environment (for example) are not affected by bookmarks coming from the test environment when the dashboard is upgraded. The command to export the dashboard with no bookmarks is:
Export_dashboard_sample_no_bookmarks.sh
Argument | Definition |
---|---|
package_output_path | The export path. |
dashboard path | Dashboard paths separated by space, with paths in quotes where there the name has spaces. Names are case sensitive. |
session | The current web user session. Often this is a reference to a local shell variable, $session . |
Command: import_dashboards
Imports the package to the current tenant. Use the following command to import dashboards.
python incorta.py import_dashboards
$session demo_dashboards.zip
To replace an existing dashboard and import a dashboard:
python incorta.py import_dashboards
$session demo_dashboards.zip true
Argument | Definition |
---|---|
session | The current web user session. Often this is a reference to a local shell variable, $session . |
package_path | The source path of the package to be imported. |
overwrite | True or false as to whether to overwrite existing data. The default is false. |
Command: export_datasources
Exports data sources. Use the following command to export data sources.
$incorta_cmd export_datasources $session
"export_datasource.zip" "datasource1" "datasource2" "datasource3"
Argument | Description |
---|---|
session | The current web user session. Often this is a reference to a local shell variable, $session . |
package_output_path | The destination path for the exported data sources. |
Data source | takes the data source names separated by spaces. Names are case-sensitive. |
Command: import_datasources
Import data sources to the current tenant. Use the following command to import data sources.
$incorta_cmd import_datasources $session
"export_datasource.zip" true
Argument | Description |
---|---|
session | The current web user session. Often this is a reference to a local shell variable, $session . |
package_path | The source path of the package to be imported. |
overwrite | overwrites existing items [true / false]. The default is false. |
Command: upload_data_file
Uploads a data file to the current tenant. Use the following command to upload a data file.
python incorta.py upload_data_file $session
“Employees.csv“
Argument | Definition |
---|---|
file_path | The path to the file to be uploaded. |
session | The current web user session. Often this is a reference to a local shell variable, $session . |
Command: grant_group_access
Grants access to a group on an entity instance. Use the following command to grant group access.
python incorta.py grant_group_access $session
<GROUP_NAME> <OBJECT_TYPE (e.g. schema)> <OBJECT_NAME>
Argument | Description |
---|---|
entity_type | The type of the entity granted access. |
entity_name | The name of the <entity_type> instance that the group would access. |
group_name | The group name. |
session | The current web user session. Often this is a reference to a local shell variable, $session . |
permission | The privilege type granted to the group. This is an optional parameter with possible values (e.g. view [default], share, edit). |
Grant group access options
- Grant view access for group “group1” to the “SALES” schema with edit privilege.
python incorta.py grant_group_access $session
group1 schema “SALES” edit
- Grant view access for group “group1” to the folder “folder1”.
python incorta.py grant_group_access $session
group1 folder “/folder1”
- Grant view access for group “group1” to the “Countries” dashboard.
python incorta.py grant_group_access $session
group1 dashboard “Countries”
Command: grant_user_access
Grants access to a user on an entity instance. Use the following command to grant user access.
python incorta.py grant_user_access $session
<USER_NAME> <OBJECT_TYPE (e.g. schema)> <OBJECT_NAME>
Argument | Description |
---|---|
user_name | The name of the user to which access is granted. |
entity_type | The type of entity to which the access is granted. |
entity_name | The name of the <entity_type> instance that the user would access. |
permission | The privilege type granted to the user. This is an optional parameter with possible values (e.g. view [default], share, edit). |
session | The current web user session. Often this is a reference to a local shell variable, $session . |
Grant user access examples:
- Grant view access for the user “aa” to the “SALES” schema with share privilege
python incorta.py grant_user_access $session
aa schema “SALES” share
- Grant view access for the user “aa” to the folder “folder1” with share privilege
python incorta.py grant_user_access $session
aa folder “/folder1” share
Out of the box Bash shell scripts
Incorta also provides a number of sample shell scripts located in the bin
directory:
assign_role_to_group_sample.sh
export_dashboard_sample.sh
export_dashboard_sample_no_bookmarks.sh
export_datasource_sample.sh
export_sample.sh
export_session_variable_sample.sh
import_dashboards_sample.sh
import_datasources_sample.sh
import_sample.sh
import_session_variable_sample.sh
incorta.sh
list_groups_sample.sh
list_roles_sample.sh
load_stagging_sample.sh
permissions_sample.sh
sync_directory_with_db.sh
sync_directory_with_ldap.sh
upload_data_file_sample.sh