Unit tag

This tag adds a unit to the target topology or accesses an existing unit in the target topology.

Attributes

Table 1. Attributes of the unit tag
Attribute	Type	Required or optional	Description
description	String	Optional	The description of the unit.
displayName	String	Optional	The caption of the unit.
goalInstallState	String	Optional	The goal install state of the unit. Valid values are: Unknown (the default) Installed Uninstalled
initInstallState	String	Optional	The initial install state of the unit. Valid values are: Unknown (the default) Installed Uninstalled
preferDisplayNameMatch	Boolean	Optional	The default value is false.
isConceptual	Boolean	Optional	`true` is the unit is conceptual or `false` if it is concrete. The default value is `false`.
isConfig	Boolean	Optional	`true` if the unit is a configuration unit or `false` if it is not. The default is `false`.
isPublish	Boolean	Optional	The publish intent of the unit. The default is `true`.
name	String	Optional	The internal name of the unit. This name is not visible in the topology editor. Each unit must have a different internal name.
origin	String	Optional	A string that provides information on how the unit was created.
topology	XPath	Optional	The XPath location of the topology that contains the unit. The default value is `$TargetObject`, which refers to the topology that you select when you import information from the CSV file.
type	String	Required	The type of the unit, such as core.Unit. For a list of unit types in the topology editor domains, see Domains supported by the topology editor.
var	String	Optional	The name of a variable to create that refers to the unit. If you assign a variable name here, you can use that variable in other places in the JET code to refer to the unit.

Examples

In most cases, it is best to add units by using the template tag rather than the unit tag. When you use the template tag to create units, the new units include capabilities, requirements, attribute values, and related units, based on the topology elements in the template. When you use the unit tag to create a unit, the new unit does not have any capabilities, requirements, or other topology elements. The following example shows how to create a unit with no capabilities, requirements, or other topology elements.

<deploy:unit name="New unit" type="core.Unit"/>

You can nest other tags within the unit tag to create or access capabilities, requirements, and attributes on the unit. The following example shows how to create a unit, add a capability to it, and set an attribute value on the capability.

<deploy:unit name="New Windows unit" type="os.WindowsOperatingSystemUnit">
  <deploy:capability type="os.WindowsOperatingSystem" 
    name="Windows Server">
    <%-- set hostname --%>
    <c:setVariable select="'com.mycompany.server1'" var="hostnameVar"/>
    <deploy:set name="hostname" value="$hostnameVar"/>
  </deploy:capability>
</deploy:unit>

The unit tag can also access existing units. If the target topology contains a unit with the name and type that you specify in the unit tag, the JET code does not create another unit; instead, it assigns a variable to the unit so you can access the unit in other JET code. The following example shows how to create two units with the template tag and use the unit tag to assign variables to those units. Then, it uses the variables to link the units.

<%-- create a server unit from a template --%>
<deploy:template id="server.base.conceptual">
  <%-- assign a variable to the server unit --%>
  <deploy:unit name="New server" var="server" type="server.ServerUnit"/>
</deploy:template>

<%-- create an operating system unit from a template --%>
<deploy:template id="os.OperatingSystemUnit.conceptual">
  <%-- assign a variable to the operating system unit --%>
  <deploy:unit name="New OS" var="os" type="os.OperatingSystemUnit"/>
</deploy:template>

<%-- using the variables, link the units --%>
<deploy:hostingLink hostee="$os" host="$server"/>

The context and the attributes determine whether the unit tag creates a new unit or accesses an existing unit. When the unit tag is nested within the template tag, the unit tag behaves as follows:

If the type attribute matches the type of exactly one unit in the template, the unit tag accesses that unit rather than creating a unit.
If the type attribute does not match the type of any units in the template, the unit tag creates a unit in addition to the units that are in the template.
If there is more than one unit of the specified type in the template and
- if preferDisplayNameMatch is false, the behavior of the unit tag depends on the names of those units and the name attribute of the unit tag. If the name attribute matches the name of one or more of the units in the template, the unit tag accesses the first unit with a matching name. If the name attribute does not match the name of any of the units, the unit tag creates a unit.
- if preferDisplayNameMatch is true, the behavior of the unit tag depends on the displayNames of those units and the displayName attribute of the unit tag. If the displayName attribute matches the displayName of one or more of the units in the template, the unit tag accesses the first unit with a matching displayName. If the displayName attribute does not match the displayName of any of the units, the unit tag creates a unit.

When the unit tag is not nested within the template tag, the unit tag behaves as follows:

if preferDisplayNameMatch is false, both type and name attributes of the unit tag are matched against the type and name of an existing unit in the topology. If no unit match is found, new unit will be created.
if preferDisplayNameMatch is true, both type and displayName attributes of the unit tag are matched against the type and displayName of an existing unit in the topology. If no unit match is found, new unit will be created.