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`

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

Note

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