TIA Portal VCI vs Global Library: Version Control Selection Guide

Overview

Selecting between the TIA Portal Version Control Interface (VCI) and the Global Library is a recurring architectural decision for engineering teams that maintain reusable code across multiple PLC projects. Both mechanisms are designed to centralize, version, and distribute automation objects, but they target different layers of the engineering workflow and they are not mutually exclusive.

The Global Library is the long-standing mechanism for distributing typed function blocks, UDTs, faceplates, and HMI style objects across projects with central update capability. The Version Control Interface, introduced and extended across recent TIA Portal releases, exposes a document-based export/import of program objects to external version control systems such as GIT, SVN, or Perforce. Each has constraints: a typed FB placed in a global library cannot be exported through the VCI, and a plain program block without a library type can be put under GIT but cannot be centrally updated through the library update mechanism.

This reference clarifies the responsibilities of each tool, documents the practical limits observed in production engineering workflows, and provides a selection matrix for teams that must run multi-user engineering on multiple SIMATIC projects.

Global Library Fundamentals

The Global Library is a file-based repository (default extension .zal) that lives either on a local file system, a network share, or a cloud-backed UNC path. It stores master copies of reusable TIA Portal objects and is referenced by every project that needs access to those objects.

Library modes

TIA Portal supports three handling modes for library objects:

• Without type – the object is a static copy. Changes in the library propagate to projects only when the engineer re-drags the object. No instance/master relationship exists.
• With type – the library contains a master type. Every instance in every consumer project is linked to that type. A library update on the project side overwrites all instances consistently. This is the mode used for centrally maintained FBs, FCs, UDTs, faceplates, and style objects.
• With type and versioning – the master is duplicated at the project side as a versioned instance. Updates are pushed explicitly to selected versions, supporting parallel maintenance of multiple product variants.

What the Global Library can manage

The library scope is broader than just program code. A single global library can hold:

• Program blocks (FB, FC, OB, DB) including typed instances
• User-defined data types (UDT / PLC data types)
• HMI faceplates, style objects, and language resources
• Watch tables, force tables, and trace configurations
• Hardware catalog components and module parameter records (from V18 onwards, with limitations)
• Technology objects (TO) parameter sets for SIMATIC drives and motion

Versioning model

The library has its own internal versioning. Each type instance tracks the version of the master from which it was last updated. Project engineers can inspect the version timestamp, compare instance-to-master, and apply selective updates block-by-block. There is no native concept of branches or distributed commits: updates are linear and centralized.

For the official library handling reference, see the Siemens Industry Online Support entry on Library handling in TIA Portal.

Version Control Interface (VCI) Fundamentals

The VCI exposes a TIA Portal project tree to an external, file-based version control system. It does not replace the project file model; it serializes selected objects into a neutral, text-friendly format that a VCS can diff, branch, and merge. The official basics are documented in the TIA Portal Version Control Interface basics page.

What VCI can export

The interface supports document-based export and import of program-level objects:

• Function blocks (FB), functions (FC), organization blocks (OB)
• Global and instance data blocks (DB)
• PLC data types (UDT)
• PLC tags and tag tables
• Watch and force tables

What VCI cannot export

The interface has hard limits that must be respected before designing a workflow around it:

• Type instances from a global library cannot be exported. TIA Portal returns the error: "The object 'block name' cannot be exported for the following reason: The block is a type instance. Export is not possible." The block must first be detached from its master type.
• HMI faceplates, style objects, and most HMI graphics are not part of the VCI export surface in TIA Portal V17–V20.
• Hardware configuration objects, GSD-based device descriptions, and topology data are not exported via VCI.
• Technology object parameter sets are partially supported in V20+ but not in earlier versions.

Workflow

1. Engineer marks one or more PLC program folders in the project tree.
2. Right-click → Version Control Interface → Export. TIA Portal serializes the selection into an XML-based document set under a configured working folder.
3. The engineer commits the document set to GIT (or SVN/Perforce) using standard VCS tooling.
4. On a second workstation, the engineer imports the document set with Version Control Interface → Import, which reconstructs the original TIA Portal objects.

Why pair VCI with GIT

GIT provides the capabilities that the library alone lacks: branching for parallel development, pull-request review, distributed copies for offline work, audit trail of every change, and CI hooks for static analysis or automated regression tests. VCI supplies the file format that makes a TIA Portal program diffable in GIT.

TIA Multiuser Server

The Multiuser Server is a separate collaboration tier from both VCI and the global library. It allows multiple engineers to open the same TIA Portal project concurrently, with a check-out / check-in model on individual objects. The Multiuser Server:

• Operates on a TIA Portal project file (.ap20 for V20) hosted on a server-side repository.
• Requires the project to be committed to a Multiuser Server session; offline copies are not the default mode.
• Conflicts are resolved at check-in time per object.
• Coexists with both Global Library and VCI. A multi-user project can reference a shared global library and the engineers can still run VCI export/import on locally checked-out copies of the program.

The Multiuser Server is not a substitute for VCI; it does not produce a diffable file stream. It is a complement.

Feature Comparison

Type FB Constraint and Workarounds

The single largest practical obstacle to a pure VCI workflow is that a typed FB pulled from a global library cannot be exported through the VCI. Attempting the operation raises:

The object "MyMotorFB" cannot be exported for the following reason:
The block is a type instance. Export is not possible.

This is by design: the type-instance relationship is a TIA Portal construct that has no equivalent in the document-based VCI export, and detaching it silently would break the central-update model that the library is meant to provide.

