@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title User Guide: Customizing Forms
2@group userguide
3
4Guide to prefilling and customizing forms in Phorge applications.
5
6Overview
7========
8
9In most applications, objects are created by clicking a "Create" button from
10the main list view, and edited by clicking an "Edit" link from the main detail
11view. For example, you create a new task by clicking "Create Task", and edit it
12by clicking "Edit Task".
13
14The forms these workflows use can be customized to accommodate a number of
15different use cases. In particular:
16
17**Prefilling**: You can use HTTP GET parameters to prefill fields or copy
18fields from another object. This is a lightweight way to create a link with
19some fields set to initial values. For example, you might want to create a
20link to create a task which has some default projects or subscribers.
21
22**Custom Forms**: You can create custom forms which can have default values;
23locked, hidden, and reordered fields; and additional instructions. This can let
24you make specialized forms for creating certain types of objects, like a
25"New Bug Report" form with extra help text or a "New Security Issue" form with
26locked policies.
27
28**"Create" Defaults**: You can change the default form available to users for
29creating objects, or provide multiple default forms for them to choose between.
30This can let you simplify or specialize the creation process.
31
32**"Edit" Defaults**: You can change the default form users are given to edit
33objects, which will also affect their ability to take inline actions in the
34comment form if you're working in an application which supports comments. This
35can streamline the edit workflow for less experienced users.
36
37Anyone can use prefilling, but you must have permission to configure an
38application in order to modify the application's forms. By default, only
39administrators can configure applications.
40
41The remainder of this document walks through configuring these features in
42greater detail.
43
44
45Supported Applications
46======================
47
48These applications currently support form customization:
49
50| Application | Support |
51|-------------------|---------|
52| Maniphest | Full
53| Owners | Full
54| Paste | Full
55| ApplicationEditor | Meta
56
57This documentation is geared toward use in Maniphest because customizing task
58creation flows is the most common use case for many of these features, but the
59features discussed here work in any application with support.
60
61These features first became available in December 2015. Additional applications
62will support them in the future.
63
64Internally, this infrastructure is called `ApplicationEditor`, and the main
65component is `EditEngine`. You may see technical documentation, changelogs, or
66internal discussion using these terms.
67
68Prefilling
69==========
70
71You can prefill the fields in forms by providing HTTP parameters. For example,
72if a form has a "Projects" field, you can generally prefill it by adding a
73`projects` parameter to the URI like this:
74
75```
76https://phorge.example.com/application/edit/?projects=skunkworks
77```
78
79The parameters available in each application vary, and depend on which fields
80the application supports.
81
82For full documentation on a particular form, navigate to that form (by
83selecting the "Create" or "Edit" action in the application) and then use
84{nav Actions > Show HTTP Parameters} to see full details on which parameters
85you can use and how to specify them.
86
87You can also use the `template` parameter to copy fields from an existing
88object that you have permission to see. Which fields are copied depend on the
89application, but usually content fields (like a name or title) are not copied
90while other fields (like projects, subscribers, and object states) are.
91The {nav Show HTTP Parameters} page has a full list of which fields will be
92copied.
93
94You can combine the `template` parameter with other prefilling. The `template`
95will act first, then prefilling will take effect. This allows you to overwrite
96template values with prefilled values.
97
98Some use cases for this include:
99
100**Lightweight Integrations**: If you want to give users a way to file tasks from
101an external application, this is an easy way to get a basic integration
102working. For example, you might have a tool for reviewing error logs in
103production that has a link to "File a Bug" about an error. The link could
104prefill the `title`, `body` and `projects` fields with details about the log
105message and a link back into the external tool.
106
107**Convenience**: You can create lightweight, ad-hoc links that make taking
108actions a little easier for users. For example, if you're sending out an email
109about a change you just made to a lot of people, you could include instructions
110like "If you run into any issues, assign a task to me with details: ..." and
111include a link which prefills you as the task assignee.
112
113**Searchbar Commands**: If you use a searchbar plugin which gives you shortcut
114commands, you can write a custom shortcut so a command like "bug ..." can
115quickly redirect you to a prefilled form.
116
117
118Creating New Forms
119==================
120
121Beyond prefilling forms with HTTP parameters, you can create and save form
122configurations. This is more heavyweight than prefilling and allows you to
123customize, streamline, or structure a workflow more heavily.
124
125You must be able to configure an application in order to manage its forms.
126
127Form configurations can have special names (like "New Bug Report") and
128additional instruction text, and may prefill, lock, hide, and reorder fields.
129Prefilling and templating still work with custom form configurations, but only
130apply to visible fields.
131
132To create a new form configuration, navigate to an existing form via "Create"
133or "Edit" and choose {nav Actions > View Form Configurations}. This will show
134you a list of current configurations.
135
136You can also edit existing configurations, including the default configuration.
137
138You can use {nav Create Form} from this screen to create a new configuration.
139After setting some basic information you will be able to lock, hide, and
140reorder form fields, as well as set defaults.
141
142Clicking {nav Use Form} will take you to the permanent URI for this form. You
143can link to this form from elsewhere to take the user directly to your
144custom flow.
145
146You can adjust defaults using {nav Change Default Values}. These defaults are
147saved with the form, and do not require HTTP parameter prefilling. However,
148they work in conjunction with prefilling, and you can use prefilling or
149templating to overwrite the defaults for visible fields.
150
151If you set a default value for a field and lock or hide the field, the default
152you set will still be respected and can not be overridden with templating
153or prefilling. This allows you to force certain forms to create tasks with
154specific field values, like projects or policies.
155
156You can also set a view policy for a form. Only users who are able to view the
157form can use it to create objects.
158
159There are some additional options ("Mark as Create Form" and
160"Mark as Edit Form") which are more complicated and explained in greater
161detail later in this document.
162
163Some use cases for this include:
164
165**Tailoring Workflows**: If you have certain intake workflows like
166"New Bug Report" or "New Security Issue", you can create forms for them with
167more structure than the default form.
168
169You can provide detailed instructions and links to documentation in the
170"Preamble" for the form configuration. You might use this to remind users about
171reporting guidelines, help them fill out the form correctly, or link to other
172resources.
173
174You can hide fields that aren't important to simplify the workflow, or reorder
175fields to emphasize things that are important. For example, you might want to
176hide the "Priority" field on a bug report form if you'd like all bugs to come
177in at the default priority before they are triaged.
178
179You can set default view and edit policies, and optionally lock or hide those
180fields. This allows you to create a form that is locked to certain policy
181settings.
182
183**Simplifying Forms**: If you rarely (or never) use some object fields, you can
184create a simplified form by hiding the fields you don't use regularly, or
185hide these fields completely from the default form.
186
187
188Changing Creation Defaults
189=========================
190
191You can control which form or forms are presented to users by default when
192they go to create new objects in an application.
193
194Using {nav Mark as "Create" Form} from the detail page for a form
195configuration, you can mark a form to appear in the create menu.
196
197When a user visits the application, Phorge finds all the form
198configurations that are:
199
200 - marked as "create" forms; and
201 - visible to the user based on policy configuration; and
202 - enabled.
203
204If there is only one such form, Phorge renders a single "Create" button.
205(If there are zero forms, it renders the button but disables it.)
206
207If there are several such forms, Phorge renders a dropdown which allows
208the user to choose between them.
209
210You can reorder these forms by returning to the configuration list and using
211{nav Reorder Create Forms} in the left menu.
212
213This logic is also used to select items for the global "Quick Create" menu
214in the main menu bar.
215
216Some use cases for this include:
217
218**Simplification**: You can modify the default form to reorder fields, add
219instructions, or hide fields you never use.
220
221**Multiple Intake Workflows**: If you have multiple distinct intake workflows
222like "New Bug Report" and "New Security Issue", you can mark several forms
223as "Create" forms and users will be given a choice between them when they go
224to create a task.
225
226These flows can provide different instructions and defaults to help users
227provide the desired information correctly.
228
229**Basic and Advanced Workflows**: You can create a simplified "Basic" workflow
230which hides or locks some fields, and a separate "Advanced" workflow which
231has all of the fields.
232
233If you do this, you can also restrict the visibility policy for the "Advanced"
234form to experienced users. If you do, newer users will see a button which
235takes them to the basic form, while advanced users will be able to choose
236between the basic and advanced forms.
237
238
239Changing Editing Defaults
240=========================
241
242You can control which form users are taken to when they click "Edit" on an
243object detail page.
244
245Using {nav Mark as "Edit" Form} from the detail page for a form configuration,
246you can mark a form as a default edit form.
247
248When a user goes to edit an object, they are taken to the first form which is:
249
250 - marked as an "edit" form; and
251 - visible to them; and
252 - enabled.
253
254You can reorder forms by going up one level and using {nav Reorder Edit Forms}
255in the left menu. This will let you choose which forms have precedence if
256a user has access to multiple edit forms.
257
258The default edit form also controls which which actions are available inline
259in the "Comment" form at the bottom of the detail page, for applications which
260support comments. If you hide or lock a field, corresponding actions will not
261be available.
262
263Some use cases for this include:
264
265**Simplification**: You can modify the default form to reorder fields, add
266instructions, or hide fields you never use.
267
268By default, applications tend to have just one form, which is both an edit form
269and a create form. You can split this into two forms (one edit form and one
270create form) and then simplify the create form without affecting the edit
271form.
272
273You might do this if there are some fields you still want access to that you
274never modify when creating objects. For example, you might always want to
275create tasks with status "Open", and just hide that field from from the create
276form completely. A separate edit form can still give you access to these fields
277if you want to adjust them later.
278
279**Basic and Advanced Workflows**: You can create a basic edit form (with fewer
280fields available) and an advanced edit form, then restrict access to the
281advanced form to experienced users.
282
283By ordering the forms as "Advanced", then "Basic", and applying a view policy
284to the "Advanced" form, you can send experienced users to the advanced form
285and less experienced users to the basic form.
286
287For example, you might use this to hide policy controls or task priorities from
288inexperienced users.
289
290
291Understanding Policies
292======================
293
294IMPORTANT: Simplifying workflows by restricting access to forms and fields does
295**not** enforce policy controls for those fields.
296
297The configurations described above which simplify workflows are advisory, and
298are intended to help users complete workflows quickly and correctly. A user who
299has very limited access to an application through forms will generally still be
300able to use other workflows (like Conduit, Herald, Workboards, email, and other
301applications and integrations) to directly or indirectly modify fields.
302
303For example, even if you lock a user out of all the forms in an application
304that have a "Subscribers" field, they can still add subscribers indirectly by
305using `@username` mentions.
306
307We do not currently plan to change this or introduce enforced, platform-wide
308field-level policy controls. These form customization features are generally
309aimed at helping well-intentioned but inexperienced users complete workflows
310quickly and correctly.
311
312For more details about policies in general, see @{article:Policies User Guide}.
313
314
315Disabling Form Configurations
316=============================
317
318You can disable a form configuration from the form configuration details screen,
319by selecting {nav Disable Form}.
320
321Disabled forms do not appear in any menus by default, and can not be used to
322create or edit objects.
323
324
325Use Case: Specialized Report Form
326=================================
327
328A project might want to provide a specialized bug report form for a specific
329type of issue. For example, if you have an Android application, you might have
330an internal link in that application for employees to "Report a Bug".
331
332A simple way to do this would be to link to the default form and use HTTP
333parameter prefilling to set a project. You might end up with a link like this
334one:
335
336```
337https://phorge.example.com/maniphest/task/edit/?projects=android
338```
339
340A slightly more advanced method is to create a template task, then use it to
341prefill the form. For example, you might set some projects, subscribers, and
342custom field values on the template task. Then have the application link to
343the a URI that prefills using the template:
344
345```
346https://phorge.example.com/maniphest/task/edit/?template=123
347```
348
349This is a little easier to use, and lets you update the template later if you
350want to change anything about the defaults that the new tasks are created
351with.
352
353An even more advanced method is to create a new custom form configuration.
354You could call this something like "New Android Bug Report". In addition to
355setting defaults, you could lock, hide, or reorder fields so that the form
356only presents the fields that are relevant to the workflow. You could also
357provide instructions to help users file good reports.
358
359After customizing your form configuration, you'd link to the {nav Use Form}
360URI, like this:
361
362```
363https://phorge.example.com/maniphest/task/edit/form/123/
364```
365
366You can also combine this with templating or prefilling to further specialize
367the flow.
368
369
370Use Case: Simple Report Flow
371============================
372
373An open source project might want to give new users a simpler bug report form
374with fewer fields and more instructions.
375
376To do this, create a custom form and configure it so it has only the relevant
377fields and includes any instructions. Once it looks good, mark it as a "Create"
378form.
379
380The "Create Task" button should now change into a menu and show both the
381default form and the new simpler form, as well as in the global "Quick Create"
382menu in the main menu bar.
383
384If you prefer the fields appear in a different order, use
385{nav Reorder Create Forms} to adjust the display order. (You could also rename
386the default creation flow to something like "Create Advanced Task" to guide
387users toward the best form).
388
389
390Use Case: Basic and Advanced Users
391==================================
392
393An open source project or a company with a mixture of experienced and less
394experienced users might want to give only some users access to adjust advanced
395fields like "View Policy" and "Edit Policy" when creating tasks.
396
397Before configuring things like this, make sure you review "Understanding
398Policies" above.
399
400To do this, first customize four forms:
401
402 - Basic Create
403 - Advanced Create
404 - Basic Edit
405 - Advanced Edit
406
407You can customize these however you'd like.
408
409The "Advanced" forms should have more fields, while the "Basic" forms should
410be simpler. You may want to add additional instructions to the "Basic Create"
411form.
412
413Then:
414
415 - Mark the two "Create" forms as create forms.
416 - Mark the two "Edit" forms as edit forms.
417 - Limit the visibility of the two "Advanced" forms to only advanced users
418 (for example, "Members of Project: Elite Strike Force").
419 - Use {nav Reorder Edit Forms} to make sure the "Advanced" edit form is at
420 the top of the list. The first visible form on this list will be used, so
421 this makes sure advanced users see the advanced edit form.
422
423Basic users should now only have access to basic fields when creating, editing,
424and commenting on tasks, while advanced users will retain full access.
425
426
427Use Case: Security Issues
428=========================
429
430If you want to make sure security issues are reported with the correct
431policies, you can create a "New Security Issue" form. On this form, prefill the
432View and Edit policies and lock or hide them, then lock or hide any additional
433fields (like projects or subscribers) that you don't want users to adjust. You
434might use a custom policy like this for both the View and Edit policies:
435
436> Allow: Members of Project "Security"
437> Allow: Task Author
438> Deny all other users
439
440This will make it nearly impossible for users to make policy mistakes, and will
441prevent other users from observing these tasks indirectly through Herald rules.
442
443You should review "Understanding Policies" above before pursuing this. In
444particular, note that the author may still be able to leak information about
445the report like this:
446
447 - if they have access to a full-power edit form, they can edit the task
448 //after// creating it and open the policies; or
449 - regardless of their edit form access, they can use the Conduit API to
450 change the task policy; or
451 - regardless of any policy controls in Phorge, they can screenshot,
452 print, or forward email about the task to anyone; or
453 - regardless of any technical controls in any software, they can decline to
454 report the issue to you in the first place and sell it on the black market
455 instead.
456
457This goals of this workflow are to:
458
459 - prevent other users from observing security issues improperly through
460 mechanisms like Herald; and
461 - prevent mistakes by well-meaning reporters who are unfamiliar with
462 the software.
463
464It is **not** aimed at preventing reporters who are already in possession of
465information from //intentionally// disclosing that information, since they have
466many other channels by which to do this anyway and no software can ever prevent
467it.
468
469
470Use Case: Upstream
471==================
472
473This section describes the upstream configuration circa December 2015. The
474current configuration may not be exactly the same as the one described below.
475
476We run an open source project with a small core team, a moderate number
477of regular contributors, and a large public userbase. Access to the upstream
478Phorge instance is open to the public.
479
480Although our product is fairly technical, we receive many bug reports and
481feature requests which are of very poor quality. Some users also ignore all the
482documentation and warnings and use the upstream instance as a demo/test
483instance to click as many buttons as they can.
484
485The goals of our configuration are:
486
487 - Provide highly structured "New Bug Report" and "New Feature Request"
488 workflows which make things as easy as possible to get right, in order
489 to improve the quality of new reports.
490 - Separate the userbase into "basic" and "advanced" users. Give the
491 basic users simpler, more streamlined workflows, to make expectations
492 more clear, improve report quality, and limit collateral damage from
493 testing and fiddling.
494
495To these ends, we've configured things like this:
496
497**Community Project**: Advanced users are added to a "Community" project, which
498gives them more advanced access. Advanced forms are "Visible To: Members of
499Project Community".
500
501**Basic and Advanced Edit**: We have basic and advanced task edit forms.
502Members of the community project get access to the advanced one, while other
503users only have access to the basic one.
504
505**Bug, Feature and Advanced Create**: We have "New Bug", "New Feature" and
506"New Advanced Task" creation forms.
507
508The advanced form is the standard creation form, and is only accessible to
509community members.
510
511The basic forms have fewer fields, and each form provides tailored instructions
512which point users at relevant documentation to help them provide good reports.
513
514The basic versions of these forms also have their "Edit Policy" locked down to
515members of the "Community" project and the task author. This means that users
516generally can't mess around with other users' reports, but more experienced
517users can still help manage and resolve tasks.