NAME
RT-Extension-Assets - Asset management for RT
INSTALLATION
Assets requires version 4.2.1 or higher of RT.
perl Makefile.PL
make
make install
This step may require root permissions.
Patch your RT
Assets requires a small patch to work on versions of RT prior to
4.2.3. To patch RT, run:
patch -d /opt/rt4 -p1 < patches/rt-4.2.1-4.2.2.patch
RT version 4.2.3 and above already contain this patch.
make initdb
Only run this the first time you install this module.
If you run this twice, you will end up with duplicate data in your
database.
If you are upgrading this module, check for upgrading instructions
in case changes need to be made to your database.
Edit your /opt/rt4/etc/RT_SiteConfig.pm
Add this line:
Plugin( "RT::Extension::Assets" );
Configure portlets for RT's Homepage and User Summary
If you would like the MyAssets or FindAsset portlets to be available
on RT at a Glance and Dashboards, you will need to copy
$HomepageComponents from RT_Config.pm to RT_SiteConfig.pm and add
them to the list.
If you would like the UserAssets portlet to show up on the User
Summary page, you will need to copy @UserSummaryPortlets from
RT_Config.pm to RT_SiteConfig.pm and add UserAssets to the list.
Clear your mason cache
rm -rf /opt/rt4/var/mason_data/obj
Restart your webserver
CONFIGURATION
See Assets_Config.pm for documentation on the available configuration
parameters.
USAGE
Assets start as a small set of fundamental record data upon which you
build custom fields (CFs) of any type you like to describe the assets
you want to track. By themselves, before you setup any CFs, assets are
not very useful.
Just like tickets are assigned to queues, assets are assigned to
catalogs. The default catalog is named "General assets", but we suggest
you rename it and add additional catalogs to better fit your
organization.
You may want to use catalogs to separate assets into departments,
general type of asset, hardware vs. software, etc. Catalogs, like
queues, are generally easiest to work with when there's more than few
but less than many dozen. The catalog of an asset should represent some
fundamental quality of it (and many other assets!), that could just as
easily be expressed as a custom field, but which is more important than
other qualities for categorizing, sorting, and searching.
Managing catalogs
Catalogs are managed by RT administrators, or anyone with the
"AdminCatalog" right. You can find the list of catalogs, create new
catalogs, and manage existing ones under the Tools → Configuration →
Assets → Catalogs menu.
Currently you need to log out and log back in to see changes to catalogs
in any of the catalog selection dropdowns. This doesn't affect the
catalog name displayed on individual asset pages.
Adding fields
You can see the current asset CFs by navigating to Admin > Assets >
Custom Fields. From there you can use the "Create" link to create a new
asset CF. If you know you want to create a new CF right away, you can do
so via Admin > Assets > Custom Fields > Create.
When creating a CF, be sure to select "Assets" in the "Applies To"
dropdown. You'll also need to grant rights to the groups and/or roles
which need to see the fields, otherwise they'll be hidden. See the
following section.
Similar to ticket CFs, asset custom fields are added globally or to
specific catalogs. Only assets within those specific catalogs will have
the CFs available. After creating a CF, you'll need to visit the
"Applies To" page to add it to the catalogs you want or make it global.
Rights
There are three rights controlling basic access to assets and two for
catalogs. Each right is grantable at the global level or individual
catalog level, and grantable to system groups, asset roles, user groups,
and individual users (just like ticket and queue rights).
ShowAsset
Allows viewing an asset record and it's core fields (but not CFs).
Without it, no assets can be seen. Similar to ShowTicket.
CreateAsset
Allows creating assets and filling in the core fields (but not CFs).
Without it, no assets can be created. Similar to CreateTicket.
ModifyAsset
Allows modifying existing assets and their core fields (but not CFs).
Without it, basic asset data cannot be modified after creation. Similar
to ModifyTicket.
Most of your rights configuration will be on the CFs, and will likely
need to be done for each CF. This lets you fine tune which fields are
visible to individual groups and/or roles of users. Relevant CF rights
are SeeCustomField and ModifyCustomField.
Rights related to assets may also come from the "Lifecycle statuses"
configuration and restrict status transitions.
ShowCatalog
Allows seeing a catalog's name and other details when associated with
assets. Without it, users will see "[a hidden catalog]" or a blank space
where the catalog name would normally be. Similar to SeeQueue.
AdminCatalog
Allows creating new catalogs and modifying all aspects of existing
catalogs, including changing the CFs associated with the catalog,
granting/revoking rights, and adding/removing role members. This right
should only be granted to administrators of RT. Similar to AdminQueue.
Typical configuration
A typical configuration grants the system Privileged group the
following: ShowAsset, CreateAsset, ModifyAsset, and ShowCatalog
globally, and SeeCustomField and ModifyCustomField globally on all asset
CFs.
If you want self service users (Unprivileged) to be able to view the
assets they hold, grant the Held By role ShowAsset and ShowCatalog
globally and SeeCustomField on the necessary asset CFs.
People and Roles
Just like tickets, assets have various roles which users and groups may
be assigned to. The intended usages of these roles are described below,
but you're free to use them for whatever you'd like, of course.
The roles provide ways to keep track of who is involved with each asset,
as well as providing a place to grant rights that depend on the user's
association with each asset.
In addition to adding people to individual asset roles, you can also add
role members at an entire catalog level. These catalog-level roles are
useful in cases when you might have an entire catalog of assets for
which the same people should be the Contacts, or which are Held By the
same group. Unlike tickets where the queue watchers are invisible,
catalog role members are visible because assets are generally much
longer lived than tickets. When a problem with an asset arises, it's
easier to see who to create a ticket for. On individual asset pages,
catalog role members are shown with the text "(via this asset's
catalog)" following each name.
Owner
The person responsible for the asset, perhaps the purchaser or manager.
Restricted to a single user. Not available at a catalog level.
Held By
The person or people who physically possess the asset or are actively
using the asset (if it isn't physical). This may be the same as the
Contacts or may be different. For example, a computer workstation may be
"held by" a university professor, but the contact may be the IT staff
member responsible for all assets in the professor's department. This
role is most similar to Requestor on tickets, although not equivalent.
May be multiple users and/or groups.
Contact
The person or people who should be contacted with questions, problems,
notifications, etc. about the asset. Contacts share some of the same
intended usages of both Requestors and Ccs on tickets.
May be multiple users and/or groups.
Lifecycle statuses
One of the basic asset fields is "Status". Similar to tickets, the valid
statuses and their transitions and actions can be customized via RT's
standard Lifecycles configuration (see "Lifecycles" in RT_Config.pm).
The default lifecycle is named "assets". You're free to modify it as
much as you'd like, or add your own lifecycles. Each catalog may have
its own lifecycle.
For the default "assets" configuration, see etc/Assets_Config.pm.
Field organization
Groupings
You can organize your asset CFs into visual and logical "groupings" as
you see fit. These groupings appear as separate boxes on the asset
display page and become separate pages for editing (showing up in the
per-asset menu).
By default your CFs will appear in a Custom Fields box on the asset
display page and will be editable from a box of the same name on the
Basics editing page.
Using the %CustomFieldGroupings option (documented in etc/RT_Config.pm),
you can move individual CFs by name into one of the four built-in
groupings (Basics, People, Dates, and Links) or create your own just by
naming it. An example, assuming a date CF named "Purchased" and two
"enter one value" CFs named "Weight" and "Color":
# In etc/RT_SiteConfig.pm
Set(%CustomFieldGroupings,
'RT::Asset' => {
'Dates' => ['Purchased'],
'Physical Properties' => ['Weight', 'Color'],
},
);
This configuration snippet will move all three CFs out of the generic
Custom Fields box and into the Dates box and a new box titled Physical
Properties. The "Purchased" CF will be editable from the Dates page and
a new page titled "Physical Properties" will appear in the menu to allow
editing of the "Weight" and "Color" CFs.
Ordering
Within a box, CFs come after any built-in asset fields such as Name,
Description, Created, Last Updated, etc. The CFs themselves are ordered
according to the sorting seen (and adjustable) on the global Asset
Custom Fields page (Tools → Configuration → Global → Custom Fields →
Assets) and the individual catalog Custom Fields pages (Tools →
Configuration → Assets → Catalogs → (Pick one) → Custom Fields).
Global asset CFs may be intermixed with per-catalog CFs with ordering.
Importing existing data
Another extension, RT::Extension::Assets::Import::CSV provides tools to
import new and update existing assets from a CSV dump. Its configuration
lets you map the fields in the CSV to the asset fields you've already
created in RT. RT::Extension::Assets::AppleGSX also provides tools for
looking up data associated with an Apple product.
METHODS ADDED TO OTHER CLASSES
RT::CustomField
LoadByNameAndCatalog
Loads the described asset custom field, if one is found, into the
current object. This method only consults custom fields applied to
RT::Catalog for RT::Asset objects.
Takes a hash with the keys:
Name
A RT::CustomField ID or Name which applies to assets.
Catalog
Optional. An RT::Catalog ID or Name.
If Catalog is specified, only a custom field added to that Catalog will
be loaded.
If Catalog is 0, only global asset custom fields will be loaded.
If no Catalog is specified, all asset custom fields are searched
including global and catalog-specific CFs.
Please note that this method may load a Disabled custom field if no
others matching the same criteria are found. Enabled CFs are
preferentially loaded.
RT::CustomFields
LimitToCatalog
Takes a numeric RT::Catalog ID. Limits the RT::CustomFields collection
to only those fields applied directly to the specified catalog. This
limit is OR'd with other "LimitToCatalog" and "LimitToObjectId" in
RT::CustomFields calls.
Note that this will cause the collection to only return asset CFs.
BUGS
Please report bugs to assets-bugs@bestpractical.com; if you're not sure
if what you've discovered is a bug, please discuss it on
rt-users@lists.bestpractical.com before reporting it.
LICENSE AND COPYRIGHT
This software is Copyright (c) 2014 by Best Practical Solutions
This is free software, licensed under:
The GNU General Public License, Version 2, June 1991