Custom objects

Custom objects allow you to extend DevRev’s data model beyond the standard use-cases served by the native apps like Build and Support. Custom objects allow you to create and manage object types tailored to your specific business needs.

Key concepts

  1. Leaf type: The base type of a custom object. For example, “campaign”.
  2. Subtype: A categorization of a leaf type. For example, “promotion” or “advertising” for a “campaign” leaf type.
  3. Schema fragment: A schema fragment defines the schema for an object.
  4. Custom fields: User-defined fields that store specific data for your custom object.
  5. ID prefix: A unique prefix used to generate the display ID for the custom object. If the id_prefix is “CAMP”, the generated custom object display ID is “C-CAMP-1”. The display ID is used to identify the custom object in the UI, similar to the standard DevRev object display IDs like “ISS-001” for issues.

For more details on customization concepts, please refer to the Customization documentation.

Custom object lifecycle

Let’s say you want to manage marketing campaigns on DevRev. This guide goes through the process of creating a “Campaign” custom object with relevant fields.

All DevRev objects require a schema. First, create a schema for the “Campaign” custom object. Make sure to replace the <TOKEN> with your API token.

Create custom objects

1curl --location 'https://api.devrev.ai/schemas.custom.set' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Authorization: Bearer <TOKEN>' \
5--data '{
6    "type": "tenant_fragment",
7    "description": "Attributes for Campaign",
8    "leaf_type": "campaign",
9    "leaf_type_display_name": "Campaign",
10    "is_custom_leaf_type": true,
11    "id_prefix": "CAMP"
12    "fields": [
13        {
14            "name": "name",
15            "field_type": "tokens",
16            "description": "Name of the campaign"
17        },
18        {
19            "name": "start_date",
20            "field_type": "date",
21            "description": "Start date of the campaign"
22        },
23        {
24            "name": "end_date",
25            "field_type": "date",
26            "description": "End date of the campaign"
27        },
28        {
29            "name": "budget",
30            "field_type": "int",
31            "description": "Budget allocated for the campaign"
32        },
33        {
34            "name": "target_audience",
35            "field_type": "enum",
36            "description": "Target audience for the campaign",
37            "allowed_values": [
38                "Professionals",
39                "Students"
40            ]
41        }
42    ]
43}'

Note that for custom object schemas, is_custom_leaf_type must be set to true to differentiate it from standard DevRev object schemas.

Once the schema is created, you can create a custom object of type “Campaign”:

1curl --location 'https://api.devrev.ai/custom-objects.create' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Authorization: Bearer <TOKEN>' \
5--data '{
6    "leaf_type": "campaign",
7    "custom_schema_spec": {
8        "tenant_fragment": true
9    },
10    "custom_fields": {
11        "tnt__name": "Summer Sale 2023",
12        "tnt__start_date": "2023-06-01",
13        "tnt__end_date": "2023-08-31",
14        "tnt__budget": 10000,
15        "tnt__target_audience": "Professionals"
16    }
17}'

The response of the above API call is the ID of the custom object created.

1{
2  "custom_object": {
3    "id": "don:core:dvrv-us-1:devo/demo:custom_object/campaign/1",
4    "created_by": {...},
5    "created_date": "2024-10-01T07:02:58.958Z",
6    "modified_by": {...},
7    "modified_date": "2024-10-01T07:02:58.958Z",
8    "display_id": "C-CAMP-1",
9    "leaf_type": "campaign",
10    "stock_schema_fragment": "don:core:dvrv-us-1:stock_sf/1",
11    "custom_schema_fragments": [
12      "don:core:dvrv-us-1:devo/demo:tenant_fragment/1"
13    ],
14    "custom_fields": {
15      "tnt__name": "Summer Sale 2023",
16      "tnt__start_date": "2023-06-01",
17      "tnt__end_date": "2023-08-31",
18      "tnt__budget": 10000,
19      "tnt__target_audience": "Professionals"
20    }
21  }
22}

Note that the id field in the above response is the system generated unique ID for the custom object.

