Skip to content

Commit 82d6d4f

Browse files
shivanshshivansh
authored
docs: add custom objects beta API documentation (#96)
1 parent 3dfd1ef commit 82d6d4f

File tree

2 files changed

+258
-0
lines changed

2 files changed

+258
-0
lines changed

‎fern/docs/pages/custom-objects.mdx

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
<Callout intent="warning">
2+
This functionality is in Beta. It is not recommended for use in production applications.
3+
</Callout>
4+
5+
Custom objects allow you to extend DevRev's data model beyond the standard use-cases
6+
served by the native apps like Build and Support. Custom objects allow you to create
7+
and manage object types tailored to your specific business needs.
8+
9+
## Key concepts
10+
11+
1. **Leaf type**: The base type of a custom object. For example, "campaign".
12+
2. **Subtype**: A categorization of a leaf type. For example, "promotion" or "advertising" for a "campaign" leaf type.
13+
3. **Schema fragment**: A schema fragment defines the schema for an object.
14+
4. **Custom fields**: User-defined fields that store specific data for your custom object.
15+
5. **Unique key**: A unique identifier for each custom object. This is useful for maintaining idempotency when retrying custom object creation requests.
16+
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.
17+
18+
For more details on customization concepts, please refer to the
19+
[Customization](./object-customization) documentation.
20+
21+
## Custom object lifecycle
22+
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.
23+
24+
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.
25+
26+
### Create a schema and a custom object
27+
28+
```curl
29+
curl --location 'https://api.devrev.ai/schemas.custom.set' \
30+
--header 'Content-Type: application/json' \
31+
--header 'Accept: application/json' \
32+
--header 'Authorization: <TOKEN>' \
33+
--data '{
34+
"type": "tenant_fragment",
35+
"description": "Attributes for Campaign",
36+
"leaf_type": "campaign",
37+
"fields": [
38+
{
39+
"name": "name",
40+
"field_type": "tokens",
41+
"description": "Name of the campaign"
42+
},
43+
{
44+
"name": "start_date",
45+
"field_type": "date",
46+
"description": "Start date of the campaign"
47+
},
48+
{
49+
"name": "end_date",
50+
"field_type": "date",
51+
"description": "End date of the campaign"
52+
},
53+
{
54+
"name": "budget",
55+
"field_type": "int",
56+
"description": "Budget allocated for the campaign"
57+
},
58+
{
59+
"name": "target_audience",
60+
"field_type": "enum",
61+
"description": "Target audience for the campaign",
62+
"allowed_values": [
63+
"Professionals",
64+
"Students"
65+
]
66+
}
67+
],
68+
"is_custom_leaf_type": true,
69+
"id_prefix": "CAMP"
70+
}'
71+
```
72+
73+
Note that for custom object schemas, `is_custom_leaf_type` must be set to `true` to
74+
differentiate it from standard DevRev object schemas.
75+
76+
Once the schema is created, you can create a custom object of type "Campaign":
77+
78+
```curl
79+
curl --location 'https://api.devrev.ai/custom-objects.create' \
80+
--header 'Content-Type: application/json' \
81+
--header 'Accept: application/json' \
82+
--header 'Authorization: <TOKEN>' \
83+
--data '{
84+
"leaf_type": "campaign",
85+
"unique_key": "CAMP-001",
86+
"custom_schema_spec": {
87+
"tenant_fragment": true
88+
},
89+
"custom_fields": {
90+
"tnt__name": "Summer Sale 2023",
91+
"tnt__start_date": "2023-06-01",
92+
"tnt__end_date": "2023-08-31",
93+
"tnt__budget": 10000,
94+
"tnt__target_audience": "Professionals"
95+
}
96+
}'
97+
```
98+
99+
The response of the above API call is the ID of the custom object created.
100+
```json {12-21}
101+
{
102+
"custom_object": {
103+
"id": "don:core:dvrv-us-1:devo/demo:custom_object/campaign/1",
104+
"created_by": {...},
105+
"created_date": "2024-10-01T07:02:58.958Z",
106+
"modified_by": {...},
107+
"modified_date": "2024-10-01T07:02:58.958Z",
108+
"display_id": "C-CAMP-1",
109+
"leaf_type": "campaign",
110+
"unique_key": "CAMP-001"
111+
"stock_schema_fragment": "don:core:dvrv-us-1:stock_sf/1",
112+
"custom_schema_fragments": [
113+
"don:core:dvrv-us-1:devo/demo:tenant_fragment/1"
114+
],
115+
"custom_fields": {
116+
"tnt__name": "Summer Sale 2023",
117+
"tnt__start_date": "2023-06-01",
118+
"tnt__end_date": "2023-08-31",
119+
"tnt__budget": 10000,
120+
"tnt__target_audience": "Professionals"
121+
}
122+
}
123+
}
124+
```
125+
126+
Note that the `id` field in the above response is the system generated unique ID for the custom object.
127+
128+
The sections below provide more details on the available API endpoints for interacting with custom objects.
129+
130+
### Get a custom object
131+
132+
To get a custom object, use the `custom-objects.get` endpoint:
133+
134+
```curl
135+
curl --location 'https://api.devrev.ai/custom-objects.get' \
136+
--header 'Content-Type: application/json' \
137+
--header 'Accept: application/json' \
138+
--header 'Authorization: <TOKEN>' \
139+
--data '{
140+
"id": "don:core:dvrv-us-1:devo/demo:custom_object/campaign/1"
141+
}'
142+
```
143+
144+
### List custom objects
145+
146+
To list custom objects, use the `custom-objects.list` endpoint:
147+
148+
```curl
149+
curl --location 'https://api.devrev.ai/custom-objects.list' \
150+
--header 'Content-Type: application/json' \
151+
--header 'Accept: application/json' \
152+
--header 'Authorization: <TOKEN>' \
153+
--data '{
154+
"leaf_type": "campaign",
155+
"filter": [
156+
"eq",
157+
"$custom_fields.tnt__target_audience",
158+
"Young adults"
159+
]
160+
}'
161+
```
162+
163+
### Update a custom object
164+
165+
To update an existing custom object, use the `custom-objects.update` endpoint. The
166+
following example updates the budget of the previously created campaign custom object:
167+
168+
```curl
169+
curl --location 'https://api.devrev.ai/custom-objects.update' \
170+
--header 'Content-Type: application/json' \
171+
--header 'Accept: application/json' \
172+
--header 'Authorization: <TOKEN>' \
173+
--data '{
174+
"id": "don:core:dvrv-us-1:devo/demo:custom_object/campaign/1",
175+
"custom_fields": {
176+
"tnt__budget": 15000
177+
}
178+
}'
179+
```
180+
181+
### Delete a custom object
182+
183+
To delete a custom object, use the `custom-objects.delete` endpoint.
184+
The following example deletes the previously created campaign custom object:
185+
186+
```curl
187+
curl --location 'https://api.devrev.ai/custom-objects.delete' \
188+
--header 'Content-Type: application/json' \
189+
--header 'Accept: application/json' \
190+
--header 'Authorization: <TOKEN>' \
191+
--data '{
192+
"id": "don:core:dvrv-us-1:devo/demo:custom_object/campaign/1"
193+
}'
194+
```
195+
196+
## Extended use cases
197+
198+
### Reference custom objects in other objects
199+
Let's say you want to reference all the campaigns that have been run for a customer
200+
workspace. You can do so by adding a field of type "id" and "id_type: custom_object.campaign"
201+
in the account tenant schema.
202+
203+
```curl {13-14}
204+
curl --location 'https://api.devrev.ai/schemas.custom.set' \
205+
--header 'Content-Type: application/json' \
206+
--header 'Accept: application/json' \
207+
--header 'Authorization: <TOKEN>' \
208+
--data '{
209+
"type": "tenant_fragment",
210+
"description": "Tenant attributes for Account",
211+
"leaf_type": "account",
212+
"fields": [
213+
{
214+
"name": "campaigns",
215+
"field_type": "array",
216+
"base_type": "id",
217+
"id_type": [ "custom_object.campaign" ],
218+
},
219+
... // other fields
220+
],
221+
}'
222+
```
223+
224+
### Add subtypes to custom objects
225+
Adding subtypes to custom objects allows you to categorize and manage your custom
226+
objects more effectively. The process is the same as adding subtypes to other standard
227+
DevRev objects like issues and tickets.
228+
229+
Let's say you have run different types of campaigns like social media and email
230+
marketing. You can create a subtype for each of these variants. If you want to create a
231+
campaign custom object with subtype "social_media", you can do so as follows:
232+
233+
```curl {8, 17-18}
234+
curl --location 'https://api.devrev.ai/custom-objects.create' \
235+
--header 'Content-Type: application/json' \
236+
--header 'Accept: application/json' \
237+
--header 'Authorization: <TOKEN>' \
238+
--data '{
239+
"leaf_type": "campaign",
240+
"custom_schema_spec": {
241+
"subtype": "social_media",
242+
"tenant_fragment": true
243+
},
244+
"custom_fields": {
245+
"tnt__name": "Summer Sale 2023",
246+
"tnt__start_date": "2023-06-01",
247+
"tnt__end_date": "2023-08-31",
248+
"tnt__budget": 10000,
249+
"tnt__target_audience": "Professionals",
250+
"ctype__social_media_platform": "Facebook",
251+
"ctype__post_id": "1234567890"
252+
},
253+
"unique_key": "CAMP-001"
254+
}'
255+
```
256+

‎fern/versions/beta.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,7 @@ navigation:
1313
contents:
1414
- page: Object Customization
1515
path: ../docs/pages/customization.mdx
16+
- page: Custom Objects
17+
path: ../docs/pages/custom-objects.mdx
1618
- page: Create accounts and contacts in DevRev
1719
path: ../docs/pages/create-accounts.mdx

0 commit comments

Comments
 (0)