XBOM Manager - Administration Guide : XML Baselines (XBL)

21 March 2016

Table of Contents

1. XML Baselines (XBL)

1. XML Baselines (XBL)

As an alternative to the traditional baseline concept that exists in the XBOM component, there is also a feature that allows you to create more light-weighted baselines (called XBL).

While the traditional baselines creates several business objects and connections in the database, as every object in the baseline is represented by a business object and every connection by a connect in the database, the XBL feature just creates one object to represent the baseline as the actual data structure that the baseline represents is stored in a XML file that is checked-in to the baseline business object.

Even though the release 2010.3.0 introduced support for modifying an XBL structure, the normal usage of XBL is to use it as a snapshot tool.

The picture below illustrates how the XBL tool stores the data.

The benefits of using the XBL feature over the traditional baseline support in the XBOM manager component are:

Speed of creation: Since only one business object is created, the time to create a baseline will be shorter than a traditional baseline.
Creating a baseline doesn’t result in duplication of business object and connections for the whole structure. It’s cheaper, from a storage point of view, to hold the data in an XML file outside from the database.
The XBL baseline can be applied to any kind of structure, with just a few steps of configurations required. The traditional Baselining tool requires a larger effort, if to apply it on other kind of structures than EBOM structures.
Allows the user to perform comparisons and see changes in a structure from one day to another quick and easily.

1.1. Usage Scenarios

1.1.1. Showing Baselines

A command is added to the database called "TVC XBL Show Baselines". This command can be attached to the category tree menu for any type. Once attached, it will allow the user to list the baselines that have been created for the object, as well as allowing the user to create a new baseline.

The MQL code below illustrates how to add this command to the Part category menu.

mod menu type_Part add command "TVC XBL Show Baselines";

You can add the command to the category menu for any type; however, you must ensure that the types you enable the XBL support for, should have at least one configuration allowing the user to create an XBL for the specific type of object in question.

Once the user clicks on the command, the baselines page is shown in the content frame as illustrated below.

The URL that is used to show the list of baselines is:

${ROOT_DIR}/tvc-action/xblShowBaselines

1.1.2. Creating a Baseline

Baselines are created from the top object of the structure that is supposed to be "baselined".

By default, the created baseline will get the same number as the top object with the addition of a prefix that is based upon an auto-number generator. The revision will follow the format of A, B, C…Z. The different Baselines (of the same kind) are all revisions of each other.

You can override this behavior via the XBL configuration. See this chapter for details around the configuration format.

Below is a screenshot showing the "create baseline dialog" in the side panel.

Figure 1. Creating an XML Baseline

Once the baseline is created, the new baseline will appear in the table among the other baselines.

1.1.3. Viewing baselines

Viewing a baseline can be achieved in a couple of different ways. These are shown below.

The differences between these are described below:

If the baseline is opened in the same window (using the blue "go-there" button), this will look like:

If the baseline is opened in a popup window, this will be shown as:

If the name of the baseline is clicked, the baseline object is shown and inserter in the category tree to the left.

Figure 2. Viewing the details of a baseline

The navigate view is where the user can view the "baselined" structure information.

Figure 3. Navigating a baseline

1.1.4. Editable Baselines

When viewing a Baseline that was set to support edit upon creation, some additional functions in the user interface will appear (the exact functions that will appear depends on the configuration).

Examples of those are:

Toggle edit mode
Disconnect button
Create Version (Stamp version)
- This command is used to tag the current baseline. For example, after a set of modification, one might want to save the state of the structure in a version. This command will save a copy of the baseline in a new version.
List Versions
- Used to list the versions created. Note that there will always be at least one version; since when the baseline is created a version representing the initial baseline is always present.
Show Changelog
- Creates a PDF change log for the changes made in the baseline.
Edit Menu Contaning one or more commands for doing:
- Build structure
  - Add, replace and move
- Quick Connect
- Disconnect

See this chapter for details how to configure and add commands that enables build structure-, quick connect- and disconnect operations.

Important Notes about Edit Mode

Since the XBL data is stored in an XML file at the bottom line; some things needs to be considered when enabling edit mode in the table.

The columns in the table that should be editable must have been configured so in the table(s) used.
Use of Cell Editor’s should be done very carefully, as there is a risk that those cell editors are performing operations against the database using ID’s of objects or connections that no longer exist. It might be OK to use a cell-editor for validation of input values, but one should carefully review that such a cell editor itself isn’t doing anything against the database.
Custom Updaters will NOT be used in the XBL
When modifying a cell, the modified value is expected to be related with the expression defined in the column. When using custom data handlers, the values in the cell doesn’t need to origin from the expression. Hence, be careful to enable edit on columns whose values are retrieved via a data handler.

