Custom Objects

This functionality is in Beta. It is not recommended for use in production applications.

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. Unique key: A unique identifier for each custom object. This is useful for maintaining idempotency when retrying custom object creation requests.
  6. 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 a schema and a custom object

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

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: <TOKEN>' \
5--data '{
6    "leaf_type": "campaign",
7    "unique_key": "CAMP-001",
8    "custom_schema_spec": {
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    }
18}'

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    "unique_key": "CAMP-001"
11    "stock_schema_fragment": "don:core:dvrv-us-1:stock_sf/1",
12    "custom_schema_fragments": [
13      "don:core:dvrv-us-1:devo/demo:tenant_fragment/1"
14    ],
15    "custom_fields": {
16      "tnt__name": "Summer Sale 2023",
17      "tnt__start_date": "2023-06-01",
18      "tnt__end_date": "2023-08-31",
19      "tnt__budget": 10000,
20      "tnt__target_audience": "Professionals"
21    }
22  }
23}

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 a custom object

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: <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: <TOKEN>' \
5--data '{
6    "leaf_type": "campaign",
7    "filter": [
8      "eq",
9      "$custom_fields.tnt__target_audience",
10      "Young adults"
11    ]
12}'

Update a custom object

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: <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 a custom object

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: <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: <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: <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    "unique_key": "CAMP-001"
21}'