Skip to main content

Manual post-installation steps for the Windchill add-on

This article outlines the steps to follow when manual or custom installation is selected during the Windchill add-on installation process.

Note: The procedure described below is also documented in the help.txt file located at <WT_HOME>/codebase/com/colabsoftware

⚙️ Prerequisite: You must have a solid understanding of the PTC Windchill structure and configuration, as well as the fundamentals of Windchill customization, before performing the manual configuration steps.

⚠️ Important: Windchill must be stopped before performing the manual configuration steps.

Register the services

Run the following command to register the CoLab data utility and action filter:

xconfmanager -i codebase/com/colabsoftware/ui/service.properties.xconf -p

To register the CoLab MVC builders, edit the file <WT_HOME>/codebase/config/mvc/custom.xml and add the following:

<bean class="com.colabsoftware.ui.PartInfoBuilder"/>
<bean class="com.colabsoftware.ui.DefaultMiniInfoComponentBuilder"/>
<bean class="com.colabsoftware.ui.CadDocInfoBuilder"/>
<bean class="com.colabsoftware.ui.DocumentManagementInfoBuilder"/>

Register the CoLab actions

Run the following command to register the CoLab actions:

xconfmanager --add com.ptc.netmarkets.util.misc.defaultActions=config/actions/CoLab-actions.xml

xconfmanager --add com.ptc.netmarkets.util.misc.defaultActionmodels=config/actions/CoLab-actionModels.xml -p

Add the CoLab actions to business objects.

The business object types supported by CoLab are WTPart, WTDocument, and EPMDocument.
​

Follow the steps below to locate, copy, and update the menu definition to include the CoLab actions for each supported type.

  1. Locate the menu.

    1. Use the Action Model Report in Windchill to identify where the target menu (model) is defined — especially helpful if customizations exist.

    2. If the menu has not been customized, refer to the default files in <WT_HOME>/codebase/config/actions:

      • EPMDocument:

        • File UwgmCadx-actionmodels.xml

        • Model epmdocuments details page actions

      • WTDocument:

        • File DocumentManagement-actionmodels.xml

        • Model docs row actions toolbar

      • WTPart:

        • File PartClient-actionmodels.xml

        • Model more parts actions

  2. Copy the menu (if needed).

    • Open the file found in step 1.

    • Locate the desired <model> section.

    • Copy that <model> block.

    • Paste it into the following file: <WT_HOME>/codebase/config/actions/custom-actionModels.xml

  3. Add the CoLab Actions.

    • Inside the pasted <model>, add:

      <submodel name="openCoLabMenuModel"/>
      <action name="shareForReview" type="object" />


      💡Tip: Add separator(s) to visually distinguish the CoLab action from other menu items.

      <action name="separator" type="separator"/>

  4. Save and Validate

    • Save the file and confirm the XML is valid.

Add the multiple objects 'Share with CoLab' action

Adding the multi-object Share with CoLab action follows the exact same pattern across virtually all Windchill tables: identify the table's target action model, copy it to your custom override file, and insert the action tag.

UI Location / Table

Target Action Model Name

Base Configuration File

Folder View

folderbrowser_toolbar_actions

FolderManagement-actionModels.xml

Change Notice (Change Summary)

changeNotice.changeSummaryTableActions

ChangeManagement-actionModels.xml

Change Task (Resulting Objects)

changeTask.resultingItems.table.view

ChangeManagement-actionModels.xml

Promotion Request (Promotion Objects)

promotionRequest promotionItems table

PromotionRequest-actionModels.xml

Search Results

search_table_actions_toolbar

search-actionmodels.xml

Implementation Pattern

  1. Locate: Find the corresponding <model name="..."> in <WT_HOME>/codebase/config/actions/<BaseFile>.xml.

  2. Override: Copy the target <model> block into <WT_HOME>/codebase/config/actions/custom-actionModels.xml.

  3. Inject Action Tag: Add the following line inside the <model> block:

<action name="shareForReview" type="object" />

Add the CoLab login/logout to the 'Quick Links' menu