Workarounds for the type-FB limit

1. Detach at export time. In the library, copy the master into the project, right-click the instance → Library → Detach from type, then run VCI export. Re-attaching on the import side is a manual operation and must be scripted if done at scale.
2. Keep two copies of the FB. Maintain a typed master in the global library for the runtime instances and an untyped reference copy in a non-library subfolder for VCI / GIT review. This doubles the maintenance footprint but is the cleanest separation.
3. Use the VCI on the library's own project. VCI can be applied to the project that hosts the library masters. This gives version control over the master itself without touching the type-instance relationship in consumer projects.
4. Switch the library object to "without type" mode. Sacrifices central update for the block but allows VCI export. Acceptable when the block rarely changes and the team prefers GIT over library management for that specific object.

Integration Patterns: Using VCI and the Global Library Together

The two mechanisms are designed to operate at different layers and can be combined without conflict. Three patterns are observed in production:

Pattern A – Global library for distribution, VCI for change review

Maintain the canonical master in the global library as a typed object. Run VCI against a sandbox project that contains a copy of the master (or the library's own project). Use GIT to review proposed changes before they are promoted back into the library master. VCI never touches production consumer projects; it is a code-review surface.

Pattern B – VCI for project history, library for shared modules

Run the daily engineering workflow in a TIA Multiuser Server project. Run VCI export on a scheduled basis to a GIT repository, producing a permanent, auditable history of the project that the Multiuser Server's own backup model does not provide. Use the global library only for objects that are shared across multiple projects (cross-product platform code).

Pattern C – Per-engineer VCI branches, library for released versions

Each engineer has a personal GIT branch containing VCI exports of their in-progress work. When an engineer is ready to release, the engineer imports from the branch into a shared staging project, tests, and only then pushes the change into the global library master. The library remains the single source of truth for what is released; GIT is the source of truth for what is in flight.

None of these patterns attempt to export a type instance through VCI. That is the one combination that the toolchain does not support.

Selection Criteria and Decision Matrix

Use the following matrix to pick the dominant mechanism for a given team. The labels refer to the primary tool; supporting tools are listed in the last column.

Workflow Best Practices

1. Decide the source of truth up front. One and only one mechanism should be the canonical store for each object. Mixing master ownership is the most common source of "stale instance" bugs.
2. Lock the TIA Portal version across the team. VCI export format has changed across major versions. A V17 export cannot always be imported cleanly into a V20 project, and vice versa. Centralize the TIA Portal install via IT, not per-engineer preference.
3. Use the .gitignore discipline for the project file. The TIA Portal project file (.ap20) and its support files (IM caches, S7TMP folders) should never be committed to GIT. Commit only VCI export folders.
4. Tag every release in GIT. A release should correspond to a VCI export snapshot, and that snapshot should be GIT-tagged. This makes it possible to reproduce the exact project state that was commissioned.
5. Document the library version in the project header. Every project should carry, in a UDT or DB, the version string of the global library master it was last updated from. This makes field diagnostics straightforward.
6. Treat faceplates as a separate stream. Faceplates are not in the VCI export surface in V17–V20. Maintain them in the global library exclusively, and accept that they will not appear in the GIT history of the program.
7. Run VCI exports from a clean build state. If the project has unresolved warnings or an inconsistent compilation state, the export will reflect that state. Run a full compile before export.

Limitations and Edge Cases

Library-side edge cases

• Updating a typed instance can be blocked if the master has signature changes that the instance cannot absorb. The project engineer must re-link manually, and the update is no longer transparent.
• Library files on cloud sync folders (OneDrive, Dropbox) can be corrupted by file-locking conflicts. Use a Windows file share or a Siemens-approved cloud storage target.
• Two engineers cannot open the same library master for write access simultaneously. The library is not a true multi-writer repository.

VCI-side edge cases

• Cross-version import/export is not guaranteed. Always export from and import to the same TIA Portal major version, or test the round-trip before relying on it.
• Symbolic names with extended characters may round-trip incorrectly if the GIT repository is configured for a different default encoding. Force UTF-8 on the GIT side.
• VCI export of large projects produces thousands of XML files. A "small" 50-block program can produce 200+ files including references. Build a sensible folder structure in the VCI working directory before committing to GIT.
• Imported blocks are created with new internal IDs. If the receiving project already has a block of the same name with different contents, the import may collide. Pre-namespace your VCI exports to avoid collision.

Multiuser-side edge cases

• The Multiuser Server's project file is not a stable target for external backup tools mid-session. Schedule server-side backups at times when no check-in is in progress.
• Local caches on each engineering workstation can drift from the server state if a check-in is interrupted. TIA Portal offers a "repair session" workflow; do not bypass it.

Verification Checklist

After implementing either tool, run the following checks before declaring the configuration ready for the team:

1. Create a test library master with a typed FB. Insert two instances in two different projects. Modify the master. Update both projects. Confirm that both instances reflect the change.
2. Export a test PLC program through VCI. Commit to a local GIT repo. Delete the program from the project. Re-import from the GIT checkout. Confirm a byte-for-byte identical block interface and code section.
3. Attempt to VCI-export a typed FB instance and confirm the expected "type instance, export is not possible" message. This proves the workflow does not accidentally rely on an unsupported path.
4. Run a Multiuser Server session with two engineers editing different blocks simultaneously. Verify that the per-object check-out prevents overwrites.
5. Tag a release in GIT, then re-import that tag into a fresh project on a clean workstation. Confirm the project compiles and downloads to a PLC.

Frequently Asked Questions