Inventory User Documentation

Logging In and Out

The Inventory application is shared between CSCF and MFCF staff, with common software and separate databases. Find the inventory system here:

Staff	Location
CSCF	https://cs.uwaterloo.ca/cscf/internal/inventory/
MFCF	https://odyssey.uwaterloo.ca/mfcf/inventory/

Use your WatIAM password to get into the system. Sessions expire after one day. However, the campus authentication will usually lose your session after three hours- which means you could loose data if you don't reload the page after being away for three hours.

If you follow a link to an inventory item, you may first have to log in to the inventory system to view the inventory record.

To log out of Inventory, click the "Log Out" button in the top-right corner of any page.

Getting Help

To get help at any time once you're logged in, click the "Help" button in the top-right corner of any page. This document ("Inventory User Documentation") will be opened in a new browser tab or in a new instance of your browser, depending on your browser's configuration.

To get help for a specific field in the Inventory system, click on the field name. The Inventory Database: Field Descriptions page will open in a pop-up window and take you to help for the chosen field.

Searching for Existing Equipment

Searching All Fields

In many instances, you can simply enter a string in the top-left text field and either click the "Search every field that" button or press the <Enter> key.

This 'every field' search will find all inventory items that contain that string in any field. If you need to be more precise, you can search specific fields.

Searching a Specific Field

To perform a more precise search, enter a search string in one of these frequently searched fields:

• Domain
• MAC Address
• Barcode
• Room
• Equipment Type
• Fixed Asset Tag
• Serial Number
• Purchase Order
• Account number

Then either click the "Search" button or press <Enter>.

If the field you want to search is not among the frequently searched fields, click the "Advanced Search" button to get access to nearly all of the fields in the inventory database.

Search Types

The default search type, "contains," looks for your search string anywhere within the field's value. That is, it will find any record that has the specified string of characters in the chosen field, regardless of whether there are characters before and/or after the string. For example, the search value "xerox" will find "Colour Xerox printer".

You can change the search type from "contains" to "starts with," "ends with," "is," "is not," or "excludes" with the pull-down menu directly to the left of the search string field.

"starts with" allows additional trailing characters, but not additional leading characters. "ends with" allows additional leading characters, but not additional trailing characters.

"is" and "is not" perform exact-match searches; a value with additional preceding or following characters will not be matched. Be careful when using "is not"; it tends to yield very large result sets.

"excludes" matches any item that does not contain your search term anwhere in the field.

All searches are case-insensitive—even "is" and "is not" searches.

Example: Barcode CS123456 and barcode cs123456 are equivalent for searching purposes.

Searching Multiple Specific Fields

If you enter search strings into more than one field, there will be an implicit AND relationship among the search criteria, narrowing your search results. That is, records matching all of your search criteria, rather than just any of your search criteria, will be retrieved.

Example: Room is DC2610 and Equipment Type is Computer will find computers that live in Davis Centre room 2610.

Searching For Multiple Values In a Field

Enter multiple search values separated by a pipe or vertical bar ("|") character. There will be an implicit OR relationship among the search values, augmenting your search results.

Example: Room is DC2608 | DC2610 will find equipment that is in either room DC2608 or room DC2610.

Using Wildcards

Insert the wildcard character "%" into a search string to represent any set of characters.

Example: You can enter Barcode contains CS%8 to match "CS123458".

Exceptions: In an "is" or "is not" search, the "%" character is just another character in the search string, because they are exact-match searches. The "%" symbol is not interpreted as a wildcard.

Searching For Null Values

You cannot search for null values. Any field in the search page that does not have a non-null search value is excluded from the search criteria. So, for example, you can't search for all equipment that has no barcode (Barcode is "").

Search Scope

Current and History

By default, the search looks only at values currently found in inventory items and not at values that have been present in inventory items in the past. That is, the scope of the search does not include items' entire change histories. To search only for past values or to expand the search to include both current and past values, choose a scope of "History" or "Current and History," respectively.

Active and Inactive

By default, the search looks only at inventory items that are in active use or in storage and not at surplussed items. To search for only surplussed items, choose a scope of "Inactive". To expand the search to include both active and surplussed items, choose a scope of "Active and Inactive".

See Surplussing Old Equipment for details on retiring equipment.

Valid Search Strings

Rooms

Room numbers consist of two letters, followed by either four or five numeric digits, and optionally one additional letter.
Example: DC2610
Rooms "DC0000" and "DC9999" are special values that indicate off-site use.
The prefix "AD" refers to "Asset Disposal". These are items that have been surplussed.

Dates

Enter a date in ISO 8601 format ("yyyy-mm-dd").
Example: 2015-06-30

