Branch components

If you want to make a copy of a component and maintain a relationship between the original component and the new copy, you can use the Save as a branch option. This is helpful if there are different versions of a component that you want to track and update separately but still want to have a common starting point for the information.

A content owner or administrator can set permissions to deny access to components or folders. If your permissions to content has been blocked and you are not an administrator, you cannot use the Save as branch option in a project's Content pane.

For example, you want to create a prototype of a book with a new style that you want to distribute in a test market.

  • You can take the original components of the standard-style book and create a branch.
  • Then you can edit the content in the branch to create the prototype.
  • While creating the prototype you may need to refer back to the standard style.
  • You'll be able to see where the original content came from because Inspire tracks the branched relationship.

When you select the Save as a branch... option, you can choose to either save all references or select only the ones you want to include in the new branch.

  • To keep all the same references in the branch copy that exist in the source, click Create.
  • To see the references or select a customized list of references in the List or Hierarchy view, select Show referenced components.

    When you select Show referenced components, a request is sent to Inspire to display the list.

    • If this is the first time you are selecting Show referenced components for this component, then you are prompted to make a selection:
      • Wait for the list to be built
      • Be notified when the list has been built

    • If you choose to wait, the Save as branch screen stays open while the references are being collected. Look for a notification in the top right corner of your Inspire screen telling you that the list of references for the component has been built. Then you can continue to select the references you want to keep.
    • If you choose not to wait, the Save as branch screen closes. Look for a notification in the top right corner of your Inspire screen telling you that the list of references for the component has been built. Then you can either:
      • Open the notification in the Notifications module to go to the component that you were working with.
      • Select the component again and select Save as branch...

    • After the list of references has been built for a component, it is saved in Inspire.
    • When you choose Save as branch and select Show referenced components for a component that has a saved list of references, the list appears right away.
    • You won't see the prompt again unless you select a component that doesn't have a saved list or if you update the component after the list is saved.

By default, the Show referenced components option is not selected.

When branching a component, you must decide if you also want to branch the components that it references. You can choose from:
  • No referenced components
  • All referenced components
  • Referenced components except xref/conref
  • Referenced components except xref/conref/images

You may not see all referenced components on the Save as a branch screen.

  • Components that are referenced in the source component are only listed if:
    • You select the Show referenced components option
    • In the Branch referenced components dropdown menu you select anything other than No referenced components
    • It doesn't have a tag applied to it called ExcludeFromBranch. For more details, read Prevent branching.

Whenever you save a component by branching, Inspire ensures content that is read from Right-to-Left displays correctly in Oxygen.

For the topic's language, Inspire sets the Reading property in these cases:
  • If it doesn't exist yet
  • Only if the language Reading property is rtl (Right-to-Left)
  • For example: <concept id="concept_guid" xml:lang="ar-Ar" dir="rtl">
  • Inspire makes no changes if the language Reading property is ltr (Left-to-Right)

Quickly branch a component with many references

To quickly branch a component with a long list of references, leave the Show referenced components option unselected and click Create.
  • Clearing this option means you don't have to wait for Inspire to list all the references in the List or Hierarchy views.
  • This action branches the source component along with the references you select in the Branch referenced components dropdown menu.
For example, if you:
  1. Go to the Branch referenced components dropdown menu and select Referenced components except xref/conref/images.
  2. Clear the Show referenced components option.
  3. Click Create.
Inspire branches the source components and all the topics it references. No cross references, content references, or images are branched.

Can I choose which references are branched?

If you want to customize which references are branched, you can choose All referenced components, make sure the Show referenced components option is selected, and then in the Hierarchy or List view, select the checkbox for only the components you want to branch.

You can't clear the checkbox for the source component. If you don't want to branch the source component, click Cancel, find the source component you want to use, and then select Save as a branch again.

You may not see all referenced components on the Save as a branch screen.

  • Components that are referenced in the source component are only listed if:
    • You select the Show referenced components option
    • In the Branch referenced components dropdown menu you select anything other than No referenced components
    • It doesn't have a tag applied to it called ExcludeFromBranch. For more details, read Prevent branching.