1.1.5. Comparing Baselines

Baselines can be compared in a few different ways:

Against the source object (the object, which the baseline were created for)
- Against other baselines of the source object
Against another revision of the source object
- Against baselines of other revisions of the source object
Against object found by configurable search
- Against baselines of object found
Against the multiple parents (the objects, which the baseline connected from)
- Against baselines connected from multiple parents

Baselines compared against each other are restricted to be compared to other baseline created using the same source object, and using the same definition.

Comparing a baseline to a source object will make the comparison to use the same definition that was used to create the baseline.

Figure 4. Setting up a comparison

Important to note here is that the "Result Table" selected will determine which data is actually compared. The columns in this table define what will be compared.

Any data that is not part of the selected table will not be compared. Added or removed rows will always be detected.

The comparison result indicates any added or removed row and possibly any modifications that have been done to a field in the table.

Figure 5. Comparison result table

Quick compare

If you want to compare a baseline without the user input for selecting settings you can use an action called "/xblQuickCompare". This will launch a compare result where selected baseline will be compared against the source object. It will use the default table and settings for "multi level".

The behavior of this action can be configured using parameters to the action:

Name	Description	Possible values
objectId	The object id for the baseline to compare against source structure	Any baseline object id
tableName	Name of table to use for comparison	Any table name that is valid for this comparison
multiLevel	Use Multi Level or not	true/false

Name

Description

Possible values

objectId

The object id for the baseline to compare against source structure

Any baseline object id

tableName

Name of table to use for comparison

Any table name that is valid for this comparison

multiLevel

Use Multi Level or not

true/false

When you show a traditional list of object, or a structure, there is a new column type defined that allows the user to directly get access to the baseline(s) related to the object in the table (if any). If the object has a baseline, an icon will be shown that, upon click, will load the related baselines into the side panel.

From the side panel, the user can start the comparison tool, open the baseline or simply delete it.

The column type is called: "xbl-baselines".

The screenshot below illustrates how this might look like:

The actions available on a baseline shown in the side panel are:

Side-panel configuration

To configure the appearance of the baseline object item in the side-panel see this chapter.

Column type settings

The column type "xbl-baselines" is configurable through column settings.

Setting Description Possible values

Setting	Description	Possible values
Order By	The property to sort the side-panel list items on	Select macro example: `$<attribute[attribute_AttributeName]>` Select example: originated
Sort Order	Control if to sort ascending or descending	ascending, descending

Order By

The property to sort the side-panel list items on

Select macro example: $<attribute[attribute_AttributeName]>

Select example: originated

Sort Order

Control if to sort ascending or descending

ascending, descending

Example configuration:

<Column>
    <ColumnType>xbl-baselines</ColumnType>
    <Name>xbl-baselines</Name>
    <RenderAsRowAction>true</RenderAsRowAction>
    <Setting name="Required Components">xbom</Setting>
    <Setting name="Searchable">false</Setting>
    <Setting name="Order By">originated</Setting>
    <Setting name="Sort Order">descending</Setting>
</Column>

1.1.7. Renew baseline

To include recent changes in a baseline there is a renew command that deletes previous baseline definition and replaces it with a new one based on the same settings and input values.

The renew command is disabled by default and can be activated by copying the file WEB-INF/tvc/xbom/xbl/menu/BaselinesToolbar.xml into WEB-INF/tvc-ext/xbom/xbl/menu/BaselinesToolbar.xml and then uncomment the line with RenewBaseline.xml.

1.2. Configuring XBL

An XBL configuration can be added to either the page object called TVC XBL Configuration, or as a resource added to the web-application (under /WEB-INF/tvc). If stored as a resource, the name of the resource type associated with an XBL configuration is "xblconfig".

Independent on if the XBL Configuration is stored in the page object or as a resource on the file system, the format of the configuration is identical. The only difference is that the page-object holds multiple configurations, while a file resource represents one single configuration.

1.2.1. Stored in the Page Object

When the XBL configurations are defined in the page object, the following format is used (note that this is required as the page object holds multiple configurations).

<XBLConfigurations>
    <Configuration id="xbl-1">
        ...
    </Configuration>
    <Configuration id="xbl-2">
        ...
    </Configuration>
    <Configuration id="xbl-3">
        ...
    </Configuration>
</XBLConfigurations>

It is important that each configuration is given a unique identifier. Otherwise you are not able to refer to the configuration.

