3 mvPath

This chapter contains information on how to use mvPath. It includes complete mvPath syntax and copious examples of its use.

3.1 Using mvPath

Several CLI commands use mvPath expressions to refer to containers and properties.

mvPath is similar to XPath, but is designed specifically for navigating the data hierarchy in Application Configuration Console. If you're not familiar with XPath but have experience typing directory and file names at a DOS or UNIX command prompt, you should find mvPath intuitive.

All mvPath expressions refer to a context, which you can usually think of as the current location in the data hierarchy.

3.2 mvPath Reference

mvPath is an expression language for referring to objects in Application Configuration Console such as containers and properties. In Application Configuration Console you use mvPath when specifying variables and constraints, when using the command line interface, and when writing your own scripts.

The mvPath view of configuration data is simple: everything is a container except for properties and metadata. Projects, environments, layers, folders, assets, configurations, views, configuration elements -- they're all containers. Both containers and properties can have metadata, and properties and metadata can have values.

3.2.1 mvPath Constructors

You use mvPath to navigate up and down the hierarchy of containers. All mvPath expressions are evaluated in relation to a context. A context as a container in the data hierarchy (a contexts is always a container). The context for an mvPath expression is usually the current container. However, if an expression starts with / then the context is the data root.

mvPath expressions are constructed from a fairly short list of words and punctuation.

Container names = Refer to containers directly by name, with no special punctuation. For example, Asset1 would refer to a container named "Asset1" that is located in the current context.

Property names = Precede a property name with @. For example, @port refers to a property named "port."

Metadata names = Precede metadata names with a tilde (~). For example, ~http refers to a metadata named "http." Note that both containers and properties can have metadata.

Property and Metadata values = Set or test the values of properties and metadata with = (equals). For example, @port="80" refers to a property named "port" with the value "80."

. (period) = the current context. This is optional, except when preceding //

.. = go up to the parent container. Note that you cannot use this to navigate from one top-level project to another, such as ../P2 from P1.

/ = root or separator. If used at the beginning of an expression, the slash indicates the root of the Data folder. If used elsewhere in an expression, it separates the components of the path.

/MV_CONFIG = root of System Configuration folder. To address objects under the System Configuration folder, you must start the path with /MV_CONFIG.

// = recurse all descendants.

//- = recurse descendants, but don't recurse below a positive result.

^ = Match limiter. Will not allow the expression to match inside configurations. The search will only be in containers above configurations.

[] = contains or has. For example, E2[L2] refers to a container named "E2" that contains a child named "L2." E2[def()="D1"] refers to a container named "E2" that has a definition of "D1."

* = wildcard for a complete container name, property name, or metadata name. Cannot be used to complete a partial name.

+ = concatenate mvPaths (must be strings, including name(), value() and literal strings). Do not use spaces on either side of the plus sign. Concatenation cannot be used inside predicates, for example: C1[@P1/value()="foo"+@P2/value]

value() = the value of a property or metadata

id() = the id of a container, property or metadata

name() = the name of a container, property or metadata

list("regex") = returns a list string that matches a pattern found in the supplied name() or value() operator.

Examples:

If a returned name() or value() is “SIBusMember_114678997643" then:

value()/list("^[a-zA-Z]*") returns "SIBusMember"

value()/list("[0-9]*$") returns "114678997643"

value()/list("M[a-z]*") returns "Member"

/slice(start:end) = returns a part of a string, where start is the (zero-based) number of the first character to return and end is the number of the last character to return. If end is a negative number, then it is counted from the right end of the string.

Examples:

If a returned value() is "ABCDEFG" then:

value()/slice("2:5") returns "CDE"

value()/slice("2:-2") returns "CDE"

value()/slice("2:") returns "CDEFG"

value()/slice(":5") returns "ABCDE

value()/slice("-3:") returns "EFG"

def() = the container or property definition. Possible values are the strings represented by the constants defined in mvcontainer.ContainerDefinitions. To get the actual string, type the following in the CLI console view:

import mvcontainer

mvcontainer.ContainerDefinitions.<CONSTANT>

where <CONSTANT> is a containerDefinitions constant, for example:

mvcontainer.ContainerDefinitions.PROJECT

Possible constant values:

ASSET = http://mvalent.com/2003/container#asset

