Serialization

Relations and Identities

Entities can be related to each other in various ways. E.g. a package can be related to a release, a release can be related to several application, etc. The import/export API provides a simple and consistent system to identify and change related entities.

1 : N relations

If two entities are related to each other via a 1:N relationship you can change the relationship only via the child entity. E.g. a package belongs to exactly one release but several package can reference the same release. The relationship between package and release can be changed only via the package.

To change an entity reference, you specify an ID property of the new entity via the path notation (PROPERTYNAME< dot> ID_PROPERTY).

E.g. A package has a "system_release" property that specifies the relation to the release to which the package belongs to. On your custom release types, you specified an IDENTITY property named "release_id" which uniquely identifies your releases. To change the the release assignment of a package you have to include a property (or column in CSV) "system_release.release_id" which lets you set the association to the release, via the release_id property of an existing release.

Object Identity

Each entity can be uniquely identified in three different ways:

Internal ID: This is a system wide unique identifier for most entities that gets created automatically for new entities. It cannot be changed. If you export system_id, it will automatically be marked as identity property.
External ID: For all custom types, you can define any number of IDENTITY properties which uniquely identify an entity within its Main Type (-- it is unique for all packages but a release may have the same external ID). An entity may have several external IDs and you can also change those IDs if required.
Unique Attributes: Some entities can be identified uniquely via its name. E.g. the name of a Release is unique.

When you import an entity you have to specify which property you want to use to identify the entity. If an entity with the given ID is found, it will be updated with the provided date. If no entity is found with the given ID it will be inserted.

Note: When importing entities with a system_id property, you do not have to explicitly mark it as identity property.

How to specify the identity property depends on the format:

Format	Description	Example which updates the description of a PackageEin Package ist eine Instanz (eine Version, eine Revision, ein Tag, ...) Ihrer Applikation und definiert den Content, den Sie deployen möchten. Hier entscheiden Sie, ob Sie die gesamte Applikation oder nur einige spezifische Komponenten deployen möchten.
XML	You have to set the isIdentity on the property that should be used to identify the entity.	<Entity main-type="PACKAGE" custom-type="Feature"> <Property name="redmine_feature_id" isIdentity="true"> <Value>57</Value> </Property> <Property name="system_description"> <Value>A new description.</Value> </Property> </Entity>
CSV	The column that contains the identity properties is named system_identity_properties and behaves like a multi choice field.	system_customtype,redmine_feature_id,system_description, system_identity_properties Feature,57,"The description",redmine_feature_id

Format

Description

Example which updates the description of a PackageEin Package ist eine Instanz (eine Version, eine Revision, ein Tag, ...) Ihrer Applikation und definiert den Content, den Sie deployen möchten. Hier entscheiden Sie, ob Sie die gesamte Applikation oder nur einige spezifische Komponenten deployen möchten.

XML

You have to set the isIdentity on the property that should be used to identify the entity.

<Entity main-type="PACKAGE" custom-type="Feature">
	<Property name="redmine_feature_id" isIdentity="true">
		<Value>57</Value>
	</Property>
	<Property name="system_description">
		<Value>A new description.</Value>
	</Property>	
</Entity>

CSV

The column that contains the identity properties is named system_identity_properties and behaves like a multi choice field.

system_customtype,redmine_feature_id,system_description, system_identity_properties

Feature,57,"The description",redmine_feature_id

If more than one property is specified, the first applicable identity property is used.

Note: All Identity values belonging to the same group will be need to set together. To get e.g. a package, you can specify either (id) or name.

Get Deployment Package by id, update name

<Entity mainType="Package">
  <Property name=”system_id” isIdentity=”true”>
    <Value>123</Value>
  </Property>
  <Property name=”system_name”>
    <Value>new name</Value>
  </Property>
</Entity>

N to M relations

N to M relations are described via their own main types. These simple main types have two system properties which point to the related entities. You specify a related entity via the dot notation as with 1:n relations.