Administration UI guide

This guide explains how to manage users and develop applications in Kaa Admin UI.

This guide assumes that Kaa has already been installed and Admin UI is available from the web. If it's not the case, look at the Installation guide for more info, or at the Sandbox guide in case you use Kaa Sandbox.

First registration

The first time you log in to Kaa Admin UI, it is required that you register as a Kaa admin.

Kaa user types

The following three user types are available in Kaa:

• Kaa admin
• Tenant admin
• Tenant developer

NOTE
In Kaa Sandbox, default credentials are provided for all three types of Kaa users.

Kaa admin

The Kaa admin is the highest level administrator of Kaa. He is able to create, edit, and delete tenant admins. 

To log into the Kaa UI as a Kaa admin, use the previously created username/password for the Kaa admin.

To customize the account, click Settings => Profile in the upper right corner of the window and change the first/last name and e-mail to the private ones. Click Save to apply the changes.
Note that Email is a mandatory field.

To set a private password, click Settings => Change password and fill in the fields as required.

Configuring general settings

The General settings window allows you to configure the application title and application base URL parameters. These parameters are used for sending email notifications to registered users.

To customize the general settings, click Settings => General settings and fill in the fields as required.

Configuring outgoing mail settings

Outgoing mail settings are used to send emails to newly created users with the information about their passwords, as well as for sending other notifications.

To customize the outgoing mail settings, click Settings => Outgoing mail settings and fill in the fields according to your SMTP mail server configuration.

Managing tenant admins

The Tenants window, which is the starting window for a Kaa admin, displays a list of tenant admins. A Kaa admin can edit a tenant admin's name/e-mail and delete tenant admins from the system.

To view a tenant admin's details, select the tenant admin either from the list or from the navigation panel on the left side.

To create a new tenant admin, click Add tenant and then fill in all the required fields. Click Add to apply the changes.

The newly created tenant admin will receive an e-mail with his or her login to Kaa web UI credentials window.

Managing System CTL

The System CTL window displays a list of CTs with the system scope. The Kaa admin can add new system CTs and delete system CTs.

To create a new system CT, click Add new type and then fill in all the required fields. Click Add to apply the changes.

To view a system CT, open the CT details window by clicking the row in the list in the System CTL window.

To view another version of the system CT, click on the version drop-down and select the appropriate version.

To create a new version of the system CT of the same FQN, click Create new version at the top of CT details window.

To export the system CT, click Export and select export method from drop-down. See CT schema export support for available export methods details.

To delete the system CT version, click Delete at the top of the CT details window.

Tenant admin

The tenant admin is a Kaa user who is responsible for managing applications, users and event class families.

To log into the Admin UI as a tenant admin, use the previously generated username/password for the tenant admin.

To customize the account, click Settings => Profile and change the first/last name and e-mail to private ones.

To set a private password, click Settings => Change password and fill in the fields as required.

Managing applications

As a tenant admin, you can add and edit applications.

To create a new application, do the following:

1. Open the Applications window by clicking the corresponding link on the navigation panel.
   
2. Click Add application at the top of the window.
3. Enter the title of your application and then click Add.
   

NOTE: If you open the Application details window of the newly created application (by clicking this application on either the Applications menu on the navigation panel or the Applications window), you will notice that the Application Token field has been filled in automatically. This is a unique auto-generated application ID.

To edit the application, open the Application details window by clicking the application name either on the navigation panel or in the list in the Applications window.

Managing users

The tenant admin can add, edit and delete users.

To add a user, do the following:

1. Open to the Users window and click Add user. 
   
2. In the Add user window, enter the username and email.
3. In the Account role field, select Tenant developer.
   

To edit a user's profile, open the User details window by clicking the user's name either on the navigation panel or in the list in the Users window..

To delete a user, open the Users window and click Delete next to the user's name.

Managing event class families

To use the Kaa events feature for one or more applications, the tenant admin should create an event class family (ECF). Each ECF should be described using the Avro format.  

To create a new ECF, do the following:

1. Open the Event class families window by clicking the corresponding link on the navigation panel.
2. In the Event class families window, click Add ECF.
   
3. In the Add ECF window, fill in all the required fields and then click Add.
   NOTE: the namespace and class name values should be unique.
   
4. In the Event class family window, add (optionally) an ECF schema by clicking Add schema under the Schemas table.
   