ASSET_RESOURCE_VIEW = http://mvalent.com/2003/container#asset_resource_view

AUTHPACK_FOLDER = http://mvalent.com/2003/container#authpack_folder

CONFIGURATION = http://mvalent.com/2003/container#configuration

CONFIGURATION_VIEW = http://mvalent.com/2003/container#configuration_view

CUSTOM_VIEW = http://mvalent.com/2003/container#custom_view

CUSTOM_VIEW_FOLDER = http://mvalent.com/2003/container#custom_view_folder

ELEMENT_TREE = http://mvalent.com/2003/container#element_tree

ENVIRONMENT = http://mvalent.com/2003/container#environment

FILE_FOLDER = http://mvalent.com/2003/container#file_folder

FILE_TEMPLATE = http://mvalent.com/2003/container#file_template

FOLDER = http://mvalent.com/2003/container#folder

HOST_FOLDER = http://mvalent.com/2003/container#host_folder

LAYER = http://mvalent.com/2003/container#layer

MV_CONFIG_ASSET = http://mvalent.com/2003/container#mv_config_asset

PROJECT = http://mvalent.com/2003/container#project

RESOURCESPEC_FOLDER = http://mvalent.com/2003/container#resourcespec_folder

type() = container type. Possible values are the strings represented by the constants defined in mvcontainer.Type. To get the actual string, type the following in the CLI console view:

regex(".*.xml")

where <CONSTANT> is the mvcontainer.Type, for example:

mvcontainer.Type.ORGANIZATION.uri()

Possible constant values:

ASSET = http://mvalent.com/2003/container#asset

ASSET_VIEW = http://mvalent.com/2003/container#asset_view

AUTHPACK_FOLDER = http://mvalent.com/2003/container#authpack_folder

CONFIGURATION = http://mvalent.com/2003/container#configuration

CONFIGURATION_VIEW = http://mvalent.com/2003/container#configuration_view

ELEMENT_TREE = http://mvalent.com/2003/container#element_tree

FILE_TEMPLATE = http://mvalent.com/2003/container#file_template

HOST_FOLDER = http://mvalent.com/2003/container#host_folder

MV_CONFIG = http://mvalent.com/2003/container#mv_config

ORGANIZATION = http://mvalent.com/2003/container#organization

RESOURCESPEC_FOLDER = http://mvalent.com/2003/container#resourcespec_folder

regex() = regular expression. You can use regular expressions for pattern matching, such as:

import mvcontainer

mvcontainer.Type.<CONSTANT>.uri()

to match all configuration names that end in .xml. Regular expressions can be quite powerful, but are beyond the scope of this reference page. For more information, look at regex sites on the Web, such as http://www.regular-expressions.info/.

