Custom Item Types

Reference of the custom item types feature in Ketryx

Ketryx enables the tracking of arbitrary item types using the Custom Item Types feature. These item types can be either long-lived or point-wise (explained here) and they will behave in the exact same way as the default item types (e.g. Requirement) would.

NOTES:

• Adding custom item types should only be performed by your Ketryx organization owner and Jira instance admin.

• After adding a custom item type, it is not recommended to change its lifecycle afterwards.

Getting started

The following will explain the full workflow for configuring a custom long-lived item type called Folder in both Ketryx and Jira. The steps assume that a project called Test Project exists in both systems.

Configuration in Ketryx

1. Navigate to Organization > Advanced

2. Add the Folder item type into the Custom item types setting:

[
  {
    "lifecycle": "LONG_LIVED",
    "name": "Folder",
    "shortName": "FOL",
    "isEditableInKetryx": true,
    "fields": [
       { "kind": "SYSTEM", "fieldKey": "description", "isEditableInKetryx": true },
       { "kind": "SYSTEM", "fieldKey": "introducedInVersion", "isEditableInKetryx": true },
       { "kind": "SYSTEM", "fieldKey": "obsoleteInVersion", "isEditableInKetryx": true },
       { "kind": "SYSTEM", "fieldKey": "implementedItems", "isEditableInKetryx": true },
       { "kind": "SYSTEM", "fieldKey": "relatedItems", "isEditableInKetryx": true }
    ]
  }
]

