Handler - ReferenceCopy
ReferenceCopy handler creates a Search command button next to the attribute data field for locating and retrieving data from the referred data card to the referrer data card. An attribute with the ReferenceCopy handler is different from a general reference attribute in the way that the referring attribute retrieves values for other attributes on the data card but does not need a value itself. Again, once the values are copied to the referrer data card, changes in the values do not affect the referred data card.
With metadata, you can specify attributes, whose values you want to retrieve to the parent data card. In order to succeed in retrieving the values, each attribute in both templates must have an individual attribute code that you denote in the metadata. For example, to retrieve user information from existing User data cards to Car data cards, create a reference attribute in the Car data card and attach the ReferenceCopy handler to it. Then, in the metadata of the reference attribute, specify the correlating attributes so that in the metadata Name fields, enter the source attribute codes, and in the corresponding metadata Value fields, enter the corresponding target attribute codes. Hereby, values from attributes on User data card are retrievable to the attributes on the Car data card. The following picture provides an example of metadata definition.
Metadata for an attribute with ReferenceCopy handler:
On the data card, a Search button appears next to the reference attributes field. Clicking it opens a Search window for searching and copying existing data to the data card under a creation as illustrated in the following picture.
A User attribute with ReferenceCopy:
In the data card under a creation the reference attribute User (with ReferenceCopy) that includes the ReferenceCopy handler is visible. However, in the saved data card, only the attributes with retrieved values are visible but the parent attribute is hidden as illustrated in the following picture.
A ReferenceCopy output:
To be able to save the data card with retrieved values, the data type of the target and source attributes must be identical. For example, if you want to copy a date, the data type of both, source and target attribute, must be either date or date and time. Matrix42 validates the data type when saving a created data card and fails in saving if the data types do not match.
In order to function as intended, a reference attribute must refer to one template at least.
Also, in order to retrieve values from the source attributes to the target attributes, users utilizing the template must have at least read permission to the referred template. If the parent attribute does not refer to any template OR the user does not have permission to the referred template, the parent attribute field is hidden and the handler does not work.
Normally, the existing values of the data card will be replaced by the values of source data card. Check metadata configuration information for instructions how you can make the existing values to be preserved. If the reference copy attribute (this attribute) is multi value, and you want to store the links to original data cards by using :SOURCE: configuration, use plus-sign mechanism too. Again, check metadata configuration information for instructions.
If a link to the referred data card is wanted, remember to set the meta data configuration :SOURCE: to have the attribute code of this attribute as its value. This way the referrer data card (an instance of the template holding this ReferenceCopy handler) will have a link to the data card that it is referring to.
If the parent attribute is fixed for more than one template, the templates may not have identical codes for attributes you want to copy. In this case, you can define the codes of referred templates by starting a metadata name with template_code:attribute_code . These template-related copying rules are applied first, after the common (not template related) rules appleied.
The following tables provide information on the attribute settings and metadata requirements for ReferenceCopy handler. Compulsory metadata is provided in a Required attribute metadata table including proposals for possible metadata values.
Table 1. Attribute Settings
| Handler name | Datatype |
|---|---|
ReferenceCopy |
Reference |
Table 2. Required Attribute Metadata
| Name | Value | Description |
|---|---|---|
[source_attribute_code] |
[target_attribute_code] |
In the Enter the attribute code of the referrer attribute in the You can define multiple attribute code pairs for copying multiple values. If you add plus-sign (+) in value field before an attribute code, existing values will not be overriden, but new values will be appended to existing ones. This is usefull when target attribute is multivalue or when the reference copy attribute (this attribute) is multivalue. This works also with single value string and text attribute. |
Table 3. Optional Attribute Metadata
| Name | Value | Description |
|---|---|---|
:SOURCE: |
[target_attribute_code] | Reference to original entity is stored to the attribute whose code is defined in value field. Normally, value could be the code of this attribute. |
Preserve existing |
[on | off] |
If you want to preserve possibly existing data of a referrer datacard, set this value Default is |
Table of Contents