Administration guide

The ADMIN menu allows administrators to manage:

  • Group and user permissions
  • Bug tracking systems
  • and more …

Kiwi TCMS admin interface is automatically generated by Django and allows the user to add, edit and delete records in the database.

The Administration screen

Configure external bug trackers

One of the first steps when working with Kiwi TCMS is to configure bug tracking systems. This can be done via the interface located at ADMIN -> Everything else -> Test cases -> Bug trackers. Each bug tracker is given a name, URL, API credentials and integration type. The extent of integration with 3rd party bug tracking systems is documented in tcms.issuetracker.


External bug tracker integration classes are defined as a dotted path list in the EXTERNAL_BUG_TRACKERS setting, see Kiwi TCMS configuration settings. Plugins and Kiwi TCMS admins may override this setting to provide more control and customized integration.

New in version 8.5.


Details on what each field means can be found at tcms.testcases.models.BugSystem. Integration details for supported bug trackers can be found at tcms.issuetracker.types! Please read these sections carefully before configuring integration with external bug tracking systems!


Kiwi TCMS comes with its own internal bug tracker. This is designed as a light-weight solution for small teams. In case you are already using an external defect tracking system like Bugzilla you may disable the internal one by defining KIWI_DISABLE_BUGTRACKER=yes in your environment variables!

New in version 8.4.

Managing permissions

The Auth administration section covers Groups and Users.

The Auth screen


Kiwi TCMS uses groups to manage access to parts of the system. Groups have two fields: name and permissions. By default there are two groups created

  • Administrator - has all available permissions;
  • Tester - has add, change and delete permissions from the attachments, bugs, django_comments, management, linkreference, testcases, testplans and testruns applications.

Adding a group

A group requires a name and a set of permissions.

Procedure: Adding a group

To add a group:

  1. From the ADMIN menu, click Users and groups.

    The Admin menu 1

  2. Click Groups, then click Add Group.

    The Add group link

  3. In the add group screen, perform the following actions:

    • Enter the Name for the group.
    • From Available permissions, select the Group’s permissions.
  4. Click Add.

    The Add Group button

    The Chosen permissions list is updated.

  5. Click Save.

Editing a group

The group name can be changed. Permissions can be added or removed.

Procedure: Editing a group

To edit a group:

  1. From the ADMIN menu, click Users and groups.
  2. Click Groups.
  3. From the Group list, click the group to edit.
  4. Select the permission required. Click Add or Remove as required.
  5. Click Save.


Assigning administrator rights

A user with administrator rights can access the ADMIN menu.

Procedure: Assigning administrator rights

To assign administrator rights:

  1. From the ADMIN menu, click Users and groups.

  2. Click Users.

  3. In the Search Bar, enter the username, and then click Search.

  4. Click the Username.

  5. In the Permissions screen, select Staff status.

    The Staff Status check box

  6. Click Save. The Staff Status icon changes to a green tick.


If the user requires full permissions, select Superuser status.

Assigning permissions

User permissions can be granted or revoked for individual components of Kiwi TCMS. All permissions are prefixed with the add_, change_ and delete_ prefixes signifying the operation which is controlled by this permission. Then the codename contains the name of the model for which this permission applies. For example, the ability to add attachments to a Test Case is controlled via the add_testcaseattachment permission.

Procedure: Assigning permissions

To assign permissions:

  1. From the ADMIN menu, click Users and groups.
  2. Click Users.
  3. In the Search Bar, enter the username, and then click Search.
  4. Click the Username.
  5. In the User permission screen:
    • To add permissions, select the permissions to be granted, and then click Add.
    • To remove permissions, select the permissions to be revoked, and then click Remove.
  6. Click Save.

Adding a user to a group

Group permissions in Kiwi TCMS work the same as they do in Linux. The system checks a user’s personal permissions, then group permissions.

Procedure: Adding a user to a group

To add a user to a group:

  1. From the ADMIN menu, click Users and groups.
  2. Click Users.
  3. In the Search Bar, enter the username, and then click Search.
  4. Click the Username.
  5. From Groups select the user to add.
  6. Click Save.

Updating personal information

Kiwi TCMS can store email, first and last name details of a user. To update personal information:

  1. From the ADMIN menu, click Users and groups.
  2. Click Users.
  3. In the Search Bar, enter the username, and then click Search.
  4. Click the Username.
  5. From Personal Information edit:
    • First Name
    • Last Name
    • Email Address
  6. Click Save.

