Child pages
  • The Component Database User Guide
Skip to end of metadata
Go to start of metadata

Overview

The Component Database (CDB) is a tool to assist in documenting, organizing, and tracking the components planned for use in the MBA accelerator. It assists in capturing the documentation of components, provides a repository for inspection and measurement data (e.g. travelers), and supports the logging of component history through the component’s life cycle. The CDB also provides links and interfaces to other commonly used tools, such as PDMLink, ICMS, PARIS, EDP, etc. 

The CDB has the potential to capture a complete “Bill of Materials” for the MBA well before the installation timeframe. Having an exhaustive BOM in a relational database will facilitate careful planning and tracking of the construction and installation process, a prerequisite for such an ambitious schedule. 

There are three primary “domains” captured by the CDB: Component Catalog, Designs, and Inventory. A clear understanding of these domains and how they interrelate is important for proper and consistent use of the CDB. Figure 1 illustrates these domains and indicates some of the links between them. The following sections describe these domains (tables) in greater detail. 

Figure 1

CDB Domains

Component Catalog (Component Table)

A core purpose of the CDB is to provide a “Component Catalog” for the MBA. This catalog will contain a list of all components planned for use on the MBA, both custom-fabricated and commercially available. This is implemented with a database table (the component table) that contains an entry for each unique component design. For example, each design of a gate valve, magnet, or vacuum chamber and each unique VME module will have an entry in the Component Catalog.

The minimum data required for a component entry is a Name, Component Type, Owner, and Owner Group. The Component Type is selected from a list of “Component Types” which represent generic components used on an accelerator. Figure 2 shows a screenshot of a few existing components in the Component Catalog. 

Figure 2

Optional meta-data for a component entry include Description, Sources (Vendor), images and component “Properties”. Figure 3 is a screenshot of a “Component Details” view that shows a significant amount of meta-data for a specific component. As can be seen, a thorough description consisting of many “properties” can be included in the definition of a component in the Component Catalog.

A key question in defining components is “at what level of granularity should I enter components?”. A good rule of thumb is to describe components that would be “field replaceable” or components for which you would have “spares” on hand. 

Figure 3

Supporting Information for Components

Component Types and Component Categories:

There are two additional tables that allow for grouping of components for easier discovery, sorting, exporting, managing, etc. The component type table includes generic components typically used on an accelerator, such as motor, magnet, ADC, gate valve, etc. The component category table lists the engineering subsystems that are part of an accelerator, such as RF, Diagnostics, Vacuum, etc. Using these attributes, one can find all components that are “gate valves” or narrow the search for a component by filtering on the category “Diagnostics”. 

These attributes provide a <virtual> structure to the “Component Catalog” as follows:

  • Component Categories represent chapters within the component catalog, e.g. Controls, Magnets, RF, etc.
  • Component Types represent sections within a chapter, e.g. ADCs, CPUs, Undulators, etc.
  • Components represent specific designs of the component type that is of interest 

Sources:

The “Sources” table contains a list of vendors that supply components described in the component catalog. Each component can have multiple sources associated with it and sources can be designated as the vendor (from whom you procure the component) and/or the manufacturer (the fabricator of the component). 

Properties:

Please see information about properties below

Logs:

Please see information about Logs below


 

Component Inventory (Component Instance Table)

Component entries in the Component Catalog describe a specific component design or a particular model number of a commercially available component. The actual component fabricated or procured is referred to as a Component Instance of that component design. Component instances are tangible hardware components that require inspection, testing, storage, installation, and maintenance. Tracking component instances becomes an inventory management challenge.

Each component instance procured or fabricated for the MBA will be uniquely identified with a QR ID code. A sticker with the QR ID code will be adhered to the component in a visible location (if possible). An entry in the Component Instance table will relate the component instance to a particular component; thereby allowing all relevant information about this component instance to be referenced using the QR ID.

Figure 4 shows one view of the component instance table. Additional information is easily accessed from links in this table. 

Figure 4

Supporting Information for Component Instances

Location:

Inventory management includes knowing where components are installed or stored. To assist in location tracking, a table of all buildings and rooms used by the APS Upgrade is included in the CDB. Component instances have a “Location” attribute that can be assigned to a specific room. If desired, adding cabinets, tables, or shelves to a room can create further granularity of a location. 

