Linking Existing Components to a Company Database using a Database Link File in Altium NEXUS

Parent page: Working with Database Libraries

A common requirement for many organizations is to link from the electronic CAD components, to the company's central component database. Altium NEXUS supports this by providing the ability to link existing components to records in the company database, through the creation and use of a Database Link file. The Database Link file is added to your design project, or library package, allowing you to link from components already placed on schematic sheets or, more typically, defined components in a source schematic library, respectively.

Once linked, you can transfer mapped parametric information from the database records - to design parameters in the components - using the Update Parameters From Database command. This information can then be included in the final Bill of Materials (BOM), ready for component procurement.

A Word About Linking Choices...

Altium NEXUS provides three methods of linking from a component to a database - using either a Database Link file (*.DbLink), a Database Library file (*.DbLib), or an SVN Database Library file (*.SVNDbLib) respectively. The DbLink approach provides an efficient means of linking and keeping the components used in your design (or libraries) synchronized with the data entered in the database. The DbLib/SVNDbLib approach takes this proven linking efficiency and adds to it the freedom to be able to place a component directly from the database - in essence creating the component dynamically from the information stored for it in the corresponding database record.

Before launching into the greater depths of the database link feature, it is worth discussing the differences between these two methods, in regard to the way you use them.

Linking using a Database Link file

• Using this method, the Database Link file defines linkage between the schematic component and a matched record in a database. The record match is established by key field linking, which can be a single key field (for example a part number), or multiple key fields (by defining a Where clause).
• With this method of linking, the model and parameter information for the component must be predefined as part of the Altium NEXUS library component. The library component must also include the necessary key field information as part of it's definition. Once this has been defined you add a Database Link file to your Library Package, or Design project, then you can synchronize the component information (parameters) with the contents of fields in the database.
• Although each physical component defined by each database record does not need to map to a unique Altium NEXUS library component - many database components can share the same component symbol - this method of linking would typically be used in a "one database record-to-one Altium NEXUS component" fashion. The unique Altium NEXUS component can either be an instance placed on a schematic sheet, or a unique component in a component library.
• With DbLink-style database linking, you include the Database Link file with the library package, or design project.

Linking using a Database Library file

Related page: Working with Database Libraries

• Using this method, the Database Library file also defines the linkage between the schematic component and a matched record in a database. Again, the record match is established by key field linking, which can be a single key field (for example a part number), or multiple key fields (by defining a Where clause).
• With this method of linking the component symbol, model, and parameter information for a component is stored as part of the record definition for that component in the external database. The referenced schematic component (stored in an underlying component library (*.SchLib)) is only the symbol; it has no linked models, and no defined design parameters.
• When the component is placed, its parameter and model information is created on-the-fly, using the corresponding fields in the matched database record, and in accordance with defined mapping. One or more of these parameters will then be used to maintain an ongoing link back to the database, as per the matching criteria defined, enabling future synchronization after placement.
• This method of linking, due to its dynamic creation of components at the time of placement, lends itself very well to being used in a "many database records-to-one Altium NEXUS component" fashion. For example, your database might include the E96 resistor series, with every record referencing the same schematic resistor symbol and the same PCB footprint.
• Unlike the DbLink-style of database linking, whereby the DbLink file must be included with the library package (or design project), the DbLib/SvnDbLib file need not be added to the project. The database library (DbLib) is included in the Available Libraries - accessible by the Components panel. Remember, the Available Libraries can consist of Project Libraries, Installed Libraries, or libraries found along specified search paths.
• You would typically configure DbLib/SVNDbLib files in a library-oriented fashion. For example you might have one for all the resistors detailed in your company database, another for capacitors, and so on.

Creating the Database Link File

As mentioned, the backbone of the database link feature is the Database Link file. This file is created and managed using Altium NEXUS's DatabaseLink Editor. This editor becomes available when the active document in the main design window is a *.DbLink file.

Example DbLink file, open in the DatabaseLink Editor.

Create a new file of this type by:

