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 "LimitToGlobal" 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