5. In the Add event class family schema window, create an ECF schema either by using the Event class family schema schema form or by uploading the schema from a file, then click Add.
   NOTE: More than one schema can be added to an ECF.
   NOTE: If uploaded from a file, a schema(s) should be written in the Avro format and describe how event classes should be grouped depending on subject areas.
   
   A unique version number is assigned to a schema after its creation and then the schema appears as a clickable line in the Schemas table. To review the ECF schema details, click the appropriate schema line in the Schemas table. Each schema automatically splits into event classes. A full qualifier name, schema and type are shown for each event class in the table with the same name.

Managing Tenant CTL

The Tenant CTL window displays a list of CTs with the tenant and system scopes. The tenant admin can add new tenant CTs and delete tenant CTs from the system. It has read-only access to the system CTs.

To display/hide higher scopes of CTs, check/uncheck Display higher scopes.

To create a new tenant CT, click Add new type and then fill in all the required fields. Click Add to apply the changes.

To view a CT, open the CT details window by clicking the row in the list in the Tenant CTL window.

To view another version of the CT, click on the version drop-down and select the appropriate version.

To create a new version of the tenant CT of the same FQN, click Create new version at the top of the CT details window.

To export the CT, click Export and select an export method from the drop-down list. See CT schema export support for available export methods details.

To delete the tenant CT version, click Delete at the top of the CT details window.

Tenant developer

The tenant developer is a user that creates SDKs based on customer requirements. Tenant developers set the Kaa schemas, group endpoints, and control notification processes.

To log into the Kaa UI as a tenant developer, use the previously generated credentials for the tenant developer.

To customize this account, click Settings => Profile and change the first/last name and e-mail to private ones.

To set a private password, click Settings => Change password.

NOTE: A tenant developer is able to work only with those applications which have been created by his tenant admin. The list of available applications is displayed in the Applications window, as well as on the navigation panel under the Applications menu.

SDK profiles

Each SDK instance in Kaa is based on the SDK profile – a template which is used to generate SDK instances for different target platforms. This template must be created by the tenant developer as the first step of the application development process.

Viewing SDK profiles

To view a list of the SDK profiles already created for the application, open the SDK profiles window either from the navigation panel or by clicking Generate SDK in the application view.

To view some SDK profile in detail, open the SDK profile window by clicking on the profile from the list.

Creating SDK profiles

To create an SDK profile for the application, do the following:

1. Select the application under the Applications menu on the navigation panel.
2. In the Application details window, click Generate SDK.
3. In the SDK profiles window, click Add SDK profile.
4. In the Add SDK profile window, provide a name and select schema versions for the SDK profile.
5. To use the Kaa event feature, add one or more event class families and specify a user verifier.
6. Click Add at the top of the window to finish creating the SDK profile.

Once created, the SDK profile cannot be changed. However, unused or erroneous SDK profiles can be deleted by clicking on the Delete icon.

SDK token

Each SDK profile has a unique SDK token associated with it. These tokens are generated from the SDK profile's raw data using SHA-1 algorithm and then encoded in URL-safe Base64.

Generating endpoint SDK

To generate the SDK instance from the SDK profile, open the SDK profiles window, then click on the Generate SDK icon next to the selected SDK profile, select the target platform, and click Generate SDK.

The resulting file will contain the appropriate SDK token as a part of its name.

Adding shemas

In Kaa, an SDK for an application is generated based on the following five schemas: client-side endpoint profile, server-side endpoint profile, configuration, notification, and log. Every application has default schemas, which can be accessed from the Schema submenu in the corresponding application menu on the navigation panel.

Client-side endpoint profile schema

The list of client-side endpoint profile schemas created by a tenant developer for the application is shown in the Client-side EP profile schemas window, which can be opened from the application menu on the navigation panel as illustrated by the following screenshot.

To export the client-side EP profile schema, click Export in the last column of desired schema row and select export method from drop-down. See CT schema export support for available export methods details.

As a tenant developer, you can create new client-side EP schemas for the application as follows:

1. In the Client-side EP profile schemas window for the application, click Add schema.
2. In the Add profile schema window enter the name of the schema.
3. Then create a schema using one of the two options:
   
   1. Using the existing CT by clicking Select existing type and selecting exiting CT version from FQN and version drop-downs.
      
   2. Create new CT by clicking Create new type. In this case you will be redirected to Add new type window. Here you can create a schema either by using the schema form or by uploading a schema in the Avro format from a file.
      
4. Click Add at the top of the window to save the schema.

If you want to review the added Avro schema, open the corresponding Client-side EP profile schema window by clicking the schema in the Client-side EP profile schemas window.

