Home

Nomenclature

• Asset: An individual piece of equipment that is uniquely identifiable.
• Attribute: A property or metric of a model or asset, with a specified value.
• Category: A hierarchical organization of the purpose and/or form factor of a model, such as Handheld Multimeters. Models may be assigned to multiple categories.
• Manufacturer: The producer or vendor of an asset that specifies a model.
• Model: A manufacturer code that identifies a specific design or option. There may be may assets of the same model, each with different serial numbers.
• Location: A hierarchical organization of the physical storage and/or usage location of an asset, such as Campus > Building > Room. Every asset has a home location (where it is stored), and possibly a usage location specified by the user during check-out.
• Transaction: A timestamped action that changes the state (availability) of an asset.
  • Check-in: Return an asset to its home location.
  • Check-out: Claim temporary custody of an asset by moving it to a specified location for a specified purpose and estimated time period.
  • Restrict: Prevent check-outs of an asset. This does not preclude use of the assets, but it must remain at its home location, such as for a permanent test fixture or workstation.
  • Unrestrict: Allow check-outs of an asset that is currently restricted.
• User: An authenticated person, assigned to one of the following roles with associated permissions:
  • Disabled: No access.
  • Viewer: Can view all assets, models, manufacturers, locations, categories, and attributes, but not transactions or users.
  • User: Viewer permissions, but can view transactions, and can check in and out assets.
  • Contributor: User permissions, and can add/edit/delete assets, models, manufactures, locations, categories, and attributes.
  • Administrator: Contributor permissions, and can add/edit/delete users and transactions, including (un)restricting assets; import/export SQL and uninstall.

Usage

Page Layout

With the exception of the asset details page, each page has a similar layout, but can vary depending on the role of the user.

Header

The header floats at (sticks to) the top of the page. On its left is the logo and title; in the center are the navigation links to each page; and on the right is the authenticated user menu, asset search field, and shopping cart icon. The shopping cart is disabled when empty, and its contents appear on the left side of the page when the icon clicked. The number inside the badge next to the icon shows the number of assets in the cart.

Sidebar

If available, the sidebar resides on the left side of the page. It may contain a button to add an element. It also may contain one or more collapsible trees that filter the search results. Each tree can have up to one selected option.

Search Results

The center of the page displays the table of search results, with additional filtering options above it, including: the number of results pagination navigation links (if applicable), a beginning-of-word search filter, and possibly other filters. Certain columns of the table can be sorted by clicking on the sort icon to the right of the column header text. The current sort order is displayed by the direction of the arrow, with the highest priority column's icon darker than the rest.

Footer

By default, the footer contains various links to learn about or get support for using ISLE.

Populating the Database

The following order is recommended for the initial population of the database with assets.

1. Add users and assign roles (optional, more can be added later).
2. Add manufacturers (prerequisite for models).
3. Add models (prerequisite for assets).
4. Add locations (prerequisite for assets).
5. Add categories and attributes (optional, more can be added later).
6. Add assets. Model, serial, and home location are required.

Transacting

Assets may be checked-in/out in two ways. One asset may be immediately checked-out by clicking on the "Check-out" button on the assets page. One or more assets may be checked-out at the same time by adding them to your shopping cart by clicking the green icon next to an available asset. Once added, click on the shopping cart icon in the header, then the "Check-out" button in the shopping cart. Checking-in assets are done in a similar fashion, except that a returns cart is used, which is displayed below the header when on the assets page.

Assets must be checked-out to a location (for tracking purposes) with an estimated return date, and given a reason (in the Notes field). They must be returned to their home location when checked-in.

Deleting

As ISLE uses a relational database with ON DELETE CASCADE set for all foreign keys, deleting a foreign key row will delete all rows in all tables that reference that key. This was chosen over ON DELETE RESTRICT to allow for quick purging of large amounts of data, at the risk of unintentional deletes. This is why every delete action must be confirmed with two clicks. Deleting elements below will result in cascading deletions:

• Assets: Deletes all associated transactions.
• Categories: Deletes all descendant categories.
• Locations: Deletes all descendant locations, and associated assets and transactions.
• Manufacturers: Deletes all associated models.
• Models: Deletes all associated assets.
• Users: Deletes all associated transactions.

Administrative Overrides

The Administrator role can emulate other roles and/or users via the admin query string parameter array with keys:

• role: Numeric ID of role to emulate listed in the roles table and www/includes/classes/DataModels/Role.php. Non-persistent, must be present in HTTP GET request.
• user: Numeric ID of user to emulate listed in the users table. Persistent until changed or re-authenticated.

Note that if both role and user are provided, the given user is emulated with the given role. Example: ?admin[role]=8&admin[user]=3

Customization

Without modifying the source code, there are some convenient options to customize some features of ISLE, all of which are accomplished my modifying www/includes/settings.php, which is generated by the setup wizard. The complete list of settings and their defaults can be found in www/includes/classes/Settings.php.

Hooks

While most settings have literal values, hooks are PHP callables that may return a value and/or output to the buffer.

Authentication

ISLE has a built-in simple user/password authentication function (ISLE\Service::userAuthenticator), but this can be overridden by a custom function. A common example is to implement LDAP authentication:

return [
    'hooks' => [
        'authentication' => function() {
            try {
                $entries = Ldap::search('uid=' . $_SERVER['PHP_AUTH_USER']);
                if (!($entries['count'] ?? 0)) {
                    throw new Exception('User ' . $_SERVER['PHP_AUTH_USER'] . ' not found in the LDAP directory!');
                }
                $entry = $entries[0];
                $id = ISLE\Service::executeStatement(
                    '
  SELECT `id`
  FROM `' . ISLE\Settings::get('table_prefix') . 'users`
  WHERE LOWER(`email`) = LOWER(?)
                    ',
                    [['value' => $entry['email'][0], 'type' => PDO::PARAM_STR]]
                )->fetchColumn();
                if (!$id) {
                    throw new Exception('You are not authorized.  Please contact an administrator for access.');
                }
            } catch (Exception $e) {
                $_SESSION['message'] = [
                    'type' => 'danger',
                    'text' => $e->getMessage()
                ];
                require 'views/layouts/pagestart.php';
                require 'views/layouts/pageend.php';
                exit;
            }
            return [
                'id' => $id,
                'name' => $entry['displayname'][0],
                'email' => $entry['email'][0]
            ];
        },
    ]
...
];