• Choosing the File » New » Library » Database Link File command from the main menus.
• Right-clicking on the required project's entry in the Projects panel, and choosing the Add New to Project » Database Link File command from the context menu.

Connecting to an External Database

Table and mapping data will only appear in the Editor's main display window after the active Database Link file is successfully connected to the required external database. Connection is defined using the controls provided in the Source of Connection region.

Specifying the connection to the external database.

Any database which provides OLE DB support can be connected to. The options provided in this region each use an OLE DB connection string to connect to the target database. Some databases may not offer OLE DB support. However, virtually all Database Management Systems in use today can be accessed through the Open Database Connectivity (ODBC) interface. The database link feature uses Microsoft's ODBC provider, which allows an ADO (ActiveX Data Object) to connect to any ODBC data source. The result is that any ODBC database can be connected to. The OLE DB provider for the ODBC database is specified as part of the connection string.

Fast Connection to Access and Excel Databases

The Select Database Type option offers an expedited method of creating a connection string when the target database has been created using Microsoft Access, or Microsoft Excel. Using this option, select the database type and then browse to and select the required database file. The corresponding connection string will automatically be composed and entered into the field for the Use Connection String option.

Building a Connection String

If your company database is not Access or Excel-based, and you want to build the connection string explicitly, enable the Use Connection String option and then click the associated Build button to the right. The Data Link Properties dialog will appear.

Building a connection string through the Data Link Properties dialog.

The dialog opens at the Connection tab. The OLE DB Provider Microsoft Office <Version> Access Database Engine OLE DB Provider is set by default on the Provider tab of the dialog. This is the default provider setting for new Database Link files and is also used to connect to Access database files (*.mdb). Change the provider as necessary.

On the Connection tab enter the name (including path) of the database you wish to connect to.

If your database requires login permission, enter this as required, along with any other advanced settings available from the Advanced tab of the dialog. The All tab provides a summary listing of link options defined, as well as extended options relating to the chosen OLE DB Provider. Options can also be modified in this tab, as required.

Once link options have been defined you can check for successful connection by clicking on the Test Connection button (on the Connection tab). A successful connection will yield a confirmation dialog to that effect.

Specifying a Data Link file

If the data source to which you wish to connect is described using a Microsoft Data Link file (*.udl), enable the third of the connection options - Use Data Link File - and click the associated Browse button to locate the required file. A Data Link File is essentially a storage vessel for a connection string.

Proceeding with the Connection

After defining the connection to the external database, the text of the Connect button will become bold, signifying that you can proceed with the connection. If the connection details are correct, the table and mapping information for the target database will be loaded into the Database Link file. The text on the Connect button will change to Connected and the button will be grayed-out.

If there is a problem with the connection details, for example a connection string is built incorrectly or a path is entered erroneously, connection will fail and a message will appear alerting you to this fact. Check your connection settings and click the Connect button again.

Examples of flagging connection failure.

After successful initial connection, and after saving the Database Link file, the connection will be made automatically each time the file is opened, provided the target database's location and filename are not changed.

Database Table Listing

After successful connection to the external database, table and mapping data will be loaded. The left-hand side of the DbLink document lists all tables that exist in the connected database.

Tables existing in the connected database.

The Enable option next to each table entry allows you to control whether or not that table is to be used when updating parameters from the database.

As you click on a table entry in the list, its icon changes from  to  in order to distinguish it as being the currently active table. The table - with all its data - appears on the Table Browser tab of the document. This is a non-editable copy of the table and allows you to quickly refer to its contents, without having to launch the external database itself.

Browsing a source table in the connected database .

To enlarge the area of the Table Browser (as shown in the illustration above), collapse the entire area above (connection and field settings) by clicking the  control, at the top-right of the DbLink document view. Click  to re-expand it.

Specifying Matching Criteria

In order to update part parameter information with that stored in fields of the external database, each part in the design must first be 'matched' with one row, from one table in the database. The Field Settings region of the document allows you to define the matching criteria - either a simple, single key lookup, or a more advanced match using a Where clause.

