Generalized Documents

This document provides step-by-step instructions for enabling functionality to manage documents as configuration items in Ketryx. This allows documents to leverage the robust configuration item system within Ketryx, which includes features like custom fields and custom relations.

It also includes important notes and considerations to ensure correct setup and usage.

To enable this capability, Ketryx support must activate the following feature flag: Documents as Items

Organization-level advanced settings:

Add the following configuration under Custom item types

[
  {
    "name": "Long-Lived Document",
    "fields": [
      {
        "kind": "SYSTEM",
        "fieldKey": "description",
        "isEditableInKetryx": true
      },
      {
        "kind": "SYSTEM",
        "fieldKey": "introducedInVersion",
        "isEditableInKetryx": true
      },
      {
        "kind": "SYSTEM",
        "fieldKey": "obsoleteInVersion",
        "isEditableInKetryx": true
      }
    ],
    "category": "DOCUMENT",
    "lifecycle": "LONG_LIVED",
    "shortName": "LLD",
    "isEditableInKetryx": true
  },
  {
    "name": "Pointwise Document",
    "fields": [
      {
        "kind": "SYSTEM",
        "fieldKey": "description",
        "isEditableInKetryx": true
      },
      {
        "kind": "SYSTEM",
        "fieldKey": "introducedInVersion",
        "isEditableInKetryx": true
      }
    ],
    "category": "DOCUMENT",
    "lifecycle": "POINT_WISE",
    "shortName": "PD",
    "isEditableInKetryx": true
  }
]

Enable documents as items

Navigate to the organization's advanced settings, scroll down and select “Yes” for the enable documents as items option

Verify configuration

1. Navigate to the Documents page

2. Upload or create a new document

3. Click the Edit button in the upper left corner

4. You will be able to see an option to select one of the three document types: Document / Long-lived Document / Pointwise Document

Adding a custom relation

A standard relation can be used from any other item type. However, if you want the relation to be accessible directly from the document itself, you must create custom relations from the document.

To enable this capability, Ketryx support must activate the following feature flag: Custom Relations.

Organization-level advanced settings:

Add the following configuration under Custom relations:

{
  "DOC_CR": {
    "direction": "downstream",
    "fieldName": "Is impacted by",
    "relationName": "relates to CR",
    "sourceItemTypes": [
      "Long-Lived Document",
      "Pointwise Document"
    ],
    "reverseFieldName": "Is related to document",
    "targetItemFilter": "type:CR",
    "reverseRelationName": "relates to doc",
    "traceabilityWidgetAddLabel": "Add related change request"
  },
  "DOC_USES_RQ": {
    "direction": "upstream",
    "fieldName": "Is related to requirement",
    "relationName": "relates to RQ",
    "sourceItemTypes": [
      "Long-Lived Document",
      "Pointwise Document"
    ],
    "reverseFieldName": "Is related to document",
    "targetItemFilter": "type:RQ",
    "reverseRelationName": "relates to doc",
    "traceabilityWidgetAddLabel": "Add related requirement"
  }
}

Note: To link a document to any specific type of item (e.g., a change request), you need to configure custom relations tailored for each item type.

Next steps

1. Choosing one of the options: Long-lived Document or Pointwise Document

   1. Only users who have the "Control documents" permission (Organization level) can change the document type.

2. Choose the custom relations that you want to create

Adding a custom field

Organization-level advanced settings:

For any custom field, you need to:

1. Add a Custom Item Fields Configuration.

2. Add the relevant Item Fields.

3. Add a ‘custom’ section under Custom Item Types

Add the following configuration under the custom item fields configuration

{
  "Extra ID": {
    "type": "SHORT_TEXT",
    "isEditableInKetryx": true,
    "syncToExternalSystem": true
  }
}

Note: You can choose different types of custom fields by using this guide.

Add the following configuration under item fields:

{
  "Long-Lived Document": {
    "addedFields": [
      {
        "kind": "CUSTOM",
        "name": "Extra ID"
      }
    ]
  },
  "Pointwise Document": {
    "addedFields": [
      {
        "kind": "CUSTOM",
        "name": "Extra ID"
      }
    ]
  }
}

Add the following configuration under Custom item types

[
  {
    "name": "Long-Lived Document",
    "fields": [
      {
        "kind": "CUSTOM",
        "name": "Extra ID",
        "isEditableInKetryx": true
      }
    ],
    "category": "DOCUMENT",
    "lifecycle": "LONG_LIVED",
    "shortName": "LLD",
    "isEditableInKetryx": true
  },
  {
    "name": "Pointwise Document",
    "fields": [
      {
        "kind": "CUSTOM",
        "name": "Extra ID",
        "isEditableInKetryx": true
      }
    ],
    "category": "DOCUMENT",
    "lifecycle": "POINT_WISE",
    "shortName": "PD",
    "isEditableInKetryx": true
  }
]

Clarifications

• Bulk Upload of Documents and Custom Fields: It is possible to upload multiple documents simultaneously. However, custom fields cannot be included during the bulk upload process. These fields must be added manually after the upload is complete.

• Commenting on Documents: Similar to other configuration items in Ketryx, documents support comments. Please refer to this link for additional details.

• Folder Structure Impact: The folder structure used for organizing documents has no effect on their functionality or behavior within the system.

• Cross-Referencing Between Projects: Currently, cross-referencing documents across different projects is not supported. This functionality is expected to be introduced in a future update.