MAC Addresses

Enter a MAC address in hh:hh:hh:hh:hh:hh format, where "h" is a hexadecimal digit. Any address entered with the proper number of hexadecimal digits will be accepted and converted to this format.

Host Names

Enter a host name as a single string without any dots. If any dots are detected, the system will do the following:

• If the host name has a dot, followed by one or multiple dots without a dot as the last character (e.g. scsmac074.cs or scsmac074.cs.uwaterloo), the system will look up a list of pre-defined and user-defined domains and match the part after the dot to the names in the list (e.g. .cs will match to cs.uwaterloo.ca), and the system will automatically take the first part as the hostname and put the matched domain name as the domain name. If the domain name does not match a name on the list, an error will be dropped.
• Otherwise, if the host name has a dot, followed by one or multiple dots with an dot as the last character (e.g. host.foo.bar.), the system will define a new user-defined domain and will enter the part before the first dot as the hostname and the rest as the domain name (e.g. hostname: host, domain name: foo.bar).

URLs

Enter an eDoc's URL with one of these prefixes:

• http://
• https://
• ftp://
• ftps://

…along with at least one dot.

Active Record, DHCP, VLAN Tagging

These three fields require either 'y' for yes or 'n' for no.

Parent, Child, See Also

Type an identifier into these search fields and choose an item from the possible items in dropdown box. It accepts Room, Barcode, hostname, and "Primary Key" (the unique id that appears in the URL bar). Multiple search values are separated by ','.

Search Results

A search will result either in a list of matches or, if there is only one match, in the single item. See the Viewing Items section below if there is exactly one match.

The Search Results page shows a list of matched items with sortable columns for Barcode, Type, Model, Location, Hostname, Domain, IP address, and whether the item is Active. The default search is sorted by barcode. Click a column heading to resort the result set by the column's data. Click it again to reverse the sorting order.

A maximum of twenty-five items are displayed by default. Use the "Show [#] entries" drop-down field to change the number of listed items to 10, 25, 50, or 100.

To view the details of a particular item in the Search Results page, click the arrow in the left-most column on the item's row. The Item Details page appears. See Viewing Items, below.

Linking to Search Results

You can create a link to a search result set in a service tracking item or in an e-mail message by clicking the "Generate PermaLink" button near the top of the Search Results page and copying the displayed permanent link into your ST item or e-mail message. When a user clicks your link, they will be asked to log into the inventory system and the search will be redisplayed on successful login.

Examples:

Link to a barcode with the URL-ending (replacing SC000170 with your item barcode) search.php?barcode=SC000170

Link to a (partially or fully qualified) hostname with the URL-ending search.php?hostDomainName=database.cs

Link to a room-number with the URL-ending search.php?room=dc2555f

Link to a pKey with the URL-ending search.php?pKey=1101

For historical compatibility reasons, the search terms sbarcode and shostDomainName will also work.

Exporting Search Results to a CSV File

To generate a comma-separated-values (CSV) search result set that can be imported into a spreadsheet or a database, click the "Generate CSV" button next to the "Generate PermaLink" button near the top of the Search Results page.

A dialog box will appear with a textbox in which will be a header line and one line of output for each matched inventory record, including all editable data for each record. To save the CSV file to disk, click the "Download" button in the CSV dialog box. The generated CSV then can be pasted into the Mass Add and Mass Update features, which are described below.

Viewing Items

If your search matches exactly one item in the database, you will be taken directly to the Item Detail page. If it matches more than one item, you will see the Search Results page, showing a list of matched items. To view the details of a particular item, click the arrow in the left-most column on the item's row.

For details on all data fields in the Item Detail page, see Inventory Fields.

To expand or collapse a section of the record, click the small arrow beside the section heading. To expand all sections, click the "Expand All" button. To collapse all sections, click the "Collapse All" button.

Adding Items

Creating a New Item From Scratch

To add a new item to the inventory database from scratch:

1. Click the "New Record" button at the top of any of these pages:
   • Search
   • Search Results
   • Item Details
     
2. Select an Equipment Type: Computer, Display, Printer, etc. The Equipment Type affects whether some fields are displayed.
3. Fill in details as needed. See Inventory Fields for details on specific data fields.
4. Click the "Create" button. Any data entry errors will be described in a red section at the top of the page.

Duplicating an Existing Item

When adding a new item, you can save some time and effort by duplicating a similar item and altering the details in the duplicate. To duplicate an existing item:

1. Search for and find the existing item.
2. At the Item Detail page, click the "Duplicate Record" button. A copy of the existing record will appear with any fields that require unique information blanked out.
3. Fill in and update details as needed. See Inventory Fields for details on specific data fields.
4. Click the "Create" button. Any data entry errors will be described in a red section at the top of the page.