1.2.2. Stored as a Resource

When storing the XBL configuration as a resource (file in the application), the format looks like:

<Configuration>
   ...
</Configuration>

The difference is that the root element is the "Configuration" element and you should not assign the Configuration an ID, as the id will be calculated from the name of the file.

1.2.3. The Configuration

This chapter explains and describes the format of the Configuration.

Below is a sample configuration were the important sections are highlighted and numbered. The section is described in details later on in this chapter. (Note that this particular example is not usable, it’s for explanation use only).

<Configuration>
    <DisplayName>EBOM Example Baseline</DisplayName>(1)
    <DisplayName locale="de">Deutsche name</DisplayName>

    <Description>This is an example baseline configuration used to create baselines from an EBOM structure</Description>(2)
    <Description locale="de">Dies ist ein beispiel Baseline-Konfiguration verwendet, um basislinien von einem EBOM struktur</Description>

    <ValidFor>(3)
        <Type>type_Part</Type>
        <Policy>policy_ECPart</Policy>
        <Policy>policy_DevelopmentPart</Policy>
    </ValidFor>

    <FilterExpression>$&lt;type.kindof[type_Part]&gt; == TRUE</FilterExpression>

    <Access>
        <UserList>
            <User>name of a user</User>
            <User>another user</User>
        </UserList>
        <RoleList>
            <Role>role_FirstRole</Role>
            <Role>role_SecondRole</Role>
        </RoleList>
        <GroupList>
            <Group>group_FirstGroup</Group>
            <Group>group_SecondGroup</Group>
            <Group>group_ThirdGroup</Group>
        </GroupList>
    </Access>

    <ExpandSpec>(4)
        <From>true</From>
        <To>false</To>
        <Depth>all<!-- all | 0 | 1 | 2 | 3 | 4 | 5 --></Depth>
        <Relationship>
            <Type>relationship_EBOM</Type>
            <Type>relationship_PartSpecification</Type>
            <Type>relationship_ReferenceDocument</Type>
            <!--<Where></Where>-->
        </Relationship>
        <!--
        <Object>
            <Type>type_Part</Type>
            <Type>type_DOCUMENTS</Type>
            <Where></Where>
        </Object>
        -->
    </ExpandSpec>
    <ExpandSpec>
        <Depth>2</Depth>
        <Filter>First Filter</Filter>
        <Filter>Second Filter</Filter>
        <Role>The name of the role, which owns the filters (not needed if XML filters are being used)</Role>
    </ExpandSpec>

    <ExpandSpec>
        <Expander>jpo:MyExpander:nameOfMethod</Expander>
        <Expander>inquiry:MyInquiry</Expander>
        <Expander>java:com.acme.MyExpander</Expander>
        <Expander>shadow:type_ABC,type_DEF</Expander>
    </ExpandSpec>

    <Tables>(5)
        <Table default="true">TVC XBL Baseline</Table>
        <Table>TVC Basic Information</Table>
    </Tables>

    <NavigationExcludeFilter>(6)
        <Type>type_CADDrawing</Type>
        <Type>type_SomeOtherType</Type>
        <Policy>policy_APolicy</Policy>
        <Policy>policy_AnotherPolicy</Policy>
        <Relationship>relationship_ARelationship</Relationship>
        <Relationship>relationship_AnotherRelationship</Relationship>
    </NavigationExcludeFilter>

    <ComparisonExcludeFilter>(7)
        <Type>type_CADDrawing</Type>
        <Type>type_SomeOtherType</Type>
        <Policy>policy_APolicy</Policy>
        <Policy>policy_AnotherPolicy</Policy>
        <Relationship>relationship_ARelationship</Relationship>
        <Relationship>relationship_AnotherRelationship</Relationship>
    </ComparisonExcludeFilter>

    <Compare>(8)
        <Key relationship="relationship_EBOM">
            <Field appliesToRel="true">
                $&lt;attribute[attribute_FindNumber]&gt;
            </Field>
        </Key>
        <Key relationship="*">
          <Field appliesToRel="false">type</Field>
          <Field appliesToRel="false">name</Field>
          <Field appliesToRel="false">revision</Field>
          <Field appliesToRel="true">type</Field>
        </Key>
    </Compare>

    <Editable>true | false</Editable>(9)

    <UI>(10)
         <Header>...</Header>
         <SubHeader>...</SubHeader>
         <CustomMenu>...</CustomMenu>
         <EditMenu>
             <Disconnect/>
             <BuildStructure>
                 <Label>...</Label>
                 <RegisteredSuite>...</RegisteredSuite>
                 <Configuration>...</Configuration>
                 <AutoLoad>...</AutoLoad>
            </BuildStructure>
            <QuickConnect>
                 <Label>...</Label>
                 <RegisteredSuite>...</RegisteredSuite>
                 <SearchConfig>name</SearchConfig>
                 <Relationship>relationship_EBOM</Relationship>
                 <Direction>from</Direction>
            </QuickConnect>
         </EditMenu>
     </UI>
     <CreateSettings>(11)
         <Type>name or symbolic name of type derived from TVC XBL Baseline</Type>
         <Policy>name or symbolic name of policy to be user</Policy>
         <Vault>name or symbolic name of vault to create the object in</Vault>
         <IncludeSourceName>true | false</IncludeSourceName>
         <Revision>Custom revision to be used</Revision>
     </CreateSettings>

    <ListConfig>(12)
        <ShowTypeIcon>false</ShowTypeIcon>
        <Action>delete</Action>
        <Action>details</Action>
        <Action>compare</Action>
        <Action>navigate</Action>
        <Row style="bold underline"><![CDATA[$<name> ($<revision>)]]></Row>
        <Row style="normal"><![CDATA[$<attribute[attribute_TVCXBLPurpose]>]]></Row>
        <Row style="normal "><![CDATA[$<originated>]]></Row>
    </ListConfig>

    <Handler>com.acme.MyHandler</Handler>(13)
     <DoAsPrivileged>true</DoAsPrivileged>
     <Hidden>false</Hidden>
     <AutoDescriptionMacro>
         ${NAME}, ${ORIGINATED}, {FULLNAME}
     </AutoDescriptionMacro>