1. Add the Folder item type into the Issue mapping setting (this can also be done in a specific project's advanced settings):

[
  {
    "issueType": "Folder",
    "itemType": "CUSTOM",
    "itemTypeName": "Folder"
  }
]

1. Click Save changes and confirm

At this point, every project in the Ketryx organization is ready to track Folder items from Jira. However, Ketryx does not assign any approval groups to custom item types by default. Therefore, it is recommended to configure the approval groups accordingly.

1. Navigate to Projects > Test Project > Settings > Approval rules

2. Add approval groups for the Folder item type

Configuration in Jira

It is considered a best practice to copy the default Ketryx schemes (Work type scheme and Work type screen scheme) into new ones instead of modifying the default ones.

NOTE: If the aforementioned Ketryx-specific schemes have already been copied for your project, you can directly edit them instead of copying them again.

1. Create a new work type. This will introduce a new item type that can be used in Jira and Ketryx. Click the cogwheel button in the top right and navigate to Jira Settings > Work items. From the left-hand menu, navigate to Work types

   
2. Click Add work type

   1. Name: Folder

      1. Type: Standard Issue Type (Level 0)

      2. Click Add

3. Update the work type scheme. This will make sure that the new work type is available in your project by adding it to a copy of the issue type scheme. From the left-hand menu, navigate to Work type schemes

   1. Filter for "ketryx" and click the "..." button next to the scheme assigned to your project (in most cases, it will be Ketryx issue type scheme)

   2. Click Copy

      1. Give the scheme a descriptive name, such as "Ketryx issue type scheme (Test Project)"

      2. Empty the Description field

      3. Drag-and-drop the Folder issue type from Available Work Types into Work Types for Current Scheme

      4. Click Save

4. Create a new screen. This will define what fields are shown when someone creates, views, or edits the work item.

   1. From the left-hand menu, navigate to Screens

      1. Filter for "ketryx task" and click the "..." button for Ketryx Task screen (the Task work type is a good default to base a new screen configuration on)

         1. Click Copy

            1. Give the screen a descriptive name, such as "Ketryx Folder screen"

            2. Empty the Description field

            3. Click Copy

         2. The following steps are only required for long-lived item types:

            1. Filter for "ketryx folder" and click the "..." button for Ketryx Folder screen

            2. Click Configure

               1. Add the Obsolete in version field

5. Create a screen scheme. This will associate your new screen with the new work type

   1. From the left-hand menu, navigate to Screen schemes

      1. Click Add screen scheme

         1. Give the screen scheme a descriptive name, such as "Ketryx Folder screen scheme"

            1. Default Screen: Ketryx Folder screen

            2. Click Add

6. Update the Work Type Screen Scheme. This will connect your new work type to the screen scheme you just created, so Jira knows what layout to use.

   1. From the left-hand menu, navigate to Work type screen schemes

      1. Filter for "ketryx" and click the "..." button for Ketryx issue type screen scheme

         1. Click Copy

            1. Give the issue type screen scheme a descriptive name, such as "Ketryx issue type screen scheme (Test Project)"

            2. Empty the Description field

            3. Click Copy

         2. Filter for "ketryx" and click the "..." button for Ketryx issue type screen scheme (Test Project)

         3. Click Configure

            1. Click Associate an issue type with a screen scheme

               1. Issue Type: Folder

               2. Screen Scheme: Ketryx Folder screen scheme

               3. Click Add

7. Assign the new schemes to your project. This will apply your new configurations to the project so the new work type and screen are available to users.

   1. Click the cogwheel button in the top right and navigate to Jira Settings > Projects

      1. Click the "..." button for Test Project

         1. Click Project settings

   2. From the left-hand menu, navigate to All work > Types

      1. Click Actions > Use a different scheme

         1. Select Ketryx issue type scheme (Test Project)

         2. Click OK

   3. From the left-hand menu, navigate to All work > Screens

      1. Click Actions > Use a different scheme

      2. Select Ketryx issue type screen scheme (Test Project)

      3. Click Associate

8. From the left-hand menu, navigate to Work types

   1. Click Add Work type

      1. Name: Folder

      2. Type: Standard Work Type (Level 0)

      3. Click Add

9. From the left-hand menu, navigate to Work type schemes

   1. Filter for "ketryx" and click the "..." button next to the scheme assigned to your project (in most cases, it will be Ketryx work type scheme)

   2. Click Copy

      1. Give the scheme a descriptive name, such as "Ketryx work type scheme (Test Project)"

      2. Empty the Description field

      3. Drag-and-drop the Folder work type from Available Work Types into Work Types for Current Scheme

      4. Click Save

10. From the left-hand menu, navigate to Screens

    1. Filter for "ketryx task" and click the "..." button for Ketryx Task screen (the Task item type is a good default to base a new screen configuration on)

    2. Click Copy

       1. Give the screen a descriptive name, such as "Ketryx Folder screen"

       2. Empty the Description field

       3. Click Save

    3. The following steps are only required for long-lived item types:

       1. Filter for "ketryx folder" and click the "..." button for Ketryx Folder screen

       2. Click Configure

          1. Add the Obsolete in version field

11. From the left-hand menu, navigate to Screen schemes

    1. Click Add screen scheme

       1. Give the screen scheme a descriptive name, such as "Ketryx Folder screen scheme"

       2. Default Screen: Ketryx Folder screen

       3. Click Add

12. From the left-hand menu, navigate to Work type screen schemes

    1. Filter for "ketryx" and click the "..." button for Ketryx work type screen scheme

    2. Click Copy

       1. Give the work type screen scheme a descriptive name, such as "Ketryx work type screen scheme (Test Project)"

       2. Empty the Description field

       3. Click Copy

    3. Filter for "ketryx" and click the "..." button for Ketryx work type screen scheme (Test Project)

    4. Click Configure

       1. Click Associate an work type with a screen scheme

          1. Work Type: Folder

          2. Screen Scheme: Ketryx Folder screen scheme

          3. Click Add

13. Click the cogwheel button in the top right and navigate to Jira Settings > Projects

    1. Click the "..." button for Test Project

    2. Click Project settings

14. From the left-hand menu, navigate to Work items > Types

    1. Click Actions > Use a different scheme

    2. Select Ketryx work type scheme (Test Project)

    3. Click OK

15. From the left-hand menu, navigate to Work items > Screens

16. Click Actions > Use a different scheme

17. Select Ketryx work type screen scheme (Test Project)

18. Click Associate

Now, both the Jira and Ketryx projects are configured to track Folder items.