In addition to attributes, a document may contain links to attributes belonging to other documents. The following terminology is used in ImageMaster regarding linked attributes:
-
Detail revision is the revision that contains links to attributes belonging to other revisions.
-
Master revision is the corresponding target revision that contains an attribute linked from another document.
When the user retrieves a detail revision, the linked attributes display the values of their respective target attributes in the associated master revision.
To make use of linked attributes you must first create or update a document type to be suited for detail revisions (see Example – request for creating a document type for a detail document). In this document type definition for detail revisions do the following:
-
Provide a link to an attribute (i.e. an element <linkedAttribute…>) pointing to an attribute in another document type.1
-
Within the link definition (i.e. element <link…>) define the link mode according to Modes of associating detail and master revisions.
-
If the link resolver method “Attributes” is used (see Methods of resolving a revision for available methods to resolve a revision), provide at least one normal attribute that represents the source key of the link. This attribute is characterized by a name that is also specified in the link definition as “sourceKey” (see Example – request for creating a document type for a detail document).
-
Alternatively, if the link resolver method “Query” is used, the query must guarantee that exactly one target revision is identified as master revision.
After creating the document type for detail revisions you may create a detail revision only if a corresponding master revision is already available. If the link resolver method “Attributes” is used, in the corresponding creation request (see Example – request for creating a detail document) at least the source key attribute must be provided. Note that by the value that is assigned to this attribute during revision creation exactly one target revision must be identified based on a comparison with the target key in the master revision.
In the creation process of the detail revision the link is being resolved and the detail revision is associated with the found master revision. Furthermore, each time the detail revision is retrieved, the links are being resolved according to the selected link mode (see Modes of associating detail and master revisions) and resolve method (see Methods of resolving a revision).
For each link the following requirements must be met, otherwise an error will be returned:
- There must be exactly one master revision for the link!
- The target attribute in a master document must be available at the moment of creating the link definition, i.e. when the document type for the detail revisions is created!
To delete a linked attribute, do the following:
-
Perform an update of the document type for the detail document.
-
During the update, delete the linked attribute from the attributes set associated with this document type.
A master revision, or the underlying document type of a master revision, cannot be deleted as long as there is at least one detail revision, or detail revision document type, which targets the master with a link.
Attribute link modes
The following table provides descriptions of attribute link modes.
|
Link Mode |
Description |
|---|---|
|
fixedRevision |
The association is made with a fixed master revision. A check-in of new revisions on the master document does not affect the content of the linked attributes in the detail revision. |
|
latestRevision |
The association is always made with the latest revision of the master document. This means that if a new revision is checked in on the master document, the detail revision will reflect these updates in its linked attributes. |
|
freezeOnUpdate |
The mixed mode of association, which actually freezes links in old detail revisions:
|
|
dynamic |
Dynamic links do not establish a fixed relationship between the detail and master revision. Instead, the link is resolved each time the detail revision is retrieved or searched. The linked attributes display whatever values the latest revision of the target document contains at the time the detail revision is retrieved. Due to this dynamic relationship, it is allowed to create a detail revision without a matching master revision (or with multiple master revisions) and it is allowed to delete a master revision while it is still being referenced through a dynamic link. Attributes that use a dynamic link act like multi-value attributes: They contain no values if no corresponding master revision exists and they contain multiple values if multiple master revisions exist. Only the resolver method “Attributes” can be used with dynamic links. Resolving through a query or an extension is not allowed. Dynamic links can be added or removed from a document type after the document type has been created. |
Methods to resolve linked attributes
The following table provides a description of the available methods to resolve a revision.
|
Method |
Description |
|---|---|
|
Attributes |
The target is resolved by comparing attribute values of the detail revision with possible master revisions. The sourceKey and targetKey are the attributes in the source and target document types respectively that establish the connection. Both attributes may not be optional and not multi-value attributes. |
|
Query |
The target is resolved by executing the specified query. The query must result in exactly one revision or document. The detail revision is placed in the transient params:createRevision galaxy for the evaluation. |
|
Extension |
The mechanism for resolving the link targets is implemented as a customer specific extension at the extension point ILinkResolverExt. |
SOAP requests example
The following SOAP request illustrates the creation of a document type for a detail document:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ns="http://www.tsystems.com/ima9/integrationws/messaging/201101">
<soap:Body>
<ns:createDocumentType>
<documentType name="detail" isSystemType="false">
<attributes>
<!-- Attributes that will be used for linking documents -->
<attribute name="detail.id" isKey="false" minOccurs="1"
maxOccurs="1">
<type name="decimal"/>
<description>detail.id link key</description>
<constraints/>
</attribute>
<!-- Linked attributes from the master document type -->
<linkedAttribute name="file.firstName">
<link name="detail.link" />
<targetAttribute name="master.firstName"/>
<description>?</description>
</linkedAttribute>
<linkedAttribute name="file.lastName">
<link name="detail.link" />
<targetAttribute name="master.lastName"/>
<description>?</description>
</linkedAttribute>
<linkedAttribute name="file.dates">
<link name="detail.link" />
<targetAttribute name="master.dates"/>
<description>?</description>
</linkedAttribute>
<!-- Another "true" attribute is not Linked -->
<attribute name="detail.real" isKey="false" minOccurs="0"
maxOccurs="1">
<type name="string"/>
<description>not a link</description>
<constraints/>
</attribute>
</attributes>
<links>
<!-- Definition of Links -->
<link name="detail.link" mode="latestRevision">
<targetDocumentType name="master"/>
<resolver>
<!-- If the link should be defined using a query, insert
<query> </query> here -->
<attributes sourceKey="detail.id" targetKey="master.id"/>
</resolver>
<description>?</description>
</link>
</links>
<description>?</description>
</documentType>
</ns:createDocumentType>
</soap:Body>
</soap:Envelope>
Figure 573: Example – request for creating a document type for a detail document
The following SOAP request illustrates the creation of a document type for a master document:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ns="http://www.tsystems.com/ima9/integrationws/messaging/201101">
<soap:Body>
<ns:createDocumentType>
<documentType name="master" isSystemType="false">
<attributes>
<!-- The attribute that will be used for linking documents -->
<attribute name="master.id" isKey="false" minOccurs="1"
maxOccurs="1">
<type name="decimal"/>
<description>?</description>
<constraints/>
</attribute>
<!-- Other attributes -->
<attribute name="master.firstName" isKey="false"
minOccurs="0" maxOccurs="1">
<type name="string"/>
<description>?</description>
<constraints/>
</attribute>
<attribute name="master.lastName" isKey="false"
minOccurs="1" maxOccurs="1">
<type name="string"/>
<description>?</description>
<constraints/>
</attribute>
<attribute name="master.dates" isKey="false" minOccurs="0"
maxOccurs="100">
<type name="date"/>
<description>?</description>
<constraints/>
</attribute>
</attributes>
<description>?</description>
</documentType>
</ns:createDocumentType>
</soap:Body>
</soap:Envelope>
Figure 574: Example – request for creating a document type for a master document
The following SOAP request illustrates the creation of a master document:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ns="http://www.tsystems.com/ima9/integrationws/messaging/201101">
<soap:Body>
<ns:createDocument>
<revision>
<documentType name="master"/>
<metadata>
<attribute name="master.id">0815</attribute>
<attribute name="master.firstName">Max</attribute>
<attribute name="master.lastName">Mustermann</attribute>
<attribute name="master.dates">2012-01-01</attribute>
</metadata>
<contents>
</contents>
</revision>
</ns:createDocument>
</soap:Body>
</soap:Envelope>
Figure 575: Example – request for creating a master document
The following SOAP request illustrates the creation of a detail document:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ns="http://www.tsystems.com/ima9/integrationws/messaging/201101">
<soap:Body>
<ns:createDocument>
<revision>
<documentType name="detail"/>
<metadata>
<!-- This is the key for the link. it must match a master document -->
<attribute name="detail.id">0815</attribute>
<!-- This is a non-linked attribute in the detail document type -->
<attribute name="detail.real">A value</attribute>
<!-- The linked attributes must not be provided and will be filled from the master document -->
</metadata>
<contents>
</contents>
</revision>
</ns:createDocument>
</soap:Body>
</soap:Envelope>
Figure 576: Example – request for creating a detail document