Deleting a user


Users can be deleted from Kiwi TCMS however this will remove all database records connected to this user. A user that is no longer required must be disabled instead!

To disable a user:

  1. From the ADMIN menu, click Users and groups.

  2. Click Users.

  3. In the Search Bar, enter the username, and then click Search.

  4. Click the Username.

  5. Untick the Active checkbox.

    The Active checkbox

  6. Click Save.

Explanation of editable entities

Some DB entities are editable via the Admin interface. Their meaning is explained below.


All testing is based around products made by the organization.

Product Classifications

A Classification is a title used to group products of a similar nature. For example: Mobile apps, Desktop apps, etc.

Builds and Versions

The entity Build describes a product build used for testing. Depending on your versioning scheme and release workflow this entity may be used or not!

For example there could be an upcoming product version tagged “3.1” with several daily builds (aka smaller versions) until you are satisfied with the quality of the product before “3.1” released.

On the other hand if you release often in small increments product Version is likely the only numbering scheme that you will use. Each product in Kiwi TCMS needs a version. Many products will have multiple versions. For example, Firefox 3.0.14, 3.5.3.

Kiwi TCMS allows both Build and Version to be specified when testing. If you don’t use builds we advise you either to leave as “undefined” or use the same value as for the version being tested.


Kiwi TCMS uses tags to assign additional meta-data during testing. Tags can be assigned to TestPlan, TestCase and TestRun objects. The following permissions are taken into account:

  • management.add_tag - if missing users will not be able to auto-create tags and are instead forced to use pre-existing ones. Inside the web UI autocomplete widgets help figure out what is available. This is useful in organizations where freely creating tags is not allowed! Also controls adding new objects via admin panel. management.delete_tag - controls deleting tags from the database via admin panel
  • test{case|run|plan}.{add|delete}_test{case|run|plan}tag - control if user can assign or remove tags to test case, test run or test plan objects respectively.


A product is broken down into components. For example, two components of Kiwi TCMS are the web interface and the RPC API service. Components may be used to classify test cases that are related to particular area under test.


Test cases can be assigned a priority. The priority designation may be used to organize your testing workflow and does not have special meaning inside Kiwi TCMS.

Test Plan types

A Test Plan type is used to describe the test being performed. For example, acceptance or smoke testing, functional testing, etc.

Test Case categories

A test case category may be used to further describe the type of test being performed or convey additional information about the test case. Similar information may also be conveyed with tags, properties or in other way so it is up to you to decide how you want to organize your testing workflow!

Test Execution statuses

New in version 8.0.

As shown in Data organization within Kiwi TCMS TestExecution objects record the status for each TestCase tied to a particular TestRun. Kiwi TCMS installs several pre-configured statuses by default. Starting with v8.0 you can fully customize them!

For this purpose the following fields are available:

  • Name - human readable status name


    For statuses shipped with Kiwi TCMS the names may appear translated into local language! If you change these default names they will appear untranslated!

    Translation of non-default names is currently not straight forward, see

  • Color - a color to be used for icons, charts, etc.


    For a consistent user experience we recommend using colors of the same family (or even the same color) for the various weight categories - green for Positive, black/gray for Neutral and red for Negative!

  • Icon - a CSS class to be used for visual display. The accepted value is any valid class name from Font Awesome v4.7 or Patternfly v3.0


    Icons must be specified with their full CSS class name. For example PASSED is fa fa-check-circle-o!

  • Weight - integer representation of this status


    Kiwi TCMS recognizes only 3 weight categories:

    • Positive - PASSED and WAIVED - test completed and was successfull or was skipped/ignored on purpose
    • Neutral - IDLE, PAUSED and RUNNING - test has not been executed yet and the result is unknown
    • Negative - BLOCKED, ERROR and FAILED - test completed unsuccessfully or was not able to complete due to external factors

    Kiwi TCMS does not make any other distinction based on weight except when sorting statuses for display (e.g. a row of buttons)! It is up to you to define what each individual status means.


    Make sure to always have at least 1 positive, 1 negative and 1 nautral status, e.g. PASSED, IDLE, FAILED. If you delete all statuses within a certain weight group Kiwi TCMS will crash!