Skip to content

Commit 9df921a

Browse files
shivanshshivansh
authored
Add custom links beta documentation (#274)
1 parent 503c1ee commit 9df921a

File tree

2 files changed

+196
-0
lines changed

2 files changed

+196
-0
lines changed

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

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
Links allow you to create organization-specific relationships between any two objects in DevRev.
2+
This feature enables you to define meaningful connections with custom names that reflect your business processes.
3+
4+
This section provides an overview of links and walks you through the process of creating and managing them.
5+
By the end of this section, you'll be able to:
6+
1. Define link types
7+
2. Create links between objects
8+
3. List link types
9+
4. Update link types
10+
5. Deprecate link types
11+
12+
## Concepts
13+
14+
### Link type
15+
16+
A link type defines a relationship between two types of objects. It specifies:
17+
- The source object types that the link initiates from
18+
- The target object types that the link can be created to
19+
- A forward name describing the relationship from source to target
20+
- A backward name describing the relationship from target to source
21+
22+
### Supported object types
23+
24+
Links can be created between the following object types:
25+
- custom object
26+
- work (issue, ticket, task, opportunity)
27+
- account, user
28+
- part (product, capability, feature, enhancement)
29+
30+
For more details on customization or custom object concepts, please refer to the documentation below:
31+
- [Customization](./object-customization)
32+
- [Custom objects](./custom-objects)
33+
34+
## Create link types
35+
36+
<Callout intent="note">
37+
Let's say you want to establish a parent-child relationship between tickets and a custom object
38+
type called "Campaign". This relationship helps track which tickets are assigned to which campaigns.
39+
</Callout>
40+
41+
To create this relationship, make an API call to create a link type:
42+
43+
```curl
44+
curl --location 'https://api.devrev.ai/link-types.custom.create' \
45+
--header 'Content-Type: application/json' \
46+
--header 'Authorization: Bearer <TOKEN>' \
47+
--data '{
48+
"name": "Link between ticket and campaign",
49+
"source_types": [
50+
{
51+
"leaf_type": "ticket"
52+
}
53+
],
54+
"target_types": [
55+
{
56+
"leaf_type": "campaign",
57+
"is_custom_leaf_type": true
58+
}
59+
],
60+
"forward_name": "is parent of",
61+
"backward_name": "is child of",
62+
"deprecated": false
63+
}'
64+
```
65+
66+
The link type above defines:
67+
- A descriptive name
68+
- Source types that the link can be created from (ticket)
69+
- Target types that the link can be created to (campaign custom object)
70+
- Forward name ("is parent of") describing the relationship from ticket to campaign
71+
- Backward name ("is child of") describing the relationship from campaign to ticket
72+
73+
## Create links between objects
74+
75+
Once you have defined a link type, you can create links between objects:
76+
77+
```curl
78+
curl --location 'https://api.devrev.ai/links.create' \
79+
--header 'Content-Type: application/json' \
80+
--header 'Authorization: Bearer <TOKEN>' \
81+
--data '{
82+
"custom_link_type": "don:core:dvrv-us-1:devo/demo:custom_link_type/1",
83+
"link_type": "custom_link",
84+
"source": "don:core:dvrv-us-1:devo/demo:ticket/1",
85+
"target": "don:core:dvrv-us-1:devo/demo:custom_object/campaign/1"
86+
}'
87+
```
88+
89+
<Callout intent="tip">
90+
When creating a link:
91+
- Set `link_type` to `"custom_link"`
92+
- Provide the link type ID in `custom_link_type`
93+
- Ensure both source and target objects exist
94+
</Callout>
95+
96+
## List link types
97+
98+
You can list link types in your organization, with optional filtering:
99+
100+
```curl
101+
curl --location 'https://api.devrev.ai/link-types.custom.list' \
102+
--header 'Content-Type: application/json' \
103+
--header 'Authorization: Bearer <TOKEN>' \
104+
--data '{
105+
"source_types_v2": [
106+
{
107+
"leaf_type": "ticket,
108+
}
109+
]
110+
}'
111+
```
112+
113+
## Update link types
114+
115+
<Callout intent="note">
116+
Now, you want to expand the source types to allow both issues and tickets to have this relationship
117+
with campaigns.
118+
</Callout>
119+
120+
You can update the existing link type to include additional source types:
121+
122+
```curl
123+
curl --location 'https://api.devrev.ai/link-types.custom.update' \
124+
--header 'Content-Type: application/json' \
125+
--header 'Authorization: Bearer <TOKEN>' \
126+
--data '{
127+
"id": "don:core:dvrv-us-1:devo/demo:custom_link_type/1",
128+
"name": "Link type between issue/ticket and campaign",
129+
"source_types_v2": [
130+
{
131+
"leaf_type": "issue"
132+
},
133+
{
134+
"leaf_type": "ticket"
135+
}
136+
]
137+
}'
138+
```
139+
140+
## Create links between objects with subtypes
141+
142+
<Callout intent="note">
143+
You may want to restrict links to specific subtypes of objects. For example, only allowing issues
144+
of a particular subtype to be linked to tickets.
145+
</Callout>
146+
147+
```curl {9}
148+
curl --location 'https://api.devrev.ai/link-types.custom.create' \
149+
--header 'Content-Type: application/json' \
150+
--header 'Authorization: Bearer <TOKEN>' \
151+
--data '{
152+
"name": "Link between social media issues and tickets",
153+
"source_types": [
154+
{
155+
"leaf_type": "issue",
156+
"subtype": "social_media"
157+
}
158+
],
159+
"target_types": [
160+
{
161+
"leaf_type": "ticket"
162+
}
163+
],
164+
"forward_name": "is related to",
165+
"backward_name": "is related to"
166+
}'
167+
```
168+
169+
This configuration:
170+
- Allows issues of subtype "social_media" to be linked to tickets
171+
- Rejects attempts to link issues with no subtype or with other subtypes
172+
173+
<Callout intent="tip">
174+
The subtype should exist for the corresponding source type.
175+
To add more valid source subtypes, use the update endpoint to add them to the `source_types` array.
176+
</Callout>
177+
178+
## Deprecate link types
179+
180+
<Callout intent="note">
181+
Link types cannot be deleted, only deprecated. This ensures that existing links maintain
182+
referential integrity and prevents data corruption.
183+
</Callout>
184+
185+
To deprecate a link type, use the update endpoint and set `deprecated` to `true`:
186+
```curl {6}
187+
curl --location 'https://api.devrev.ai/link-types.custom.update' \
188+
--header 'Content-Type: application/json' \
189+
--header 'Authorization: Bearer <TOKEN>' \
190+
--data '{
191+
"id": "don:core:dvrv-us-1:devo/demo:custom_link_type/1",
192+
"deprecated": true
193+
}'
194+
```

‎fern/versions/beta.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,5 @@ navigation:
1919
- page: Agents async API
2020
slug: agents-async-api
2121
path: ../docs/pages/interact-agent.mdx
22+
- page: Links
23+
path: ../docs/pages/custom-links.mdx

0 commit comments

Comments
 (0)