Containments and associations are relationships between pages in Microsoft Dynamics NAV. OData web services in Microsoft Dynamics NAV 2013 R2 support navigation between pages using containments and associations.

Identifying Containments and Associations in Metadata

OData metadata shows containments and associations with the NavigationProperty tag. For example, if you published page 42, Sales Order, and page 22, Customer List, and then obtained the service metadata document for the server instance, you would see this tag in the metadata:

 Copy Code
<NavigationProperty Name="SalesOrderSalesLines" ToRole="SalesOrderSalesLines" FromRole="SalesOrder" Relationship="NAV.SalesOrder_SalesOrderSalesLines"/>

This tag is followed by metadata that specific to the SalesOrderSalesLines subpage. This page metadata indicates that this NavigationProperty tag is a containment:

 Copy Code
<EntityType Name="SalesOrderSalesLines">
<Key>
     <PropertyRef Name="Document_No"/>
     <PropertyRef Name="Document_Type"/>
     <PropertyRef Name="Line_No"/>
</Key>
     <Property Name="Document_Type" Nullable="false" Type="Edm.String"/>
     <Property Name="Document_No" Nullable="false" Type="Edm.String"/>
     .......many additional properties........
     <Property Name="ShortcutDimCode_x005B_7_x005D_" Nullable="true" Type="Edm.String"/>
     <Property Name="ShortcutDimCode_x005B_8_x005D_" Nullable="true" Type="Edm.String"/>
</EntityType>

Elsewhere in the metadata, you would see additional NavigationProperty lines and a series of Association tags. Two of these tags have a Multiplicity parameter with a value of 0..1:

 Copy Code
<Association Name="SalesOrder_Sell_to_Customer_No_Link">
     <End Type="NAV.SalesOrder" Multiplicity="*" Role="SalesOrder"/>
     <End Type="NAV.CustomerList" Multiplicity="0..1" Role="Sell_to_Customer_No_Link"/>
</Association>
<Association Name="SalesOrder_Bill_to_Customer_No_Link">
     <End Type="NAV.SalesOrder" Multiplicity="*" Role="SalesOrder"/>
     <End Type="NAV.CustomerList" Multiplicity="0..1" Role="Bill_to_Customer_No_Link"/>
</Association>

These tags describe two associations from the Sales Order page to the Customer List page:

  • The Sell-to Customer No. field.
  • The Bill-to Customer No. field.

Using Containments

When you publish a page that has a subpage, you can identify that subpage in the AtomPub document that is returned for the published page. For example, when you publish page 42, Sales Order, you can access a single record on the page using a URI such as the following:

 Copy Code
http://localhost:7048/DynamicsNAV71/OData/Company('CRONUS%20International%20Ltd.')/SalesOrder(Document_Type='Order',No='101005')/

The following line in the returned AtomPub document for the record provides link information for a containment:

 Copy Code
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/SalesOrderSalesLines" 
             type="application/atom+xml;type=feed" title="SalesOrderSalesLines" 
             href="SalesOrder(Document_Type='Order',No='101005')/SalesOrderSalesLines" />

Notice the type=feed in the line above. To access the subpage data feed, use a URI that incorporates the link that was identified in the previous document:

 Copy Code
http://localhost:7048/DynamicsNAV71/OData/Company('CRONUS%20International%20Ltd.')/SalesOrder(Document_Type='Order',No='101005')/SalesOrderSalesLines

Using Associations

Associations are possible when two published pages are linked. Here is an example:

  • Page 42, Sales Order, has its SourceTable property set to table 36, Sales Header. The source expression for the Sell_to_Customer_No control on page 42 is field 2, Sell-to Customer No., in table 36.
  • Field 2, Sell-to Customer No., in table 36 has a TableRelation property set to table 18, Customer, field No.
  • Table 18, Customer, has a LookupPageId property set to page 22, Customer List.

Thus if both page 42, Sales Order, and page 22, Customer List, are published as web services, then an OData URI can link from the Sell_to_Customer_No control on page 42 to the related entity on page 22.

Because of this association, you can create OData URIs to access data on the Customer List page as you work with data on the Sales Order page.

If you publish pages 42 and 22 as web services, then you can return an AtomPub document for the Sales Order page. The following URI returns data for a single record on the page, which is order number 101005:

 Copy Code
http://localhost:7048/DynamicsNAV71/OData/Company('CRONUS%20International%20Ltd.')/SalesOrder(Document_Type='Order',No='101005')/

A set of three tags near the top of the returned document show one containment (SalesOrderSalesLines) and two associations (Sell_to_Customer_No and Bill_to_Customer_No) on the page. Notice the type=entry in the following lines:

 Copy Code
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/SalesOrderSalesLines" 
             type="application/atom+xml;type=feed" title="SalesOrderSalesLines" 
             href="SalesOrder(Document_Type='Order',No='101005')/SalesOrderSalesLines" /> 
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Sell_to_Customer_No_Link" 
             type="application/atom+xml;type=entry" title="Sell_to_Customer_No_Link" 
             href="SalesOrder(Document_Type='Order',No='101005')/Sell_to_Customer_No_Link" /> 
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Bill_to_Customer_No_Link" 
              type="application/atom+xml;type=entry" title="Bill_to_Customer_No_Link" 
              href="SalesOrder(Document_Type='Order',No='101005')/Bill_to_Customer_No_Link" />

This information provides the necessary information to create a URI to access a record on the Customer List page by using an association:

 Copy Code
http://localhost:7048/DynamicsNAV71/OData/Company('CRONUS%20International%20Ltd.')
             /SalesOrder(Document_Type='Order',No='101005')/Sell_to_Customer_No_Link

The following URI returns the same information with direct access to the Customer List page:

 Copy Code
http://localhost:7048/DynamicsNAV71/OData/CustomerList('30000')

See Also