</Configuration>

The configuration is built up of 12 major sections; they are explained in the sub chapters below.

DisplayName (1)

The DisplayName element is used to give the configuration a human understandable name. The name should be short and precise. The display name can be localized into different languages.

The display name is used when the user creates a new XBL and is able to select what configuration to be used.

Description (2)

The description is used to give the user an understanding on the purpose with the configuration. This is important if you provide multiple configurations for a certain type of object as it gives the user an understanding on what configuration to choose.

The description can be localized into different languages.

The description is shown when the user is about to create a new XBL.

Validity (3)

The section (3) in the configuration shows a number of ways how you can make the configuration valid for a particular object and for what users the configuration is valid for.

If you only want to mask a configuration for a certain object type, or for objects that has a certain policy, you can use the easier construct "ValidFor". This allows you to define one or more types, which the configuration is valid for, and/or one or more policies that the source objects must have in order for this configuration to be usable.

If you need to make more complex decision, you can use the "FilterExpression" element that allows you to define a Matrix expression that must evaluate to true for the source object. It is possible to use both a "FilterExpression" and a "ValidFor" element.

Restricting access to the configuration can be accomplished by using the "Access" element. Here you can either define named user(s) or role/groups the user must be assigned to.

ExpandSpec (4)

The ExpandSpec element defines how to expand the structure, e.g. what objects and connections are supposed to be serialized down to the XBL data.

You can expand the structure in a number of different ways.

Expand using a pre-defined way to do the expansion
Expand by using filters
Expand using an expand-mode (a.k.a Expander) Please see the Structure browser admin guide for more information regarding how to use Expanders.

An example of the first approach is displayed below:

<ExpandSpec>
    <From>true</From>
    <To>false</To>
    <Depth fixed="true | false">all<!-- all | 0 | 1 | 2 | 3 | 4 | 5 --></Depth>
    <Relationship>
        <Type>relationship_EBOM</Type>
        <Type>relationship_PartSpecification</Type>
        <Type>relationship_ReferenceDocument</Type>
        <!--<Where></Where>-->
    </Relationship>
    <!--
    <Object>
        <Type>type_Part</Type>
        <Type>type_DOCUMENTS</Type>
        <Where></Where>
    </Object>
    -->
</ExpandSpec>

In this case you define exactly how to expand the structure, regarding relationship types and object types (optional) including possible where clauses applying to either the connections or the objects. The table below describes the elements more in detail.

Element	Description	Possible values
From	Expand in the from direction?	true, false
To	Expand in the to direction?	true, false
Depth	Levels to expand NOTE: You can use the attribute fixed on this element to disallow the user to change the expand depth upon create.	"all" or specific value (1,2,3,4,5 …)
Relationship	Defines the relationship settings for the expansion. Includes the subelements Type and Where
Object	Defines the object settings for the expansion. Includes the sub elements Type and Where.
Type	Defines either the relationship or object type to use for the expansion	Symbolic or non-symbolic type name: relationship_EBOM, EBOM type_Part, Part