Controlling matching criteria.

Single Key Lookup

If the Single key lookup option is enabled (default), the Database field and Part parameter fields become available. The Database field lists all of the available field names (column headers) in the active table of the database. The Part parameter field lists all of the parameters found across all parts in the design - both system and user-defined parameters.

Use these fields to specify the matching between one field in the table and one parameter in a part (common to all parts). Typically, the matching field in both cases is something that uniquely identifies each component in the external database, such as a Part Number. The chosen lookup field is distinguished on the Field Mappings tab of the document by the Design Parameter entry shown as grayed-out.

Single key mapping by Part Number

When using the Update Parameters From Database feature, information is read from the chosen key parameter in the placed schematic components and then searched for in the chosen (key) field of the database - across all enabled tables. When there is a match, information from other cells in that record of the parent table can then be taken back to the mapped parameters in the schematic component.

Advanced Matching - the Where Clause

While the Single key lookup option works well if there is a unique part number/id to match on, it is not so effective when matching by a parameter that is not unique, such as capacitance or resistance. In this case the more advanced Where clause should be used, enabling you to specify multiple key matching in order to link the schematic component to the required row in the relevant database table.

In its simplest form the Where clause (written using SQL syntax) reflects the chosen entries that define the single key lookup. For example if the Database field was chosen to be Part Number and the unique Part parameter (existing for all parts in the design) was chosen to be Part Number, the entry for the Where clause would be:

[Part Number] = '{Part Number}'

The square brackets around the database field (table column) are quote characters, as specified on the Advanced tab of the Database Connection dialog. Access this dialog either by clicking on the Advanced button in the Source of Connection region of the document, or from the main Tools menu.

The Advanced tab of the Database Connection dialog provides additional SQL options for quoting tables,
or using table schema names, in a constructed Where clause.

The curly brackets (braces) specify that the entry being referenced is a design parameter. The single quotes are used to specify the design parameter be treated as a string, as opposed to a number (no quotes). The type matching is very important, as SQL is type sensitive. The design parameter should be made the same type as the column in the database.

Using standard SQL syntax, the Where clause can then be extended to match using multiple Database field/Part parameter entries, for example:

[Capacitance] = '{Capacitance}' AND [Tolerance] = {Tolerance} AND [Manufacturer] = '{Manufacturer}'

In this case a single record in the relevant table of the database would be linked to, using three different design parameters. Notice that the entry for the Tolerance design parameter is not quoted. This means that the column type in the associated table of the database is Number and not String.

Using standard SQL syntax you can conceivably make the Where clause as simple or as complicated as you like. An example of a more complicated clause might be:

[Tolerance] BETWEEN {Min Tolerance} AND {Max Tolerance} AND [Price] <= {Max Price} AND [Manufacturer] IN ('{Preferred Manufacturer 1}', '{Preferred Manufacturer 2}')

In this case, the table would be queried for matching parts based on three database fields - Tolerance, Price, and Manufacturer. The tolerance must lie in the range defined by the Min Tolerance and Max Tolerance design parameters. The price must be less than, or equal to, that specified in the Max Price design parameter, and the manufacturer can be any of the two candidates specified by the Preferred Manufacturer 1 and Preferred Manufacturer 2 design parameters.

Creating a Part Parameter

If no suitable parameter exists in your Altium NEXUS components - for use as the Part parameter for matching purposes in the DbLink file - you will need to create one. Addition of this 'base' parameter can be achieved quickly using either the Parameter Management feature, or the relevant editor's Properties panel.

Adding a Parameter using the Parameter Management Feature

To add a new parameter using the Parameter Management feature:

1. From a schematic document (or schematic library document) choose Tools » Parameter Manager from the main menus. The Parameter Editor Options dialog will appear. To add the new parameter to all parts, ensure that he Parts option is enabled in the Include Parameters Owned By region, and that All Objects is set as the criteria in the That Meet the Following Criteria region.

Setting parameter management options.