The sections below provide more details on the available API endpoints for interacting with custom objects.

Get custom objects

To get a custom object, use the custom-objects.get endpoint:

1curl --location 'https://api.devrev.ai/custom-objects.get' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Authorization: Bearer <TOKEN>' \
5--data '{
6    "id": "don:core:dvrv-us-1:devo/demo:custom_object/campaign/1"
7}'

List custom objects

To list custom objects, use the custom-objects.list endpoint:

1curl --location 'https://api.devrev.ai/custom-objects.list' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Authorization: Bearer <TOKEN>' \
5--data '{
6    "leaf_type": "campaign",
7    "filter": [
8      "eq",
9      "$custom_fields.tnt__target_audience",
10      "Young adults"
11    ]
12}'

Update custom objects

To update an existing custom object, use the custom-objects.update endpoint. The following example updates the budget of the previously created campaign custom object:

1curl --location 'https://api.devrev.ai/custom-objects.update' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Authorization: Bearer <TOKEN>' \
5--data '{
6    "id": "don:core:dvrv-us-1:devo/demo:custom_object/campaign/1",
7    "custom_fields": {
8        "tnt__budget": 15000
9    }
10}'

Delete custom objects

To delete a custom object, use the custom-objects.delete endpoint. The following example deletes the previously created campaign custom object:

1curl --location 'https://api.devrev.ai/custom-objects.delete' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Authorization: Bearer <TOKEN>' \
5--data '{
6    "id": "don:core:dvrv-us-1:devo/demo:custom_object/campaign/1"
7}'

Extended use cases

Reference custom objects in other objects

Let’s say you want to reference all the campaigns that have been run for a customer workspace. You can do so by adding a field of type “id” and “id_type: custom_object.campaign” in the account tenant schema.

1curl --location 'https://api.devrev.ai/schemas.custom.set' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Authorization: Bearer <TOKEN>' \
5--data '{
6    "type": "tenant_fragment",
7    "description": "Tenant attributes for Account",
8    "leaf_type": "account",
9    "fields": [
10        {
11            "name": "campaigns",
12            "field_type": "array",
13            "base_type": "id",
14            "id_type": [ "custom_object.campaign" ],
15        },
16        ... // other fields
17    ],
18}'

Add subtypes to custom objects

Adding subtypes to custom objects allows you to categorize and manage your custom objects more effectively. The process is the same as adding subtypes to other standard DevRev objects like issues and tickets.

Let’s say you have run different types of campaigns like social media and email marketing. You can create a subtype for each of these variants. If you want to create a campaign custom object with subtype “social_media”, you can do so as follows:

1curl --location 'https://api.devrev.ai/custom-objects.create' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Authorization: Bearer <TOKEN>' \
5--data '{
6    "leaf_type": "campaign",
7    "custom_schema_spec": {
8        "subtype": "social_media",
9        "tenant_fragment": true
10    },
11    "custom_fields": {
12        "tnt__name": "Summer Sale 2023",
13        "tnt__start_date": "2023-06-01",
14        "tnt__end_date": "2023-08-31",
15        "tnt__budget": 10000,
16        "tnt__target_audience": "Professionals",
17        "ctype__social_media_platform": "Facebook",
18        "ctype__post_id": "1234567890"
19    }
20}'

Use unique keys for custom objects

A unique identifier for each custom object can be used to maintain idempotency when retrying custom object creation requests. No other custom object of the same type can have the same unique key.

1curl --location 'https://api.devrev.ai/custom-objects.create' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Authorization: Bearer <TOKEN>' \
5--data '{
6    "leaf_type": "campaign",
7    "custom_schema_spec": {
8        "tenant_fragment": true
9    },
10    "unique_key": "CAMP-1",
11    "custom_fields": {
12        "tnt__name": "Summer Sale 2023",
13        "tnt__start_date": "2023-06-01",
14        "tnt__end_date": "2023-08-31",
15        "tnt__budget": 10000,
16        "tnt__target_audience": "Professionals"
17    }
18}'
Built with