Relative Facilities are a powerful way to present data on your Canvas and Thin Web Client screens. For any given facility you can configure a relationship or syntax to define a path to another facility in your CygNet environment. You can combine data from facilities in multiple Facility services into a single relative facility definition. Relative facilities can also be used to associate a facility in a hierarchy with a closely related facility that is not in the same hierarchy. For example, you could use relative facilities to associate a well facility that is in a hierarchy with a meter facility that is not, so you can build a screen to show data from other facilities without having to hard-code the objects on a screen.
Before you configure relative facilities, be sure that you understand your data model, including the facility types in it, how its facilities are organized, what attributes are associated with the facilities, any ordinal relationships, the types of data points (UDCs) that belong to each facility type, and so on. Based on your data model's organization and components, a relative facility definition provides the rules by which a specific value resolves to a single, terminal relative facility. These rules are filters and paths that apply logic to attributes to resolve to the terminal relative facility. Relative facility resolution returns a facility tag rather than a facility ID.
Canvas controls can be configured to be aware of how data in your site is related and which facility attributes a facility should reference with respect to associated data points. For example, you might have a gas meter that links to a well. You can configure a chart to be associated with a well but set a series in the chart to display a point associated with the related gas meter.
These settings are saved in XML format as part of the global settings file (.gsf) for your Canvas application and applied to all instances of Canvas. If no global settings file is available, none of these settings will be configurable, but a message will provide a link to the Backstage view where you can configure one.
Configure Relative Facilities
Relative facility definitions are configured in the Settings section of the Canvas Backstage view.
- See Configuring Relative Facilities for information about creating relative facility definitions for use on your Canvas screens.
- See Testing Relative Facility Links for information about testing relative facility definitions and resolving to the appropriate facility tag.
All Canvas controls that support point configuration allow the setting of a Relative link when specifying a facility tag to use for the control.
- See the Properties topic for each control. The following table lists the relevant properties that can be configured for each control:
| Property | Description |
|---|---|
|
The Resolve to a relative facility check box redirects the source of the facility to a relative facility, overriding the configured source facility. Once selected a list of configured Relative links is displayed. See Using Relative Facilities in Canvas for more information about configuring and scripting relative facility links. |
|
|
The Relative link property specifies a list of all available relative facility paths. Click |
|
|
The Order in type property specifies the attribute value used to represent the order in type (facility ordinal) if the relative facility definition is configured for one. It is possible to have multiple relative facility definition sets with the same definition name. In this case, if the specified Relative link is configured for ordinalization, then you need to configure the attribute value in the box. |
to reveal a drop-down menu of all available relative facility definitions (relative links). Select a link from the list. If an order-in-type attribute is specified for the selected link, the Order in type field will display.Relative Facility Tree Control
See the Relative Facility Tree for information about a control you can add to your screens to show a hierarchical tree of CygNet facilities based on the relative facility settings.
Design Screens to use Relative Facilities
Some planning is required to implement controls and design screens that resolve to facilities and relative facilities in the desired way.
- See Design Considerations for more information about resolving facilities when using Order in type and how to avoid configuring facilities with multiple parents.
API Integration
The CygNet .NET API includes a CygNet.API.Facilities.Relative namespace, which contains methods and properties required to configure and resolve relative facilities via script.
- See Scripting Relative Facilities for information about configuring relative facility definitions via script.
Facility Resolution
CygNet Studio allows the configuration of relative facilities in its CygNet-aware tools via the [ReferenceFacility] property. However, reference facilities only support a single level of resolution, whereas Canvas allows for multi-level resolution of relative facilities via the CygNet .NET API.
In CygNet Studio, you must configure a screen object to the point level to resolve a reference facility, even if you want to only show facility attributes. For example, in order to have a text box object show a facility description, you need to configure the UDC of the text box for facility attributes to work. While not necessarily related to reference facility configuration, it's important to know that you cannot show facility attributes in a Studio object unless you have a UDC defined for the object. In Studio any facility resolution is done at the point level.
In Canvas, it is possible to configure objects to show facility attributes without the need to configure the UDC. The relative facility methods in the CygNet .NET API do not require the UDC; they just require relative facility definitions, relative facility name, and the source facility tag. In Canvas the resolution is done at the facility level, rather than at the point level.
