CLI guide

The Incorta Unified Data Analytics Platform includes both an application programming interface (API) and corresponding command line interface (CLI) commands. The CLI requires an Incorta Node with the Analytics Service to be running using incorta.py (Python API) which requests the module required by the API.

To use the API, navigate to the directory containing the incorta.py file. The default location is: /<Incorta_Home>/IncortaNode/bin

The command line uses the following format: python incorta.py <api_command> <arguments>

Incorta also provides a number of sample shell scripts located in the ~/IncortaAnalytics/IncortaNode/bin folder. Those scripts are:

  • 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

Command: login

Logs into the server and returns the session for additional CLI commands.

Use the following to sign in to the Analytics Service: python incorta.py login https://<url>:443/incorta tenant_name user_name password.

Argument Definition
URL The login URL
tenant Tenant name
username User name
password Password
verify Verifies the server certificate. When verify is true, verification fails if the certificate is self-signed.

Use the following to add the login to a script:

session=python incorta.py login http://<url>:0000/incorta tenant_name user_name password
echo $session
python incorta.py do_another_command $session

Command: logout

Logs out from the current session.

Use the following command to logout of Incorta.

python incorta.py logout $session

Argument Definition
session The current logged in session.

Command: list_schemas

Lists all the schemas owned by the logged in user.

Use the following command to list the schemas owned by the user login.

python incorta.py list_schemas $session

Argument Definition
session The current logged in session.

Command: export_schemas

Exports schemas to an Incorta package.

Use the following command to export the schemas to a file.

python incorta.py export_schemas $session demo_sales_and_hr.zip HR SALES

Argument Definition
package_output_path Tenant name
username User name
schema
Password
session The current session ID.

Command: import_schemas

Imports schemas from a file.

Use the following command to import schemas from a file.

python incorta.py import_schemas $session demo_sales_and_hr.zip

Argument Definition
package_path The path to the package being imported.
session The current session ID.

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 Definition
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 session ID

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 Definition
schema name Refers to the schema to be loaded. Names are case sensitive.
session The current session ID

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 Definition
schema name Refers to the schema to be loaded. Names are case sensitive.
session The current session ID.

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

Command Argument Definition
export_session_variables <session> <package_output_path> <SV_1> <SV_2 ...> Exports session variables.
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 session ID.

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

Command Argument Definition
import_session_variables <session> <package_path> <overwrite> Imports session variables to the current tenant.
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.
session The current session ID.

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”

Command Argument Definition
export_dashboards <session> <package_output_path> “/path/to/dashboard/” “/another/path/*”... Exports schemas to an Incorta package.
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 session ID

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 session ID

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 session ID.
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 Definition
session The current session ID.
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 Definition
session The current session ID.
package_path The source path of the package to be imported.
overwrite overwrites existing items [true / false]. The default is false.

Command: export_alerts

Exports alerts. Use the following command to export data alerts.

python incorta.py export_alert $session export_alert.zip user1:alert1, user2:alert2

Argument Definition
session The current session ID.
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.

Command: import_alerts

Import data sources to the current tenant. Use the following command to import data alerts:

python incorta.py import_alerts $session demo_alerts.zip

Use the following command to import data alerts, replacing existing alerts:

python incorta.py import_alerts $session demo_alerts.zip true

Argument Definition
session The current session ID.
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 session ID.

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 Definition
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 session ID.
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: revoke_group_access

Revokes access to a group on an entity instance. Use the following command to revoke group access.

python incorta.py revoke_group_access $session <GROUP_NAME> <OBJECT_TYPE (e.g. schema)> <OBJECT_NAME>

Argument Definition
entity_type The type of entity to which the access is is to be revoked.
entity_name The entity to which access by the group is revoked.
group_name The group name.
session The current session ID.

Revoke group access options

  • Revoke access for group “group1” to the “SALES” schema with edit privilege.

python incorta.py revoke_group_access $session group1 schema “SALES”

  • Revoke access for group “group1” to the folder “folder1”.

python incorta.py revoke_group_access $session group1 folder “/folder1”

  • Revoke access for group “group1” to the “Countries” dashboard.

python incorta.py revoke_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 Definition
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 session ID.

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

Command: revoke_group_access

Revokes access to a group on an entity instance. Use the following command to revoke user access.

python incorta.py revoke_user_access $session <USER_NAME> <OBJECT_TYPE (e.g. schema)> <OBJECT_NAME>

Argument Definition
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 session ID.

Revoke user access options

  • Revoke access for the user “aa” to the “SALES” schema

python incorta.py revoke_user_access $session aa schema “SALES”

  • Grant view access to the user “aa” on the folder “folder1”

python incorta.py revoke_user_access $session aa folder “/folder1”

  • Revoke access to group “group1” on the “Countries” dashboard.

python incorta.py revoke_user_access $session aa dashboard “Countries”

Command: list_groups

Lists the available groups. Use the following command to list the available groups.

python incorta.py list_groups $session

Argument Definition
session The current session ID.

Command: assign_role_to_group

Grants roles to newly created groups. Use the following command to assign a role to a group.

python incorta.py assign_role_to_group $session “AdminGrp“ “User”

Argument Definition
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 session ID.

Command: 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 Definition
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 session ID.

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.

Use the following command to synchronize users and groups, along with their assignments with an SSO or an LDAP directory:

python incorta.py sync_directory $session directory.zip

To use the sync directory and replace the existing users/groups:

python incorta.py sync_directory $session directory.zip true

Related Links
© Incorta, Inc. All Rights Reserved.