Relations

Relations are a tool to describe links between entities. A relation specifies two entities and the nature of the links between them. A specific link is referenced with its identifier, the Alias.

Aliases are used to create cross-filters where there is more than one possible type of link between two entity types. For example, a design step can have two relations to a test. A test can contain a design step and a design step can call to a test. Therefore, this query is ambiguous:
.../design-steps?query={test.name=[e]}

An ambiguous query fails. Use aliases to create unambiguous queries. The query above might be:
.../design-steps?query={has-parts-test.name[e]}
This query unambiguously specifies that the link between the design-steps and the test is that the test contains the design-steps.

Aliases are also used in queries in sort, fields, and group-by clauses.

To use a Alias in these in cross-filters and in sort, fields and group-by clauses, the Alias:

• Must be unique.

      <TargetEntity>test</TargetEntity>
         <TargetAliases>
              <Alias Unique="false" Name="test"/>
              <Alias Unique="true" Name="used-by-test"/>
          </TargetAliases>
  

• Must represent a 1:1 relation. An Alias represents a 1:1 relation if the storage reference location is in the source entity.

         <StorageDescriptor>
              <ReferenceStorage>
                  <ReferenceIdColumn>link-test</ReferenceIdColumn>
                  <ReferenceLocation>IN_SOURCE_ENTITY</ReferenceLocation>
              </ReferenceStorage>
  

See also, relations Collection and relations/{name}.

Principle Elements of a Relation

For the description of all the elements in a relation, see Relation Schema.

Name Attribute

A relation has a name attribute. The name of a relation is descriptive and cannot be used in a query.

The name of a relation consists of <source entity> to <target entity> <relation type> [<mirrored>]. For example, <Relation Name="testFolderToTestContainment_mirrored"> is a relation between a test folder and a test. The type of relation is Containment, meaning the test folder contains the test. The relation is mirrored, meaning that this is the relation defined on test folders, seen from the test side. There is a corresponding relation, testFolderToTestContainment, that belongs to the test folder entity.

Aliases

The aliases are used in building the cross filter query.

The unique aliases refer to the entity in the context of a specific relation. An alias starts with a word that describes the relation. The second part of the alias is the entity type that is returned when this alias is used to specify a field.

In the example below, the contained-in-test alias indicates entities of type test that are in a "contained in" relation with the source entity, the test-folder. Therefore, in a query on a test-folder, you can use the contained-in-test alias to fetch information about the tests in the test folder.

	<Relation Name="testFolderToTestContainment">
		<SourceEntity>test-folder</SourceEntity>
		<TargetEntity>test</TargetEntity>
		<TargetAliases>
			<Alias Unique="true" Name="contained-in-test"/>
			<Alias Unique="true" Name="test"/>
	

Do not attempt to read an alias as a sentence. The name of the entity and the description of the relation are not necessarily in a "subject-verb" relationship with each other. The entity indicates not the subject of a sentence, but the type that is returned. You should understand the meaning of the alias from context.

SourceEntity

The source entity is the name of the entity at the start point of the relation. For example, in the relation testFolderToTestContainment_mirrored, the source entity is test.

    <Relation Name="testFolderToTestContainment_mirrored">
	    <Label>Tests in Test Folder</Label>
	    <SourceEntity>test</SourceEntity>
	    <TargetEntity>test-folder</Target>

TargetEntity

The target entity is the name of the entity at the endpoint of the relation. For example, in the relation testFolderToTestContainment_mirrored, the target entity is test-folder.

Reference Storage

The ReferenceStorage element contains information about the columns that link the source and target entities. This information reflects the logical model on which the REST API is built. It does not represent physical storage in the project database.

For information about physical storage, see the ALM Project Database Reference.