Python API for admin
Python API for admin

Python API for admin

📌

1. Install KAWA’s Python client

Some of the advanced administration tasks are managed through KAWA’s Python client.

In order to install it, you need python 3.8 at least.

Run the following command to install KAWA Client:

pip install kywy --upgrade --extra-index-url https://kawa:Br2zFU2Y5EGBWr4khYzh@gitlab.com/api/v4/projects/31007056/packages/pypi/simple

⚠️ Make sure that the machine on which you install the python client has access to the KAWA server (via HTTP(S) on whatever port was configured on the server).

2. Setup the setup-admin user

The setup-admin user is unique inside each KAWA instance. It has the privileges of any admin user, but can never be downgraded to non-admin nor deactivated.

2.a) Retrieve the setup-admin API Key

In order to authenticate on KAWA via the Python client, it is recommended to use your API Key. In order to do so, login on KAWA with the setup-admin user with the following credentials:

login: setup-admin@kawa.io

password: changeme

From there, generate your API Key.

⚠️ Once the API Key has been generated, it cannot be recovered (KAWA does not store it anywhere). You can always generate a new one if you wish.

image

2.b) Login to KAWA via the Python Client

To login into KAWA from the Python client, use the following script:

from kywy.client.kawa_client import KawaClient

k = KawaClient(kawa_api_url='http(s)://<YOUR URL>')

# Copy and paste your key into a file and load it
# to authenticate.
# (The file must contain only one line, which is the key.
k.set_api_key(api_key_file='kawa.key')

# Alternatively, copy and paste your key into your script
# (Not recommended)
k.set_api_key(api_key='*********')

# You can optionally set a worksapce id
# If you don't, it will position you in the last workspace you were in
k.set_active_workspace_id(workspace_id=1)

sheets = k.entities.sheets()

print('There are {} sheets in workspace {}'.format(len(sheets.list_entities()), k.active_workspace_id))

2.c) Change the setup admin user’s password

The change_user_password command is only available for admin users. With it, you can set any password to users in the application.

from kywy.client.kawa_client import KawaClient

k = KawaClient(kawa_api_url='http(s)://<YOUR URL>')
k.set_api_key(api_key_file='kawa.key')
cmd = k.commands

cmd.change_user_password(email='setup-admin@kawa.io', new_password='*******')

3. Create a new workspace and new users

A Workspace allows users to collaborate together on shared data sources, shared sheets, shared data models and shared reports (dashboards…).

📌
The Row Level Security configuration will be configured per user inside each workspace. Users inside the same workspace will be subject to their own row level security policies and will not benefit from the same access on the shared data.

In order to create a new workspace, use the following command (any user can run that command):

some_workspace = cmd.create_workspace('<WORKSPACE NAME>')

In order to create new users into KAWA, use the following command (admin only):

cmd.create_user_with_email_and_password(
  email='some@email.com', 
  password='*****',
  first_name='Lucius',
  last_name='Fox')

Lastly, in order to add users in workspaces, use this command (admin, workspace owner, or workspace member admin only):

cmd.add_users_to_workspace(emails, some_workspace['id'])

Here is a sample of a script that creates a user and add them into a new workspace.

from kywy.client.kawa_client import KawaClient

k = KawaClient(kawa_api_url='http(s)://<YOUR URL>')
k.set_api_key(api_key_file='kawa.key')
cmd = k.commands

some_workspace = cmd.create_workspace('<WORKSPACE NAME>')

# Creates the user with a defined password
# You need one upper case, one lower case, one number and one special character
cmd.create_user_with_email_and_password(email='lucius@wayne.ai', 
																				password='$SomePassword123$',
																				first_name='Lucius',
																				last_name='Fox')

# Add the new user into the workspace
cmd.add_users_to_workspace(['lucius@wayne.ai'], some_workspace['id'])

Note that workspace creation and assignation can be achieved in the Web UI:

image

And then:

image

Please refer to the “Collaborating in KAWA” guide to learn more about workspaces and workspace permissions.

4. Manage existing users

4. a) Update users’ role

There are three global roles in KAWA. Those roles are meant to define high level permissions, but Workspace roles are used to define more precise roles for users in each workspace.

READER_ROLE

Most users of KAWA will have this role. READERS can create their workspaces and be administrators of their own workspaces. They will be affected by each workspace permission flags.

ADMIN_ROLE