Element

Description

Possible values

From

Expand in the from direction?

true, false

Expand in the to direction?

true, false

Depth

Levels to expand

NOTE: You can use the attribute fixed on this element to disallow the user to change the expand depth upon create.

"all" or specific value (1,2,3,4,5 …)

Relationship

Defines the relationship settings for the expansion. Includes the subelements Type and Where

Object

Defines the object settings for the expansion. Includes the sub elements Type and Where.

Type

Defines either the relationship or object type to use for the expansion

Symbolic or non-symbolic type name:

relationship_EBOM, EBOM

type_Part, Part

An example of the second approach is displayed below:

<ExpandSpec>
    <Depth fixed="true">2</Depth>
    <Filter>First Filter</Filter>
    <Filter>Second Filter</Filter>
    <Role>The name of the role, which owns the filters (not needed if XML filters are being used)</Role>
</ExpandSpec>

In this case, you can reuse already implemented filters in order to perform the expansion. Note that you must specify the role (which owns the filters) unless you use XML based filters (see the document describing XML based definitions).

The last approach, e.g. using so called Expanders is by using a so called expander. This is defined like below:

<ExpandSpec>
    <!-- Select one approach -->
    <!--<Expander>jpo:MyExpander:nameOfMethod</Expander>-->
    <!--<Expander>inquiry:MyInquiry</Expander>-->
    <!--<Expander>java:com.acme.MyExpander</Expander>-->
    <!--<Expander>shadow:type_ABC,type_DEF</Expander>-->
</ExpandSpec>

If you intend to do a full expand, you cannot expand in both the FROM and TO direction. The XBL logic will by default validate that this scenario doesn’t occur by changing to 1 level expansion if full expand isn’t possible.

Tables (System tables or XML tables) (5)

The tables in an XBL configuration define how and what data can be viewed and compared when viewing a baseline structure. The tables contains columns that either uses standard expressions, or can use so called Data Handlers that can be used to select more complex data from the database (see the developer documentation for more information regarding data handlers).

Example:

<Tables>
    <Table default="true">TVC XBL Baseline</Table>
    <Table>TVC Basic Information</Table>
    <Table>tvc:table:namespace/XBL-2.xml</Table>
    <Table>tvc:table:namespace/XBL-3.xml</Table>
</Tables>

In this example, the table "TVC XBL Baseline" will be the default table to use. The other tables will be selectable in the navigation view and the comparison view of the baseline.

The table you use when displaying XBL data can take advantage of using so called cell renderers. Please note that a cell renderer might create links to other pages, containing the ID of the object (w/wo the connection id). This might result in confusions or in worst case errors, since the page you are linking to probably will try to read information from the database (using the provided ID’s). Hence, the data shown on the target page is not originated from the XBL data. In some cases, the ID in the baseline might refer to an object that no longer exists for some reason. E.g. use cell renderers with care, especially if you create links from your table page.

When you define your selectables in the XBL. Either it is in a table, or in another place. Either use the selectable "attribute[name]" or "attribute[name].value". Don’t mix these since if you refer to the same attribute, but are using ".value" in one place but not in the other – the XBL logic will have problems to find the desired value.

There are two column types that can be used together with XBL date. These are:

xbl-document-file
- If you have document objects in your XBL data, these will ensure that information from the document such as the current active file version (and filename) is serialized into the XBL once created. When displaying the baseline, this column will provide a link for the user in order to be able to download the version of the file, which were the active version once the XBL were created.
xbl-name
- This column will display the name of the object + a link to a special page that will show information about the object in the side panel. The page shown will load the data from the XBL and not from the real data base. Depending on the tables being used, the number of basics/attributes shown on this page might however vary.

NavigationExcludeFilter (6)

The NavigationExcludeFilter element can be used to define type, policies and relationships that should be excluded from the navigation view of a baseline. Nodes that fit any of the requirements specified in this section will not be shown in the navigation view. This means that your baseline configuration can specify to include more data than actually is being shown when navigating the structure.

The elements supported below the NavigationExcludeFilter are shown in the table below:

Element	Description	Possible values
Type	The type to exclude	Symbolic or non-symbolic type name: type_ CADDrawing, CAD Drawing
Policy	The policy to exclude	Symbolic or non-symbolic type name: policy_ Part, Part
Relationship	The relationship to exclude	Symbolic or non-symbolic type name: relationship_ EBOM, EBOM

Element

Description

Possible values

Type

The type to exclude

