Object Customization

DevRev’s customization framework offers workspace admins the ability to customize DevRev objects to your organization’s needs. Extend entities in your DevRev workspace by adding new custom fields or defining new subtypes from existing objects.

Glossary

1. Leaf type: A DevRev object type. For example, issue, ticket.
2. Subtype: A flavor of a leaf type. For example, incident can be a subtype of issue.

Customization options

Tenant custom fields

Use tenant custom fields to extend a DevRev object type with new fields that apply to all records of the object type in your application workspace.

Subtypes

Use subtypes to create specific flavors of a DevRev object type that includes an additional fieldset and stock fields on the object type. Once subtypes are defined, your application can maintain records of the original object type, and optionally a subtype with its defined fields.

Concepts

Schema fragments

Objects in DevRev are customized with “schema fragments”. When an object record is created or updated, multiple such schema fragments can be mixed to define the aggregate custom fields available to that record.

Multiple object records can reference the same fragment specifying a set of custom fields.

Custom schema fragments are immutable, and thus updating a fragment means creating a new one.

Two older objects (1 and 2) and one newer object referencing different fragment versions.

References

References to each fragment describing the object fields are stored with the object. An object can contain references to a subtype fragment and a tenant fragment.

Prefixing

Fields defined by different schema fragments are held in different namespaces in an object. Stock fields, subtype fields, tenant custom fields, and app custom fields live in their respective namespaces to prevent field name conflicts. Specifically:

1. Names for tenant custom fields are in the form tnt__<name>.
2. Names for subtype custom fields are of the form ctype__<name>.

For illustration, a fully populated object might look like this:

1
{
2
    "id": "don:core:dvrv-us-1:devo/test:issue/1",
3
    "dev_oid": "don:identity:dvrv-us-1:devo/test",
4
    ... // other stock fields
5
6
    // references to schema fragments used
7
    "schema_fragments": [
8
        "don:core:dvrv-us-1:devo/test:tenant_fragment/1"
9
        "don:core:dvrv-us-1:devo/test:custom_type_fragment/1",
10
    ],
11
12
    // map of custom fields
13
    "custom_fields": {
14
        "tnt__field_1": 1234,
15
        "tnt__field_2": "enterprise custom data",
16
        "ctype__field_1": 5678
17
        ...
18
    }
19
}

Using the APIs for customization

Creating a custom schema fragment

An example usage of custom fields is to extend the DevRev schema for ticket to track incidents across various environments (dev, QA, prod). This can be done by creating a subtype called “Incident”. The following API call describes the custom attributes introduced by the subtype.

1
curl --location 'https://api.devrev.ai/schemas.custom.set' \
2
--header 'Content-Type: application/json' \
3
--header 'Accept: application/json' \
4
--header 'X-Devrev-Scope: beta' \
5
--header 'Authorization: <TOKEN>' \
6
--data '{
7
    "type": "custom_type_fragment",
8
    "description": "Attributes for tracking an incident",
9
    "leaf_type": "ticket",
10
    "subtype": "Incident",
11
    "fields": [
12
        {
13
            "field_type": "enum",
14
            "allowed_values": [
15
                "Yes",
16
                "No"
17
            ],
18
            "is_filterable": true,
19
            "name": "regression",
20
            "is_required": true,
21
            "default_value": "No",
22
            "ui": {
23
                "display_name": "Regression",
24
            }
25
        },
26
        {
27
            "field_type": "text",
28
            "name": "pia",
29
            "ui": {
30
                "display_name": "PIA",
31
            }
32
        },
33
        {
34
            "field_type": "array",
35
            "base_type": "enum",
36
            "allowed_values": [
37
                "Dev",
38
                "QA",
39
                "Prod"
40
            ],
41
            "name": "impacted_environments",
42
            "ui": {
43
                "display_name": "Impacted Environments",
44
            }
45
        }
46
    ]
47
}'

Supported custom field types

The following custom field types are supported -

The list variants of all the supported custom field types are also supported ([]tokens, []text, etc).

Deprecating a custom schema fragment

Custom schema fragments can be marked as deprecated to avoid creating work items with them. The following POST request payload can be used for the same.

1
{
2
    "type": "custom_type_fragment",
3
    "description": "Attributes for tracking an incident",
4
    "leaf_type": "ticket",
5
    "subtype": "Incident",
6
    "fields": [
7
        ...
8
    ],
9
    "deprecated": true,
10
}

Listing custom schema fragments

To verify the result of the above API invocation, you can list the custom schema fragments in the org:

1
curl --location 'https://api.devrev.ai/schemas.custom.list' \
2
--header 'Accept: application/json' \
3
--header 'X-Devrev-Scope: beta' \
4
--header 'Authorization: <TOKEN>'

Deprecated fragments aren’t returned when listing custom schema fragments.