"Fossies" - the Fresh Open Source Software Archive 
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
See also the last
Fossies "Diffs" side-by-side code changes report for "README":
1.01_vs_1.02.
1 NAME
2 RT-Extension-Assets - Asset management for RT
3
4 INSTALLATION
5 Assets requires version 4.2.1 or higher of RT.
6
7 perl Makefile.PL
8 make
9 make install
10 This step may require root permissions.
11
12 Patch your RT
13 Assets requires a small patch to work on versions of RT prior to
14 4.2.3. To patch RT, run:
15
16 patch -d /opt/rt4 -p1 < patches/rt-4.2.1-4.2.2.patch
17
18 RT version 4.2.3 and above already contain this patch.
19
20 make initdb
21 Only run this the first time you install this module.
22
23 If you run this twice, you will end up with duplicate data in your
24 database.
25
26 If you are upgrading this module, check for upgrading instructions
27 in case changes need to be made to your database.
28
29 Edit your /opt/rt4/etc/RT_SiteConfig.pm
30 Add this line:
31
32 Plugin( "RT::Extension::Assets" );
33
34 Configure portlets for RT's Homepage and User Summary
35 If you would like the MyAssets or FindAsset portlets to be available
36 on RT at a Glance and Dashboards, you will need to copy
37 $HomepageComponents from RT_Config.pm to RT_SiteConfig.pm and add
38 them to the list.
39
40 If you would like the UserAssets portlet to show up on the User
41 Summary page, you will need to copy @UserSummaryPortlets from
42 RT_Config.pm to RT_SiteConfig.pm and add UserAssets to the list.
43
44 Clear your mason cache
45 rm -rf /opt/rt4/var/mason_data/obj
46
47 Restart your webserver
48
49 CONFIGURATION
50 See Assets_Config.pm for documentation on the available configuration
51 parameters.
52
53 USAGE
54 Assets start as a small set of fundamental record data upon which you
55 build custom fields (CFs) of any type you like to describe the assets
56 you want to track. By themselves, before you setup any CFs, assets are
57 not very useful.
58
59 Just like tickets are assigned to queues, assets are assigned to
60 catalogs. The default catalog is named "General assets", but we suggest
61 you rename it and add additional catalogs to better fit your
62 organization.
63
64 You may want to use catalogs to separate assets into departments,
65 general type of asset, hardware vs. software, etc. Catalogs, like
66 queues, are generally easiest to work with when there's more than few
67 but less than many dozen. The catalog of an asset should represent some
68 fundamental quality of it (and many other assets!), that could just as
69 easily be expressed as a custom field, but which is more important than
70 other qualities for categorizing, sorting, and searching.
71
72 Managing catalogs
73 Catalogs are managed by RT administrators, or anyone with the
74 "AdminCatalog" right. You can find the list of catalogs, create new
75 catalogs, and manage existing ones under the Tools → Configuration →
76 Assets → Catalogs menu.
77
78 Currently you need to log out and log back in to see changes to catalogs
79 in any of the catalog selection dropdowns. This doesn't affect the
80 catalog name displayed on individual asset pages.
81
82 Adding fields
83 You can see the current asset CFs by navigating to Admin > Assets >
84 Custom Fields. From there you can use the "Create" link to create a new
85 asset CF. If you know you want to create a new CF right away, you can do
86 so via Admin > Assets > Custom Fields > Create.
87
88 When creating a CF, be sure to select "Assets" in the "Applies To"
89 dropdown. You'll also need to grant rights to the groups and/or roles
90 which need to see the fields, otherwise they'll be hidden. See the
91 following section.
92
93 Similar to ticket CFs, asset custom fields are added globally or to
94 specific catalogs. Only assets within those specific catalogs will have
95 the CFs available. After creating a CF, you'll need to visit the
96 "Applies To" page to add it to the catalogs you want or make it global.
97
98 Rights
99 There are three rights controlling basic access to assets and two for
100 catalogs. Each right is grantable at the global level or individual
101 catalog level, and grantable to system groups, asset roles, user groups,
102 and individual users (just like ticket and queue rights).
103
104 ShowAsset
105 Allows viewing an asset record and it's core fields (but not CFs).
106 Without it, no assets can be seen. Similar to ShowTicket.
107
108 CreateAsset
109 Allows creating assets and filling in the core fields (but not CFs).
110 Without it, no assets can be created. Similar to CreateTicket.
111
112 ModifyAsset
113 Allows modifying existing assets and their core fields (but not CFs).
114 Without it, basic asset data cannot be modified after creation. Similar
115 to ModifyTicket.
116
117 Most of your rights configuration will be on the CFs, and will likely
118 need to be done for each CF. This lets you fine tune which fields are
119 visible to individual groups and/or roles of users. Relevant CF rights
120 are SeeCustomField and ModifyCustomField.
121
122 Rights related to assets may also come from the "Lifecycle statuses"
123 configuration and restrict status transitions.
124
125 ShowCatalog
126 Allows seeing a catalog's name and other details when associated with
127 assets. Without it, users will see "[a hidden catalog]" or a blank space
128 where the catalog name would normally be. Similar to SeeQueue.
129
130 AdminCatalog
131 Allows creating new catalogs and modifying all aspects of existing
132 catalogs, including changing the CFs associated with the catalog,
133 granting/revoking rights, and adding/removing role members. This right
134 should only be granted to administrators of RT. Similar to AdminQueue.
135
136 Typical configuration
137 A typical configuration grants the system Privileged group the
138 following: ShowAsset, CreateAsset, ModifyAsset, and ShowCatalog
139 globally, and SeeCustomField and ModifyCustomField globally on all asset
140 CFs.
141
142 If you want self service users (Unprivileged) to be able to view the
143 assets they hold, grant the Held By role ShowAsset and ShowCatalog
144 globally and SeeCustomField on the necessary asset CFs.
145
146 People and Roles
147 Just like tickets, assets have various roles which users and groups may
148 be assigned to. The intended usages of these roles are described below,
149 but you're free to use them for whatever you'd like, of course.
150
151 The roles provide ways to keep track of who is involved with each asset,
152 as well as providing a place to grant rights that depend on the user's
153 association with each asset.
154
155 In addition to adding people to individual asset roles, you can also add
156 role members at an entire catalog level. These catalog-level roles are
157 useful in cases when you might have an entire catalog of assets for
158 which the same people should be the Contacts, or which are Held By the
159 same group. Unlike tickets where the queue watchers are invisible,
160 catalog role members are visible because assets are generally much
161 longer lived than tickets. When a problem with an asset arises, it's
162 easier to see who to create a ticket for. On individual asset pages,
163 catalog role members are shown with the text "(via this asset's
164 catalog)" following each name.
165
166 Owner
167 The person responsible for the asset, perhaps the purchaser or manager.
168
169 Restricted to a single user. Not available at a catalog level.
170
171 Held By
172 The person or people who physically possess the asset or are actively
173 using the asset (if it isn't physical). This may be the same as the
174 Contacts or may be different. For example, a computer workstation may be
175 "held by" a university professor, but the contact may be the IT staff
176 member responsible for all assets in the professor's department. This
177 role is most similar to Requestor on tickets, although not equivalent.
178
179 May be multiple users and/or groups.
180
181 Contact
182 The person or people who should be contacted with questions, problems,
183 notifications, etc. about the asset. Contacts share some of the same
184 intended usages of both Requestors and Ccs on tickets.
185
186 May be multiple users and/or groups.
187
188 Lifecycle statuses
189 One of the basic asset fields is "Status". Similar to tickets, the valid
190 statuses and their transitions and actions can be customized via RT's
191 standard Lifecycles configuration (see "Lifecycles" in RT_Config.pm).
192 The default lifecycle is named "assets". You're free to modify it as
193 much as you'd like, or add your own lifecycles. Each catalog may have
194 its own lifecycle.
195
196 For the default "assets" configuration, see etc/Assets_Config.pm.
197
198 Field organization
199 Groupings
200 You can organize your asset CFs into visual and logical "groupings" as
201 you see fit. These groupings appear as separate boxes on the asset
202 display page and become separate pages for editing (showing up in the
203 per-asset menu).
204
205 By default your CFs will appear in a Custom Fields box on the asset
206 display page and will be editable from a box of the same name on the
207 Basics editing page.
208
209 Using the %CustomFieldGroupings option (documented in etc/RT_Config.pm),
210 you can move individual CFs by name into one of the four built-in
211 groupings (Basics, People, Dates, and Links) or create your own just by
212 naming it. An example, assuming a date CF named "Purchased" and two
213 "enter one value" CFs named "Weight" and "Color":
214
215 # In etc/RT_SiteConfig.pm
216 Set(%CustomFieldGroupings,
217 'RT::Asset' => {
218 'Dates' => ['Purchased'],
219 'Physical Properties' => ['Weight', 'Color'],
220 },
221 );
222
223 This configuration snippet will move all three CFs out of the generic
224 Custom Fields box and into the Dates box and a new box titled Physical
225 Properties. The "Purchased" CF will be editable from the Dates page and
226 a new page titled "Physical Properties" will appear in the menu to allow
227 editing of the "Weight" and "Color" CFs.
228
229 Ordering
230 Within a box, CFs come after any built-in asset fields such as Name,
231 Description, Created, Last Updated, etc. The CFs themselves are ordered
232 according to the sorting seen (and adjustable) on the global Asset
233 Custom Fields page (Tools → Configuration → Global → Custom Fields →
234 Assets) and the individual catalog Custom Fields pages (Tools →
235 Configuration → Assets → Catalogs → (Pick one) → Custom Fields).
236
237 Global asset CFs may be intermixed with per-catalog CFs with ordering.
238
239 Importing existing data
240 Another extension, RT::Extension::Assets::Import::CSV provides tools to
241 import new and update existing assets from a CSV dump. Its configuration
242 lets you map the fields in the CSV to the asset fields you've already
243 created in RT. RT::Extension::Assets::AppleGSX also provides tools for
244 looking up data associated with an Apple product.
245
246 METHODS ADDED TO OTHER CLASSES
247 RT::CustomField
248 LoadByNameAndCatalog
249 Loads the described asset custom field, if one is found, into the
250 current object. This method only consults custom fields applied to
251 RT::Catalog for RT::Asset objects.
252
253 Takes a hash with the keys:
254
255 Name
256 A RT::CustomField ID or Name which applies to assets.
257
258 Catalog
259 Optional. An RT::Catalog ID or Name.
260
261 If Catalog is specified, only a custom field added to that Catalog will
262 be loaded.
263
264 If Catalog is 0, only global asset custom fields will be loaded.
265
266 If no Catalog is specified, all asset custom fields are searched
267 including global and catalog-specific CFs.
268
269 Please note that this method may load a Disabled custom field if no
270 others matching the same criteria are found. Enabled CFs are
271 preferentially loaded.
272
273 RT::CustomFields
274 LimitToCatalog
275 Takes a numeric RT::Catalog ID. Limits the RT::CustomFields collection
276 to only those fields applied directly to the specified catalog. This
277 limit is OR'd with other "LimitToCatalog" and "LimitToObjectId" in
278 RT::CustomFields calls.
279
280 Note that this will cause the collection to only return asset CFs.
281
282 BUGS
283 Please report bugs to assets-bugs@bestpractical.com; if you're not sure
284 if what you've discovered is a bug, please discuss it on
285 rt-users@lists.bestpractical.com before reporting it.
286
287 LICENSE AND COPYRIGHT
288 This software is Copyright (c) 2014 by Best Practical Solutions
289
290 This is free software, licensed under:
291
292 The GNU General Public License, Version 2, June 1991
293