Altium Designer Documentation

Component Synchronization with Enterprise Systems

Modified by Jason Howie on Jul 16, 2020

Parent page: Altium 365 Workspace

Component Synchronization functionality is not supported in Altium 365 Standard.

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.

The Component Synchronization capability is available with the Workspace only by having Altium Concord Pro hosted on Altium 365. In addition, the Workspace does not offer full PLM integration – this level of integration is only available through Altium NEXUS.
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® PLM system is currently supported, and a base configuration file for the Arena system is 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 (in this case, Arena PLM) 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 for 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 Arena system configuration file 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 configuration file.

The Workspace provides a downloadable sample configuration file.

Modify the dm-Arena-config-basic.xml configuration file to suit your company's enterprise system instance and requirements. This supplied configuration includes a URL reference to the Arena 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:

  1. Configuring the synchronization for each component type. This involves:
    1. Determining the direction of synchronization.
    2. Determining which components are involved, and where components are to be created.
    3. Configuring parameter mapping.
  2. Configuring the synchronization of Part Choices data mapping, if applicable.
  3. 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 PLM system. 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 a 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 inthe 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 recieved 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>.

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.

Performing Component Synchronization

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 Arena and the Explorer view of Altium Designer or the Workspace. In this example case 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.

Found an issue with this document? Highlight the area, then use Ctrl+Enter to report it.

Contact Us

Contact our corporate or local offices directly.

You are reporting an issue with the following selected text
and/or image within the active document:
ALTIUM DESIGNER FREE TRIAL
Altium Designer Free Trial
Let’s get started. First off, are you or your organization already using Altium Designer?

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

In that case, why do you need an evaluation license?

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

Got it. You actually don’t need an evaluation license for that.

Click the button below to download the latest Altium Designer installer.

Download Altium Designer Installer

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

Please fill out the form below to get a quote for a new seat of Altium Designer.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

If you are on Altium Subscription, you don’t need an evaluation license.

If you are not an active Altium Subscription member, please fill out the form below to get your free trial.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

Why are you looking to evaluate Altium Designer?

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

You came to the right place! Please fill out the form below to get your free trial started.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

Great News!

Valid students can get their very own 6-month Altium Designer Student License for FREE! Just fill out the form below to request your Student License today.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

Got it. You can download a free Altium Designer Viewer license which is valid for a 6 months.

Please fill out the form below to request one.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

That’s great! Making things is awesome. We have the perfect program for you.

Upverter is a free community-driven platform designed specifically to meet the needs of makers like you.

Click here to give it a try!

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

Got it. You can download a free Altium Designer Viewer license which is valid for a 6 months.

Please fill out the form below to request one.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.