Libraries

Overview

A library is an ordinary project whose owners publish releases: fixed copies of the project with a label such as 1.0 or 2026 Q4. Another project uses one release of the library in two ways, alone or together:

• It shows the library items: every item of the release appears in the project read-only, as a library item. You relate your own items to them, place them on diagrams and add them to documents, but you cannot change them here.
• It adopts items: adopted items are local copies. They get new ids, you can edit them like any other item, and each remembers the library item and release it came from.

When the library publishes a newer release, the project that uses it sees which adopted items changed in the library, which changed locally, and which changed in both, and updates them field by field.

Libraries are part of the Team plan. The plan of the project's owner decides, for the library and for the project that uses it.

Concepts

Releases

A release never gives access to the library project itself: its later edits, history, comments and members stay closed to people who only read releases.

Who can read a release

A new release is visible to the library project's organization. When the library project is deleted, its releases stay readable for the projects that use them.

Library items shown read-only

When a project shows a library's items, they are read from the release for each person, with that person's access, and kept only while the project is open. The project stores none of their content, only the subscription (the library and release ids) and its own relationships and diagram places that point at them.

Adopted items

An adopted item keeps an origin record with the ids of the library, the release and the library item. The project holds no name of the library: the library's name and release label are read with each person's access.

Each adopted item has one of these states against the release the project uses:

The comparison covers the class, number, name, description text and attributes. Attributes that start with an underscore (workflow records) are not compared.

How to use it

When and why

Use a library for content that several projects share and that changes in controlled steps: a company's standard requirements, interface standards, a catalog of verified components, or a parent program's requirements for its subprojects. Releases make reuse deliberate: each project chooses when to take a newer release and sees exactly what changes.

Show the library items when the project should use them as they are, such as standard parts on its diagrams or standard requirements in its specification, and take each new release as a whole. Adopt items when the project needs to change its copy.

For traceability to items that stay in another project, use links to other projects instead. Both work together: you can link to an item of a release.

Publish a project as a library

1. Open the project, then Control & Reviews → Libraries.
2. Under Publish, click Publish This Project as a Library…. The card says "This project is a library."
3. Click New Release…, enter a Label such as 1.0 and Notes, then click Create Release. The release appears in the list.
4. To choose who can read it, click ⋯ → Visibility… on the release, tick organizations and projects, and click Save.

Only owners publish and create releases. Publish a new release whenever the library reaches a state that other projects should take.

Use a library and adopt items

1. Open the project that will use the library, then Control & Reviews → Libraries.
2. Under Available Libraries, click Use in This Project… on the library, choose the Release, and click Use Library. The release opens.
3. Search by number or name and narrow by Class. Tick the items to adopt.
4. Click Adopt Selected…. Choose Include the relationships among them and Include their diagrams and the items they show. The dialog counts what it adds, for example "Adds 2 items, 1 relationship."
5. Click Adopt. The items appear in the project with new ids. Adopting is one undo step.

Items adopted before are reused, not copied again. Items of a class this project does not have are left out and counted in the preview. Attributes this project does not have, and attachments, stay in the library.

Show a library's items in this project

1. Open the project, then Control & Reviews → Libraries.
2. When you start using the library, tick Show all its items in this project, read-only in Use Library. For a library already in use, click ⋯ → Show Library Items on its row. Shown here then counts the items, for example "3 items, read-only".
3. Open the Database and turn on Library Items to list them with your own items. Select one to see where it comes from; its banner offers Adopt… and Libraries.
4. Use them: in an item's Trace section click + → Link existing… and choose a library item; on a diagram, add one with Add existing; in a document, use Add Existing Item….
5. To make an editable copy, click Adopt… in the item's banner, or select library items in the Database and click Adopt… in the bulk bar.

⋯ → Hide Library Items takes them out again. Showing and hiding are each one undo step.

Take a newer release

1. In Libraries This Project Uses, the Updates column shows n newer releases when the library has published more.
2. Click ⋯ → Change Release…, choose the release and click Change Release. Library items shown here follow the release at once. Adopted items do not change yet; the Updates list opens.
3. Click Update n Items Changed Only in the Library to take every change that has no local edit, in one undo step.
4. For each item Changed in both, click Update From Source…. Each differing field shows a word diff (local text deleted, library text inserted). Fields changed only in the library are ticked Take library value; fields changed only here are not. Tick or untick, then click Update Item.
5. For an item Removed from the library, click Resolve…, then Keep as Local Item (it loses its origin record) or Delete Item.

Compare one item

Open an adopted item. The Item section shows From the library name and release label. Click Compare With Source to see the differences, or Update From Source… to apply them.

Worked example: a fastener library for the CubeSat EO-1 demo

1. Create a project named Fastener Library with the requirements FL.1 Bolt torque ("Torque to 12 Nm.") and FL.2 Thread size ("M6 threads."), and relate FL.1 traced to FL.2.
2. In Fastener Library, open Libraries, click Publish This Project as a Library…, then New Release… with label 1.0.
3. Open CubeSat EO-1, then Libraries → Available Libraries → Use in This Project…, choose 1.0, tick FL.1 and FL.2, and adopt them with their relationship.
4. Later the library renames FL.1 to Bolt torque max and changes the description of FL.2, then releases 1.1. In CubeSat EO-1 you had renamed FL.2 to Thread size (local).
5. Change Release… to 1.1: FL.1 is Changed in the library, FL.2 is Changed in both. Update 1 Item Changed Only in the Library renames FL.1. Update From Source… on FL.2 takes the new description and keeps your name.

Showing the items instead: in step 3 tick Show all its items in this project, read-only and adopt nothing. FL.1 and FL.2 appear in the Database (with Library Items on) with a Library tag; relate FL.1 to your structure in the Trace section. After Change Release… to 1.1, FL.1 reads Bolt torque max without any update step.

Tips and good practice

• Keep a library small and focused, and write release notes that say what changed.
• Take newer releases at planned points, such as before a design review, and record the change in a change request when the project is under configuration control.
• Edit adopted items only when the project really differs; local edits make later updates manual.
• Withdraw a release that should no longer be used instead of deleting the library.

Common mistakes

How it connects to other features

• Links to other projects: in Trace → Other projects → +, choose a library and a Version such as Release 1.1 to link to the release's copy of an item. The row shows the release label instead of current. See Links to Other Projects.
• Change requests: a change request can stage links to other projects (Add Change ▾ → Add a Link to Another Project…).
• Activity: using, changing and stopping a library, and showing or hiding its items, are recorded as "Changed the libraries used".
• Program Coverage: a parent program sees the links from its subprojects on Program Coverage.

The Libraries page

Stop Using… removes the library from the project; adopted items stay as they are, and library items shown here disappear. Stop Publishing… prevents new releases; existing releases stay readable.

Messages

Limits

Related

• Links to Other Projects
• Program Coverage
• Change Requests
• Collaboration