Sharing GCM type definitions across project areas

Edit online

You can share type definitions for global components and configurations to maintain consistency across global configuration management (GCM) project areas.

First, export the type definitions and then import into other GCM project areas, even the type definitions that are on other servers. You can also centrally manage the types by marking them as final to prevent further changes after they're imported.

Type definitions include artifact types, attributes, data types, and link types.

Before you begin

When you import or export, you work with all the type definitions in a project area at one time. You cannot import or export specific type definitions.

  • Exporting: Assign URIs to locally-defined type definitions. If you don't, new type definitions will be created and they might be listed as duplicates.
    • Each bounded data type, enumerated data type, and enumeration member must have a URI.
    • Each artifact attribute and link type must have an RDF predicate URI.
    • URIs also facilitate reporting, such as with Jazz® Reporting Service. See the related topic about assigning URIs.
  • Importing:
    • To create and modify type definitions, you must have the corresponding privilege or be a Configuration Lead.
    • To import type definitions or modify the type definitions that marked as final, you must have the corresponding privilege or be an Administrator.

About this task

Centrally managing type definitions

To keep type definitions consistent across project areas, consider maintaining any one definition in only one project area and propagating the type definitions to project areas that need them. The following are two examples of how to achieve consistency:
  • Simple: Choose one project area in which you create and maintain all type definitions. Export the type definitions from this project area, and import into each project area that uses them.
  • Complex: Designate two or more project areas to centrally manage the type definitions, but manage any one type definition in only one project area.

    In this scenario, don't mark the type definitions as final when you export them from those project areas and import them elsewhere. That way, the type definitions from the multiple project areas are merged.

    For more information about how marking as final affects imported type definitions, see the table in the Importing type definitions section.

If you change a type definition in multiple project areas and propagate it to the same destination project area, you might see unexpected results. For example, artifact attributes or link types might have the wrong cardinality, or bounded data types might have the wrong bounds.

URI values

The system uses URI values to match type definitions. If you change the URI of an imported resource and then export the type definitions or make the same change in other project areas, you might get unexpected results.

To avoid unexpected results, designate one project area to centrally manage type definitions.

Marking as final

Marking type definitions as final applies to all the type definitions in a project area (artifact types, attributes, data types, and link types). You cannot mark specific ones as final.

Exporting type definitions

Any project area member can export type definitions, which generates a .gcmt file. Use the following table to decide whether to mark them as final.

Factors Not marked as final Marked as final
Why To combine type definitions from multiple project areas

To back up the type system so that you can revert to original type definitions after experimenting

 To enforce one set of type definitions across project areas

Marking as final indicates the type system must be managed by imports only, and not manual updates.

Consequences for import Whoever imports this file can choose whether to mark type definitions as final. Type definitions are imported as final. There is no choice.

Importing type definitions

Administrators or the ones with the corresponding permission can import type definitions from a .gcmt file. If the type definitions were not marked as final when they were exported, you can choose whether to import them as final.

Use the following table to decide whether to mark them as final. You can also refer to the simple example described later.
Factors Not marked as final Marked as final
Why To combine type definitions from multiple project areas. To ensure consistency by enforcing the use of type definitions from one project area across a set of project areas.

Be careful - if you change final type definitions after you import, you lose the consistency benefit of central management, and any changes are overwritten in the next import.
Who can modify imported type definitions

Configuration Leads or higher, or project area members with the Create and modify type definitions privilege can change type definitions after import.

Administrators or project area members with the Modify imported type definitions marked as final privilege can unlock and change imported final type definitions.
Results Artifact types (global configurations and global components) are merged to combine the attributes and link types of both the project area you're importing from with the ones that are in use by the existing project area.

Attributes, data types, and link types imported from other project areas are removed from the artifact types but are still available on the other tabs.

 Artifact types are overwritten and contain only the attributes and link types from the project area you import from.

Attributes, data types, and link types are created or updated. What is imported overwrites what's already there if the semantics are the same.

You can also import and export type definitions by using the GCM REST API. See https://host:port/gc/doc/scenarios.