Admin users have the same sets of permissions as Readers. In addition, they can bypass all the workspace permission flags set for them and more importantly: they can create, remove, activate and deactivate users via the Python API. They also have access to all the administration API to configure the KAWA instance.

SETUP_ADMIN_ROLE

This roles grants the same permissions as the ADMIN ROLE. The only difference is that a SETUP_ADMIN can never be disabled, removed or turned into another role. There is always one and only one setup admin in each KAWA instance.

In order to update a user’s role, you need to have the ADMIN or SETUP_ADMIN role.

from kywy.client.kawa_client import KawaClient

k = KawaClient(kawa_api_url='http(s)://<YOUR URL>')
k.set_api_key(api_key_file='kawa.key')
cmd = k.commands

# Use one of: ADMIN_ROLE or READER_ROLE
# (No user can be turned into a SETUP_ADMIN user)
cmd.replace_user_role(user_id='lucius@wayne.com', new_role='ADMIN_ROLE')

4. b) Toggle users on and off

Admin users can turn off users. When a user is turned off, they will instantly lose access to KAWA an will be able to login again only if their account is turned back on.

from kywy.client.kawa_client import KawaClient

k = KawaClient(kawa_api_url='http(s)://<YOUR URL>')
k.set_api_key(api_key_file='kawa.key')
cmd = k.commands

# the SETUP_ADMIN_ROLE cannot be deactivated
cmd.toggle_users_status(user_id_list=['lucius@wayne.com', 'bruce@wayne.com'], 
                        active=False)

5. Assign users to perimeters

In KAWA, perimeters are used to define groups of users to which will be applied Row Level Security rules for data access.

Perimeters are different from Workspaces as: Workspaces define a set of data sources, sheets, reports on which users can collaborate on Perimeters define the groups of users who will be allowed to see the same data (Row level security).

Here is a Python snippet that will let you assign perimeters (Here: US and AS) to users:

ℹ️ The perimeters will be created automatically.

⚠️ After the command has run, each user will be exactly in the perimeters that were specified. It means that they will be added to the perimeters in the list and removed from the ones that are NOT in the list. 

from kywy.client.kawa_client import KawaClient

k = KawaClient(kawa_api_url='http(s)://<YOUR URL>')
k.set_api_key(api_key_file='kawa.key')
cmd = k.commands

cmd.assign_user_to_perimeters('user1@kawa.io', ['US','AS'])
cmd.assign_user_to_perimeters('user2@kawa.io', ['AS'])
cmd.assign_user_to_perimeters('user3@kawa.io', ['US'])

You can then configure Row Level Security based on those perimeters. To do so, please refer to the ROW Level Security documentation.

Users can pick in which Perimeter they work from the settings modal:

image

6. Restrict data source types

6.a) Data Source types

There are a few types of data sources in KAWA. This type comes from how the data source was created:

TRANSFORMATION

Creates a data source by transforming a view into a new data source. Achieved from the view itself:

image

USER_FILE

Creates a data source by uploading files to KAWA.

EXTERNAL_SYSTEM

Creates a data source by connecting to an external system (Google sheet, Airtable, MySQL server, etc..).

PYTHON_CLIENT

Creates a data source from the Python client

LIVE_CONNECT

Connects to a table in the connected data warehouse: SNOWFLAKE, BIG QUERY, etc

6.b) Restricting data source type creation

By default, principals can create data sources for all types. Administrators are not affected by this limitation.

ℹ️ This configuration is applied per user and across all workspaces.

You can limit this by using the following command: replace_forbidden_data_types

The following elements are supported:

TRANSFORMATION, USER_FILE, EXTERNAL_SYSTEM, PYTHON_CLIENT, LIVE_CONNECT

from kywy.client.kawa_client import KawaClient

k = KawaClient(kawa_api_url='http(s)://<YOUR URL>')
k.set_api_key(api_key_file='kawa.key')
cmd = k.commands

# Forbid the creation of data sources of type: EXTERNAL_SYSTEM and TRANSFORMATION
# to user snow@flake.io
cmd.replace_forbidden_data_types(['snow@flake.io'], ['EXTERNAL_SYSTEM', 'TRANSFORMATION'])

7. Configure SMTP

In order to configure a SMTP server, use a script similar to the following one. SMTP can be used to send account activation messages (when working with KAWA’s native authentication mechanism) or to send emails from automations.