Server-side endpoint profile schema

The list of server-side endpoint profile schemas created by a tenant developer for the application is shown in the Server-side EP profile schemas window, which can be opened from the application menu on the navigation panel as illustrated by the following screenshot.

To export the server-side EP profile schema, click Export in the last column of desired schema row and select export method from drop-down. See CT schema export support for available export methods details.

As a tenant developer, you can create new server-side EP schemas for the application as follows:

1. In the Server-side EP profile schemas window for the application, click Add schema.
2. In the Add profile schema window enter the name of the schema.
3. Then create a schema using one of the two options:
   
   1. Using the existing CT by clicking Select existing type and selecting exiting CT version from FQN and version drop-downs.
      
   2. Create new CT by clicking Create new type. In this case you will be redirected to Add new type window. Here you can create a schema either by using the schema form or by uploading a schema in the Avro format from a file.
      
4. Click Add at the top of the window to save the schema.

If you want to review the added Avro schema, open the corresponding Server-side EP profile schema window by clicking the schema in the Server-side EP profile schemas window.

Configuration schema

The list of configuration schemas created by a tenant developer for the application is shown in the Configuration schemas window.

As a tenant developer, you can create new configuration schemas for the application as follows:

1. In the Configuration schemas window for the application, click Add schema.
2. In the Add configuration schema window, create a configuration schema either by using the schema form or by uploading a schema in the Avro format from a file.
   
3. Click Add to save the schema.

If you want to review the added Avro schema, open the corresponding Configuration schema window by clicking the schema in the Configuration schemas window.

Notification schema

The list of notification schemas created by a tenant developer for the application is shown in the Notification schemas window.

As a tenant developer, you can create new notification schemas for the application as follows:

1. In the Notification schemas window for the application, click Add schema.
2. In the Add notification schema window, create a notification schema either by using the schema form or by uploading a schema in the Avro format from a file.
   
3. Click Add to save the schema.

If you want to review the added Avro schema, open the corresponding Notification schema window by clicking the schema in the Notification schemas window.

Log schema

The list of log schemas created by a tenant developer for the application is shown in the Log schemas window.

As a tenant developer, you can create new log schemas for the application as follows:

1. In the Log schemas window for the application, click Add schema.
2. In the Add log schema window, create a log schema either by using the schema form or by uploading a schema in the Avro format from a file.
   
3. Click Add to save the schema.

If you want to review the added Avro schema, open the Log schema details window by clicking the schema in the Log schemas window.

Adding notification topics

Notification topics are used for grouping notifications by subject. An endpoint group will receive only those notifications which correspond to the notification topics this endpoint group is subscribed to.

To add a new notification topic to the application, do the following:

1. Open the Notification topics window by clicking Notification topics under the application menu on the navigation panel and then click Add notification topic.
   
2. Fill in all necessary fields and then click Add.
   
   

   The newly created topic will appear in the Notification topics window.
   

Sending notifications

To send a notification for the application, do the following:

1. In the Notification topics, click the mail icon next to the appropriate notification topic.
2. In the Send notification window, create a notification either by using the Notification body record form or by uploading the data in the JSON format from a file.
   NOTE: The contents of the file should match the corresponding notification schema.
   
3. Click Send to send the notification.

For example, the default sandbox notification schema structure is the following:

{
    "type": "record",
    "name": "Notification",
    "namespace": "org.kaa.config",
    "fields": [
        {
            "name": "message",
            "type": "string"
        }
    ]
}

The file with the following contents will match the default sandbox notification schema.

{"message": "Hello from Kaa!"}

Adding endpoint groups

Endpoint groups are created based on the profile filter and configuration.

To add a new endpoint group, do the following:

1. Open the Endpoint groups window by clicking Endpoint groups under the application menu on the navigation panel and then click Add endpoint group.
   
2. In the Add endpoint group window, fill in the required fields and then click Add.
   
3. In the Endpoint group window, add profile filters, configurations, and notifications topics to the group, if necessary (see the following paragraphs for instructions).
   

Add profile filter to endpoint group

To add a profile filter to the endpoint group, do the following:

1. In the Endpoint group window, click Add profile filter.
2. In the Profile filter window, select the schema version.
3. On the Draft tab, enter the description and filter body.
    
   NOTE: In order to test profile filter click Test filter. Afterwards the Test profile filter window will be displayed. Complete the endpoint and/or server profile forms and then click Test filter.
   