Procedure

  1. Open the Manage Type Definitions page. Click Administration Shows the Administration icon > Manage Type Definitions.
  2. Export or import the type definitions.
    • Export
      1. Click Export near the upper right on the screen to open the Export Type Definitions dialog box.
      2. If prompted for missing URIs, go back to the Manage Type Definitions page and assign URIs as needed. Then, click refresh this list in the Export Type Definitions dialog box.

        Remember, providing URIs makes reporting easier and prevents unintended duplication of type definitions.

      3. If you want to prevent further changes when the type definitions are imported into other project areas, select Mark as final to ensure that type definitions are centrally managed from the current project area. If you choose to ignore this step, whoever imports these type definitions is given the choice to mark them as final.
      4. Click Finish and save the generated .gcmt file.
    • Import
      1. Click Import.
      2. In the Import Type Definitions dialog box, browse to the .gcmt file to import, and click Next.
      3. If the type definitions were not marked as final when they were exported, you can prevent further changes by selecting Mark as final.
      4. Click Next, and on each tab, review the proposed changes. Check warnings and fix any errors in the project area you're importing into. Then, click refresh this preview in the Import Type Definitions dialog box.
      5. Click Finish.
      6. Imported type definitions show the user ID of the person who exported them from the source project area. This information is captured for audit purposes. To delete the name for privacy purposes:
        1. In the project area you recently imported into, complete the steps that are described in the Exporting and Importing type definitions and stored personal information wiki.
        2. Delete the .gcmt file that you imported.

Example

Your company builds vehicles that include sports cars and pickup trucks, each with their own project area that contains many global components. To facilitate auditing, compliance, and traceability across project areas, you want both project areas to use the same type definitions. Your organization decides that all project areas must use the SportsCar type definitions, so in this example you export from SportsCar and import into PickupTruck.

You can see here only the global configuration artifact type and its type definitions for both project areas before you import. For global components, the import behavior is similar.
  • The SportsCar Geography attribute and the PickupTruck TargetMarket attribute have different names but are used the same way in both project areas. Notice that they have the same attribute URI and they both use the same geo data type.
  • The SportsCar has an Engine attribute and engineType data type. The PickupTruck project area doesn't use these type definitions.
  • The PickupTruck project area has a Brochure link type.
Shows the global configuration artifact type for the SportsCar and PickupTruck project areas
Now, look at the wheels data type in both project areas: the URI is the same, but the member values differ. You can examine this data type again after the import.
Shows differences between the enumerated data type from SportsCar and from PickupTruck

You then export from SportsCar and import into PickupTruck. When you import, you preview your changes in the import wizard.

Now you see how the import results in the following image differ, based on whether you marked the type definitions as final. Notice the renamed and preserved items in the following images, a non-final import compared to the results of an import that is marked as final, which now match the SportsCar project area.
The image shows the PickupTruck global configuration artifact type after a non-final import, and the bottom image shows it after a final import

After the import, what you see depends on whether the type definitions were marked as final. The following are some key points:

  • Not marked as final: Artifact types (global configurations and components) are updated to include:
    • Attributes and link types that ate used by the imported artifact types.
    • Locally defined attributes and link types used by the artifact types of the project area you import into.
    • Attributes and link types that are imported from other project areas are removed from the artifact types. For example, if the PickupTruck global configuration artifact type has a reviewer attribute that was imported from the CubeVan project area, that attribute is removed from the PickupTruck global configuration, but it is still available on the Attributes tab of the Manage Type Definitions page.

    You can see that the PickupTruck wheels data type now has the same member values as the SportsCar wheels data type. If your organization wants all project areas to use the same type definitions as the SportsCar project area but some vehicles need a 20-inch wheel size option, consider adding that member value to the SportsCar wheels data type so that it's included when you import into other project areas.

    Other imported attributes, data types, and link types that aren't used by the artifact types are added to the PickupTruck project area.

  • Marked as final: The artifact types are overwritten to contain only the attributes and link types from the project area you're importing from.

    Attributes, data types, and link types whose URIs don't match imported ones are removed from the artifact type, but they are still available on the other tabs. In the example, notice that the Brochure link type is removed from the PickupTruck global configuration, but it is still available on the Link Types tab.

    You can unlock the global configuration artifact type and add them later, if needed, but remember, you lose any consistency from centrally managing the type definitions.
Even though the URIs of the wheels data type are now the same in the SportsCar and PickupTruck project areas, the member values in the PickupTruck project area are overwritten (they are not combined even for a non-final import):
Shows that enumeration member values are overwritten regardless of a non-final or final import

What to do next

After you import, review the type definitions on the tabs of the Manage Type Definitions page. These icons help you understand what you're seeing:
  • Shows an imported type definition: In the list on the left, an imported type definition.
  • Shows in imported and changed type definition: An imported type definition that was changed after the import. Remember, changes might be overwritten by another import.
  • Lock icon: In the details on the right, a type definition marked as final. Click to unlock and edit, and save your changes.

Changes from the import don't automatically change the attributes or links of existing artifacts (streams, baselines, or components). They have the same attribute and link values as when they were last edited. You see the changes the next time when you edit an artifact.