⚠️ Please note that the server needs to be restarted for the SMTP parameters to be taken in account.

from kywy.client.kawa_client import KawaClient

k = KawaClient(kawa_api_url='http(s)://<YOUR URL>')
k.set_api_key(api_key_file='kawa.key')
cmd = k.commands

# Turn on SMTP communications
# To turn back off, use: LOG instead of SMTP
cmd.replace_communication_provider_type('SMTP')

# Configure the SMTP server
# Use extraSmtpProperties to put any additional configuration from
#  https://javadoc.io/doc/com.sun.mail/jakarta.mail/latest/jakarta.mail/com/sun/mail/smtp/package-summary.html
cmd.replace_configuration('SmtpConfig', {
    'host': 'smtp.wayne.com',
    'port': 2525,
    'sslEnabled': False,
    'startTlsEnabled': True,
    'authenticationEnabled': True,
    'extraSmtpProperties': {
        "mail.smtp.ssl.trust": "some-domain.com"
    }
})

# Defines a subject + sender for email activation emails
cmd.replace_configuration('EmailActivatorConfiguration', {
    'sender': 'postmaster@kawa-analytics.com',
    'subject': 'One last step to activate your account'
})

# Defines a subject + sender for autimation emails
cmd.replace_configuration('AutomationBehaviourConfiguration', {
    'emailSender': 'robot@kawa-analytics.com',
    'emailSubject': 'New automation from KAWA'
})

6. Retrieve usage report

As an admin, you can retrieve some statistics about the usage of KAWA over a period of time.

from kywy.client.kawa_client import KawaClient

k = KawaClient(kawa_api_url='http(s)://<YOUR URL>')
k.set_api_key(api_key_file='kawa.key')
df = k.get_usage_stats(
   from_date=date(2023, 2, 1), 
   to_date=date(2023,3,1), 
   tz='Europe/London')

The get_usage_stats methods takes three optional inputs that you can use to restrict the period on which you want to retrieve statistics.

It gives, per user, the following data:

  • The number of workspaces that the user owns (Does not depend on the time window)
  • The number of sheets that the user owns (Does not depend on the time window)
  • The number of data sources that the user owns (Does not depend on the time window)
  • How many computations were done within the time window
  • How many write operations were done within the time window
  • How many python ingestions were done within the time window

⚠️ This method can take several minutes to run - it is recommended to use it outside of the periods of peak usage of the application.

7. Activate experimental features

In order to activate experimental features, contact the KAWA team to know the feature names you wish to experiment.

from kywy.client.kawa_client import KawaClient

k = KawaClient(kawa_api_url='http(s)://<YOUR URL>')
k.set_api_key(api_key_file='kawa.key')
cmd = k.commands

cmd.toggle_feature(feature_name='experimentatl-feature-name', is_enabled=True)

When enabling a feature, no redeployment is needed. The change will be taken in account immediately.

8. Configure the API server general parameters

You can use this command to change parameters of the web server:

from kywy.client.kawa_client import KawaClient

k = KawaClient(kawa_api_url='http(s)://<YOUR URL>')
k.set_api_key(api_key_file='kawa.key')
cmd = k.commands

cmd.replace_configuration(configuration_type='StandaloneApiServerConfiguration',
                          payload={
                              "port": 8080,
                              "maxThreads": 50,
                              "enabledFeatures": [
                                  'data-patching',
                                  'list-principals',
                              ],
                          })

9. Activate the KAWA platform

In order to enter your license into your platform, use the following:

cmd = k.commands
cmd.set_license(path_to_license_file='/path/to/license.json')

A License file will be provided to you by the KAWA team. It is a JSON file similar to this one:

{
    "mainContactEmailAddress": "emmanuel@kawa.ai",
    "licenseDescription": "dev platform license",
    "licenceId": "KAWA-DEV",
    "companyName": "KAWA Analytics",
    "gracePeriodInDays": 30,
    "from": "2023-01-01",
    "to": "2023-12-30",
    "base64Signature": "****"
}

The validity of the license extends from the from date to the to date in the license file. Once the to date is passed, the software will still work for gracePeriodInDays days. After that interval, users will still be able to login and open their assets. All computations will be blocked.

Contact support@kawa.ai for more information about licensing.

📌

This guide should be used when working on the on-premise version of KAWA. All those features are available only for users with the ADMIN privileges. This applies to on premise instances of KAWA only.