-
Notifications
You must be signed in to change notification settings - Fork 3
/
README
244 lines (182 loc) · 9.05 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
NAME
RT::Extension::FormTools - Create multi-page ticket creation wizards for
RT
DESCRIPTION
Starting in version 1.00, this extension provides a full UI for RT
administrators to create multi-page form wizards to collect information
and create a ticket.
RT VERSION
Works with RT 5.0.5 and newer.
INSTALLATION
perl Makefile.PL
make
make install
May need root permissions
Edit your /opt/rt5/etc/RT_SiteConfig.pm
Add this line:
Plugin('RT::Extension::FormTools');
Clear your mason cache
rm -rf /opt/rt5/var/mason_data/obj
Restart your webserver
USAGE
Creating Forms
Modify
Once installed and activated, users with the SuperUser or AdminForms
right can go to Admin > FormTools > Create to build new forms. Use
Select to view a list of existing forms.
When you initially create a form, you select the queue that the ticket
will be created in after a user fills out the form. The selected queue
will also determine which custom fields are available in the form
builder.
The Modify page allows you to configure all of the pages for the
selected form. The Components bar on the left lists HTML elements, Core
RT fields, and all custom fields available to the queue selected for the
current form. To build pages in your form, drag elements from the left
into the Content area in the FormTools Pages section on the right.
You can drag elements up and down to arrange content for each page. To
configure elements or add text content, click the pencil icon.
Click the plus (+) to create new pages. To change the order of the
pages, click the gearbox and update the sort order.
HTML Element
One of the available components is "HTML Element" and this accepts HTML
that will be displayed on the form in the location you select. This
allows you to place blocks of text that include additional interactive
elements like links (anchor tags).
If you place one of these blocks on the Result page, you can also
reference information about the ticket just created by the form. You can
use all variables defined for Simple templates
<https://docs.bestpractical.com/rt/latest/customizing/templates.html#Sel
ected-Simple-template-variables> in RT. As with RT templates, place the
variables in curly braces in your HTML. For example, if you wanted to
include a link to the created ticket, you could define it like this:
<p>You can review your ticket regarding
<a href="/Ticket/Display.html?id={$TicketId}">{$TicketSubject}</a>
and check there for status updates. You should also receive email.</p>
Description
Your forms will be made available to users on a dedicated Forms page in
the RT web UI. Forms can be accessed by privileged users in the main RT
interface and by unprivilged users in the self service interface.
The Description tab allows you to upload an icon and provide text to
show on this forms page. Include an icon that represents what the form
is intended for and include a description to help users pick the right
form for the right task.
Routing
The routing page allows you to change the default queue that the form
will create a ticket in when submitted.
You can also add alternate routing based on the values entered for
custom fields on the form. Select a custom field and comparison logic to
evaluate the value entered by the user. If the comparison logic matches
then the ticket will be created in the alternate queue.
Advanced
The advanced page shows the raw JSON representation of the configured
pages in your form. We recommend not editing the JSON directly. However,
you can copy the content and paste it into another page if you want to
migrate a form from development to production. You can also save the
JSON to a file and use the rt-insert-formtools-config utility to load it
into another RT.
Rights
You can control access to forms by granting the ShowForm right for
groups or users. By default, only SuperUsers can see forms, so you need
to grant ShowForm to users or groups for them to be visible.
Using Forms
Privileged and unprivileged users can find a list of available forms at
Home > Forms. Users need to have the ShowForm right to see forms listed.
Once the form is filled out, it will create a ticket, so form users also
need CreateTicket in the queue where the form will be created. FormTools
checks this at the beginning of a form and shows the user a message if
they don't have sufficient rights.
Form Groups
If you would like to organize your forms by placing them in groups you
can enable Form Groups by setting FormToolsEnableGroups in your
/opt/rt5/etc/RT_SiteConfig.pm:
Set( $FormToolsEnableGroups, 1 );
Setting this config option to a true value will enable form group admin
pages where you can create and maintain form groups.
All forms will be required to placed in a form group.
The list of forms will first show a list of available form groups.
Clicking a form group will show all available forms in that group.
Users with the ShowForm right for a form group will see the group listed
and all forms in a group.
Users with the ShowForm right for a form will see the form group listed
and when clicking the group will only see the forms in that group they
have the ShowForm right for.
A banner message may be added to a form group that will be displayed to
the user when listing available forms in that group. A new ShowBanner
component is available that will also show the banner message on a form
page.
As with forms the form group Description tab allows you to upload an
icon and provide text to show on this form groups listing page. Include
an icon that represents what the forms in this group are intended for
and include a description to help users pick the right form group for
the right task.
Internals
In earlier versions, this extension provided code-level Mason templates
as helpers to manually code forms. We believe pages created with these
earlier versions will continue to work, but it's possible they may stop
working at some point as we continue to work on FormTools. If you have
older FormTools code, it's safest to run with version 0.60. Going
forward, we recommend converting your forms to the new interface using
the new UI.
The documentation below is retained as the components are all still
available.
Mason Components
See ex/RT-Example-FormTools/ for an example extension written using this
module.
/FormTools/Form
The top-level component that most elements will call, as a wrapper:
<&|/FormTools/Form, next => "/URI/of/next/page" &>
(form elements)
</&>
It requires that the next page in the wizard be passed as the next
parameter; this may be empty at the end of the wizard. It renders page
decoration (using /Elements/Header). It assumes that the queue will be
stored in $m-notes('queue')>.
/FormTools/Field
Renders a field in the form. It takes the name of a core field, or CF
name:
<& /FormTools/Field, name => 'Requestors' &>
Valid core fields include:
Requestors
Cc
AdminCc
Owner
Subject
Content
Attach
Due
TimeEstimated
Any other argument to name is assumed to be the name of a custom field.
/FormTools/Next
Renders the "Next page" button.
/FormTools/ShowChoices
Shows the values that have already been submitted.
Internal Functions
In addition to the Mason components, this module provides a number of
functions which may be useful to call from Mason templates.
is_core_field field_name
Checks if the given field_name is is a field that we consider 'core' to
RT (subject, AdminCc, etc) rather than something which should be treated
as a Custom Field.
Naming a Custom Field Subject would cause serious pain with FormTools.
validate_cf CF, ARGSRef
Takes a given RT::CustomField object and a hashref of query parameters,
and returns a list of a boolean of if the custom field validates,
followed by a list of errors.
email_is_privileged email_address
Returns true if the given email address belongs to a privileged user.
has_value value
Returns true if the value is defined and non-empty.
LoadFormIcon($current_user, $form_id)
Loads the form icon attribute associated with the passed form id.
Returns a tuple of attribute object or false, and a message.
AUTHOR
Best Practical Solutions, LLC
BUGS
All bugs should be reported via email to
L<[email protected]|mailto:[email protected]>
or via the web at
L<rt.cpan.org|http://rt.cpan.org/Public/Dist/Display.html?Name=RT-Extension-FormTools>.
LICENSE AND COPYRIGHT
This software is Copyright (c) 2014-2024 by Best Practical Solutions
This is free software, licensed under:
The GNU General Public License, Version 2, June 1991