Mass Adding Items

Adding items in bulk, using a comma-separated-values (CSV) file, can be an efficient way to add a large number of similar items. You can create the CSV file manually with a text editor, export it from a spread sheet, or use Inventory's Generate CSV feature.

To use the Generate CSV feature:

1. Find an item that is similar to the ones that you want to add.
2. At the Item Details page, use the Generate CSV feature to save a CSV file with a single row of column headings and a single row of data.
3. Open the saved CSV file in a text editor or spread sheet application.
4. Duplicate the data row as many times as needed.
5. Modify the data to describe the items you want to add to Inventory, one item per row.
   General information about the CSV file:
   • When adding records, these fields are required:
     • equipmentType
     • room
     • barcode
     • model
     • serialNumber
     • sponsorCode
     • sponsorClass
   • A data field may contain a comma or a carriage return if it is surrounded by quotes.
   • These fields are not available in either Mass Add or Mass Update:
     • pKey (except as a unique identifier in Mass Update)
     • entered
     • lastModified
     • pingDate
     • parentBarcode
     • systemDescription
     • systemDescriptionDate
     • physicalAddress
     • physicalAddressDate
     • unit
   • 'hostDomainName' is the proper field to change items' hostnames.
   • Fields that appear in the UI as drop-boxes are not case sensitive, but will have their case corrected when records are created or updated.
6. Save the CSV file.
7. Open the CSV file as plain text and copy its contents to your clipboard.

To add the items from the CSV file:

1. Click the "More Options" button at the top of any Inventory page.
2. Expand the "Mass Add" section. Note the CSV data formatting information displayed there.
3. Click the "Mass Add" link. A large text area appears on the "Mass Add" tab.
4. Paste your CSV data into the text area.
5. Check the "Sync With DNS" option if you have provided properly formatted DNS details in the CSV file and want campus DNS updated automatically. Otherwise uncheck "Sync With DNS".
6. Click the "Mass Add" button. One new inventory item will be created for each data row in the CSV file.

A report of any errors will appear in the "Error" tab. Problem data will be kept in the "Mass Update" tab with instructions to go back and edit the problem items. Only the rows and columns that had errors will be listed. Fix the errors and resubmit the data.

Updating Items

Updating an Individual Item

When you search for, and find, an inventory item and arrive at the Item Detail page, the record is already in an editable state. You can change data in any field that is not identified as read-only by a medium grey background. See Inventory Fields for details on specific data fields.

To save changes, click the "Save" button. Any data errors will be identified at the top of the page and highlighted in red.

To abandon unsaved changes either click the "Reload" button or simply navigate away from the Item Details page.

Mass Updating Items

Updating items in bulk, using a comma-separated-values (CSV) file, can be an efficient way to make a change to a large number of inventory items all at once.

See Mass Adding Items, above, for instructions on generating and editing a CSV file.

To uniquely match inventory items, Mass Update uses the left-most column in the CSV file that contains one of these fields:

• barcode
• ipAddress
• hostDomainName
• pKey

pKey is found by looking at the URL of an existing record; it is used internally by the database, and is guaranteed to uniquely identify an item.

Example: If the URL of an Item Details page contains the field and value pair "id=16501" in its query string, the item's pKey is "16501".

To ensure that all DNS fields (including Room, DNS Contacts, and Policy 8) are updated, include the ipAddress field in your update, even if IP/MAC/Hostname are not actually being changed.

To update items from the CSV file:

1. Click the "More Options" button at the top of any Inventory page.
2. Expand the "Mass Update" section. Note the CSV data formatting information displayed there.
3. Click the "Mass Update" link. A large text area appears on the "Mass Update" tab.
4. Paste your CSV data into the text area.
5. Check the "Sync With DNS" option if you want campus DNS updated automatically. Otherwise uncheck "Sync With DNS". As noted above, to ensure that all DNS fields (including Room, DNS Contacts, and Policy 8) are updated, include the ipAddress field in your update, even if IP/MAC/Hostname are not actually being changed.

1. Click the "Mass Edit" button. One inventory item will be updated for each uniquely matched data row in the CSV file.

Successful submissions will change all fields listed in the column header for each uniquely identified item. Any row whose value in the unique matching column does not match exactly one existing item in the database will generate an error in the Error tab. Rows that could not be processed will remain in the Mass Update tab. Correct the errors and resubmit the changes.

Deleting Items

Deleting at the Search Results Page

