Parent page: Altium 365 Workspace
Note: Component Synchronization functionality is not available with the Standard or Pro Subscription Plans. It is currently only accessible to existing Pro Subscription Plan users who have actively engaged in this area previously.
Also note that the Workspace does not offer full PLM integration – this level of integration is only available through Altium NEXUS.
The Workspace facilitates the uni- or bi-directional synchronization of component data with an enterprise system. The Workspace uses an XML-based configuration file to specify the directions of synchronization, the components that will be included and the mapping of parameter data. Component data synchronization between the Workspace and the target enterprise system uses a built-in synchronization process that is manually triggered on demand.
Note that synchronization of component Part Choice data is unidirectional – from the enterprise system to the Workspace only.
When the synchronization process first adds a component's data in the target enterprise system, a system-generated item number is passed back to the component in the Workspace as a PlmPartNumber parameter. This acts as the key parameter when synchronizing data between the Workspace and the enterprise system instance. In addition, the configuration can be arranged so that item parameters/attributes on the enterprise system side will update properties in the Workspace server (configurable per field), without having to formally release a new revision of that Component Item.
The connection to an external enterprise system and its configuration is set up through the Workspace's browser interface. Synchronization to an Arena® or PTC Windchill® PLM system is currently supported, and a base configuration files for these system are available to get you started.
Connecting to Your Enterprise System
Connection to your enterprise system is performed from the Admin – Component Sync page of the Workspace's browser interface. This involves uploading a suitable XML-based configuration file and setting up the connectivity between the enterprise system and the Altium 365 hosted Workspace.
Add and configure the interface to your company's enterprise system. With a valid connection, you can instigate synchronization of components between that system and your Workspace instance as required.
To create a new interface instance, click the button, name the instance, and then upload a configuration file that applies to the enterprise system and your component data synchronization needs. While it's most likely you will need to set up only one enterprise system instance, any number of instances may be added to the Workspace as required. Each instance must be uniquely named and have a configuration file (see below).
Configuration Files
Each added enterprise system instance must have an associated configuration file, defined and uploaded for it. It is the configuration file that defines the synchronization of components between your Workspace and the enterprise system instance by specifying, for each component type, the direction of synchronization, which components are involved, where components are to be created and the parameter mapping.
Sample Configuration File
The sample PLM system configuration files can be obtained when adding a new instance by clicking the Download sample configuration link, below the Configuration file field. A Zip file – ConfigurationSamples.zip – will be downloaded to your browser's default download folder. This archive contains the basic dm-Arena-config-basic.xml and dm-Windchill-config-basic.xml configuration files.
The Workspace provides a downloadable sample configuration file.
Modify the appropriate supplied configuration file to suit your company's enterprise system instance and requirements. The XML configurations include a URL reference to the Arena or Windchill API and two representative component entity sections (Capacitors and Diodes), where each of those also includes a ToPLM and ToAltium attribute/parameter mapping sub section.
The essentials on setting up the configuration file are included in the
below sections, however more detailed information is available as comments within the sample configuration file to help guide you in what to configure, and how.
Generated Configuration File
The Workspace also provides a configuration generator option as an alternative way of creating a configuration file for the Component Sync service. Available from the Generate configuration link in the Add new instance dialog, the generator requests connection information (PLM type and URL), and then interrogates the Workspace component data model to construct a base configuration file.
Component types that are registered in the Workspace are added as entity types in the configuration with matching ToPlm and ToAltium synchronization sections and mapped attributes. Also included are TODO comments that highlight areas to add or change for compatibility with your Workspace and PLM configuration. Once created, the configuration file (dm-configuration.xml) is automatically downloaded to your browser.
Modify this file to suit the configuration requirements of your company's enterprise system, such as its component attribute naming scheme, and upload the updated version to the Workspace as outlined below.
For more information on editing the configuration file to work with your server/PLM setup, see
below and the explanatory comments included in the supplied sample configuration file.
Uploading a Configuration
Upload a suitable configuration file for the enterprise system instance currently being defined by clicking the button – a standard Windows Open dialog will appear with which to browse to, and open the required XML-format configuration file. Once uploaded, use the button to check for warnings and errors that relate to the configuration. The test process will first request sign in credentials for the enterprise system if these have not been already established via the button.
When the connection validation report is run, the Workspace analyses the current configuration settings for compatibility with both Workspace and the target enterprise system data. Configuration issues such as path errors, unmatched component type definitions and parameters, invalid Lifecycle or Revision settings are detected and reported in the Configuration Validation Report window.
Add and configure the interface to your company's enterprise system then check and correct any errors in the uploaded Configuration file.
If configuration errors are reported – resulting in an overall ERROR status (Status) – these will need to be addressed before the new instance can be created. A WARNING status, which indicates issues such as Workspace components types that are not included in the configuration, allows the configured instance to be saved and used.
When a configuration file has been edited and then re-uploaded to the new instance, use the
button again to detect any problems that may have been introduced.
Be sure to click the button once your instance is defined successfully. That instance will appear in the current listing of connected instances, back on the main Component Sync page of the interface.
Component Synchronization
Synchronization of components between the Workspace server and the connected enterprise system instance – or to be more specific, their parametric data – involves the following:
- Configuring the synchronization for each component type. This involves:
- Determining the direction of synchronization.
- Determining which components are involved, and where components are to be created.
- Configuring parameter mapping.
- Configuring the synchronization of Part Choices data mapping, if applicable.
- Performing the synchronization.
The first two item groups above are handled in the configuration file used for the connected enterprise system instance. The synchronization itself is performed on-demand from the Component Sync page of the Workspace's browser interface.
Configuring Synchronization
Within the configuration file, the connectivity with the enterprise system instance is defined between the Instance tags, which is preloaded with Driver and URL entries for the Arena or Winchill PLM system. In an Arena configuration, the section also accommodates the nomination of a particular Arena workspace that is available for an Arena user account. The optional Arena workspace ID is defined in the Context tagset.
<Instance>
<Driver>Arena</Driver>
<Url>https://api.arenasolutions.com/v1/</Url>
<Context>12345678</Context>
</Instance>
If an Arena workspace ID is not explicitly defined, component synchronization will use Arena's default workspace for that account. Also note that the system will report an error if another synchronization session is attempting to use a second workspace from the Arena user account.
In the following Schema section of the configuration file, you define a section for synchronization mapping for each dedicated part type. On the Workspace side, this is the component of type altiumType (and is the name you see in Altium Designer's Component Type dialog). On the enterprise system side, a part is defined as a plmType. This entire component section is declared as an Entity in the file, an example of which might be, for capacitors:
<Entity altiumType="Capacitors" plmType="Capacitor">
.
.
</Entity>
The plmType value may vary, depending on the particular enterprise system instance you are using.
Within the Entity tags, two sections are used to control and configure synchronization from the Workspace server to the enterprise system , and the enterprise system to the Workspace server – allowing for uni- or bi-directional synchronization. Use the following sections, in conjunction with the comments available in the sample configuration files, to learn more. Ultimately, what gets defined in the configuration file will vary depending on your specific needs, and also the (PLM) attributes that have been defined in the connected enterprise system instance.
This sub-section is used to control and configure synchronization from the Workspace to the enterprise system instance (PLM) in the form:
<ToPlm sync="true">
.
.
</ToPlm>
To disable synchronization in this direction, set sync="false".
Within the ToPlm section, the following sections are defined:
- How new components are created in the enterprise system instance – between the tagset <CreateInfo> and </CreateInfo>. One example might be choosing an item naming scheme defined in the target enterprise system, and specifying an item numbering prefix:
<CreateInfo>
<Numbering name="Electrical">
<Fields>
<Field name="Code" value="120"/>
</Fields>
</Numbering>
</CreateInfo>
- Filtering to limit which components in Workspace are synchronized with the enterprise system – between the tagset <SourceCriteria> and </SourceCriteria>.
This is essential if you have 6000 capacitors for example in your Workspace, but only want a folder of 85 ceramic capacitors to be synchronized! You might specify a particular folder be involved (e.g. with the entry: <Folder>Components/Capacitors/Ceramic</Folder>). You can optionally use other criteria to narrow the filter even more, based on parameter values – all such criteria filters should be joined by AND.
- A listing of attributes (parameters) that should be passed for the components from the Workspace to the enterprise system – between the tagset <Attributes> and </Attributes>. An example of this is:
<Attributes>
<ns2:Attribute>
<ns2:Key>Name</ns2:Key>
<ns2:Value>${parameter.name}</ns2:Value>
</ns2:Attribute>
<ns2:Attribute attributeType="item" primaryKeyOrdinal="1">
<ns2:Key>Number</ns2:Key>
<ns2:Value>${parameter.PlmPartNumber}</ns2:Value>
</ns2:Attribute>
<!-- Workspace component description will go to enterprise system field Description. Value will be prefixed with 'Extended' -->
<ns2:Attribute attributeType="revision">
<ns2:Key>Description</ns2:Key>
<ns2:Value>Extended ${parameter.Description}</ns2:Value>
</ns2:Attribute>
</Attributes>
Note that the part number that gets created on the enterprise system side (PlmPartNumber) is the primary key for linking the components on either side, and will be propagated back to the component in the Workspace.
Notice also, that there is the notion of Item parameters (attributeType="item"). These parameters, such as the PlmPartNumber parameter above, are added to the parent Component Item in the Workspace and available to its revisions. They do not cause a new revision of a Component Item to be created if their value is changed. This is in contrast with Revision parameters (attributeType="revision"). These parameters, such as the Description parameter above, cause a new revision of a Component Item to be created if their value is changed.
This section is used to control and configure synchronization from the enterprise system instance to the Workspace server in the form:
<ToAltium sync="true" mode="createAndUpdate">
.
.
</ToAltium>
The optional mode statement determines how component data is synchronized from the enterprise system to the Workspace. The default mode (updateExisting) allows only existing Workspace components to be updated, whereas the createAndUpdate mode also allows new components to be created in the Workspace.
To disable synchronization in this direction, set sync="false".
Within the ToAltium section, the following sections are defined:
- How and where new components are created in the workpace – between the tagset <CreateInfo> and </CreateInfo>.
<CreateInfo>
<!-- <ComponentTemplate>TODO component template Revision ID</ComponentTemplate> -->
<RevisionNamingScheme>1-Level Revision Scheme</RevisionNamingScheme>
<LifecycleDefinition>Component Lifecycle</LifecycleDefinition>
<Folder>Components/Inbox/Capacitors</Folder>
</CreateInfo>
The applied component template (if available) and Item naming scheme are taken from the nominated Workspace folder. In the sample configurations, a default revision naming scheme (1-Level Revision Scheme) and lifecycle definition (Component Lifecycle) are defined to be used – these are overruled if a component template is defined for the target Workspace folder.
The component target folder specified in the configuration file overrules the Default Folder setting in a Component Template. A folder path is a required entry in a configuration file.
If a specific component template reference is added (for example; <ComponentTemplate>CMPT-00001</ComponentTemplate>), its settings and defined parameters will overrule those defined for the target Workspace folder and its associated template. Note that the specified template will apply to newly created Workspace components only.
If a parameter is specified with an item attribute type in the configuration file and that parameter exists in the applied Component Template, the component parameter value will not be updated during component synchronization. For that parameter to behave in a 'dynamic' way during component synchronization (where a Value update does not cause a new revision), the parameter reference will need to be removed from the applied Component Template.
- Filtering of data retrieved from the enterprise system instance – between the tagset <SourceCriteria> and </SourceCriteria>. A filter statement might restrict the component data received from the enterprise system to those created by a specific author (as illustrated in the supplied example configuration), or to component items that have a particular attribute Value (Company = Acme Inc), as shown below).
<SourceCriteria>
<ns2:Attribute>
<ns2:Key>Company</ns2:Key>
<ns2:Value>Acme Inc</ns2:Value>
</ns2:Attribute>
</SourceCriteria>
- A listing of attributes (parameters) that should be passed for the components from the enterprise system to the Workspace server – between the tagset <Attributes> and </Attributes>. An example of this is:
<Attributes>
<!-- Name field from enterprise system will be passed to name/comment field in Workspace -->
<ns2:Attribute attributeType="revision">
<ns2:Key>name</ns2:Key>
<ns2:Value>${attribute.Name}</ns2:Value>
</ns2:Attribute>
<!-- Description field from enterprise system will be passed to Description field in Workspace on revision level -->
<!-- Revision level attributes will cause new revision to be created when parameter value has changed -->
<ns2:Attribute attributeType="revision">
<ns2:Key>Description</ns2:Key>
<ns2:Value>${attribute.Description}</ns2:Value>
</ns2:Attribute>
<!-- Number field from enterprise system will be passed to PlmPartNumber field in Workspace on item level -->
<!-- Item level parameters will not cause revision update when changed -->
<ns2:Attribute attributeType="item" primaryKeyOrdinal="1">
<ns2:Key>PlmPartNumber</ns2:Key>
<ns2:Value>${attribute.Number}</ns2:Value>
</ns2:Attribute>
</Attributes>
Notice that the part number on the enterprise system side (PlmPartNumber) is the primary key for linking the components on either side, and is propagated back to the workspace component.
Notice also, that there is the notion of Item parameters (attributeType="item"). These parameters, such as the PlmPartNumber parameter above, are added to the parent Component Item in the Workspace server, and available to its revisions. They do not cause a new revision of a Component Item to be created if their value is changed. This is in contrast with Revision parameters (attributeType="revision"). These parameters, such as the Description parameter above, cause a new revision of a Component Item to be created if their value is changed.
The section for defining Part Choices data mapping is found at the end of the sample (or a generated) configuration file. Note also that synchronization of Part Choice data is unidirectional – from the enterprise system to the Workspace only.
Along with Entity declarations within the configuration Schema is an additional section for defining component Part Choice data mapping from the enterprise system to the Workspace. This is a global definition that specifies the component manufacturer and part number attributes used in the enterprise system.
When Part Choices synchronization is enabled in the configuration file (sync="true"), the Value of the specified attributes are transferred from the enterprise system component item to the created/updated Workspace component. As a global definition for all defined component entities, the Part Choice data will be propagated to a Workspace component whenever it is encountered in the enterprise system component dataset.
An example entry for the Part Choices mapping in a configuration file – where the enterprise system attributes are MFR1 (Manufacturer Name) and MPN1 (Manufacturer Part Number) – might be:
<PartChoices>
<ToAltium sync="true">
<MfrMapping>
<MfrName>MFR1</MfrName>
<MfrPartNumber>MPN1</MfrPartNumber>
</MfrMapping>
</PartChoices>
Part Choice data synchronization supports multiple part choice data entries found in the enterprise system component item. These additional attributes need to be specified in the configuration file mapping as another pair of attribute definitions, for example: <MfrName>MFR2</MfrName> and <MfrPartNumber>MPN2</MfrPartNumber>.
The above mapping syntax applies to Part Choice data stored as item attributes (MFR1 and MPN1), however if you are using Arena's native Part Choice system – established in Arena as Relationships under the Sourcing tab – the following syntax structure can be used:
<PartChoices>
<ToAltium sync="true">
</PartChoices>
When Part Choice data is imported into a Workspace component item it will not duplicate or replace an existing Part Choice that has been manually entered, and will otherwise be added as a new, additional Part Choice for that component – which will be updated by subsequent synchronization runs.
The PTC Winchill PLM system provides an optional PartsLink module that allows parts to be classified in groups. Part Classifications specified in Windchill also can include associated Attribute/Value pairs to provide further definition within that Classification. The PartsLink system allows specific component types to be targeted easily and quickly, and is supported by the Altium 365 Workspace Component Synchronization system.
In a Workspace configuration instance for Windchill, a PartsLink Classification is created in Windchill by specifying a binding attribute in the ToPLM section in the format as shown in the below example:
<common:Attribute>
<common:Key>Classification</common:Key>
<common:Value>102-Capacitor</common:Value>
</common:Attribute>
In the above case, the Key/Value pair defines a Classification named 102-Capacitor. This may have an associated classification Attribute created in Windchill by specifying a name and value parameter (here, Capacitance) – note that multiple Attributes can be applied to a single Classification:
<common:Attribute>
<common:ClassificationName>102-Capacitor</common:ClassificationName>
<common:Key>Capacitance</common:Key>
<common:Value>${parameter.Value}</common:Value>
</common:Attribute>
In the configuration's ToAltium synchronization section, the data sourced from Windchill can be filtered for a desired part Classification within the <SourceCritera> tagset by specifying its ClassificationName.
<SourceCriteria>
<common:ClassificationName>102-Capacitor</common:ClassificationName>
</SourceCriteria>
To source all parts that comply with a matching Classification Attribute value (say, all 10uF Capacitors), the <SourceCriteria> section should include configuration attribute settings that define a ClassificationName and its associated classification Attribute key and Value.
<SourceCriteria>
<common:Attribute>
<common:ClassificationName>102-Capacitor</common:ClassificationName>
<common:Key>Capacitance</common:Key>
<common:Value>10uF</common:Value>
</common:Attribute>
</SourceCriteria>
To extract a specific Classification Attribute value from Windchill, source the Value parameter from the specific Attribute name associated with a ClassificationName.
<common:Attribute attributeType="revision">
<common:ClassificationName>102-Capacitor</common:ClassificationName>
<common:Key>Value</common:Key>
<common:Value>${attribute.Capacitance}</common:Value>
</common:Attribute>
Within Windchill itself, a PartsLink Classification is defined by creating a binding attribute that can be applied to a part type. A part Classification Attribute is then added to a defined Classification class.
Component entries in Windchill will incorporate their defined Classification and any specified Classification Attribute parameters, which are in turn are available to the Workspace component sync process.
When a component entry is synchronized from Windchill to the Workspace and PartsLink interaction has been specified in the server's PML configuration, Windchill's Configuration Attributes for that part will propagate to Altium Designer.
- The Parameters, Attributes and Values included in a configuration file are case-sensitive.
- Other than the common inclusion of a primary sync key (such as
PlmPartNumber), it is not recommended to include the same component attribute/parameters in both the ToAltium and ToPlm sections of a configuration file. Bi-directional synchronization occurs in that order (from PLM to Altium first), so the PLM data will always dominate in this situation.
- Note that synchronization of Part Choice data is unidirectional – from the enterprise system to the Workspace only.
Synchronization itself is performed from the Component Sync page of the Workspace's browser interface. Click the control associated with the synchronization instance. The synchronization process will proceed in accordance with the settings defined in the associated configuration file.
Synchronization will involve only those components that have been modified since the last synchronization was run (i.e. their timestamp is later than the last synchronization date), and which pass the synchronization criteria in the configuration file. This is referred to as Incremental Synchronization.
Component synchronization in progress between a Workspace and the indicated enterprise system instance.
The control changes to . If you want to stop the synchronization process, click this control. A confirmation window will appear, where you can click to cancel the synchronization – all components already synchronized will remain so, but no further synchronization beyond that point will occur.
Refresh the browser (F5) to check when the synchronization process is complete. To see further details on the completed process, or to confirm its success or otherwise, select the Synchronization status tab and choose the Closed listing option – if a process is still running it will show in the Active listing. Details of the selected synchronization event are shown in the lower pane, which also includes a link to a system-generated notification log file (PLM <Date Time>.log) for the event. Click this link to download the detailed log file to the browser's default download folder.
Example result of a successful bi-directional synchronization of 6 components.
You can also export synchronization status results to CSV file, by clicking the
button. The file will contain only those results currently presented on the
Synchronization status tab, and will include the details from the lower pane as well.
The tangible results of a synchronization process can be observed in both the PLM system and the Explorer view in Altium Designer or the Workspace. In the example included here, six LED components have been synchronized between Arena and the Workspace, linked by the Arena ITEM NUMBER attribute and the Altium PlmPartNumber parameter as index keys.