Import/Export Configuration

Since ATS Bus version 2.5, users can import and export ATS Bus configuration items. This functionality can be used to backup and restore ATS Bus configuration items and share portions of the ATS Bus configuration with other ATS Bus users. This document describes what is exported, how to import/export the ATS Bus configuration, the content of the import/export (XML file), how import/export works, how to make changes to the XML files and how to resolve common errors.

What are configuration items?

Configuration items are portions of the ATS Bus configuration that can be imported and exported:

All items from the Master Data menu in Cockpit like operations, topics, unit of measure classes etc.

Channel and channel message configuration. When importing and exporting channels and channel messages, the message definitions (for an OT bus stop) being used within the Channel and channel message(s) are automatically imported and exported.

Bus stop configuration: to import/export a complete bus stop configuration. This includes:

Channel configuration (including channel message and message definitions)

Operations and Topics

Bus and channel message actions

NServiceBus configuration

ATS Bus allows to import and export per configuration item, meaning it imports/exports only the selected channel, bus stop, operations, and topics. It is not possible to import/export multiple channels and bus stops at once.

ATS Bus stores the configuration data in a configuration database and most items are stored in aggregates, which are the items that can be imported and exported. Therefore, a configuration item equates to an aggregate in the ATS Bus configuration database.

How to import/export configuration items

Importing and exporting configuration items is a simple process with each item that can be imported/exported having an and button available.

For exporting a configuration item, just select the item and click on the Export button. The system will ask for a location to place the configuration file output.

For importing a configuration, click on the Import button, select the configuration file and click on Open.

What is exported to the XML file?

An example of a typical bus stop export is displayed below. Please note that some items have been omitted for readability:

</ChannelMessages>

</XmlChannel>

</OTBusStopChannel>

</OTBusStopChannels>

</MessageActions>

</OTBusStopBusMessageSubscription>

</BusMessageSubscriptions>

</OTBusStopOperation>

</OTBusStopOperations>

</BusMessages>

</OTBusStop>

</Bus>

The root node Bus contains the ATS Bus version number and the date the export was created. The version number helps ATS Bus when importing the configuration. The XML file is not backwards compatible meaning that ATS Bus 2.6 cannot import an XML file generated by ATS Bus 2.7, but ATS Bus 2.7 can import a file exported by ATS Bus 2.6.

The root node contains several children. These children contain the configuration for:

Operations

Channels (any channel used by the bus stop)

ChannelMessages

Channel Message

OTMessageDefinitions (for OT bus stop only)

Bus message subscriptions

Bus message actions

Bus stop specific NServiceBus configuration

Bus stop

All children of the root node are database aggregates and can be recognised by their attributes named Code and ExternalId. These attributes are very important because they must be unique within the aggregate group. The ExternalId is the primary key of the aggregate.

How are codes and external ID’s used?

The Code and ExternalId are important elements and serve 2 purposes:

They are used to determine if an aggregate can be imported or should be renamed.

They are used to ‘link’ aggregates together. In other words, they link a channel and operation to a bus stop.

The following screenshots depict how a message definition and message fields are referred to by a channel message with Code used as the primary key:

The next screenshot shows how a channel message is referred to by a bus stop. Please note the AquisitionChannelMessage and the use of the ExternalId: The final screenshot shows how an operation is referred to by a bus stop. This is done using the Code of the operation. It is not using the ExternalId for historical reasons:

How does the import work?

Assume we have an ATS Bus configuration database containing an operation where Code equals OP10 and ExternalId equals 8c7e37e7-f821-41ed-98b4-af5cbd9365ff. When importing the XML file, the data service will first try to find the ExternalId in the database and update the entry in the database with the information from the XML file if the ExternalId exists. It will create a new operation in the configuration database if the ExternalId does not exist. In both cases, when saving the operation, the data service also performs a constrain-check on the Code because the Code must be unique over all aggregates belonging to the same aggregate group. If the Code is not unique, the data service will create a new unique Code by appending a decimal value to the Code and saving the aggregate with the new Code.

In the event that both the Code and ExternalId are already present in the configuration database, the import will update the aggregate in the database.

How to make changes to the configuration

Aggregates can be copied and reused in the configuration. Important to understand is that new aggregates require a unique Code and ExternalId. The following steps must be executed when duplicating an operation. For example:

Copy an existing operation and rename the Code to OP11 and update the ExternalId with a new GUID. A new GUID can be created using the following link: https://www.guidgenerator.com/

The newly created operation can be used in the bus stop configuration as shown by the screenshots here.

It is important to understand that operations (and topics) are referred to by their code and other aggregates like channels are referred to by their external ID.

Updating channels and bus messages follow the same principles so ensure the Code and ExternalId are unique.

How to interpret the errors and warnings shown by ATS Bus Cockpit

When importing XML files, ATS Bus may show warning and error messages. These messages are shown when the data service tries to write the aggregate to the database for the first time.

The Import/Export might show the following behaviour:

A warning about duplicates is shown but the aggregate is added with a suffix. ATS Bus Cockpit showed a warning on the initial save, it updated the code and successfully saved the aggregate with a new code.

An error about duplicates is shown and the aggregate is not added because the import contains an entity that has the same code as an entity in the database but with a different external ID. The cause of this could be due to:

The imported entity having the same name but from a different database with a different external ID. For example, an import from a test database to a production database or vice versa.

The entity being exported to a file, then deleted in the database and created again resulting in the external id being different.

This issue can be solved by finding the entity in the imported file and replacing its external ID with the one found in the database.

No error is raised, and the code of an aggregate has been renamed. The import detected an aggregate with the same external ID in the database and updated the content of the aggregate in the database. This also changes all aggregates in the aggregate group meaning that a message definition in a channel messages can be updated.