Properties:

Please see information about properties below

Logs:

Please see information about Logs below


 

Designs (Design Table)

The CDB allows the user to define “designs” which consist of several components grouped together to fulfill a particular functional requirement. A few examples of “Designs” for different technical systems would include:

  • A PLC chassis with specific set of I/O modules
  • A girder that supports several magnets and vacuum chamber components 
  • The contents of a power supply cabinet
  • A BPM Processing System which consists of an analog front end chassis, an ADC chassis, four cables for the BPM buttons, and two cables between the other units 

An example of how a Design is depicted in the CDB is illustrated in Figure 5

Figure 5

“Designs” are the mechanism by which an exhaustive Bill Of Materials can be acquired for the MBA. Groups will define designs necessary to fulfill their particular technical system requirements and by so doing will be contributing to a detailed list of the all the components required to build the new machine. Since this data resides in a relational database it can be “viewed” or analyzed in numerous ways. 

Supporting Information for Designs

Design Elements:

A design may consist of a list of design elements:

  • Each design element may be a component, or another design (allows hierarchical designs). 
  • Each design element may also contain a set of additional properties required for the design and the element. 
  • Each "design element" is given a unique element name, normally derived from official naming convention. 

Properties:

Please see information about properties below

Logs:

Please see information about Logs below


Common CDB Domain Supporting Information: 

Several other tables provide additional information about components, designs, and instances. A short description of several of these tables is provided below. 

Properties

The information one would like to capture in the CDB varies widely depending on the type of component, design, or instance. Therefore, it is impractical to attempt to define a single set of meta-data common to all of these objects. To provide a flexible mechanism for capturing component-dependent meta-data, the CDB associates properties to individual components, designs, and instances. This allows each element to have a unique set of meta-data which best describes and documents that element. 

For example, a VME Chassis component might have properties of number of slots, height, and AC power requirements. In contrast, a quadrupole magnet component would have properties of maximum current, slot length, weight, and maximum field. Numerous other property types are shown in Figure 6. A complete list can be viewed in the CDB application.

Figure 6

A summary of property characteristics is provided below.

  • Property types are predefined. All available property types can be viewed in the CDB
  • New property types can be easily added (by a System Administrator)
  • Any number of properties can be associated with Components, Component Types, Designs, and Component Instances
  • Properties can have “allowed values” (which show up as a menu selection) or generic text strings
  • Properties can have “handlers” that run specific code for that property. For instance, the Purchase Requisition property knows how to formulate a web url to access a purchase requisition directly from PARIS. Handlers could even communicate with other systems such as PDMLink or eTraveler application, this allows loading information from those applications for the user directly in CDB. 
  • “Dynamic” properties are ones that <may> change with each instance, e.g. an inspection report.
  • When property values are changed, a history log is kept of all previous values.

Logs

All CDB domains have the ability to store log information. Any changes, maintenance, events, or other relevant information may be entered into the Log of any of the CDB Domains. 

A log may contain the following: 

  • Log Entry 
  • Topic
  • Any number of attachments

Using the CDB Portal 

This section gives an introduction to the CDB application. The HOME page of the CDB is shown in Figure 8 and can be reached at cdb.aps.anl.gov. You must be on the APS Intranet, the APS Visitor wifi, or in a VPN session to the APS intranet to access this site. One can view the contents of the CDB without logging in. In order to modify the contents you must have a CDB account (request one from a CDB administrator) and login using your APS LDAP password. 

 

Figure 7

A separate “development” database has been provided for individuals to practice adding and modifying contents of the CDB while going through the learning process. One can navigate to the development version using the “CDB Development” link on the HOME page. The top title for the development area is “Component Database Portal – Development”. Changes made to this “sandbox” area are not permanent and may be discarded at any time. Once the user becomes familiar with the application, permanent entries must be entered in the main application.

Directly below the main title are is a row of “tabs” (Home | Components | Component Instances | ...) to navigate to different tables of the CDB. The following sections describe these tabs and other important information about the CDB. 

Using Lists to view information in CDB.

List Buttons