Symbolic or non-symbolic type name:

type_ CADDrawing, CAD Drawing

Policy

The policy to exclude

Symbolic or non-symbolic type name:

policy_ Part, Part

Relationship

The relationship to exclude

Symbolic or non-symbolic type name:

relationship_ EBOM, EBOM

Example:

<NavigationExcludeFilter>
    <Type>type_CADDrawing</Type>
    <Type>type_SomeOtherType</Type>
    <Policy>policy_APolicy</Policy>
    <Policy>policy_AnotherPolicy</Policy>
    <Relationship>relationship_ARelationship</Relationship>
    <Relationship>relationship_AnotherRelationship</Relationship>
</NavigationExcludeFilter>

Often the settings used in this element will be the same as for the element ComparisonExcludeFilter, but the possibility to separate the two still needs to be available, which is why the two elements both exist.

ComparisonExcludeFilter (7)

The ComparisonExcludeFilter element can be used to define types, policies, and relationship that that should be excluded when comparing baselines. Nodes that fit any of the requirements specified in this section will not be compared, and they will not be shown in the result table of a comparison.

Element	Description	Possible values
Type	The type to exclude	Symbolic or non-symbolic type name: type_ CADDrawing, CAD Drawing
Policy	The policy to exclude	Symbolic or non-symbolic type name: policy_ Part, Part
Relationship	The relationship to exclude	Symbolic or non-symbolic type name: relationship_ EBOM, EBOM

Element

Description

Possible values

Type

The type to exclude

Symbolic or non-symbolic type name:

type_ CADDrawing, CAD Drawing

Policy

The policy to exclude

Symbolic or non-symbolic type name:

policy_ Part, Part

Relationship

The relationship to exclude

Symbolic or non-symbolic type name:

relationship_ EBOM, EBOM

Example:

<ComparisonExcludeFilter>
    <Type>type_CADDrawing</Type>
    <Type>type_SomeOtherType</Type>
    <Policy>policy_APolicy</Policy>
    <Policy>policy_AnotherPolicy</Policy>
    <Relationship>relationship_ARelationship</Relationship>
    <Relationship>relationship_AnotherRelationship</Relationship>
</ComparisonExcludeFilter>

Often the settings used in this element will be the same as for the element NavigationExcludeFilter, but the possibility to separate the two still needs to be available, which is why the two elements both exist.

Compare (8)

The way how the comparison tool matches a row from one structure in another can be configured. By default, the type, name and revision from the object and the relationship type is used for the key, which the row matcher uses. However, in some cases this will fail, especially if two objects are connected with multiple connections of the same type. In such case, one can define a different strategy for how the key should be computed. For example, when comparing EBOM structures, one might use the "Find Number" as part of the identifying key.

An example of how to construct a different key for an XBL configuration is shown below

<Compare>
    <ShowMultiLevelChanges>true</ShowMultiLevelChanges>
    <Key relationship="relationship_EBOM">
        <Field appliesToRel="true">$&lt;attribute[attribute_FindNumber]&gt;</Field>
    </Key>
    <Key relationship="*">
        <Field appliesToRel="false">type</Field>
        <Field appliesToRel="false">name</Field>
        <Field appliesToRel="false">revision</Field>
        <Field appliesToRel="true">type</Field>
    </Key>
</Compare>

The ShowMultiLevelChanges element can be used to specify if removed rows should include all children or not. By default, the comparator will only show the removed row and nothing below.

Editable Setting (9)

An XBL can be made editable by specifying the following within the configuration:

<Editable>true</Editable>

The user can override this setting upon create if the configuration defines that the baseline supports edit; otherwise not.

UI Settings (10)

The UI settings control the user interface when the user is navigating the baseline data.

You can specify a custom Header and SubHeader, and these can all be localized in different languages.

Example:

<UI>
    <Header>Baseline</Header>
    <Header locale="de">...</Header>
    <SubHeader>$<TYPE>, $<NAME>:$<REV> ($<CURRENT>)</SubHeader>
    <SubHeader locale="de">...</SubHeader>
</UI>

Moreover, if the XBL has been marked to support edit; you can define custom commands that support removal of rows and adding new rows into the XBL.

This is done as shown in the example below:

<UI>
    ...
    <ToggleEditMode>true | false</ToggleEditMode> <!-- Enables/disables toggle-edit -->
    <DisconnectButton>true | false</DisconnectButton> <!-- Enables/disables disconnect-btn -->

    <EditMenu>

        <Disconnect/> <!-- Adds a disconnect command -->

        <BuildStructure> <!-- Adds a button that invokes build structure -->
            <Label>...</Label> <!-- the label for the command -->
            <RegisteredSuite>...</RegisteredSuite> <!-- If your label refers a suite str. -->
            <Configuration>...</Configuration> <!-- name of build structure config -->
            <AutoLoad>inquiry:name_of_inquiry</AutoLoad> <!-- optional -->
        </BuildStructure>

        <QuickConnect> <!-- Adds a button that invokes quick connect -->
            <Label>...</Label> <!-- the label for the command -->
            <RegisteredSuite>...</RegisteredSuite> <!-- If your label refers a suite str. -->
            <SearchConfig>...</SearchConfig> <!-- name of search config -->
            <Relationship>...</Relationship> <!-- name of relationship to use for connect -->
            <Direction>from | to</Direction> <!-- direction of connection created -->
        </QuickConnect>
    </EditMenu>
</UI>

E.g. you can add three different kinds of commands:

Disconnect
Build Structure
Quick Connect

Note however that you can have several different variants of build-structure and quick-connect to support adding different kind of objects into the XBL.

To enable add to clipboard, add to collection and/or manage collection from the XBL view, use the following configuration elements:

<UI>
    <AddToClipboard>true</AddToClipboard>
    <AddToCollection>true</AddToCollection>
    <ManageCollection>true</ManageCollection>
</UI>

Since the XBL view might show objects that no longer exist in the database, or the user has no show access to them, errors might appear in the user interface due to enabling them.

Create Settings (11)

By default, the XBL framework will create the baseline with the following characteristics:

Property	Default Value	Notes
Type	TVC XBL Baseline	The value must be a type that is derived directly or indirectly from TVC XBL Baseline.
Policy	TVC XBL Baseline	The policy must govern the type. The policy must also have a store and include the formats XML + generic.
Vault	Same as where the object, which the baseline is created for
Revision	Default revision according to policy
IncludeSourceName	True	The name of the baseline will contain the name of the object, which it was created for, if this is set to true.
ReviseOnCreate	True	A new baseline is created as a revision. If setting this to false, the baselines are not revisions of each other.

Property

Default Value

Notes

Type

TVC XBL Baseline

The value must be a type that is derived directly or indirectly from TVC XBL Baseline.

Policy

TVC XBL Baseline

The policy must govern the type.

The policy must also have a store and include the formats XML + generic.

Vault

Same as where the object, which the baseline is created for

Revision

Default revision according to policy

IncludeSourceName

True

The name of the baseline will contain the name of the object, which it was created for, if this is set to true.

ReviseOnCreate

True

A new baseline is created as a revision. If setting this to false, the baselines are not revisions of each other.

Example configuration:

<CreateSettings>
    <Type>type_MyXBLType</Type>
    <Policy>policy_MyXBLPolicy</Policy>
    <IncludeSourceName> false</IncludeSourceName>
    <Revision>-</Revision>
</CreateSettings>

ListConfig (12)

The side-panel appearance of a baseline can be configured using the ListConfig element.

Element	Notes	Possible Values
ShowTypeIcon	Displays the type icon of the XBL object if set to true	true, false
Action	Add one for each action you want included for the XBL list item	Delete, details, compare, quickcompare, navigate
Row	Use the style attribute to format rows Use macros within the element text value to display object properties

Element

Notes

Possible Values

ShowTypeIcon

Displays the type icon of the XBL object if set to true

true, false

Action

Add one for each action you want included for the XBL list item

Delete, details, compare, quickcompare, navigate

Row

Use the style attribute to format rows

Use macros within the element text value to display object properties

Example configuration:

<ListConfig>
    <ShowTypeIcon>false</ShowTypeIcon>
    <Action>delete</Action>
    <Action>details</Action>
    <Action>compare</Action>
    <Action>quickcompare</Action>
    <Action>navigate</Action>
    <Row style="bold underline"><![CDATA[$<name> ($<revision>)]]></Row>
    <Row style="normal"><![CDATA[$<attribute[attribute_TVCXBLPurpose]>]]></Row>
    <Row style="normal"><![CDATA[$<originated>]]></Row>
</ListConfig>

Other Settings (13)

The last section in the example configuration shown above, allows configuring some additional things.

Element Description

