Object names and references

This topic describes the use of object names and references in the Delphix Engine command-line interface.

Most Delphix objects are persistent objects in that they have a well-known identity on the server and associated persistent state. The exceptions are objects used only as input to other operations, or global objects that have a persistent state but don’t require any explicit identity since they always exist.

Persistent objects have both a name and a reference. The reference is the canonical identifier for the object and remains valid even if the object is renamed on the server. It is an opaque token that should never be interpreted by the client; the format may change in future releases though backward compatibility with current references will be maintained. All web service APIs operate using references. References can be used in the CLI when selecting objects, but given that they are a programmatically generated internal concept, they are difficult for most users to use.

The object name, on the other hand, is a much more convenient way to refer to objects but suffers from the fact that it is not guaranteed to be globally unique. When displaying or setting references, the CLI will convert to or from the ‘canonical name’ based on the type of the reference and the current set of objects on the system. The canonical name has the form:

<Type>:/<Parent>/<Object>@<Namespace>

The type, parent, and namespace are only included if the local object name conflicts with other objects on the system that would otherwise be valid for the given type specification. Not all objects have names relative to their parent; groups, environments, users, and many other objects are globally unique on the system. This “best fit” method is used both when displaying references as well as when setting properties that are references. If the given name potentially matches multiple objects when attempting to set a reference property, then an error is displayed that includes a list of possible names to clarify which object is being referred to. The conversion from reference to name on display only happens with text output format. When the output format is JSON, the raw content is displayed (including the local name) and it is up to the consumer to format names appropriately based on their semantics. The conversion from name to reference when setting properties always occurs. Consumers can use references, optionally prefixed with a backtick (`) character to signify they are references in the unlikely event that someone has created an object with the same name as a valid reference.

Providing unique names for objects without the use of forward slashes ('/') and at signs ('@') will provide the simplest CLI experience when referencing objects.

Here are some scenarios for databases and groups and their resulting behavior:

No conflicting database name

The local name will be used when displaying references to the object, and can be used when setting references:

set container=example

Databases with the same name in different groups

The parent group name must be used when displaying references to the object and when setting references to the object:

set container=group1/example

Databases with the same name in different namespaces

The namespace name must be used when displaying references to the object and when setting references to the object:

set container=example@namespace

Objects of different types but with the same name

This conflict is exceptionally rare, as the reference context typically constrains the set of possible objects to be a single type, but there are cases (such as alerts, or policy targets) that can be applied to any object. In these cases, the type name must be included to uniquely identify the object:

set target=Container:/group1/example

In the event that one of the named components contains a slash (‘/’) or an at-sign ('@'), single quotes must be used to disambiguate the name from its parent or namespace.