CDB has the ability to store many types of lists of information. For example, properties is a list that is a part of every domain in CDB. All lists in CDB will use similar buttons, although not all buttons may always be shown, figure 8 shows the buttons that a user might expect to see when viewing any list in CDB. 

Figure 8
  1. Add
    1. Allows a user to add an item to the list. 
    2. Only appears when the user is logged in and has permission to add item to the list and the add feature for the particular list exists and is possible. 
  2. Help
    1. Shows help information relevant to the list.
    2. Only appears when help is available for the list. 
  3. View supporting list 
    1. Goes to a supporting list. Examples of supporting list:
      1. Components require a component type to be selected therefore the supporting list is component type. 
        1. Component types require a component type category to be defined therefore the supporting list is component type category.
      2. Locations have types therefore a supporting list is location types. 
      3. Users are in groups therefore the supporting list is user groups. 
    2. Only appears when supporting list exists. 
  4. Reload list filters
    1. Refreshes the list without any filters applied. 
    2. Only appears when the list may have filters applied. 
  5. Customize list view
    1. Allows a user to temporarily or premaritally change the way the list is displayed:
      1. Change the columns that are shown. 
      2. Change the number of items to be displayed at a time. 
      3. Any other relevant configuration options. 
    2. Always appears above lists. 
  6. Print
    1. Allows a user to print contents of the data table.
    2. Always appears above lists
  7. Export PDF
    1. Allows a user to export the data table to a PDF document
    2. Always appears above lists
  8. Export Excel
    1. Allows a user to export the data table to an excel document. 
    2. Always appears above lists. 

Action Column

Lists may have a an action column, this column will display available actions to they user. Logging into the CDB system may result in additional actions appearing whenever permissions allow. 

Possible action items: 

IconDescription
View details about the item in the current row.
Edit the item in the current row.
Clone the item in the current row.
Remove the item in the current row.
Upload a file and attach it to the item in the current row.
View history record of how the item in the current row changed over time.

Items below are used only for design elements. An element may have either a component or design linked to it.

View design element information.
View Component Information.
View Design Information.

Using the CDB Domain List Pages

The CDB Domain List pages allow a user to quickly browse a list of Components, inventory and designs. The lists are accessed by clicking one of the tabs on the header CDB Portal, see figure 9

Figure 9

Once the user navigates to one of the CDB domain list pages, they will be presented with a common set of widgets, this makes every domain list page feel very familiar. 

Filtering and Sorting.

Figure 10 below shows what clues signify wether a field could be filterable or sortable.

To sort: click on the field header if it has the sort icon present.

To filter: click on one of the text boxes and entered desired text to search or click on of the dropdown and select the desired value. 

Figure 10

Row Expansion capability. 

Allows for quick access to information such as logs and properties directly from the list of CDB domains without the need for viewing the details page. 

Figure 11 shows the icon that is used for expanding row, which will reveal additional information as shown in figure 12. Once the row is expanded the user will be presented with panels for properties and logs as shown, an additional panel exists for instances specifically for components, other CDB domains may have additional panels specific to their functionality. 

Figure 11

Figure 12

Adding properties into the list as a column.

Properties could be quickly loaded into the list allowing the user to quickly view a certain property value directly in the list as an additional column. As shown in figure 10, one of the columns has a header, "Property: Component Design". This particular column will display values for any CDB domain that has that particular property type. 

In order to add additional or change property types to be displayed as a column, clicking the  above the list will show customization options. After clicking the customize wrench, expand the "Property Value Columns" in the dialog that is displayed, please see figure 13. The drop-downs allow the user to change the type of property type to display as a column. Please note that some properties fetch information from external services, if those services aren't responding, this will cause the list to become slow. Removing the property type will solve the performance issues. Disabling the automatic load of property filter values may partially solve the performance issues. 

Figure 13

Using the CDB Domain Details Pages

Common Panels

Each domain detail page has four sections that are a part of every CDB domain. This should make the details pages very familiar when going from one domain to another. 

These sections include: Details, Gallery, Logs, and Properties. All of the sections have the ability to be edited directly in the detail pages, if the user has permissions. 

Details section

This section holds basic information specific to the domain being currently viewed by the user. For example, a component would have a name, model number, description, type and category while a component instance would have its QR Id, a reference to the catalog item, a tag, serial number, location information, and details. Figure 14 shows the details section for a component. 