Element	Description
DoAsPrivileged	When creating a baseline, this is by default done using the same context as the user who is creating the XBL. This might result in that data is not included correctly, as the user might lack access. Using this setting can force the creation to be done using a context from a super-user. This has the side effect that the users might see more data that shouldn’t be visible. On the other hand, this scenario could be considered from within the table by using custom data handlers etc.
Hidden	Define if the configuration is hidden or not. A configuration can be made hidden in order to prevent creating new baselines with this configuration, but still be able to use the old baselines that have been created with this configuration.
AutoDescriptionMacro	Defines a custom macro that can be used to set an automatically generate description on the Baseline object. The macro is resolved against the source object, which the baseline is created for. An example macro is shown below: `${NAME}, ${ORIGINATED}, ${FULLNAME}`
Handler	If, for some reason, you are not able to configure how to expand the structure, e.g. define what data to be included in the baseline, you can as a last attempt implement a so called Handler that will be invoked during the creation of the XBL. The value must be the fully qualified name of a class that extends from: `com.technia.tvc.xbom.xbl2.Handler`
CompressData	Can be used to override the default setting that defines if the data file should be compressed or not. Recommended is to not change this value.

DoAsPrivileged

When creating a baseline, this is by default done using the same context as the user who is creating the XBL. This might result in that data is not included correctly, as the user might lack access.

Using this setting can force the creation to be done using a context from a super-user. This has the side effect that the users might see more data that shouldn’t be visible. On the other hand, this scenario could be considered from within the table by using custom data handlers etc.

Hidden

Define if the configuration is hidden or not. A configuration can be made hidden in order to prevent creating new baselines with this configuration, but still be able to use the old baselines that have been created with this configuration.

AutoDescriptionMacro

Defines a custom macro that can be used to set an automatically generate description on the Baseline object. The macro is resolved against the source object, which the baseline is created for.

An example macro is shown below:

${NAME}, ${ORIGINATED}, ${FULLNAME}

Handler

If, for some reason, you are not able to configure how to expand the structure, e.g. define what data to be included in the baseline, you can as a last attempt implement a so called Handler that will be invoked during the creation of the XBL.

The value must be the fully qualified name of a class that extends from:

com.technia.tvc.xbom.xbl2.Handler

CompressData

Can be used to override the default setting that defines if the data file should be compressed or not. Recommended is to not change this value.

1.3. Miscellaneous Settings

This chapter describes some miscellaneous settings available for the XBL feature.

1.3.1. TVC Init Parameters

The table below lists the available TVC init parameters, which typically are set in the web.xml file within the TVC servlet definition. These are added like the example below:

<init-param>
    <param-name>name.of.parameter</param-name>
    <param-value>value of the parameter</param-value>
</init-param>

Parameter	Type	Description
tvc.xbom.xbl.compare.multiLevel	Boolean	Whether or not multilevel comparison is default. The default value is TRUE.
tvc.xbom.xbl.configName	String	The name of the page-object that holds the XBL configurations. The default value is "TVC XBL Config"
tvc.xbom.xbl.compressFiles	Boolean	Whether or not if the XBL data file should be compressed when it’s being checked in to the baseline object. The default value is true.
tvc.xbom.xbl.autoGenerateDescription	Boolean	If descriptions should be auto generated.

Parameter

Type

Description

tvc.xbom.xbl.compare.multiLevel

Boolean

Whether or not multilevel comparison is default. The default value is TRUE.

tvc.xbom.xbl.configName

String

The name of the page-object that holds the XBL configurations. The default value is "TVC XBL Config"

tvc.xbom.xbl.compressFiles

Boolean

Whether or not if the XBL data file should be compressed when it’s being checked in to the baseline object. The default value is true.

tvc.xbom.xbl.autoGenerateDescription

Boolean

If descriptions should be auto generated.

XBOM Manager - Administration Guide : XML Baselines (XBL)

1. XML Baselines (XBL)

1.1. Usage Scenarios

1.1.1. Showing Baselines

1.1.2. Creating a Baseline

1.1.3. Viewing baselines

1.1.4. Editable Baselines

Important Notes about Edit Mode

1.1.5. Comparing Baselines

Quick compare

1.1.6. Showing Related Baselines in the Side Panel

Side-panel configuration

Column type settings

1.1.7. Renew baseline

1.2. Configuring XBL

1.2.1. Stored in the Page Object

1.2.2. Stored as a Resource

1.2.3. The Configuration

DisplayName (1)

Description (2)

Validity (3)

ExpandSpec (4)

Tables (System tables or XML tables) (5)

NavigationExcludeFilter (6)

ComparisonExcludeFilter (7)

Compare (8)

Editable Setting (9)

UI Settings (10)

Create Settings (11)

ListConfig (12)

Other Settings (13)

1.3. Miscellaneous Settings

1.3.1. TVC Init Parameters