4. Click Save to save the profile filter.
   NOTE: You can save the data on the Draft tab and return to update it later as many times as needed until you click Activate.
5. Click Activate to activate the profile filter.
   All the specified information will be displayed on the Active tab.

Add configuration to endpoint group

To add a configuration to the endpoint group, do the following:

1. In the Endpoint group window, click Add configuration.
2. In the Configuration window, select the schema version.
3. On the Draft tab, enter the description, create the configuration using the Configuration body record form, and then click Save.
   NOTE: You can save the data on the Draft tab and return to update it later as many times as needed until you click Activate.
    
4. Click Activate to activate the configuration.
   All the specified information will be displayed on the Active tab.

Add notification topic to endpoint group

To add a notification topic to the endpoint group, do the following:

1. In the Endpoint group window, click Add notification topic. 
2. In the Add topic to endpoint group dialog, select the topic(s) and click Add.
   Now all the endpoints belonging to the current group will be subscribed to notifications on these topics.
   
   
   

Adding event family mappings

Event family mappings are used by tenant developers to set event class families for the application and determine the actions for each class family - whether an application should be a source, a sink, or both.

To view the list of ECFs which are mapped to the application, open the Event family mappings window by clicking Event family mappings under the application on the navigation panel.

To add a new mapping, do the following:

1. In the Event family mappings window, click Add family event mapping.
2. Select an appropriate ECF from the drop-down list and then set appropriate actions for each class of the family.

Updating configuration for specific user

To update configuration data for the specific user under the application, do the following:

1. Click Users >> Update configuration under the application menu on the navigation panel.
2. In the Update configuration window, specify the user id, select a configuration schema and specify a new configuration body.
3. Click Update to apply changes.
   

Adding log appenders

A tenant developer can set a log appender for a log schema depending on the data storage type. All created log appenders are displayed in the Log appenders window.

NOTE: It is possible to add several log appenders for one log schema.

File log appender

To create a log appender of the file system storage type, do the following:

1. In the Log appenders window, click Add log appender.
2. Enter the log appender name and description, select the minimum and maximum supported log schema version, and select necessary log metadata fields.
3. Set the log appender type to File.
4. Fill in other fields as required.
5. Click Add.
   

REST log appender

To create a log appender for access via REST, do the following:

1. In the Log appenders window, click Add log appender.
2. Enter the log appender name and description, select the minimum and maximum supported log schema version, and select necessary log metadata fields.
3. Set the log appender type to REST.
4. Fill in other fields as required.
5. Click Add.
   

MongoDB log appender

To create a log appender of the MongoDB storage type, do the following:

1. In the Log appenders window, click Add log appender.
2. Enter the log appender name and description, select the minimum and maximum supported log schema version, and select necessary log metadata fields.
3. Set the log appender type to Mongo.
4. Fill in the Mongo log appender configuration form.
5. Click Add.
   

Flume log appender

To create a log appender which will be integrated with Hadoop or Spark, do the following:

1. In the Log appenders window, click Add log appender.
2. Enter the log appender name and description, select the minimum and maximum supported log schema version, and select necessary log metadata fields.
3. Set the log appender type to Flume.
4. Fill in the Flume log appender configuration form.
   NOTE: Flume log appenders can have either prioritized or round robin host balancing.
5. For the prioritized host balancing, add the number of hosts which is equal to the number of Flume nodes. For every host, enter the host address, port and priority. The highest priority is 1. When choosing a server to which to save logs, an endpoint will send requests to the servers starting from the server with the highest priority.
   
6. For round robin host balancing, add the number of hosts which is equal to the number of Flume nodes. For every host, enter the host address and port. When choosing a server to which to save logs, an endpoint will send requests to the servers according to the round robin algorithm.
   
7. Click Add.

CDAP log appender

To create a log appender which will be integrated with CDAP, do the following:

1. In the Log appenders window, click Add log appender.
2. Enter the log appender name and description, select the minimum and maximum supported log schema version, and select necessary log metadata fields.
3. Set the log appender type to Cdap.
4. Fill in the CDAP log appender configuration form.
5. Click Add.
   

Oracle NoSQL log appender

To create a log appender of the Oracle NoSQL key/value storage type, do the following:

1. In the Log appenders window, click Add log appender.
2. Enter the log appender name and description, select the minimum and maximum supported schema version, select necessary log metadata fields.
3. Set the log appender type to Oracle NoSQL.
4. Fill in the Oracle NoSQL log appender configuration form.
5. Click Add.
   

