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
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. Superusers 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 Superuser 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
Related Links
© Incorta, Inc. All Rights Reserved.