Skip to content
tcli

Managing config artifacts

This guide walks the full config artifact roundtrip using preferences as the example: adding the artifact, exporting a baseline from a live environment, adding the file(s) you want to manage, registering them in the added deploy script, and deploying them back.

A config artifact is a type of Teamcenter configuration that tcli can version and deploy. Preferences, stylesheets, workflows, and so on. Each one is a directory under configuration/, an entry in your .tcli.yaml manifest, and a generated deploy.cmd (and, where available, export.cmd) script that drives the underlying Teamcenter utilities. For the whole catalog, see Config artifact types.

Prerequisites

Section titled “Prerequisites”
  • An initialized project (tcli init --tc-version <release>), so a .tcli.yaml manifest exists in the working directory. See the quick start.
  • tcli on your PATH. Every command below is run from the project root.

1. Set your environment

Section titled “1. Set your environment”

Deploy and export need three machine-specific values: TC_ROOT, TC_DATA, and UPG. Provide them via the per-machine .tcli.env.yaml file or environment variables. tcli never prompts in headless mode. See Environment resolution.

2. Add the config artifact

Section titled “2. Add the config artifact”

Preferences ship as a default artifact, so tcli init already added it. If it is missing, or when adding any other type, run:

Terminal window
tcli add ca --type preferences

preferences is the stable type slug, not the friendly display name. This:

  • creates the source directory configuration/preferences/,
  • copies the catalog’s deploy script into it as deploy.cmd,
  • copies the catalog’s export script into it as export.cmd,
  • appends the artifact to .tcli.yaml.
configuration/preferences/
└── deploy.cmd        # generated; imports nothing until you register files
└── export.cmd        # generated

Adding a type that is already in the manifest is refused, so this step is a no-op safeguard for defaults like preferences.

3. Export a baseline

Section titled “3. Export a baseline”

Before authoring your own preferences it helps to pull the current values out of a live environment as a starting point.

Terminal window
tcli export preferences --category General --scope SITE

The exported XML lands in TEMP/site_prefs.xml. Preference exports can be big, so they are never exported directly into the projects source directory.

4. Add the preference file

Section titled “4. Add the preference file”

Author (or trim the export down to) the preferences you want to manage as an XML file in the source directory, for example configuration/preferences/prefs_site_override___general.xml:

configuration/preferences/
├── deploy.cmd
├── export.cmd
└── prefs_site_override___general.xml    # the preferences you manage

Keep separate files per scope or concern if that suits you (e.g. prefs_site_override___general.xml, prefs_site_override___aw.xml). Each is registered independently in the next step.

5. Register the file in the deploy script

Section titled “5. Register the file in the deploy script”

The generated deploy.cmd script imports nothing by default. It aborts with a failure if no files are registered. Open configuration/preferences/deploy.cmd and add one call per file at the registration marker:

Terminal window
rem -- registration calls here --
call :OverrideSitePreferences "%THIS_DIR%\prefs_site_override___general.xml"
if errorlevel 1 goto :EXIT_FAILURE
  • %THIS_DIR% resolves to the script’s own directory, so paths are relative to configuration/preferences/.
  • Every call must be followed by if errorlevel 1 goto :EXIT_FAILURE so a failed import aborts the deployment.
  • Add the calls before the CMD_SIZE guard further down the script (i.e. at the marker shown above).

Available functions:

Function Arguments Effect
:OverrideSitePreferences "<xml_file>" Override at SITE scope
:MergeSitePreferences "<xml_file>" Merge at SITE scope
:OverrideGroupPreferences "<xml_file>" "<group>" Override for a group
:MergeGroupPreferences "<xml_file>" "<group>" Merge for a group
:OverrideRolePreferences "<xml_file>" "<role>" Override for a role
:MergeRolePreferences "<xml_file>" "<role>" Merge for a role
:OverrideUserPreferences "<xml_file>" "<user>" Override for a user
:MergeUserPreferences "<xml_file>" "<user>" Merge for a user

For a group/role/user scope, pass the target as the second argument:

Terminal window
call :MergeGroupPreferences "%THIS_DIR%\prefs_group_override__engineering___general.xml" "Engineering"
if errorlevel 1 goto :EXIT_FAILURE

Other config artifact types register files differently. Some auto-discover files by pattern, others expect a fixed filename. Every deploy and export script documents its usage.

6. Deploy

Section titled “6. Deploy”
Terminal window
tcli deploy preferences

This runs configuration/preferences/deploy.cmd, which sources the Teamcenter environment (tc_profilevars.bat), builds an import command file from your registered calls, and applies it with utility_execution_set. tcli mirrors the script’s exit code, so a failed import fails the command.

Next

Section titled “Next”