Cassandra log appender

To create a log appender of the Cassandra storage type, do the following:

1. In the Log appenders window, click Add log appender.
2. Enter the log appender name and description, select the minimum and maximum supported schema version, select necessary log metadata fields.
3. Set the log appender type to Cassandra.
4. Fill in the Cassandra log appender configuration form.
5. Click Add.
   

Kafka log appender

To create a log appender of the Kafka storage type, do the following:

1. In the Log appenders window, click Add log appender.
2. Enter the log appender name and description, select the minimum and maximum supported schema version, select necessary log metadata fields.
3. Set the log appender type to Kafka.
4. Fill in the Kafka log appender configuration form.
5. Click Add.
   

Couchbase log appender

To create a log appender of the Couchbase storage type, do the following:

1. In the Log appenders window, click Add log appender.
2. Enter the log appender name and description, select the minimum and maximum supported schema version, select necessary log metadata fields.
3. Set the log appender type to Couchbase.
4. Fill in the Couchbase server list and other fields.
5. Click Add.
   

Adding user verifiers

Each SDK can be configured to use a default user verifier. All created user verifiers are displayed in the User verifiers window.

Trustful verifier

To create a trustful user verifier, do the following:

1. In the User verifiers window, click Add user verifier.
2. Enter the user verifier name and description.
3. Set the user verifier type to Trustful verifier.

4. Click Add.
   

Facebook verifier

To create a Facebook user verifier, do the following:

1. In the User verifiers window, click Add user verifier.
2. Enter the user verifier name and description.
3. Set the user verifier type to Facebook verifier.
4. Fill in the Facebook verifier form, specifying the Facebook application id, application secret and maximum number of allowed connections per verifier.

5. Click Add.
   

Google+ verifier

To create a Google+ user verifier, do the following:

1. In the User verifiers window, click Add user verifier.
2. Enter the user verifier name and description.
3. Set the user verifier type to Google+ verifier.
4. Fill in the Google+ verifier form, specifying the minimum and maximum number of allowed connections per verifier, and the time in milliseconds to keep a connection alive.

5. Click Add.
   

Twitter verifier

To create a Twitter user verifier, do the following:

1. In the User verifiers window, click Add user verifier.
2. Enter the user verifier name and description.
3. Set the user verifier type to Twitter verifier.
4. Fill in the Twitter verifier form, specifying the Twitter application consumer key, consumer secret, and the maximum number of allowed connections per verifier.

5. Click Add.

   

Managing endpoint profiles

To retrieve information on a specific client-side and server-side endpoint profiles, do the following:

1. Under the target application on the navigation panel, click Endpoint profiles.
   

   

2. In the Endpoint profiles window, use the Endpoint group and the Endpoint KeyHash filters to limit the scope of endpoint profiles to display.
   
   
   
   
3. To view a detailed information for a specific client-side and server-side endpoint profile, open the corresponding Endpoint profile window by clicking on a profile from the list.
   

   

4. To download client-side or server-side endpoint profiles JSONs click corresponding "Download JSON" button.

Managing Application CTL

The Application CTL window displays a list of CTs of the current application, of the current tenant and all CTs with system scope. The tenant developer can add new application CTs and delete application CTs from the system. It has read-only access to the system CTs and to the tenant CTs within Application CTL window. Tenant developer is still able to manage tenant CTs within Tenant CTL window.

To display/hide higher scopes of CTs, check/uncheck Display higher scopes checkbox.

To create a new application CT, click Add new type and then fill in all the required fields. Click Add to apply the changes.

To view a CT, open the CT details window by clicking the row in the list in the Application CTL window.

To view another version of the CT, click on the version drop-down and select the appropriate version.

To create a new version of the application CT of the same FQN, click Create new version on the top of CT details.

To export the CT, click Export and select export method from drop-down. See CT schema export support for available export methods details.

To delete the application CT version, click Delete on the top of the CT details.

To promote the application CT from application to tenant scope, click Promote.

Managing Tenant CTL

The Tenant CTL window displays a list of CTs with tenant and system scope. The tenant developer can add new tenant CTs and delete tenant CTs from the system. It has read-only access to the system CTs.

The tenant developer has the same Tenant CTL management capabilities as the tenant admin. See Managing Tenant CTL in the Tenant admin section.

Further reading

Use the following guides and references to make the most of Kaa.

Copyright © 2014-2015, CyberVision, Inc.