To delete an item from the inventory database at the Search Results page, click the trash can icon in the right-hand column on the item's row. You will see a popup dialog asking for confirmation. Click "Yes" to permanently delete the item from the inventory database.

Do not delete an item because it is being surplussed. Instead, follow the procedures described in Surplussing Equipment.

Deleting at the Item Detail Page

To delete an item from the inventory database at the Item Detail page, click the "Delete" button in the Common information section near the top of the page.

Do not delete an item because it is being surplussed. Instead, follow the procedures described in Surplussing Equipment.

Merging DNS records

Prior to the addition of the multiple DNS records on one item feature there were many records created to track additional IP records that a host may have. For example the host "mutsu" also had an additional ip record of "mutsu-52". With the addition of the multiple DNS records, there is now the option to add the IP record to the main machines inventory record. This is the best practice when using inventory and is ideal to merge all a hosts IP records together. The steps to do so are straight forward.

Dealing with the IP record

You'll need to unsync the IP record in order to add it to the main inventory item without problems.

1. Open the DNS tab in the IP record
2. Uncheck "sync to DNS" and then hit "Save"

Adding the DNS into the main record

You'll now need to add the DNS information from the IP record to the main inventory record.

1. Open the "*Hardware*" tab in the main inventory item record.
2. Add a new MAC address with the same MAC address used in the original - You'll likely be warned that the MAC address is already in use. You can simply agree to proceed anyway.
3. Now open up the "*DNS*" tab.
4. Add a new DNS row with the same information that the IP record was using. Leave the default of not syncing with DNS. A row should now be created in the DNS table.
5. You can now change the DNS row you just added and check off the "sync to DNS" option. Upon saving this you'll likely get a popup saying that this is already associated with another record. You can simply hit yes and proceed.

Cleaning up

It is a good idea to now remove the MAC and DNS rows from the IP record you merged in, as well as set it to inactive as it should not longer be required since the information is now all in the main inventory record you merged it into.

Lending Equipment

Check Out

To lend a piece of equipment:

1. Search for the item and open its Item Details page.
2. Click the "Check out" button in the Common fields section of the Item Details page.
3. In the "Check Out" tab, fill in the fields:
   • Given To: (required) Enter the WatIAM id of the borrower.
     Example: f3lastna
   • Given By: (required) Enter the WatIAM id of the lender (you).
     Example: jguild
   • STs: (optional) Enter the ST numbers of any service tracking items that are related to this loan, separated by commas.
     Example: 77426, 77429
   • Due date: (required) Enter the date on which the item is due in ISO 8601 format or use the built-in date picker.
     Example: 2015-11-24
   • Comments: (optional) Enter any comments pertaining to the loan. Please keep them short and sweet.
   • Barcode: (required) Type in or scan the barcode of the item.
     Example: CS006124
     (This field is last because some barcode scanners send a carriage return, which might automatically execute the check-out.)
4. Click the "Check Out" button if the barcode scanner hasn't already executed the check-out.

Check In

To return a piece of equipment:

1. Search for the item and open its Item Details page.
2. Click the "Check in" button in the Common fields section of the Item Details page. The Barcode Loaning page appears and lands on the "Check In" tab. The "Barcode" field is prepopulated with the item's barcode.
3. Click the "Check in" button in the Check In tab. The item's lending status is updated.
4. Optionally, scan barcodes of any additional items you want to check in at this time.

Searching For Items On Loan

To find items that are on loan, go to the Search tab and choose a search method.

You may search by:

• Given By: Enter a WatIAM id to find all equipment lent by someone.
  Example: jguild
  Click the "Given By" button.
• Given To: Enter a WatIAM id to find all equipment on loan to a particular person.
  Example: f3lastna
  Click the "Given By" button.
• Given After: Enter a date, or use the built in date picker, to find all equipment lent after a given date.
  Example: 2011-05-11
  Click the "Given After" button.
• Due In: Enter a timeframe to find all equipment due within a given amount of time.
  Format: # time-unit, where time-unit is "days", "weeks", or "years".
  Example: 3 weeks
  Click the "Due in" button. Items that are already past due will be included.
• Currently Out: Click this button to find all items that are currently on loan.
• OverDue: Click this button to find all items that are on loan and past their due dates.

Taking Inventory Room By Room

Taking an inventory of the equipment in a room updates each item's location in the inventory database and records when the equipment was last seen to be in that location.

To inventory a room, follow these steps.

1. Click the "More Actions" button at the top of any page in Inventory.
2. Expand the "Room Options" section if it is not already expanded.
3. Click the "Room Options" link.
4. Enter a room number into the "Room" field and click the "Set Room" button. (See Rooms in the Valid Search Strings section.) The room you are inventorying is now indicated in the "Barcode Ops" tab.
5. In the Barcode field of the "Barcode Ops" tab, scan each barcode in the room.

