Serialization

Relations and Identities

Entities can be related to each other in various ways. 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.

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

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 . An entity may have several external IDs and you can also change those IDs if necessary.
• Unique Attributes: Some entities can be identified uniquely via its name.

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 is updated with the provided date. If no entity is found with the given ID it is 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:

• XML

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

  Example: (updates the description of a Package)

  <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.

  Example: (updates the description of a Package)

  system_custom_type,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 must be set together. To get for example, a package, you can specify either (id) or name.

Get 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.