2. Clicking OK will present the Parameter Table Editor dialog, showing all parameters currently 'owned' by all part objects on schematic source documents in the active project (or schematic components in the active schematic library). Click on the Add Column button and use the Add Parameter dialog that appears to define the name for the parameter. Ensure that the Add to all objects option is enabled, so that the new parameter will be added to all parts.

Example of using the Parameter Management feature to add a new parameter to all parts, across all source schematics in a design project.

3. Once the new column has been added, click the Accept Changes (Create ECO) button. Use the Engineering Change Order dialog that appears to Validate and then Execute the changes - adding the parameter to each of the required parts.

Executing the parameter changes (adding the new parameter to all parts) through an Engineering Change Order.

Adding a Parameter using the Properties Panel

A new parameter can be added to all selected parts using the Properties panel. The following procedure outlines the case when you wish to add the same parameter to all components in the active schematic library document, using the SCHLIB Filter and Properties panels.

1. Firstly, select all components in the library, using the SCH Filter panel and a query of IsPart. Ensure that the Whole Library option is enabled, otherwise only the active library component will be considered.

Configure a filter to select all parts in the active schematic library document.

2. In the library editor's Properties panel, verify - through the text at the bottom of the panel - that all components in the library are currently selected. If the Properties panel is not visible, click the  button at the bottom right of the workspace to display it.

Check all parts are selected.

3. Add the required parameter using the panel's Parameters tab. Click the Add button to add a new default parameter, then edit the name as required. Note that the parameter has already been added to all selected components, if you click the Add button again a second new parameter will be added.

Add the required new parameter to all selected parts.

Mapping Database Fields to Design Parameters

Design parameters for existing components - either those placed on the source schematic sheets of a design project, or those defined in a schematic component library that has been added to a library package - are updated with externally-stored information from a company database using the Update Parameters From Database command, available from the main Tools menu when the schematic document/schematic library document is active.

When a match occurs between a design component and a record in a table of the linked database, what happens next is determined by mapping and update information specified in the Database Link file. These settings are configured on the Field Mappings tab of the main document view.

Specify parameter mapping and update options on the Field Mappings tab of the DbLink document.

Parameter Mapping

The first two columns (from the left) on the Field Mappings tab allow you to control which information from the database is to be mapped to a component's parameters.

The Database Field Name column lists all field (column) names in the currently active table of the database. The Design Parameter column allows you to specify the design parameter that should be mapped to the corresponding field in the database. Initial mapping is performed automatically upon connection to the database, with all database fields mapped to design parameters using the same names. For example, if a field in the database is called Tolerance, a design parameter with the name Tolerance will be mapped to it.

You can change the entry for a design parameter, by:

• Clicking in its cell and typing the name of a different parameter directly.
• Using the cell's associated drop-down list to choose an existing design parameter.

You may have a large number of data fields associated with a component in the database, not all of which you will want, or even need, added as design parameters to the existing design component. Much of this information may only be required when generating a Bill of Materials. The Report Manager dialog includes an option that allows you to add parameter information to a BOM, directly from a linked database - allowing you to reduce the amount of information that gets 'carried' with the schematic source documents. For more information, refer to the section Adding Database Information Directly to a BOM.

For fields that you explicitly do not want mapped from the database, set the Design Parameter entry to [None]. Unmapped database fields are distinguished on the tab by the use of a red cross icon (). Mapped database fields are distinguished by a green tick icon ().

Define parameter mapping as required.

Parameter Update Options

The remaining columns on the Field Mappings tab allow you to specify the actions taken for parameters, when updating a component using the Update Parameters From Database command. In the following descriptions, the term Altium component is used to represent a placed component on a schematic sheet, or a defined component in a schematic component library (which is part of a library package).

The four columns are as follows:

• Update Values - a cell in this column is used to determine the action that should be taken if the parameter exists for the Altium component and in the database, but the values are currently different. Choose to update the parameter of the Altium component with the value stored in the database (Update), or not to update at all (Do not update).
• Add To Design - a cell in this column is used to determine the action that should be taken if the parameter is found in the database, but does not exist for the Altium NEXUS component. You can choose to add the parameter (Add), not add the parameter (Do not add), or add the parameter only if it has a value assigned to it in the database (Add only if not blank in database).
• Visible On Add - a checkbox in this column is used to determine whether a newly added parameter is made visible for the Altium component (enabled) or not (disabled).
• Remove From Design - a cell in this column is used to determine the action that should be taken if the parameter is found to exist for the Altium NEXUS component, but either is not in the database, or is, but has no value. You can choose to not remove the parameter at all (Do not remove), or only remove it if it has no value assigned to it in the database (Remove only if blank in database).

Initially, the Update Values, Add To Design, and Remove From Design fields - for each mapped database field - will be set to the entry Default, and the Visible On Add option will be disabled, as illustrated in the following image.

Initial (default) parameter update options.

Looking at the image, there are three important points to make regarding update options:

1. Unmapped database fields will have no associated update options.
2. The key field (e.g. Part Number in the image) will have no associated update options. This field is solely used for parameter matching purposes.
3. A setting of Default causes an update option to follow its corresponding default definition, as specified on the Default Actions tab of the Database Link Options dialog (Tools » Options). This dialog can also be accessed by clicking the Options button in the Field Settings region of the document view.

Define default parameter update options in a central location.

The third point is beneficial in that it allows you to specify update options from a central location, and then point to that location when defining the update options for each mapped field. That is why the Default entry is loaded automatically into the relevant update fields upon mapping a database field to a design parameter.

Should you wish to override the default setting for an update option, click inside the relevant update field, on the Field Mappings tab, then click again to access a drop-down providing the applicable update choices.

Parameter update options can be manually overridden, if required.

In this way, you have full control over how the parameters in the design are updated. You can set all fields to Default and make the required update decisions from the Database Link Options dialog, set each update field individually, or have a mixture of the two - the decision is entirely yours to make as you see fit. The update, when performed, is carried out through use of an Engineering Change Order dialog. If at this stage there are updates that you would prefer not to make, you can opt to not include those particular changes - giving you the final, and ultimate say, in which design parameters get updated.

Ensuring Synchronicity

After the mapping and update options have been specified in the Database Link file as required, and the file saved, you will be in a position to pass information from the database to the mapped parameters of Altium NEXUS components. Remember, the chosen key field parameter is used to ensure that an Altium NEXUS component retains its link to the corresponding record for that component, in the external database. This means that at any stage in the future, changes to parameter information in the database can be easily passed back to the Altium NEXUS component, synchronizing the two. Updates are performed using the Update Parameters From Database command, available from the Schematic/Schematic Library Editor's main Tools menu.

Dual Synchronization - DbLib/SVNDbLib and DBLink

You may have an existing design project where the majority of the placed parts have been linked to an external database using a DbLink file. Design changes may result in additional circuitry, the components for which might be placed using the Database Library feature. The associated DbLib/SVNDbLib file could, quite conceivably, point to a different external database.

When using the Update Parameters From Database command, all linked parameters for placed components will be queried - across all linked databases, irrespective of the linking method used - and detected differences for those parameters displayed in the Select Parameter Changes dialog.

Adding Database Information Directly to a BOM

Related page: BOM Configuration in the Report Manager

Source information for a Bill of Materials (BOM) has, in the past, been taken from the parameter information of the placed components for the design. But that can lead to a lot of information attached to a schematic that is only ever used for the BOM. If your placed Altium NEXUS components are linked to an external database using a DbLink file, the BOM Generator is able to extract any other record information that has not been added to the components as design parameters.

When configuring the Bill of Materials report using the Report Manager dialog, click the Database Parameters button (  ) in the Columns tab of the dialog to include them as a Source for the BOM, as shown below. This option will only be available if one or more components in your design are linked to an external database.

In the Columns listing, the  icon is used to distinguish a parameter that exists for one or more placed components in a linked external database. Click the visibility icon so it becomes an eye ( ), to include that column (parameter) in your BOM.

Include additional component information that exists only in an external database.