The "Machine" tab shows a list of all of the items that are supposed to be in that room, according to the Inventory database.

Evergreening

Evergreening is the process of keeping equipment up to date by scheduling the replacement of aging equipment. Inventory can produce reports that are of use to people handling evergreening tasks. To generate an Evergreen Report either of all items in a list of rooms or of all items with any of a list of barcodes:

1. Click the "More Options" button in the page header.
2. Expand the Evergreen section. Note the search value format examples provided.
3. Click the Evergreen link. A Form tab appears.
4. If the Form tab's text area, enter a heading (either "room" or "barcode") and a vertical list of search values with one search value on each line:
   Examples:
   
   room
   DC2606
   DC2608
   DC2610
   barcode
   CS009063
   CS009094
   CS007487
5. Click the Evergreen button. A Result tab appears, showing a list of relevant items.

To create a csv report for these results, click the Generate CSV button.

Domain Name Service

DNS Updates

CS Inventory updates campus DNS with relevant data from inventory records. If the "DNS" checkbox in the DNS section is checked and an inventory item has a host name, a domain, and an IP address, Inventory will create or update a corresponding DNS host record. These fields will be copied to DNS:

• Active
• Room
• Policy Eight
• DNS Technical Contact
• DNS Business Contact
• Host
• Domain
• IP Address
• MAC Address
• DHCP configuration

Host, Domain, and IP Address are required if DNS is to be updated. If any of them is missing, the campus DNS does not get updated.

If any of DNS Technical Contact, DNS Business Contact, or Policy 8 is not filled in, it gets a default value as follows:

Field	Default Value
DNS Technical Contact	dns-cs@uwaterloo.ca
DNS Business Contact	dns-cs@uwaterloo.ca
Policy 8	Restricted

Inventory synchronizes only with Infoblox "Host" records—those with A records corresponding to IP addresses. It does not yet handle aliases, a.k.a. CNAMEs.

DNS Provisos and Cautions

• Inventory will not update campus DNS unless the host name, domain, and IP address are supplied. Removing the host name from a record will leave the DNS record active.

• Mass Add and Mass Update will also update DNS. In Mass Add and Mass Update, there is an "Update DNS" checkbox. It is checked by default. Deselect if, for some reason, you want to update Inventory but not update campus DNS.

• After an update, Inventory will report success or failure of DNS changes near the top of the page. If you don't see "IPAM Result: Success", DNS was not updated. If there is an IPAM Result reporting a DNS error, the inventory item was updated, but the DNS record wasn't. Some fixes can be done inside Inventory: such as if DNS reported the contact fields weren't valid e-mail addresses, or if the IP address or host name is already in use by an item outside of Inventory. Others will require going into Infoblox to fix it, such as if you need to use an IP address that is already in use by another hostname outside of Inventory.

• The inventory application uses the Infoblox REST API to perform DNS updates. An older command-line tool is also still available for expert users: CFPrivate.Inventory Infoblox CLI Docs.

Surplussing Equipment

See Surplussing Old Equipment.

Admin Page

Users who have admin access can add, edit or delete Users, EquipmentTypes or Groups in inventory database. Any field in these tables can be modified except for Users where username cannot be edited. If username needs to be modified then delete the user and create a new user.

User Flags

A user with no user flags will have read-only access to the database.

• w = write access
• m = access to mass-add and mass-edit
• d = access to delete records (not for general use- instead, disable records, so they are visible in history)
• a = access to Admin page

Inventory API

See a complete inventory API package documented at https://git.uwaterloo.ca/cscf/inv-lib

Displays inventory model as JSON

• if no record is found return 404
• @param string $fqdn the FQDN of a record
• @param string $mac macAddress of record
• @param string $ip ipAddress of record
• @param string $history when set to 'yes' return history in JSON
• @param string $active when set to 'n' return inactive record

Example:

• http://localhost/web/inventory/index.php?r=inventory/json&fqdn=acnexus.salt.math.uwaterloo.ca
• http://localhost/web/inventory/index.php?r=inventory/json&ip=129.97.6.129
• http://localhost/web/inventory/index.php?r=inventory/json&mac=00:0c:29:df:73:be

See Also

• Inventory System Administrator Documentation
• InventoryRedesignRequirements
• EquipmentInventory
• VLAN Information
• InventoryUserDocsOldVersion2
• InventoryFields - per-field documentation, also available by clicking on fields in the Inventory web interface.
• InventorySupportGroups - descriptions of available Support Groups.
• SurplusEquipment