Configuration macros

Configuration macros use DNs to retrieve values from non-Identity objects in the Venafi Trust Protection Platform configuration store. They are typically used in combination with $Event.Component$ or any other DN-based macro to provide the DN reference which they can retrieve an attribute value from.

The following sections provide descriptions and examples of configuration macros:

Common Name

Returns the common name of the designated object.

The macro syntax is as follows:

This macro is not consumed by other macros. It is primarily used to return message content for notifications.

Example Syntax

Example Output

If the target object is \VED\Policy\Sales\Internal\InternalCert, the output is

If the target object is \VED\Policy\Engineering\QA\IIS6, the output is

Config

Returns the values of designated attributes for a target object.

The basic macro syntax is as follows:

Arguments

Example Syntax

Example Output

The $Config$ macro looks up the target object using the DN provided by the $Event.Component$ macro and returns the value of the object’s "Contact" attribute—a User or Group UID.

GUID

Returns the Configuration GUID of the object passed to the macro. Helpful in building URLs that return to pages in Aperture since the GUID is often part of the URL for pointing to a specific certificate, device, or job.

The basic macro syntax is as follows:

Example of the basic macro output

Example Syntax

Example Output

ParentDN

Returns the DN of the parent object for a designated target object.

The macro syntax is as follows:

The $object_identification$ argument identifies the target object. You may provide a static object DN such as \VED\Policy\Sales\External\www.sales.com, or you can use a sub-macro such as $Event.Component$ or $SelfDN$ to dynamically return an object DN.

This macro is primarily used within other configuration macros to provide the object DN required to retrieve object attributes.

If you want the parent object’s common name only, you can combine the ParentDN macro with the CN macro as follows:

Example Syntax

Example Output

The $ParentDN$ macro looks up the target object using the DN provided by the $Event.Component$ macro, then returns the DN of the target’s parent object.

For example, if the target object is \VED\Policy\Sales\External\www.sales.com, the result string is:

The $CN$ macro returns the parent object’s common name.

For example, if the target object is \VED\Policy\Sales\External\www.sales.com, the result string is:

Policy

Returns the effective value of the designated attribute from the target object. The returned value may be derived from a parent policy or the target object, itself, depending on where and how the value is defined:

If the attribute is defined as a locked value in a parent policy, Venafi Trust Protection Platform always returns the first locked policy value it encounters in the tree.

A locked value is the only value read for all subordinate objects in the tree.

If the attribute is defined as an unlocked value in a parent policy, Venafi Trust Protection Platform returns the policy value only if it is not defined at the object value.

Unlocked policy values flow down the tree with the lowest value taking precedence. That means that when Trust Protection Platform looks up an object’s configuration in the tree and it encounters a unlocked policy value, it continues reading down the tree until it reaches the object configuration. Attributes defined at the object level always take precedence over unlocked values inherited from folders higher up the tree.

If this attribute is only defined at the object level, Venafi Trust Protection Platform returns the object value.

For more information on policy inheritance, see Using policies to manage encryption assets.

The basic macro syntax is as follows:

Arguments

• $object_identification$ - Identifies the target object. You may provide a static object DN such as \VED\Policy\Sales\External\www.sales.com, or you can use a sub-macro such as $Event.Component$ to dynamically return an object DN.
• "attribute_name" - Identifies the attribute you want to retrieve from the target object.

• [List Argument] [Optional] - The list argument is optional and is referenced only if the action of reading the attribute from the designated object results in multiple values. It designates a delimiter and escape character. The macro uses this information to format multi-value attributes in a text string.

  The standard delimiter is a comma ( , ); the standard escape character is a backslash ( \ ). However, you can designate any delimiter or escape character.

Example Syntax

Example Output

The $Policy$ macro looks up the target object using the DN provided by the $Event.Component$ macro. It then returns the effective value of the "Certificate Authority" attribute for the target object.

Company Name

Returns the current value of the Company Name defined in Venafi Configuration Console (this is first sent when Venafi Platform is installed).

This macro makes it easier to brand email messages by including it in email templates.

The macro syntax is as follows:

This macro is not consumed by other macros. It is primarily used for notifications.

Deployment Type

Returns the current deployment type defined in Venafi Configuration Console (this is first set when Venafi Platform is installed).

This macro allows you to include the deployment type (sandbox, dev, test, prod, etc.) in email templates, providing important context information about the message. This is important because messages sent from your production instance may require immediate attention, where messages in a lower environment are likely not urgent issues that need to be resoled.

The macro syntax is as follows:

This macro is not consumed by other macros. It is primarily used for notifications.