More info button in the details section would bring up additional information about the current item being viewed by the user. This information includes: owner user, owner group, creation user and date, modified user and date, etc. Please see figure 15

Figure 14

Figure 15
Editing the details section 

User who has a permission to edit the current item will be able to do so directly in the details page. When a user with permissions to edit the current item logs in, they will see that hovering over editable fields in the details section will highlight, see figure 16. Whenever they do not highlight, it means that the field cannot be edited. To edit, simply click on the highlighted field and make necessary changes, to revert changes press "x" button and to save changes press "check" button. An field in edit mode is shown in figure 17

Figure 16


Figure 17

Gallery

This section allows quick preview of viewable items such as pdf, png, gif, jpeg. Each item that is added to the gallery is an image property, which could be added manually as an image property or automatically in the gallery. Clicking through thumbnails on the bottom of the gallery would switch the larger image, clicking on the larger image would open a new browser tab with the original image, see figure 18

Figure 18
Editing the gallery

Modifications of image properties could be done in the properties panel, which is explained below. Adding images, or viewable items could be done directly in the gallery panel, they user must have permissions to edit the current item. When the user has permissions, an "Add" button will appear inside the gallery panel, see figure 18.

Clicking the "Add" button will open a dialog in which a user may add viewable files from the file system. The user may even drag files directly from their desktop into the dialog. After the user added all of the required files, upload them by clicking the "upload" button. When all done, click "Done" button to save the newly added viewable files for the current item. See figure 19

Figure 19

Logs

This section allows to quickly add, edit, and view various logs that may be entered for the particular item that is being viewed. See Figure 20.

Figure 20
Editing Logs

Only when the user with sufficient permission for the item is logged in, they will be able to make changes to the log list. As shown in figure 20, the action column along with the add button will appear. The action column contains various buttons that are listed in the action table above

In order to edit a row, the pencil must be clicked, it will transform the row into edit mode. Click the check will save changes and clicking the x will revert changes. An example of editing a row could be seen in figure 21. Uploading additional files and deleting logs would be done by the two aditional icons in the action column. 

Adding a log could be done by clicking the "Add" button, which will bring up the dialog shown in figure 22. From this dialog, the user may enter all the log information and upload any necessary files. 

Figure 21

Figure 22

Properties

The properties section holds property information as explained in property section above. The property section is shown in figure 23. 

Figure 23
Editing Properties 

Only when the user with sufficient permission for the item is logged in, they will be able to make changes to the property list. As shown in figure 23, the add button will appear and additional pencil will appear in the action column. The action column for properties contains various buttons that are listed in the action table above

In order to add a new property, the user would click the "Add" button, which would bring up the dialog as shown in figure 24. From this point the user must choose the type of property that they would like to add, filtering and sorting is available to aide in quickly finding the correct property type. After selection and confirmation with the "Done" button, the use will be able to add property value information, a new dialog would be presented, as shown in figure 25

Editing is done by clicking on the pencil icon in the action column, it brings up a familiar dialog, along with an option to delete the property value, as shown in figure 26

NOTE: Certain property types may have handlers, which may require different way of entering the property value, one example is shown in figure 26. See section about handlers

Figure 24

Figure 25
Figure 26

 

Using the Component Detail Page 

A component is a CDB Domain, therefore it will include all the information described in the section above: Using the CDB Domain Details Pages

Aside from what applies to all CDB Domains, A component has a few additional panels on its details page, as shown in figure 27

Figure 27

Sources 

The sources list allows a user to quickly view all the vendors, their part number and pricing information for the particular component catalog item. 

Editing Sources

Please see the section on using CDB Domain Edit Pages

Instances

The component catalog item is an abstract item, it is something that could be purchased, made or obtained by any other means. The instances list shows the physical or tangible items of the component currently being viewed. 

Editing Instances

Please see the section on using CDB Domain Edit Pages

Design Membership

Designs are made of elements, an element could reference a component. Whenever an element references a component, it means that it is used in that particular design. For example, the component shown in figure 27 is used in the Double Sector Controller design.  

 

Using the Component Instance Detail Page 

A component instance is a CDB Domain, therefore it will include all the information described in the section above: Using the CDB Domain Details Pages