\ = Escape character. You must precede the following special characters with a backslash if you need to use them in an mvPath expression: / ( [ ] = +

Although there are only a few constructors, they are quite powerful when combined in mvPath expressions as shown in the examples below. When constructing an mvPath, you should be as specific as possible to increase speed and efficiency. Keep these recommendations in mind:

If the expression is not meant to find elements or properties, use //^ instead of //.

If the expression is looking for something under a specific child container, then use that child container name in the path instead of searching all child containers; that is, use: ./c1/c2 instead of .//c2.

Only start expressions with // if you don't know any part of the path to the desired object.

3.2.2 mvPath Examples

The examples below use a simple data hierarchy, represented graphically here in the Client Navigator view:

In addition to what is visible here, both config1.xml and propertyA have metadata.The context for all examples will be Folder1 that is highlighted in Project1.

3.2.2.1 Containers

Refer to a container by location:

Asset1/*

Returns all child containers of Asset1. In this example, it would just return Resource View.

.//*

Returns the current container and all its descendant containers.

..

Returns Layer1, the parent of the current container.

../../*

Returns Environment1 (and any siblings if it had any).

Refer to a container by name:

Asset1

Returns Asset1 under the current context, which is Folder1.

Asset1/Resource View/config1.xml

Returns config1.xml under Asset1.

Asset1/Resource View/config1.xml/Primary View/Element1

Returns Element1 in the Primary View of config1.xml, which is under Resource View of Asset1. Note that both views and elements are containers in the hierarchy. You must specify a view to access the elements and properties in a configuration.

//config1.xml

Returns all of the containers named "config1.xml" in the entire system.

Asset1//^Primary View

Returns all containers named "Primary View" that are descendants of Asset1 but are not configurations or under configurations. There are no matches in the example, so nothing would be returned.

/Project1

Returns the root project named "Project1."

//Primary View

Returns all the containers named "Primary View" in the entire system.

.//Primary View

Returns all the descendants of the current container named "Primary View" plus the container itself if it is named "Primary View."

../Layer1

Returns the parent container.

./"Asset"+"2"

Returns Asset2.

//-Layer1

Returns Layer1, but does not look below Layer1 for any other containers named Layer1.

Refer to a container by something it contains:

Asset1[Resource View/config1.xml]

Returns Asset1 if it has a child container named "config1.xml" in its Resource View.

Asset1/Resource View/config1.xml[CustomView]

Returns config1.xml if it is a child of Asset1's Resource View and if it has a child container named "CustomView."

Asset1[Resource View/config1.xml/CustomView]

Returns Asset1 if it has a child container named "config1.xml" in its Resource View that has a child container named "CustomView."

Asset1[Resource View/config1.xml/~metadata1]

Returns Asset1 if it has a child container named "config1.xml" in its Resource View that has metadata named "metadata1."

Asset1/Resource View/config1.xml[~metadata1]

Returns config1.xml if it has metadata named "metadata1."

Asset1/Resource View/config1.xml[~metadata1="value1"]

Returns config1.xml if it has metadata named "metadata1" with a value of "value1."

Asset1/Resource View/config1.xml[Primary View/@propertyA]

Returns config1.xml if it is a child of Asset1 and has a child container named "Primary View" which contains a property named "propertyA."

Asset1/Resource View/*[Primary View/@propertyA]

Returns any containers that are children of Asset1's Resource View and have a child container named "Primary View" which contains a property named "propertyA."

Asset1/*[Primary View/@propertyA="valueA"]

Returns any containers that are children of Asset1's Resource View and have a child container named "Primary View" which contains a property named "propertyA" with value "valueA."

./*/*/*[Primary View]

Returns both config1.xml and config2.xml because they both match the wildcard path and they both contain a container named "Primary View."

Asset1//[@propertyA="valueA"]

Returns the container Element1, because it contains "propertyA" with value "valueA". Note that this returns the container (which is an element in this case), not the property.

Asset1//[@propertyA="valueA"][@propertyB="valueB"]

Returns the container Element1, because it contains "propertyA" with value "valueA" and "propertyB" with "valueB."

Refer to a container by type:

Asset1/*[type()="organization"]

Returns the child containers of Asset1 that have a container type of "organization."

Refer to a container by definition:

Asset1/*[def()="D1"]

Returns all containers that are children of Asset1 and have a definition of "D1."

Refer to the name of a container:

Asset1/name()

Returns the name of Asset1 under the current context.

Asset1/*/name()

Returns the names of all containers directly under Asset1.

Refer to the type of a container:

Asset1/type()

Returns the container type of Asset1.

Refer to the ID of a container:

Asset1/id()

Returns the id of Asset1.

3.2.2.2 Properties

Refer to a property by location:

Asset1/Resource View/config1.xml/Primary View/Element1/@*

Returns all properties that are in Element1 of the Primary View of config1.xml.

Asset1/Resource View/config1.xml/Primary View/*/@*

Returns all properties that are in the Primary View of config1.xml.

Refer to a property by name:

Asset1/Resource View/config1.xml/Primary View/Element1/@propertyA

Returns propertyA in Element1 of the configuration. Note that a view is considered a container in the hierarchy and must be included in the mvPath to reach elements and properties. In other words, properties are contained in elements (which are containers) which are contained in views.

Asset1//@propertyA

Returns all properties named "propertyA" underneath Asset1. With the sample data, this returns the same property as the previous example because there aren't any other properties with that name.

Refer to a property by value:

Asset1/Resource View/config1.xml/Primary View/Element1/@*[value()="valueA"]

Returns all properties in Element1 with value "valueA."

Refer to a property by name and value:

Asset1//@propertyA="valueA"

Returns all properties named "propertyA" with value "valueA" that are descendants of Asset1.

Refer to a property by metadata name:

Asset1/Resource View/config1.xml/Primary View/Element1/@propertyA[~metadataA]

Returns propertyA in Element1if it has metadata named "metadataA."

Asset1//*/@*[~metadataA]

Returns all properties that are descendants of Asset1 and that have metadata named "metadataA."

Refer to a property by metadata name and value:

Asset1//*/@*[~metadataA="valueA"]

Returns all properties that have metadata named "metadataA" with value "valueA" that are descendants of Asset1.

Refer to a property by definition:

Asset1/Resource View/config1.xml/Primary View/Element1/@*[def()="port"]

Returns all properties in Element1 that have a definition of "port."

Refer to a property by another property in the same element:

Asset1/Resource View/config1.xml/Primary View/Element1[@propertyB="valueB"]/@propertyA

Returns propertyA in Element1 if Element1 contains propertyB with value "valueB."

Refer to the name of a property:

Asset1/Resource View/config1.xml/Primary View/Element1/@propertyA/name()

Returns the name of propertyA.

Asset1/Resource View/config1.xml/Primary View/Element1/@*/name()

Returns the names of all properties in Element1.

Refer to the value of a property:

Asset1/Resource View/config1.xml/Primary View/Element1/@propertyA/value()

Returns the value of propertyA in Element1.

Refer to the definition of a property:

Asset1/Resource View/config1.xml/Primary View/Element1/@propertyA/def()

Returns the property definition of the property named "propertyA." (Properties are linked to definitions in the property dictionaries.)

Refer to the ID of a property:

Asset1/Resource View/config1.xml/Primary View/Element1/@propertyA/id()

Returns the id of propertyA.

3.2.2.3 Metadata

Refer to metadata by location:

Asset1/Resource View/config1.xml/~*

Returns all container metadata of the config1.xml container.

Asset1/Resource View/config1.xml/Primary View/Element1/propertyA/~*

Returns all property metadata of the property named "propertyA."

Refer to metadata by name:

Asset1/Resource View/config1.xml/Primary View/Element1/@propertyA/~metadataA

Returns metadataA of propertyA in Element1 of the configuration.

Asset1/Resource View/config1.xml/~metadata1

Returns metadata1 of the config1.xml container.

Refer to metadata by value:

Asset1/Resource View/config1.xml/~[value()="value1"]

Returns all metadata in the config1.xml container with value "value1."

Refer to metadata by name and value:

Asset1//~metadata1="value1"

Returns all metadata named "metadata1" with value "value1" that are descendants of Asset1.

Refer to metadata names:

Asset1/Resource View/config1.xml/Primary View/Element1/@propertyA/~metadataA/name()

Returns the name of metadataA on propertyA.

Asset1/Resource View/config1.xml/~*/name()

Returns the names of all metadata in config1.xml.

Refer to metadata values:

Asset1/Resource View/config1.xml/Primary View/Element1/@propertyA/~metadataA/value()

Returns the value of metadataA on propertyA in Element1.

Asset1/Resource View/config1.xml/~metadata1/value()

Returns the value of metadata1 in config1.xml.

Refer to metadata ID:

Asset1/Resource View/config1.xml/Primary View/Element1/@propertyA/~metadataA/id()

Returns the id of metadataA.

3.2.2.4 Connectors (Hosts, Authentication Packs, Resource Specifications)

Syntax:

[objectPath]operator("objectName")

Where:

objectPath is the optional path to objectName. The path references the root, that is, it begins with /, as in /F1/F2/F3/…

operator is one of the following:

authpack
host
resourcespec

objectName is the optional name of the object to resolve. If no name is specified, all objects of the target type are returned for the specified context.

Refer to a connector by name:

authpack("passport")

Returns an authentication pack named passport from the global name space.

Refer to a connector by name and location:

/F1/F2/F3/resourcespec("xmlConfig")

Returns a resource specification named xmlConfig under the folder hierarchy /F1/F2/F3/.

Refer to all connectors of a target type:

host()

Returns all hosts in the global name space.

/F1/F2/F3/host()

Returns all hosts under the folder hierarchy /F1/F2/F3/.

3.2.2.5 Strings

Return a string:

"Your text string here."

Returns the string "Your text string here."