CLI guide

Incorta Analytics includes both an application programming interface (API) and corresponding command line interface (CLI) commands. The CLI requires the Incorta server to be up and running on 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 /incortaHome/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

API Commands

Login

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

Command Arguments Definition
login Logs into the server and returns the session for additional CLI commands
URL The login URL
tenant Tenant name
username User name
password Password
verify Verifies the server certificate. When verify=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

Logout

Use the following command to logout of Incorta.

python incorta.py logout $session

Command Definition
logout Logs out from the current session
session The current logged in session

List Schemas

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

python incorta.py list_schemas $session

Command Definition
list_schemas Lists all the schemas owned by the logged in user.
session The current logged in session.

Export Schemas

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

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

Command Definition
export_schemas Exports schemas to an Incorta package
package_output_path Tenant name
username User name
schema
Password
session The current session ID

Import Schemas

Use the following command to import schemas from a file.

python incorta.py import_schemas $session demo_sales_and_hr.zip

Command Definition
import_schemas Imports schemas from a file
package_path The path to the package being imported
session The current session ID

Load Schema

Use the following command to load a schema or a table. To load a schema:

python incorta.py load_schema $session SALES

To load a table:

python incorta.py load_schema $session SALES Customers

Command Definition
load_schema Loads a schema or table
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

Load Schema Incrementally

Use the following command to load a schema incrementally.

python incorta.py load_schema_incremental $session SALES

Command Definition
load_schema_incremental Loads the schemas from a file
schema name Refers to the schema to be loaded. Names are case sensitive
session The current session ID

Load Schemas From Snapshots

Use the following command to load a schema from a snapshot.

python incorta.py load_schema_from_snapshot $session SALES

Command Definition
load_schema_from_snapshot Loads the schemas
schema name Refers to the schema to be loaded. Names are case sensitive.
session The current session ID

Migrate Load Job

Use the following command to migrate a schema load scheduled job.

python incorta.py migrate_load_job $session

Command Definition
migrate_load_job Migrates a schema scheduled job
session The current session ID

Import and Export Schema Example

The following script exports a schema from one tenant and imports it into another tenant, or server.

$incorta_cmd=”python incorta.py”
$session=`$incorta_cmd login http://server1/incorta tenant1 user_name password`
$incorta_cmd export_schemas $session export.zip schema1 schema2 schema3
$incorta_cmd logout $session
$session=`$incorta_cmd login http://server2/incorta tenant2 user_name password`
$incorta_cmd import_schemas $session export.zip
$incorta_cmd logout $session

Export 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 Arguments 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

Import Session Variables

Use the following command to import session variables.

python incorta.py import_session_variables $session demo_sales_and_hr.zip true

Command Arguments 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

Export Dashboards

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 Arguments 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

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

Command Definition
export_dashboards_no_bookmarks Exports dashboards without bookmarks.
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

Import Dashboards

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

Command Definition
import_dashboards Imports the package to the current tenant
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

Export data source

Use the following command to export data sources.

$incorta_cmd export_datasources $session "export_datasource.zip" "datasource1" "datasource2" "datasource3"

Command Definition
export_datasources Exports data sources
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.

Import data source

Use the following command to import data sources.

$incorta_cmd import_datasources $session "export_datasource.zip" true

Command Definition
import_datasources Import data sources to the current tenant
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.

Export data alerts

Use the following command to export data alerts.

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

Command Definition
export_alerts Exports alerts
session The current session ID
package_output_path The destination path for the exported data alert(s)

Alerts name

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.

Import data alerts

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

Command Definition
import_alerts Import data sources to the current tenant.
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.

Upload Data File

Use the following command to upload a data file.

python incorta.py upload_data_file $session “Employees.csv“

Command Arguments Definition
upload_data_file Uploads a data file to the current tenant
file_path The path to the file to be uploaded
session The current session ID

Grant Group Access

Use the following command to grant group access.

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

Command Definition
grant_group_access Grants access to a group on an entity instance
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”

Revoke Group Access

Use the following command to grant group access.

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

Command Definition
revoke_group_access Revokes access to a group on an entity instance
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 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”

Grant User Access

Use the following command to grant user access.

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

Command Definition
grant_user_access Grants access to a user on an entity instance
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

Revoke User Access

Use the following command to revoke user access.

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

Command Definition
revoke_group_access Revokes access to a group on an entity instance
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”

List Groups

Use the following command to list the available groups.

python incorta.py list_groups $session

Command Definition
list_groups Lists the available groups
session The current session ID

List Roles

Use the following command to list the available roles.

python incorta.py list_roles $session

Command Definition
list_groups Lists the available groups
session The current session ID

Assign a Role to a Group

Use the following command to assign a role to a group.

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

Command Definition
assign role to group Grants roles to newly created groups
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

Synchronize Directory

This property can be used by Superuser users to check the status of synchronized rows; those that succeeded and those that failed.

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

Command Definition
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.
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.
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.