Skip to content

Commit ae88736

Browse files
B-LorentzB-Lorentz
committed
extend documentation
1 parent fde9910 commit ae88736

File tree

3 files changed

+283
-13
lines changed

3 files changed

+283
-13
lines changed

‎README.md‎

Lines changed: 87 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -161,12 +161,14 @@ The supported types are:
161161
- `enum`: A string from a predefined set of values with the optional human-readable names for each value.
162162
- `date`,
163163
- `timestamp`,
164-
- `struct`.
164+
- `struct`
165+
166+
- `permission`: A special strucuture associating a reference to an user-like record type (the field `member_id`) with an enum value that can be interpreted as the role or permission level associated with that user. This is useful in a few cases when mapping fields with the same type in devrev.
165167

166168
If the external system supports custom fields, the set of custom fields in each record type you wish to extract must be
167169
declared too.
168170

169-
Enum fields' set of possible values can often be customizable. A good practice is to retrieve the set of possible values
171+
Enum fields set of possible values can often be customizable. A good practice is to retrieve the set of possible values
170172
for all enum fields from the external system's APIs in each sync run.
171173

172174
`ID` (primary key) of the record, `created_date`, and `modified_date` must not be declared.
@@ -291,6 +293,72 @@ If the field is array in the extracted data, it is still typed with the one of t
291293
}
292294
```
293295

296+
8. Consider state transitions
297+
298+
If an external record type has some concept of states, between which only certain transitions are possible, (eg to move to the 'resolved' status, an issue first has to be 'in_testing' and similar business rules), you can declare these in the metadata too.
299+
300+
This will allow us to create a matching 'stage diagram' (a collection of stages and their permitted transitions) in DevRev, which will usually allow a much simpler import and a closer preservation of the external data than needing to map to DevRev's builtin (stock) stages.
301+
302+
This is especially important if two-way sync will eventually be needed, as setting the transitions up correctly ensures that the transitions the record undergo in DevRev will be able to be replicated in the external system.
303+
304+
To declare this in the metadata, ensure the status is represented in the extracted data as an enum field, and then declare the allowed transitions (which you might have to retrieve from an API at runtime, if they are also customized).
305+
306+
```json
307+
{
308+
"fields": {
309+
"status": {
310+
"name": "Status",
311+
"is_required": true,
312+
"type": "enum",
313+
"enum": {
314+
"values": [
315+
{
316+
"key": "detected",
317+
"name": "Detected"
318+
},
319+
{
320+
"key": "mitigated",
321+
"name": "Mitigated"
322+
},
323+
{
324+
"key": "rca_ready",
325+
"name": "RCA Ready"
326+
},
327+
{
328+
"key": "archived",
329+
"name": "Archived"
330+
}
331+
]
332+
}
333+
}
334+
},
335+
"stage_diagram": {
336+
"controlling_field": "status",
337+
"starting_stage": "detected",
338+
"stages": {
339+
"detected": {
340+
"stage_name": "Detected",
341+
"transitions_to": ["mitigated", "archived", "rca_ready"]
342+
},
343+
"mitigated": {
344+
"stage_name": "Mitigated",
345+
"transitions_to": ["archived", "detected"]
346+
},
347+
"rca_ready": {
348+
"stage_name": "RCA Ready",
349+
"transitions_to": ["archived"]
350+
},
351+
"archived": {
352+
"stage_name": "Archived",
353+
"transitions_to": []
354+
}
355+
}
356+
}
357+
}
358+
```
359+
360+
In the above example, the status field is declared the controlling field of the stage diagram, which then specifies the transitions for each stage.
361+
294362
## Normalize data
295363

296364
During the data extraction phase, the snap-in uploads batches of extracted items (the recommended batch size is 2000 items) formatted in JSONL
@@ -369,12 +437,29 @@ If your org is no in US-East-1, you have to override an environment variable to
369437
```bash
370438
ACTIVE_PARTITION=dvrv-in-1 chef-cli manage --env prod
371439
```
440+
372441
where the options are:
373442
"dvrv-us-1"
374443
"dvrv-eu-1"
375444
"dvrv-in-1"
376445
"dvrv-de-1"
377446

447+
The first function of the local UI is to assemble a 'blueprint' for concrete import running in the test-org, allowing the mapping to be tested out and evaluated.
448+
449+
## Use the local UI to create an initial domain mappings
450+
451+
The final artifact of the recipe creation process is the initial_domain_mappings.json, which has to embedded in the extractor.
452+
453+
This mapping, unlike the recipe blueprint of a concrete import, can contain multiple options for each external record type from which the end-user might choose (for example allow 'task' from an external system to map either to issue or ticket in devrev), and it can contain also mappings that apply to a record type category. When the user runs a new import, and the extractor reports in its metadata record types belonging to this category, that are not directly mapped in the initial domain mappings, the recipe manager will apply the per-category default to them.
454+
455+
After the blueprint of the test import was completed, the 'install in this org' button takes you to the initial domain mapping creation screen, where you can 'merge' the blueprint to the existing initial mappings of the org.
456+
457+
By repeating this process (run a new import, create a different configuration, merge to the initial mappings), you can create an initial mapping that contains multiple options for the user to choose from.
458+
459+
Finally the Export button allows you to retrieve the initial_domain_mapping.json.
460+
461+
## Tip: use local metadata in the local UI
462+
378463
You can also provide a local metadata file to the command using the '-m' flag for example: `chef-cli manage --end dev -m metadata.json`, this enables to use:
379464

380465
- raw jq transformations using an external field as input. (This is an experimental feature)

‎demo/metadata.json‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,62 @@
134134
"rca": {
135135
"type": "rich_text",
136136
"name": "Root cause analysis"
137+
},
138+
"status": {
139+
"name": "Status",
140+
"is_required": true,
141+
"type": "enum",
142+
"enum": {
143+
"values": [
144+
{
145+
"key": "detected",
146+
"name": "Detected"
147+
},
148+
{
149+
"key": "mitigated",
150+
"name": "Mitigated"
151+
},
152+
{
153+
"key": "rca_ready",
154+
"name": "RCA Ready"
155+
},
156+
{
157+
"key": "archived",
158+
"name": "Archived"
159+
}
160+
]
161+
}
162+
}
163+
},
164+
"stage_diagram": {
165+
"controlling_field": "status",
166+
"starting_stage": "detected",
167+
"stages": {
168+
"detected": {
169+
"stage_name": "Detected",
170+
"transitions_to": [
171+
"mitigated",
172+
"archived",
173+
"rca_ready"
174+
]
175+
},
176+
"mitigated": {
177+
"stage_name": "Mitigated",
178+
"transitions_to": [
179+
"archived",
180+
"detected"
181+
]
182+
},
183+
"rca_ready": {
184+
"stage_name": "RCA Ready",
185+
"transitions_to": [
186+
"archived"
187+
]
188+
},
189+
"archived": {
190+
"stage_name": "Archived",
191+
"transitions_to": []
192+
}
137193
}
138194
}
139195
},
@@ -154,6 +210,46 @@
154210
}
155211
}
156212
}
213+
},
214+
"knowledge_page": {
215+
"name": "Page",
216+
"fields": {
217+
"content": {
218+
"type": "rich_text"
219+
},
220+
"owner": {
221+
"is_required": true,
222+
"type": "reference",
223+
"reference": {
224+
"refers_to": {
225+
"#record:user": {}
226+
}
227+
}
228+
},
229+
"accessible_to": {
230+
"type": "permission",
231+
"collection": {},
232+
"permission": {
233+
"role": {
234+
"values": [
235+
{
236+
"key": "viewer",
237+
"name": "Viewer"
238+
},
239+
{
240+
"key": "editor",
241+
"name": "Editor"
242+
}
243+
]
244+
},
245+
"member_id": {
246+
"refers_to": {
247+
"#record:user": {}
248+
}
249+
}
250+
}
251+
}
252+
}
157253
}
158254
},
159255
"struct_types": {

0 commit comments

Comments
 (0)