"Fossies" - the Fresh Open Source Software Archive

Member "RT-Extension-Assets-1.05/lib/RT/Extension/Assets/Tutorial.pm" (15 Oct 2014, 15907 Bytes) of package /linux/misc/RT-Extension-Assets-1.05.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "Tutorial.pm" see the Fossies "Dox" file reference documentation.

    1 # BEGIN BPS TAGGED BLOCK {{{
    2 #
    3 # COPYRIGHT:
    4 #
    5 # This software is Copyright (c) 1996-2014 Best Practical Solutions, LLC
    6 #                                          <sales@bestpractical.com>
    7 #
    8 # (Except where explicitly superseded by other copyright notices)
    9 #
   10 #
   11 # LICENSE:
   12 #
   13 # This work is made available to you under the terms of Version 2 of
   14 # the GNU General Public License. A copy of that license should have
   15 # been provided with this software, but in any event can be snarfed
   16 # from www.gnu.org.
   17 #
   18 # This work is distributed in the hope that it will be useful, but
   19 # WITHOUT ANY WARRANTY; without even the implied warranty of
   20 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   21 # General Public License for more details.
   22 #
   23 # You should have received a copy of the GNU General Public License
   24 # along with this program; if not, write to the Free Software
   25 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
   26 # 02110-1301 or visit their web page on the internet at
   27 # http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
   28 #
   29 #
   30 # CONTRIBUTION SUBMISSION POLICY:
   31 #
   32 # (The following paragraph is not intended to limit the rights granted
   33 # to you to modify and distribute this software under the terms of
   34 # the GNU General Public License and is only of importance to you if
   35 # you choose to contribute your changes and enhancements to the
   36 # community by submitting them to Best Practical Solutions, LLC.)
   37 #
   38 # By intentionally submitting any modifications, corrections or
   39 # derivatives to this work, or any other work intended for use with
   40 # Request Tracker, to Best Practical Solutions, LLC, you confirm that
   41 # you are the copyright holder for those contributions and you grant
   42 # Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
   43 # royalty-free, perpetual, license to use, copy, create derivative
   44 # works based on those contributions, and sublicense and distribute
   45 # those contributions and any derivatives thereof.
   46 #
   47 # END BPS TAGGED BLOCK }}}
   48 
   49 =head1 Introduction
   50 
   51 This is a basic tutorial for setting up asset tracking in RT using Best
   52 Practical's Assets extension. At the end, you'll have a basic configuration
   53 that lets you add assets, search for them, link them to tickets, etc.
   54 
   55 =begin HTML
   56 
   57 <p><img src="http://static.bestpractical.com/images/assets/asset-search.png"
   58 alt="Asset Search Results" /></p>
   59 
   60 =end HTML
   61 
   62 You can follow along with the tutorial and try setting things up yourself to
   63 get a feel for all of the administrative controls. If you want to get a jump
   64 start, the files to set up this basic configuration are provided in the
   65 L<RT::Extension::Assets> distribution in the F<etc> directory. For
   66 configuration, look in F<etc/Tutorial_Configuration.txt>. You can copy all or
   67 part of it and paste it into your F<RT_SiteConfig.pm>.
   68 
   69 To load the test catalog, custom fields, and users, follow the
   70 installation instructions in L<RT::Extension::Assets/INSTALLATION>, then
   71 run the following from your RT directory:
   72 
   73     sbin/rt-setup-database --action insert --datafile \
   74       local/plugins/RT-Extension-Assets/etc/tutorialdata
   75 
   76 This will change the default catalog name, create some users, and give those
   77 users asset permissions. Only asset rights are granted, so you need to grant
   78 additional rights if you want to experiment with creating tickets and linking
   79 assets. The initial user passwords are 'password'. You should only run this on
   80 a test RT instance, as it is not intended to be used for configuring a
   81 production system.
   82 
   83 =head1 Getting Started
   84 
   85 Install the extension following the instructions and some new tables will be
   86 added to your RT database and the assets code will be installed. As with all
   87 extensions, first add C<RT::Extension::Assets> to your C<@Plugins> line.
   88 
   89 There are a few configuration options you might set before starting. Assets
   90 offers a C<$DefaultCatalog> feature that works similar to RT's
   91 L<DefaultQueue|http://bestpractical.com/docs/rt/latest/RT_Config.html#DefaultQueue>,
   92 but you can probably skip it for now since you don't have any catalogs yet.
   93 
   94 More interesting are some optional portlets you can activate to add asset data
   95 to RT's pages. MyAssets and FindAsset portlets are available for placement on
   96 RT at a Glance or in dashboards and a UserAssets portlet is available for the
   97 user summary pages.
   98 
   99 These portlets are fairly self-explanatory and you can add them by finding
  100 C<$HomepageComponents> and C<@UserSummaryPortlets> respectively in
  101 F<RT_Config.pm>, copying to F<RT_SiteConfig.pm>, and adding the portlets you
  102 want. There are also examples in the tutorial sample configuration file. Note
  103 that C<$HomepageComponents> makes the portlets available, but doesn't put them
  104 on RT at a Glance. To add them, just click the Edit link on the upper right-hand
  105 corner of the homepage. C<@UserSummaryPortlets> does automatically add the
  106 "Assigned Assets" portlet to the User Summary page. It will appear based on the
  107 position in the configuration, so just place it in the list where you want it
  108 to appear.
  109 
  110 Once you have your configuration complete, restart your server and you're ready
  111 to go.
  112 
  113 =head1 Catalogs
  114 
  115 For the initial configuration, we'll log in as RT's root user so we have full
  116 rights on the asset configuration. You could also create an "Asset Admin" group
  117 and assign appropriate rights to allow other users to manage catalogs.
  118 
  119 When you log in you'll see a new Assets menu, but before looking there we need
  120 to look at catalogs and some other configuration. Catalogs are to assets what
  121 queues are to tickets, so if you've used RT, the relationship should be fairly
  122 familiar. Similar to the General queue, a "General assets" catalog is provided
  123 to get you started. You can see it at Admin > Assets > Catalogs.
  124 
  125 We're going to use the default, but change it to a name more appropriate for
  126 our use. Clicking on the asset name brings us to the catalog edit page and we
  127 can update the name to "IT Department Assets". You can update the description
  128 if you like as well.
  129 
  130 =begin HTML
  131 
  132 <p><img src="http://static.bestpractical.com/images/assets/edit-catalog.png"
  133 alt="Edit Catalog" /></p>
  134 
  135 =end HTML
  136 
  137 You'll also notice that catalogs have a lifecycle just like queues. The assets
  138 extension comes with a default assets lifecycle, but just like queues you can
  139 create new ones with custom statuses and other configuration to allow RT to
  140 reflect the states of your assets.
  141 
  142 You can find the asset lifecycle in the asset configuration file in your RT
  143 installation at:
  144 
  145     local/plugins/RT-Extension-Assets/etc/Assets_Config.pm
  146 
  147 The initial statuses are new, allocated, in-use, recycled, stolen, and deleted.
  148 Depending on your process, you might add new ones like surplussed, donated, or
  149 in-repair. To create a new asset lifecycle, just copy the default into
  150 F<RT_SiteConfig.pm>, replace the top-level "assets" key with a new name, and
  151 make your changes.
  152 
  153 =head1 Asset Custom Fields
  154 
  155 Next we need to create some custom fields to hold our asset metadata. You can
  156 find asset custom fields at Admin > Assets > Custom Fields and they work just
  157 like custom fields for other RT objects.
  158 
  159 =begin HTML
  160 
  161 <p><img src="http://static.bestpractical.com/images/assets/asset-cfs.png"
  162 alt="Asset Custom Fields" /></p>
  163 
  164 =end HTML
  165 
  166 The extension will automatically provide some core values for your assets. Each
  167 asset can have a Name and Description and, like tickets, they have statuses
  168 based on the lifecycle configuration. You can use Name and Description however
  169 you want and they are not required. However, many of the asset pages use these
  170 fields so it's best to provide a descriptive name to make it easy for people
  171 working in RT to identify the asset quickly. The manufacturer's product name
  172 can be convenient (e.g., '15" Macbook Pro').
  173 
  174 Assets come with three user fields you can associate with an asset: Owner, Held
  175 By, and Contact. These are provided to cover different types of assets, from
  176 laptops to servers to software, and different asset management situations.
  177 Owner can hold the user who bought the asset, maybe the head of the department
  178 where the budget came from. Held by is who the asset is assigned to. Laptops
  179 are assigned to a user and servers might be held (or managed) by the system
  180 administrators. Contact can be used to set a manager who might need to know
  181 about needed system updates or equipment with expiring support. Like tickets,
  182 these roles give you places to attach rights, so use them however they work
  183 best for you.
  184 
  185 Any other information you want to track will need custom fields. We'll start
  186 with a few basic fields:
  187 
  188 =over
  189 
  190 =item * Serial Number (enter one value)
  191 
  192 The serial number from the asset.
  193 
  194 =item * Tracking Number (enter one value)
  195 
  196 An internal tracking number. RT will assign an asset ID as well, but you may
  197 have other systems to integrate with or already have a way to assign asset ids
  198 for accounting purposes.
  199 
  200 =item * Manufacturer (dropdown)
  201 
  202 Company that made the asset.
  203 
  204 =item * Type (dropdown)
  205 
  206 Is it a laptop, server, or cell phone?
  207 
  208 =item * Issue Date (date)
  209 
  210 When the asset was given to the owner (or held by) person.
  211 
  212 Assets keep a transaction history like tickets, so you may be able pull this
  213 information from the "owner set to X" transaction. Creating a separate field
  214 makes it easier to report on.
  215 
  216 =item * Support Expiration (date)
  217 
  218 When the current support contract expires.
  219 
  220 =back
  221 
  222 =head1 Custom Field Grouping
  223 
  224 Any custom fields you create will be displayed on the asset display page in a
  225 default "Custom Fields" section. That may be sufficient, but assets also
  226 supports RT's new custom field grouping feature, so we can group together some
  227 similar custom fields and give them a custom name. If we add the following to
  228 F<RT_SiteConfig.pm>:
  229 
  230     Set(%CustomFieldGroupings,
  231         'RT::Asset' => {
  232             'Asset Details' => ['Serial Number', 'Manufacturer', 'Type', 'Tracking Number'],
  233             'Dates'         => ['Support Expiration', 'Issue Date'],
  234         },
  235     );
  236 
  237 and restart RT, the dates will be tacked on the end of the Dates portlet and we
  238 get an Asset Details label on the other custom fields.
  239 
  240 =begin HTML
  241 
  242 <p><img
  243 src="http://static.bestpractical.com/images/assets/asset-date-details.png"
  244 alt="Asset Date and Details Display" /></p>
  245 
  246 =end HTML
  247 
  248 =head1 Asset Rights
  249 
  250 Now we've got the basic configuration in place to start recording asset data.
  251 Next we need to assign some rights so people can view and edit asset
  252 information. Our staff are all privileged users so we'll grant all view and
  253 modify rights on our catalog to the Privileged role. We'll also include rights
  254 to view and modify the catalog's custom fields, although you could set these
  255 rights individually on each custom field if you wanted to allow users to see
  256 some but not others.
  257 
  258 Similar to queues, you can set rights at the catalog level. Go to Admin >
  259 Assets > Catalogs and click on the catalog you want to edit. Click Group Rights
  260 in the submenu to assign asset rights to groups like the system Privileged
  261 group.
  262 
  263 =begin HTML
  264 
  265 <p><img src="http://static.bestpractical.com/images/assets/catalog-rights.png"
  266 alt="Catalog Rights" /></p>
  267 
  268 =end HTML
  269 
  270 We also want unprivileged users to be able to see their own assets to make it
  271 easier to submit support requests. To give them just the Name and Description
  272 on their own assets, we can grant SeeAssets and SeeCatalogs on the catalog to
  273 the Held By role.
  274 
  275 All of the asset rights are described in the Assets documentation. You can get
  276 much more detailed and fine-grained than this example, allowing selected groups
  277 and users to view and modify multiple different asset custom fields across many
  278 different catalogs.
  279 
  280 =head1 Working with Assets
  281 
  282 So now that we have all of that configuration done, what can we do? Here are a
  283 few scenarios to give you some ideas.
  284 
  285 =head2 Add Assets to Your Catalogs
  286 
  287 To start, staff can now start adding assets to RT allowing you to manage what
  288 you have, what state it's in, who currently has it, and when support expires.
  289 You could set up an intake process to get new assets added as they come in, and
  290 eventually have statuses updated as they are assigned, used, and eventually
  291 cycled out.
  292 
  293 If you already have an asset database, even something simple like a
  294 spreadsheet, you may be able to do an initial bulk import. Best Practical has
  295 released L<RT::Extension::Assets::Import::CSV> which is a CSV import tool to
  296 help you with this.
  297 
  298 =head2 Track Assets
  299 
  300 Your staff can now easily track work on assets by linking RT tickets to the
  301 assets. Assume you have an issue with an asset, like a server needs a new power
  302 supply. Your staff can use the asset search page to find the server. You'll
  303 notice that the RT search box is context sensitive, so when you're on an asset
  304 page, the search changes to Search Assets and you can search with that as well.
  305 
  306 Once you locate the server asset record, in the Actions menu you'll find
  307 "Create linked ticket", which does just that. You select the queue and which
  308 user to use from the asset as the Requestor, and you land on the ticket create
  309 page with some information pre-filled.
  310 
  311 =begin HTML
  312 
  313 <p><img
  314 src="http://static.bestpractical.com/images/assets/asset-ticket-create.png"
  315 alt="Create Ticket for Asset Work" /></p>
  316 
  317 =end HTML
  318 
  319 As you can see in the screenshot, when you create a ticket with a linked asset,
  320 you get an asset portlet on the create page and on the ticket display page as
  321 well. If you navigate back to the asset, you'll see a link back to the ticket
  322 in the Links section there. This gives you a record of all the tickets that
  323 have been opened against this asset. If this is a common scenario for you, you
  324 might even add a custom field on the ticket with the vendor tracking number of
  325 the repair. During the repair, you might flip the asset to an 'in-repair'
  326 status. Then when the ticket is resolved, flip it back to 'in-use'.
  327 
  328 =head2 End User Asset Tickets
  329 
  330 If an end user contacts us with some problems with their laptop, RT makes it
  331 easy to find the correct laptop record and create a ticket for them. Since our
  332 support staff do this frequently, they have added the Find User portlet to
  333 their RT at a glance page and can quickly search for the user and go to their
  334 User Summary page (new in RT 4.2).
  335 
  336 We have added the Assigned Assets portlet to the User Summary page, so the
  337 laptop is right there on the page when we find the user. We can just click on
  338 the asset, then use the "Create linked ticket" action as before to create the
  339 new repair ticket.
  340 
  341 =head2 End User Self Service
  342 
  343 Assume we already assign passwords to our unprivileged users so they can use
  344 RT's self service interface to submit tickets and they have basic permissions
  345 to do so (SeeQueue on the designated queue, CreateTicket, etc.). Since we've
  346 given some asset rights to unprivileged users, they can use RT's Self Service
  347 interface to find their assets (e.g., laptops, cell phones, etc.) when
  348 submitting support requests.
  349 
  350 When they log into the self service interface, they will see an Assets menu
  351 that takes them to a page displaying assets assigned to them. In our example
  352 configuration, this is based on the Held by setting we set when we gave out the
  353 laptop. When they navigate to the asset, they will see the Actions menu with
  354 the same "Create linked ticket" action our staff uses. When they click on that,
  355 they'll end up on the simplified ticket create page for self service. When the
  356 ticket is created, the laptop will already be linked to it, saving our staff
  357 the work.
  358 
  359 =begin HTML
  360 
  361 <p><img
  362 src="http://static.bestpractical.com/images/assets/asset-ticket-create-selfservice.png"
  363 alt="Self Service Ticket for Asset Work" /></p>
  364 
  365 =end HTML
  366 
  367 =head1 Summary
  368 
  369 This tutorial is only a quick overview showing how the assets extension can
  370 help you track assets. There are many more features you'll find as you explore
  371 the assets interface, like stacking multiple assets on a single ticket, bulk
  372 update features similar to tickets, and the search interface. Have fun!
  373 
  374 =cut