Skip to content

Commit 52ec78d

Browse files
tilenkavcicgithub-actions[bot]erazemkbc-devrev
authored
enh: Add permissions documentation (#199)
* Add authorization policy * Update authorization policy docs * Address comments * Update wording * Update wording * Add article explanation * Address comments * Rewrite rich text * Add links * Apply suggestions from EkLine Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Remove tabs * Apply suggestions Co-authored-by: Erazem Kokot <[email protected]> * Address comments * Address comments * Rename rich text * Make shared with it's own section * Update fern/docs/pages/airdrop/data-model/permissions.mdx Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Wording * Wording * Clarify shared with predefined roles * Address comments * move /snapin-development/adaas to /airdrop (#207) * moved Airdrop up a level * redirects from adaas to airdrop * required * Tidy * Fix merge * Add info about bulk additions to groups * Unhide permissions --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Erazem Kokot <[email protected]> Co-authored-by: Ben Colborn <[email protected]>
1 parent e9ba77c commit 52ec78d

File tree

6 files changed

+388
-51
lines changed

6 files changed

+388
-51
lines changed

‎.cursorrules

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
You are the world's best documentation writer, renowned for your clarity, precision, and engaging style. Every piece of documentation you produce is:
2+
3+
1. Clear and precise - no ambiguity, jargon, marketing language or unnecessarily complex language.
4+
2. Concise—short, direct sentences and paragraphs.
5+
3. Scientifically structured—organized like a research paper or technical white paper, with a logical flow and strict attention to detail.
6+
4. Visually engaging—using line breaks, headings, and (rarely) components to enhance readability.
7+
5. Focused on user success — no marketing language or fluff; just the necessary information.
8+
9+
# Writing guidelines
10+
11+
- Titles must always start with an uppercase letter, followed by lowercase letters unless it is a name. Examples: Getting started, Text to speech, Conversational AI...
12+
- No emojis or icons unless absolutely necessary.
13+
- Scientific research tone—professional, factual, and straightforward.
14+
- Avoid long text blocks. Use short paragraphs and line breaks.
15+
- Do not use marketing/promotional language.
16+
- Be concise, direct, and avoid wordiness.
17+
- Ensure there are well-designed links (if applicable) to take the technical or non-technical reader to the relevant page.
18+
19+
# Page structure
20+
21+
## Components
22+
23+
Use the following components if possible, don't overuse them.
24+
25+
### Accordions
26+
27+
````
28+
<AccordionGroup>
29+
<Accordion title="Option 1">
30+
You can put other components inside Accordions.
31+
```ts
32+
export function generateRandomNumber() {
33+
return Math.random();
34+
}
35+
```
36+
</Accordion>
37+
<Accordion title="Option 2">
38+
This is a second option.
39+
</Accordion>
40+
41+
<Accordion title="Option 3">
42+
This is a third option.
43+
</Accordion>
44+
</AccordionGroup>
45+
````
46+
47+
### Callouts (Tips, Notes, Warnings, etc.)
48+
49+
```
50+
<Tip title="Example Callout" icon="leaf">
51+
This Callout uses a title and a custom icon.
52+
</Tip>
53+
<Note>This adds a note in the content</Note>
54+
<Warning>This raises a warning to watch out for</Warning>
55+
<Error>This indicates a potential error</Error>
56+
<Info>This draws attention to important information</Info>
57+
<Tip>This suggests a helpful tip</Tip>
58+
<Check>This brings us a checked status</Check>
59+
```
60+
61+
### Cards & Card Groups
62+
63+
```
64+
<Card
65+
title='Python'
66+
icon='brands python'
67+
href='https://github.com/fern-api/fern/tree/main/generators/python'
68+
>
69+
View Fern's Python SDK generator.
70+
</Card>
71+
<CardGroup cols={2}>
72+
<Card title="First Card" icon="circle-1">
73+
This is the first card.
74+
</Card>
75+
<Card title="Second Card" icon="circle-2">
76+
This is the second card.
77+
</Card>
78+
<Card title="Third Card" icon="circle-3">
79+
This is the third card.
80+
</Card>
81+
<Card title="Fourth Card" icon="circle-4">
82+
This is the fourth and final card.
83+
</Card>
84+
</CardGroup>
85+
```
86+
87+
### Code snippets
88+
89+
- Always use the focus attribute to highlight the code you want to highlight.
90+
- `maxLines` is optional if it's long.
91+
- `wordWrap` is optional if the full text should wrap and be visible.
92+
93+
```javascript focus={2-4} maxLines=10 wordWrap
94+
console.log('Line 1');
95+
console.log('Line 2');
96+
console.log('Line 3');
97+
console.log('Line 4');
98+
console.log('Line 5');
99+
```
100+
101+
### Code blocks
102+
103+
- Use code blocks for groups of code, especially if there are multiple languages or if it's a code example. Always start with Python as the default.
104+
105+
````
106+
<CodeBlocks>
107+
```javascript title="helloWorld.js"
108+
console.log("Hello World");
109+
````
110+
111+
```python title="hello_world.py"
112+
print('Hello World!')
113+
```
114+
115+
```java title="HelloWorld.java"
116+
class HelloWorld {
117+
public static void main(String[] args) {
118+
System.out.println("Hello, World!");
119+
}
120+
}
121+
```
122+
123+
</CodeBlocks>
124+
```
125+
126+
### Steps (for step-by-step guides)
127+
128+
```
129+
<Steps>
130+
### First Step
131+
Initial instructions.
132+
133+
### Second Step
134+
More instructions.
135+
136+
### Third Step
137+
Final Instructions
138+
</Steps>
139+
140+
```
141+
142+
### Frames
143+
144+
- You must wrap every single image in a frame.
145+
- Every frame must have `background="subtle"`
146+
- Use captions only if the image is not self-explanatory.
147+
- Use ![alt-title](image-url) as opposed to HTML `<img>` tags unless styling.
148+
149+
```
150+
<Frame
151+
caption="Beautiful mountains"
152+
background="subtle"
153+
>
154+
<img src="https://images.pexels.com/photos/1867601.jpeg" alt="Sample photo of mountains" />
155+
</Frame>
156+
157+
```
158+
159+
### Tabs (split up content into different sections)
160+
161+
```
162+
<Tabs>
163+
<Tab title="First Tab">
164+
☝️ Welcome to the content that you can only see inside the first Tab.
165+
</Tab>
166+
<Tab title="Second Tab">
167+
✌️ Here's content that's only inside the second Tab.
168+
</Tab>
169+
<Tab title="Third Tab">
170+
💪 Here's content that's only inside the third Tab.
171+
</Tab>
172+
</Tabs>
173+
174+
```

‎fern/docs/pages/airdrop/data-model/mapping-reasons.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
Airdrop uses transformation methods to map data from one data model to another.
2-
These methods operate at the individual field level, meaning they transform data field-by-field rather than transforming entire records at once.
2+
These methods operate at the individual field level, transforming data field-by-field rather than entire records at once.
33
Each transformation method has specific requirements regarding the field types and data formats it can work with.
44
If the source data field does not meet these requirements for a particular transformation method, that mapping option is not available for selection during the mapping configuration process.
55

6-
There are several reasons why some mappings might be unavailable.
6+
There are several reasons why some mappings might be unavailable:
77

88
1. A common reason is mismatch of types. For example, if a DevRev field is expected to be `rich_text`,
99
but the field is set as `text` mapping to some fields is unavailable.

‎fern/docs/pages/airdrop/data-model/permissions.mdx

Lines changed: 175 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,185 @@
11
DevRev uses the concept of permissions to control access to records.
22
Permissions are associated with users or groups and define the level of access they have to leaf types and their fields.
3+
You can read more about permissions in the [access control documentation](https://devrev.ai/docs/product/access-control).
34

4-
## Article permissions
5+
## Groups
6+
7+
To make groups available in the DevRev platform, Airdrop expects two objects:
8+
9+
1. An object containing descriptions of groups available in the external system.
10+
- Maps to the `group` object in DevRev.
11+
2. An object containing a mapping between groups and users in the external system.
12+
- Maps to the `object_member` object in DevRev.
513

6-
{/* TODO: more on article permissions */}
7-
Articles can be shared with users or groups.
14+
### Group memberships
15+
16+
An object containing the mapping between groups and users in the external system is required to represent group memberships in DevRev.
17+
18+
- This object maps to the `object_member` object in DevRev.
19+
- It should contain a field that references a group.
20+
This field should be mapped to `object_id` field of the `object_member` object.
21+
- It should also contain a collection field that references the users belonging to that group.
22+
This field should be mapped to the `add_member_ids` field.
23+
- If the external system supports event-based updates for group membership changes, the `object_member` object should include an additional collection field.
24+
This field identifies users to be removed from the group and should be mapped to the `remove_member_ids` field.
825

9-
The `shared_with` field allows to specify the permission level for each user or group using the `permission` type.
10-
The `permission` type is a special structure associating a reference to an user-like record type (the field `member_id`)
11-
with an `enum` value that provides the user with the role or permission level.
1226
## Platform groups
1327

14-
Platform groups are groups automatically created by the DevRev platform for every organization.
15-
For example, DevRev provides *Dev users* and *Rev users* groups that contain all the Dev and Rev users respectively.
28+
Platform groups are automatically created by the DevRev platform for every organization.
29+
For example, DevRev provides *Dev users* and *Rev users* groups that contain all Dev and Rev users respectively.
30+
31+
Developers and end-users can map external default groups to platform groups.
32+
This functionality allows flexible integration with DevRev's permission system while enabling re-mapping by the end user.
33+
34+
To implement this mapping:
35+
1. Define a new object in external domain metadata with one enum field containing possible values of default groups available in the external system.
36+
2. During initial domain mapping, map this object to the *platform groups* object in DevRev.
37+
3. Reference your object in other fields, such as in the `shared_with` field of articles.
38+
39+
## Shared with field
40+
41+
The `shared_with` field enables you to define permissions for articles (and other objects in the future).
42+
It specifies both who can access the content and what permission level they have.
43+
This field utilizes the `permission` type to associate users or groups with their designated roles.
44+
45+
### Structure
46+
47+
Each entry in the `shared_with` collection contains two key components:
48+
49+
- `member_id`: Identifies which user or group is being granted access.
50+
- `role`: Specifies the permission level (for example, "viewer", "editor", "owner"). DevRev offers a set of predefined roles.
51+
52+
### Member types
53+
54+
The `member_id` field can reference three different types of objects:
55+
- Individual users (`#record:users`)
56+
- Standard groups (`#record:groups`)
57+
- Platform groups (`#record:platform_groups`)
58+
59+
### External metadata example
60+
61+
```json
62+
{
63+
"shared_with": {
64+
"type": "permission",
65+
"collection": {},
66+
"permission": {
67+
"role": {
68+
"values": [
69+
{
70+
"key": "owner",
71+
"name": "Owner"
72+
},
73+
{
74+
"key": "editor",
75+
"name": "Editor"
76+
},
77+
{
78+
"key": "viewer",
79+
"name": "Viewer"
80+
}
81+
]
82+
},
83+
"member_id": {
84+
"refers_to": {
85+
"#record:users": {},
86+
"#record:groups": {},
87+
"#record:platform_groups": {}
88+
}
89+
}
90+
}
91+
}
92+
}
93+
```
94+
95+
## Article permissions
96+
97+
Articles in DevRev can be shared with individual users or groups, allowing for granular control over who can access what content.
98+
99+
### Sharing mechanism
100+
101+
The `shared_with` field specifies the permission level for each user or group using the `permission` type.
102+
This type is a structure that connects a reference to a user-like record type (the `member_id` field)
103+
with an `enum` value that defines the user's role or permission level.
104+
105+
### Scope interaction
106+
107+
<Tabs>
108+
<Tab title="Internal scope">
109+
110+
For `scope=internal` articles:
111+
- By default, only the owner has access.
112+
- Additional access is granted exclusively through the `shared_with` field.
113+
</Tab>
114+
115+
<Tab title="External scope">
116+
117+
For `scope=external` articles, the expected behavior is that they are published to Portal/PLuG and shared with customers.
118+
119+
- By default:
120+
- Admins have CRUD (create, read, update, delete) rights.
121+
- Platform users have CRU (create, read, update) rights.
122+
- Additional rights can be assigned by creating roles and assigning them to the entire organization or specific groups.
123+
- Articles can be shared with customers and published to Portal/PLuG.
124+
</Tab>
125+
</Tabs>
126+
127+
---
128+
129+
## Authorization policy
130+
131+
The *Authorization policy* object translates permission structures from an external system into DevRev's access control model.
132+
It enables the import of external roles and their associated permissions, automatically creating corresponding roles, role sets, and access control entries (ACEs) within DevRev.
133+
This allows defining CRUD (Create, Read, Update, Delete) permissions for specific record types, applying them to users and groups.
134+
135+
<Info>
136+
Only 1-way sync (from the external system to DevRev) is supported for authorization policy.
137+
</Info>
138+
139+
### Object fields
140+
141+
The Authorization policy object supports the following fields:
142+
143+
- `groups` (optional): A list of group identifiers from the external system to which this policy applies.
144+
- `users` (optional): A list of user identifiers from the external system to which this policy applies.
145+
- `targets`: Defines the DevRev record types the permissions apply to. It uses the `type_key` type. The format differs between metadata definition and runtime import.
146+
- `privileges`: Specifies the permissions granted by the policy. These should be normalized to CRUD operations.
147+
148+
### External domain metadata
149+
150+
To define the `targets` field in the external domain metadata use the `type_key` type to specify a list of strings representing the record types or record type categories the policy applies to.
151+
- Use the prefix `#record:` for specific record types (for example, `#record:document`).
152+
- Use the prefix `#category:` for record type categories (for example, `#category:users`).
153+
154+
Example:
155+
```json
156+
["#record:document", "#category:users"]
157+
```
158+
159+
To define the `privileges` field in the external domain metadata, specify an `enum` field representing the distinct permission levels available in the external system.
160+
Normalize these external permissions to their closest CRUD equivalents (create, read, update, delete).
161+
162+
During initial domain mapping, you map these enum values to DevRev's standard CRUD permissions. End users can later customize this mapping if needed.
163+
164+
<Warning>
165+
Authorization policies should always represent the current state of the external system. In each sync run, the entire policy should be recreated or not provided at all.
166+
167+
The object must be marked as `is_snapshot` to indicate it represents the current state of the external system.
168+
</Warning>
169+
170+
### Runtime import
171+
172+
The `targets` field is an array of strings containing the actual DevRev record type names.
173+
If a category was specified in the metadata (for example, `#category:users`), it should be expanded into the list of all record types belonging to that category at runtime.
16174

17-
We allow developers to map their external default groups to platform groups.
18-
This functionality allows for flexible integration with the platform's permission system while allowing for re-mapping by the end user.
175+
For example, if the `#category:users` includes "executives" and "developers", the runtime targets field should be:
176+
```json
177+
["document", "executives", "developers"]
178+
```
19179

20-
To implement this mapping, developers need to define a new object in external metadata with one enum field containing the possible values of default groups available in the external system. During the initial domain mapping, developers can map this object to the *platform groups* object in DevRev. The platform groups object can then be referenced in other objects, such as in the `shared_with` field of articles.
180+
The `privileges` field is an array of strings representing the specific CRUD permissions granted by the policy, based on the mapping defined during domain setup (or as re-mapped by the user).
21181

22-
{/* ### Authorization policy */}
182+
For example, if the external role granted read and update access, the runtime privileges field should be:
183+
```json
184+
["read", "update"]
185+
```

0 commit comments

Comments
 (0)