Skip to content

Home

Jump to bottom
bggardner edited this page Nov 5, 2021 · 20 revisions

*NOTICE: Active development is underway at this fork and will be pushed to this repo after initial testing. While this wiki is helpful for older versions of ISLE, it is targeted for v2.0.*

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 status (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. header

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, and the filter can be cleared by clicking on the top-level node. sidebar

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. All filters, pagination, and sorts can be removed by clicking on the page link in the header.

The assets page has multi-select filters, with manufacturer, model, and series available by default. Attribute filters can be added by searching for the attribute in the "Add Attribute..." input and selecting the desired attribute. The "-" symbol is the first option for the series and attribute filters and when selected, will show assets that do not have a value for that filter. Selections can be cleared by clicking on the "Clear" link below each select box. Attribute select boxes can be removed by clicking the "x" to the right of the attribute name. All filters are not applied until the "Apply" button is clicked. search results

Footer

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

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. Assets must be available (not checked-out or restricted) before a subsequent check-out or restrict can be transacted. An asset may only be restricted by an administrator from the asset detail page by clicking on the restrict button. It may be unrestricted (by an administrator) from the assets detail page by clicking on the unrestrict button, or from its listing on the assets page by clicking on the "unlock" icon.

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. See the table below for cascading deletion relationships.

Deleting this ... ... will delete ...
Assets associated transactions and uploads
Categories descendant categories
Locations descendant locations, associated assets, and transactions
Manufacturers associated models
Models associated assets and uploads
Users associated transactions

Images

Any attachments that are detected as images, or the primary image assigned to a model, are resized and thumbnailed for display on the page. By hovering over thumbnails, larger size images are displayed. Attachments can still be downloaded in their original format, whereas primary model image originals are discarded.

Administrative Functions

Import/Export

Database data (as a SQL script) and uploads (as a tarball) can be imported to/exported from ISLE. The files imported/exported are gzip-compressed. Imported SQL scripts are executed directly, so use caution when using this feature. Imported upload tarballs are extracted to the uploads_path defined in the settings, and will overwrite existing files. Corresponding entries in the uploads table are not added, as this should be done by importing a SQL statement. Exports are intended to be imported to restore an instance after an uninstall.

Uninstall

After confirming an uninstall, all database tables, uploads, and settings will be deleted. It is recommended that www/includes/settings.php is backed up before uninstalling, especially if there are customizations.

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.

Short URLs

Similar to MediaWiki, ISLE supports the shortening of URLs so they appear less cluttered. Shortening of URLs removes the .php extension, and converts ?id= to / (asset.php?id=42 becomes asset/42). First the webserver must be configured with rewrites that perform the shortening. Examples of some webserver configurations are provided in the confs directory. Then, the short_urls key in www/includes/settings.php can be set to true (false by default). The original "long" URLs will still be accessible (unless blocked by additional rules).

Bootstrap Files

ISLE uses Bootstrap and Bootstrap Icons. By default, the required files are requested via external CDNs, but the tags can be changed via the setting keys below. This may be desirable for instances that do not have internet access and/or would prefer to host these files locally. It is recommended to use the same versions as the default files.

  • bs_css: HTML <link> tag for Bootstrap CSS
  • bs_icons: HTML <link> tag Bootstrap Icons CSS
  • bs_js: HTML <script> tag for Bootstrap JS bundled with Popper

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]
            ];
        },
    ]
...
];

Transactions

When a transaction, or set of transactions, succeed(s) the transact hook is called and passed an array of transaction IDs. This can be used for emailing a confirmation to the user or notifications to interested parties.

View Hooks

  • menu - Called between the page navigation menu and the user menu; for adding menu entries.
  • page_start - Called at the beginning of the main content of a page, after the footer; for adding messages.
  • page_end - Called at the end of the main content of a page, before the footer; for adding supplemental content.
Clone this wiki locally