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:

ArgumentDefinition
urlRequired. The login URL of the Analytics Service.
tenantRequired. The name of the tenant.
usernameRequired. The username of the user.
passwordRequired. The password of the user.
verifyOptional. 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:

ArgumentDescription
sessionThe 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:

ArgumentDescription
sessionThe current web user session. Often this is a reference to a local shell variable, $session.

Example:

python incorta.py list_schemas $session
ArgumentDefinition
sessionThe 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:

ArgumentDescription
package_output_pathThis is the path and filename for the exported schema or schemas.
schemaThe name of the schema or a space separate list of schema names.
sessionThe 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.

ArgumentDescription
package_pathThe path to the package being imported.
sessionThe 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.

ArgumentDescription
sessionThe current web user session. Often this is a reference to a local shell variable, $session.
package_output_pathThe 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.

ArgumentDescription
sessionThe current web user session. Often this is a reference to a local shell variable, $session.
package_pathThe source path of the package to be imported.
overwriteOverwrites 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.

ArgumentDescription
entity_typeThe type of entity to which the access is granted.
entity_nameThe name of the <entity_type> instance that the group would access.
group_nameThe group name.
sessionThe 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.

ArgumentDescription
entity_typeThe type of entity to which the access is granted.
entity_nameThe name of the <entity_type> instance that the group would access.
user_nameThe user name.
sessionThe 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.

ArgumentDescription
sessionThe 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.

ArgumentDescription
role_nameThe role name to be assigned to the group.
group nameThe name of the group to which the role is assigned.
sessionThe 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.

ArgumentDescription
archive_pathThe 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.
autoGenerateGroupWhen 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.
sessionThe current web user session. Often this is a reference to a local shell variable, $session.

File Content for groups.csv

ParameterNotes
NameRefers to the group name. This column is mandatory.
DescriptionRefers to the group description. This column is mandatory, but it can be left blank.
TypeRefers to the group type. This column is optional, and values are case-sensitive. Possible values are: Internal, SSO, LDAP
External IDThis 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

ParameterNotes
Login NameThis column is mandatory and unique.
EmailThis column is mandatory and unique.
Display NameThis column is mandatory.
LanguageThis column is mandatory, but it can take a blank value.
CountryThis column is mandatory, but it can take a blank value.
TimezoneThis column is mandatory, but it can take a blank value.
CalendarThis column is mandatory, but it can take a blank value.
TypeThis column contains the user type and it is optional. Values are case-sensitive. Possible values are: Internal, SSO, LDAP
External IdThis 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

ArgumentDescription
schema nameThe name of the schema to be loaded. Schema names are case sensitive.
table nameThe table name within the schema to be loaded. Table names are case sensitive.
sessionThe 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

ArgumentDescription
schema nameRefers to the schema to be loaded. Names are case sensitive.
sessionThe 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

ArgumentDescription
schema nameRefers to the schema to be loaded. Names are case sensitive.
sessionThe 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

ArgumentDescription
export_session_variables<session> <package_output_path> <SV_1> <SV_2 ...>
package_output_pathThe destination path of the exported package.
session_variableThe session variable names separated by spaces. Names are case sensitive.
sessionThe 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

ArgumentDescription
import_session_variables<session> <package_path> <overwrite>
package_path
overwrite
sessionThe 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”

ArgumentDescription
export_dashboards<session> <package_output_path> “/path/to/dashboard/” “/another/path/*”...
package_output_path
dashboard path
sessionThe 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

ArgumentDefinition
package_output_pathThe export path.
dashboard pathDashboard paths separated by space, with paths in quotes where there the name has spaces. Names are case sensitive.
sessionThe 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

ArgumentDefinition
sessionThe current web user session. Often this is a reference to a local shell variable, $session.
package_pathThe source path of the package to be imported.
overwriteTrue 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"

ArgumentDescription
sessionThe current web user session. Often this is a reference to a local shell variable, $session.
package_output_pathThe destination path for the exported data sources.
Data sourcetakes 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

ArgumentDescription
sessionThe current web user session. Often this is a reference to a local shell variable, $session.
package_pathThe source path of the package to be imported.
overwriteoverwrites 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“

ArgumentDefinition
file_pathThe path to the file to be uploaded.
sessionThe 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>

ArgumentDescription
entity_typeThe type of the entity granted access.
entity_nameThe name of the <entity_type> instance that the group would access.
group_nameThe group name.
sessionThe current web user session. Often this is a reference to a local shell variable, $session.
permissionThe 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>

ArgumentDescription
user_nameThe name of the user to which access is granted.
entity_typeThe type of entity to which the access is granted.
entity_nameThe name of the <entity_type> instance that the user would access.
permissionThe privilege type granted to the user. This is an optional parameter with possible values (e.g. view [default], share, edit).
sessionThe 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