Follow the same procedure as in Add the CoLab Actions to Business Objects to locate, copy, and update the menu definition.

  1. Locate the Quick Links menu.

    • The Quick Links menu is defined by the model named header actions.

    • If the menu is not customized, it is located in:<WT_HOME>/codebase/config/actions/navigation-actionModels.xml

  2. Copy the menu (if needed).

    • Open the file found in step 1.

    • Locate the desired <model> section.

    • Copy that <model> block.

    • Paste it into the following file: <WT_HOME>/codebase/config/actions/custom-actionModels.xm

  3. Inside the <model> section, add the following line to include the CoLab login option:

    <action name="logIntoCoLab" type="object"/>

Add CoLab actions to profile visibility settings

To configure the visibility of the CoLab actions based on profile ownership, the file <WT_HOME>/codebase/roleaccessprefs.xml must to be customized.

💡Tip: Use the wtSafeArea

As per PTC’s supported customization practices, it is recommended to perform this customization within the wtSafeArea folder.

This approach ensures that your changes are preserved during Windchill upgrades and remain compliant with supported configuration guidelines.
The steps described below do not include the wtSafeArea portion.

For more information about the wtSafeArea folder, refer to Best Practices for Customizing Files Supplied by PTC.

In the file <WT_HOME>/codebase/roleaccessprefs.xml,

  • locate the sections project, program, library, product. For each section where you want to manage the visibility of the Share to CoLab and Open in CoLab actions, add the following lines:

    <uic name="shareForReview" defaultAll="true" />
    <uic name="openCoLabMenuModel" defaultAll="true"/>

  • locate the global section and add:

    <uic name="logIntoCoLab" enabled="true" defaultAll="true"/>

Note: In the snippets above, defaultAll="true" means these actions are visible by default.
To make them hidden by default, set defaultAll="false".

Restart Windchill and verify that the CoLab actions appear in the Set Action Visibility section of profiles.

Optional: Set the action display names

The internal names of the actions appear in Windchill by default. If you prefer the names to match what end users see (as shown in the first screenshot), follow the steps below:

  1. If the file <WT_HOME>/wtCustom/wt/util/resource/resourceCustomize.rbInfo doesn't exist, copy it from <WT_HOME>/src/wt/util/resource.

  2. In the file <WT_HOME>/wtCustom/wt/util/resource/resourceCustomize.rbInfo add the following lines:

    com.ptc.netmarkets.roleAccess.roleAccessResource/shareForReview.value=Share to CoLab
    com.ptc.netmarkets.roleAccess.roleAccessResource/openCoLabMenuModel.value=Open in CoLab
    com.ptc.netmarkets.roleAccess.roleAccessResource/logIntoCoLab.value=Log into CoLab

  3. In a Windchill Shell, run the command

    ant -f bin/tools.xml bundle_custom

Additional configuration

Proxy Consideration

If your server needs to use a proxy to reach CoLab URLs, you must configure both the OS-level environment variable and the Windchill Method Server arguments:

  1. Set the OS-level environment variable:

    Set https_proxy on the host server running Windchill (despite Windchill running on Java):

    export https_proxy=http://<proxy-host>:<proxy-port>

    ℹ️Important: The HTTPS_PROXY environment variable must be accessible to the process owner running Windchill.

    How you persist this variable depends on your startup method:

    • Systemd / Service Startup (systemctl start windchill): Services do not inherit environment variables set in interactive shell sessions. You must explicitly add the variable to your service definition file (e.g., /etc/systemd/system/windchill.service) under the [Service] block:

      Environment="HTTPS_PROXY=http://<proxy-host>:<proxy-port>"

    • Script / Shell Startup (windchill start): Add export HTTPS_PROXY=http://<proxy-host>:<proxy-port> to the Windchill user's profile (~/.bashrc / ~/.bash_profile) or the custom startup script.

  2. Configure Windchill Method Server Java arguments:

    Add standard Java proxy system properties (-Dhttps.proxyHost and -Dhttps.proxyPort) to wt.properties using xconfmanager:

    xconfmanager -t codebase/wt.properties -s wt.manager.cmd.MethodServer.java.extra.args="-Dhttps.proxyHost=<PROXY_HOST> -Dhttps.proxyPort=<PROXY_PORT>" -p

Cluster Environment (Multi-Node)

In a clustered Windchill deployment, every node must share the exact same JWT secret key so authentication tokens can be verified across all instances.

Execute this command on every node in the cluster, keeping the secret identical across all runs:

xconfmanager -t codebase/wt.properties -s com.colabsoftware.jwt.base.secret=<SAME_STRONG_RANDOM_VALUE_ON_ALL_NODES> -p
Did this answer your question?