Aside from what applies to all CDB Domains, A component instance has an additional panel for Component Properties, see figure 28

Figure 28

Component Properties

These are properties that are shown from the base component of the instance. Each instance is an item from the catalog, the item from the catalog has properties these properties should all be describe every such item. Allow conveniently viewing properties of a component catalog item without going back to the catalog. 

In the example shown in figure 28, the instance has an inspection traveler attached as one of its properties. An inspection only applies to the instance and not the catalog item. The catalog item does however have a template for the inspection because every instance of the catalog item could have the same inspection completed on it. 

Editing

Editing of component properties could only be done from the component detail page or component edit page. 

 

Using the Design Detail Page 

A design is a CDB Domain, therefore it will include all the information described in the section above: Using the CDB Domain Details Pages

Aside from what applies to all CDB Domains, A design has an additional panels on its detail page, see figure 29.

Figure 29

Elements

Designs are made up of design elements as defined in the section above

Design Elements Detail Page 

The element detail page could be viewed by clicking the "E" icon in the actions column. 

A design element is a CDB Domain that belongs to a design, therefore it will include all the information described in the section above: Using the CDB Domain Details Pages

Design element detail page will include an additional section, depending on the type of element (component/design); it could either be component properties, or design properties.

Editing Elements List 

Please see the section on using CDB Domain Edit Pages

Design Membership

Designs are made of elements, an element could reference a component. Whenever an element references a component, it means that it is used in that particular design. For example, the design shown in figure 29 is used in the S27 RTFB Teststand and S27 Integrated orbit feedback prototype.  

 

Using the CDB Domain Edit Pages

Editing items could be done only by a user who has sufficient privileges for the item. Many items could be edited using methods that are already in the view, as shown in the section above

Edit page allows for quick editing of many items at once, a sample edit page is shown in figure 31

Figure 31

Accessing the edit page

If the user is currently viewing the details of the item to edit. The user must click "Edit" button in the details section of the page, as shown in figure 14. The "Edit" button will only appear if the user has sufficient privileges for the item being displayed. 

If the user is viewing a list of CDB Domain items, a pencil will show up in the action column, as shown in the action column icon table

Editing the details of a CDB Domain item. 

The details section is shown in Figure 32. It consists of various editable items, in order to make any changes, simply make the changes and hit the "Save" button. Clicking the "View" button will go back to details page, and finally clicking "Return" button will go to the CDB Domain list. 

Figure 32

 

Editing CDB Domain lists. 

The particular edit page shown in figure 31 has lists for Logs, Properties, Sources, and Instances. Each list however has similar behavior. 

Each edit list will have similar buttons, most of which are explained in a section above. The only new button is the "Save" button, this button will save the current state of the CDB Domain item, including the list, without going back to the details page. This is useful to make sure the new list item entry is valid and if it isn't the user is notified and could correct any issues. 

It is highly recommended to always click "Save" button in figure 32 after making any changes in order to make sure that everything is permanently stored. 

An example of an edit list is shown in figure 33. Adding a new item to the list is simple, just click the "Add" button.

When adding properties, the user will be presented with a dialog similar to one shown in figure 24. The user would then select a property type and continue along this guide. 

Figure 33

Once an item is added to the list, it will show up in the list as an empty item, as shown in figure 34. At this point the user may enter any required information for the new item, some edit lists will have additional options appear in the actions column, see action column section above

Figure 34

 

Property Type Handlers

Handlers allow properties have some of logic behind the way they are displayed, updated, and stored. Properties with handlers could be viewed as smart properties. An administrator could create new property types, during this process they could assign a handler to the property type, which will apply required logic of the handler to every property with same type. 

Figure 24 shows a dialog that allows a user to select property type when adding a new property value, one of the columns is called handler, the user may filter by the handler, using any property with a handler will apply the functionality explained for each handler below. 

Smart handlers

Allows user to quickly fetch information about a PDMLink drawing from windchill, see figure 35.  

Using a property with PDMLink handler

The user could enter a drawing number with the extension (asm, drw, prt, etc.) or a drawing number without the extension depending. Entering a drawing with an extension would result in a dialog opening similar to one shown in figure 35. Entering a drawing number would result in dialog allowing the user to choose one of the related drawings, which would result in the same dialog as shown in figure 35

