Scripting Relative Facilities

Canvas > Using Relative Facilities > Scripting Relative Facilities

Scripting Relative Facilities

The following section provides details about the order of operation and script examples that can be used when defining relative facility relationships via script. The CygNet .NET API includes a CygNet.API.Facilities.Relative namespace, which contains the methods and properties needed to accomplish this.

CygNet.API Help: Refer to the following topics in the CygNet.API Help for more information about the methods and properties used in these examples:

CygNet.API.Facilities.Relative Namespace
- RelativeFacilityDefinitionSets Class
- RelativeFacilityDefinitions Class
- RelativeFacilityDefinition Class

The relationships and paths defined in a relative facility definition are stored in an XML string.

Global Settings File

Relative facilities are stored in the Canvas the global settings file (.gsf). The global settings file is accessed with CygNet.Internal.SettingsPackage:

string settings = CygNet.Internal.SettingsPackage.ReadSettings("RelativeFacilityContent", settingsPath, storageType);

RelativeFacilityDefinitionSets Class

There is a RelativeFacilityDefinitionSets class as part of the CygNet.API.Facilities.Relative namespace.

To use any of the methods, the relative facility definition sets XML string must be loaded. To do this, first create a definition sets object:

RelativeFacilityDefinitionSets definitionSets = new RelativeFacilityDefinitionSets();

Then use the Load method and pass in the XML string as a parameter:

definitionSets.Load(definitionSetsXml);

There are three methods to get a specific relative facility definition set: by name, by configured facility service, and by the default definition set:

1. To get a definition by name, use the GetDefinitionSetByName method:

RelativeFacilityDefinitions definitions = definitionSets.GetDefinitionSetByName(definitionName);

2. To get a definition for a configured facility service, use the GetDefinitionSetByFacilityService method:

RelativeFacilityDefinitions definitions = definitionSets.GetDefinitionSetByFacilityService(facilityServiceName);

3. To get the default definition set, use the GetDefaultDefinitionSet method:

RelativeFacilityDefinitions definitions = definitionSets.GetDefaultDefinitionSet();

To obtain a unique list of definition names from all definition sets, use the GetDefinitionNames method:

List<string> names = definitionSets.GetDefinitionNames();

RelativeFacilityDefinitions Class

There is a RelativeFacilitiesDefinitions class as part of the CygNet.API.Facilities.Relative namespace.

To use any relative facility method, the relative facility definitions XML string must be loaded. To do this, first create a definitions object:

RelativeFacilityDefinitions definitions = new RelativeFacilityDefinitions();

Then use the Load method and pass in the XML string as a parameter:

definitions.Load(xmlDocument.InnerXml);

Use the ToXml method to get an XML representation of the definitions object:

string definitionsXml = definitions.ToXml();

There are two more useful methods that are available on the definitions object. The definitions XML only stores direct child links for a given definition; however, when loaded, the definitions class will generate all paths associated for the definition.

Use the GetAllPaths method to obtain a list of all paths generated for a definition:

List<string> allPaths = definitions.GetAllPaths("Well");

In this example, the returned list will contain the names of all definitions that a "Well" can reference.

Use the GetPath method to see the fully qualified path for any of the returned names:

string resolvedPath = definitions.GetPath("Well", "Tank 1");

In this example, the resolved path will be the path needed to go from a "Well" definition to a "Tank 1" definition. The result will be in a qualified filter format:

%PARENT%:facility_type='TANKBAT':facility_type='Tank' AND facility_attr1='1'

To resolve this path to a valid Facility service, use the ResolveRelativeFacility method of the CygNet.API.Facilities.Client class:

//Create a facility client and connect to a facility service

CygNet.API.Facilities.Client facilityClient = new Client(facilityService);

//Construct facility tag of the source facility

FacilityTag facilityTag = new FacilityTag(facilityTagString);

//Resolve facility

FacilityTag resolvedTag = facilityClient.ResolveRelativeFacility(definitionSet, tag, relationship);

To add a new definition, first create a RelativeFacilityDefinition variable. Then set the name, filter, and links. Please note, that all links must be valid definitions and can be associated with the definition:

RelativeFacilityDefinition definition = new RelativeFacilityDefinition();

definition.Name = "Test";

definition.Filter = "facility_type='TEST'";

Next, use the AddDefinition method to create the new definition:

definitions.AddDefinition(definition);

Use the AddLink method to add a new link to an existing definition:

definitions.AddLink("CDP", "Test");