To decide what to branch, use the following options:
  • On the Save as a branch dialog, the component you selected to branch is displayed in bold. This is considered the source component.
  • In the Branch referenced components field, if you select anything other than No referenced components, you see a hierarchical list of other components that are referenced by the source component. In the following figure above, this includes:

    • The root parent topic (Introduction)
    • Three child components
      • One binary image (EOSR5)
      • Two conceptual DITA topics (What is CMOS?, and What is DIGIC?)
    • Two child components with children of their own
      • What is CMOS (CMOS1, and CMOS2)
      • What is DIGIC? (DIGIC4)
  • By default, references are shown in a hierarchical view. You can expand and collapse parent topics in the hierarchical list to find the components you want to select.
    • To expand all parent topics, click Expand all

    • To collapse all parent topics, click Collapse all

    • To expand one parent topic, click Expand children

    • To collapse one parent topic, click Collapse children

  • If you want to see references as a list, select List View.

Can I choose where the branched copies are saved?

By default

Copies of all components (source and reference) that you select are branched and saved in the Target Folder.

For example:

  • A source component called Chapter2_Attach the strap is stored in a Target Folder called Tasks.
  • Two image files are referenced by the source component and are stored in an Images folder.

If you don't select the Keep folder structure option. (The Target Folder option remains available.)

  • Any components you select to branch—by default the copies are created in the Target Folder (Tasks).
  • This happens even if the referenced components are currently stored in a different folder.
  • You can select a different Target Folder however all branched copies are saved there.

Change the default

If you want to create a copy of the source and image components, but you want the copies to be saved in their current folders, you can select the Keep folder structure option.

In this example:

  • You select the Keep folder structure option. (The Target Folder option is greyed out and becomes unavailable.)
  • You select the source component and the three image files.
  • After you click Create, the branched copy of the source component is saved in Tasks.
  • The branched copies of the images are saved in the Images folder.

How can I track a branch?

When you're creating a branch, you can now add a Label. This allows you to add more information about why the branch was created or a version number.

  • The Label is attached to the component name.
    • For example, if you right-click a component named GetStarted, and select Save as branch... when you go to the Label field and enter "New version updates", after you click Create:
      • Component name = GetStarted_New version updates
    • The Filename uses the Component name with the Label, and then adds a GUID to make it unique. For example:
      • File name = GetStarted_New_version_updates_0b2426a1-1831-4114-8611-5b8db7edd7ab.xml
  • You can also see the Label on the Component Details screen, on the Branches tab. Select the component, and from the right-click menu select Details. Select the Branches tab.

The Name can also be known as the Label.

  • This is because the snapshot Name doesn't replace the component name, but allows you to identify why the history record was created.
    • When you create a snapshot on demand, the Name becomes the label but is always shown as Name.
    • When you branch a component, you add a title in the Label field. In the History record (of snapshots), the Label is always shown as Name.
    • Long unique numbers are also attached to custom labels, so be sure to keep your label short. For MyLabel__93746df4-558f-4414-9423-52835fa5d2cd.
  • Later, if you update a snapshot, you can edit the Name (Label) as long as the history record isn't for a Branch action.
  • You cannot update the Name (Label) for a snapshot where the Action is Branch.

    If you open the Component Details, select the History tab, and choose a record where Action is Branch you cannot select the Update option.

  • You can update the Name (Label) for all other types of snapshots.

After you create a branch, in the Components browser, the branched components have an icon corresponding to their place in the branch.

  • Black is the source component for a branch
  • Green was branched because a source component referenced it
  • Orange is both the source of one branch and included in another branch because a different source component referenced it

Can I see all the branch relationships in a report?

Yes.

To see a report on the relationships a component has with other components, if it's the source of a branch, is part of a branch, or is both, and find the location of all components in the branch, you can generate and view a branch report.

On the Selected Components pane, select the Reports menu, and then select Branch Report.

You see a separate notification for each component you select. You also get a separate report for each component you select.

On the Notifications tab, you can see the report details.

In the example report above, the component that was selected (Chapter1_Charge your battery) is a branch and has a branch relationship with a component it references (Chapter1_Charge_your_battery_IconCheck).

  • Chapter1_Charge your battery. Shown in the Components browser with a black branch. This means it is the source component for a branch.
  • Chapter1_Charge_your_battery_IconCheck. Shown in the Components browser with a green branch. This means it is part of a branch because a source component (Chapter1_Charge your battery) references it.

You can use links in the report to open the Components browser and see where the components are saved (Go to all, Go to one), or click the Name to open the component for editing or viewing (Open one).