Figure 35

Component Design

Allows a user to link a component to a design using a property. Whenever a component is derived from a design, the component property makes it easy to signify that by linking directly to the design. 

Using a property with a Component Design handler

The user will be presented with a dropdown of all the designs in the system. Each design may only be linked to one component. 

Traveler Template

Part of the e-Traveler integration with CDB. A traveler template could be compared to a blank form in a word document; not to be filled out but to be printed for people to fill out. A traveler template defines what items will be on the form. 

Using a property with a Traveler Template handler

A template is an abstract entity, it is a definition of what a form should be and cannot be filled out. The best practice of using properties with this handler is to link them to abstract domains such as a component catalog item or a design. The reason for this is because the fillable travelers should be applicable to the physical items such as component instances. 

When adding a value to a property with this handler the user will be presented with a button that will open a dialog similar to one shown in figure 36. From this point the user may choose templates that have already been created and are in the traveler system. The user may also enter a title for a new template and click create. A new dialog will be presented with a link to the new template from which the user may make any necessary changes in the traveler system to fulfill the requirements of the traveler template. 

Figure 36

Traveler Instance

Part of the e-Traveler integration with CDB. A traveler instance could be compared to a printed traveler that is ready to be filled out. A traveler instance is a fillable traveler in the e-traveler system. 

Using a property with a Traveler Instance handler

A traveler instance is a concrete entity, it is a fillable traveler, or form. The best practice of using properties with this handler is to link them to concrete a concrete domain, such as a component instance. The non fillable traveler templates (see above) should be linked to abstract domains such as design and component catalog item. 

When adding a value to a property with this handler the user will be presented with a button that will open a dialog similar to the on shown in figure 37. The list that is shown is of traveler templates and it is generated based on templates linked to related entities which means if a template is specified in the component catalog item, it will show up in this list for all the physical instances of that component catalog item. Once the user chooses one of the templates from the list, the title will automatically be filled out with the same name as the template, the user may choose any title and click create. The user will be presented with a new dialog similar to one shown in figure 38; at the bottom of the dialog is a link to configure the traveler, this is a way to set the initial settings such as deadline and to start work (make it fillable). Once the traveler is completed, that link will allow the user to approve the completed work or request for more (make it fillable). 

Figure 37

Figure 38

Upload based handlers 

Properties with these handlers allow a user to attach a file to them. 

Document

A property with the Document handler will allow a user to attach a file to the property. When adding a value to a property with this handler the user will be presented with a button that will open a dialog that will allow a user to upload a file. Once uploaded the file will link to that property and may be accessed in the future. The Document property allows for uploading of any files. 

Image

A property with the Image handler will allow a user to attach a viewable file (pdf, png, gif, jpg) to the property. When adding a value to a property with this handler the user will be presented with a button that will open a dialog that will allow a user to upload a file. Once uploaded the file will link to that property and may be accessed in the future. Multiple Image properties could be quickly using the Add button in the gallery, as shown in the gallery section. Every image property will show up in the gallery. 

URL based handlers

Properties with the HTTP Link handler allow a user to enter a full URL in the value section. The property will be displayed as a link to the URL. 

Properties with the EDP Link handler allow a user to enter an ID from the external EDP system in the value section. The property will be displayed as a link to the EDP collection. 

Properties with the ICMS Link handler allow a user to enter an document ID from the external ICMS system in the value section. The property will be displayed as a link to the ICMS document. 

Properties with the AMOS Link handler allow a user to enter a Master Order number (MO_######) from the external AMOS system in the value section. The property will be displayed as a link to the AMOS order. 

Properties with the PARIS Link handler allow a user to enter a Purchase Requisition number (F#-######) from the external PARIS system in the value section. The property will be displayed as a link to the PARIS order. 

Data type handlers

Currency

Properties with the Currency handler allow a user to specify a numeric value. The property will be displayed with number formatting #.##. 

Boolean

Properties with the Boolean handler allow a user to specify a true/false value with the use of a checkbox for the value. The property will be displayed as a check when true. 

Date

Properties with the Date handler allow a user to specify a date value with the use of a calendar for the value. The property will be displayed as a date. 

  • No labels