Skip to main content
Version: Early Access

Deploy manifest format

The manifest file included in a deployment package (DAR file) describes the contents of the archive for Deploy. When importing a package, the manifest is used to construct CIs in Deploy's repository based on the contents of the imported package. The format is based on XML.

A valid Deploy XML manifest file contains at least the following tags:

<?xml version="1.0" encoding="UTF-8"?>
<udm.DeploymentPackage version="1.0" application="PetClinic">
  <deployables>
    ...
  </deployables>
</udm.DeploymentPackage>

Adding artifacts​

Within the deployable tags you can add the deployables that make up your package. For example, a package that includes an ear file and a directory containing configuration files would be specified as follows:

<deployables>
  <jee.Ear name="AnimalZooBE" file="AnimalZooBE-1.0.ear">
  </jee.Ear>
  <file.Folder name="configuration-files" file="conf">
  </file.Folder>
</deployables>

In this example, the:

  • Element name is the type of configuration item that will be created in Deploy.
  • Name attribute corresponds to the specific name the configuration item will get.
  • File attribute points to an actual resource found in the package.

Adding resource specifications​

The deployables element can contain more than just the artifacts that comprise the package. You can also add resource specifications to it. For instance, you can add the specification for a datasource. You define these specifications in a similar manner as artifacts, but they do not contain the file attribute:

<was.OracleDatasourceSpec name="petclinicDS">
  <url>jdbc:mysql://localhost/petclinic</url>
  <username>petclinic</username>
  <password>my$ecret</password>
</was.OracleDatasourceSpec>

In this example, the specification was.OracleDatasourceSpec is created with the properties url, username and password set to their corresponding values.

Setting complex properties​

The above example showed how to set string properties to a certain value. In addition to strings, Deploy also supports references to other CIs, sets of strings, maps of string to string, Booleans and enumerations. The following sections provide some examples.

Refer from one CI to another​

To refer from one CI to another CI:

<sample.Sample name="referencing">
  <ciReferenceProperty ref="AnimalZooBE" />
  <ciSetReferenceProperty>
    <ci ref="AnimalZooBE" />
  </ciSetReferenceProperty>
  <ciListReferenceProperty>
    <ci ref="AnimalZooBE" />
  </ciListReferenceProperty>
</sample.Sample>

Set of strings properties​

To set a set of strings property to contain strings "a" and "b":

<sample.Sample name="setOfStringSample">
  <setOfStrings>
    <value>a</value>
    <value>b</value>
  </setOfStrings>
</sample.Sample>

List of strings properties​

To set a list of strings property to contain strings "a" and "b":

<sample.Sample name="listOfStringSample">
  <listOfStrings>
    <value>a</value>
    <value>b</value>
  </listOfStrings>
</sample.Sample>

Map of string to string properties​

To set a map of string to string property to contain pairs "key1", "value1" and "key2", "value2":

<sample.Sample name="mapStringStringSample">
  <mapOfStringString>
    <entry key="key1">value1</entry>
    <entry key="key2">value2</entry>
  </mapOfStringString>
</sample.Sample>

Boolean and enumeration properties​

To set a Boolean property to true or false:

<sample.Sample name="booleanSample">
  <booleanProperty>true</booleanProperty>
  <anotherBooleanProperty>false</anotherBooleanProperty>
</sample.Sample>

To set an enum property to a specific value:

<sample.Sample name="enumSample">
  <enumProperty>ENUMVALUE</enumProperty>
</sample.Sample>

Embedded CIs​

You can also include embedded CIs in a deployment package. Embedded CIs are nested under their parent CI and property. Here is an example:

<iis.WebsiteSpec name="NerdDinner-website">
  <websiteName>NerdDinner</websiteName>
  <physicalPath>C:\inetpub\nerddinner</physicalPath>
  <applicationPoolName>NerdDinner-applicationPool</applicationPoolName>
  <bindings>
    <iis.WebsiteBindingSpec name="NerdDinner-website/88">
      <port>8080</port>
    </iis.WebsiteBindingSpec>
  </bindings>
</iis.WebsiteSpec>

The embedded CI iis.WebsiteBindingSpec type is an embedded CI under it's parent, iis.WebsiteSpec. The property bindings on the parent stores a list of iis.WebsiteBindingSpec instances.

Using placeholders in CI properties​

You can use Deploy placeholders to customize a package for deployment to a specific environment. CI properties specified in a manifest file can also contain placeholders. These placeholders are resolved from dictionary CIs during a deployment. This is an example of using placeholders in CI properties in a was.OracleDatasourceSpec CI:

<was.OracleDatasourceSpec name="petclinicDS">
  <url>jdbc:mysql://localhost/petclinic</url>
  <username>{{DB_USERNAME}}</username>
  <password>{{DB_PASSWORD}}</password>
</was.OracleDatasourceSpec>

Placeholders can also be used in the name of a CI:

<was.OracleDatasourceSpec name="{{PETCLINIC_DS_NAME}}">
  <url>jdbc:mysql://localhost/petclinic</url>
  <username>{{DB_USERNAME}}</username>
  <password>{{DB_PASSWORD}}</password>
</was.OracleDatasourceSpec>

Deploy also supports an alternative way of using dictionary values for CI properties. If the dictionary contains keys of the form deployedtype.property, these properties are automatically filled with values from the dictionary, provided they are not specified in the deployable. This enables you to use dictionaries without specifying placeholders. For example, the above scenario could also have been achieved by specifying the following keys in the dictionary:

was.OracleDatasource.username was.OracleDatasource.password

Scanning for placeholders in artifacts​

Deploy scans files in packages for the presence of placeholders, adding them to the placeholders field in the artifact so that they can be replaced upon deployment of the package.

Enable or disable placeholder scanning​

You can enable or disable placeholder scanning by setting the scanPlaceholders flag on an artifact.

<file.File name="sample" file="sample.txt">
  <scanPlaceholders>false</scanPlaceholders>
</file.File>

Enable placeholder scanning within a specific archive​

By default, Deploy scans text files only. You can configure it to scan inside archives such as Ear, War or Zip files. To enable placeholder scanning inside a specific archive:

<jee.Ear name="sample Ear" file="WebEar.ear">
  <scanPlaceholders>true</scanPlaceholders>
</jee.Ear>

Enable placeholder scanning within all archives​

You can also enable placeholder scanning for all archives. To do this, edit deployit-defaults.properties and add the following line:

udm.BaseDeployableArchiveArtifact.scanPlaceholders=true

Control scanning by non-binary files by extension​

To avoid scanning of binary files, only files with the following extensions are scanned:

cfg, conf, config, ini, properties, props, txt, asp, aspx, htm, html, jsf, jsp, xht, xhtml, sql, xml, xsd, xsl, xslt

You can change this list by setting the textFileNamesRegex property on the udm.BaseDeployableArtifact in the deployit-defaults.properties file. Note that it takes a regular expression. You can change this on any of its subtypes which is important if you only want to change that for certain types of artifacts.

Excluding files from scanning​

If you want to enable placeholder scanning, but the package contains several files that should not be scanned, use the excludeFileNamesRegex property on the artifact:

<jee.War name="petclinic" file="petclinic-1.0.ear">
  <excludeFileNamesRegex>.*\.properties</excludeFileNamesRegex>
</jee.War>
note

The regular expression is only applied to the name of a file in a folder, not to its path. To exclude an entire folder, use a regular expression such as .*exclude-all-files-in-here (instead of .*exclude-all-files-in-here/.*).

Custom deployment package support​

If you have defined your own type of deployment package, or have added custom properties to the deployment package, you can import these by changing the manifest.

For example, if you've extended udm.DeploymentPackage as myorg.PackagedApplicationVersion which has additional properties such as releaseDate and tickets:

<?xml version="1.0" encoding="UTF-8"?>
<myorg.PackagedApplicationVersion version="1.0" application="PetClinic">
  <releaseDate>2013-04-02T16:22:00.000Z</releaseDate>
  <tickets>
    <value>JIRA-1</value>
    <value>JIRA-2</value>
  </tickets>
  <deployables>
    ...
  </deployables>
</myorg.PackagedApplicationVersion>

Specifying the location of the application​

You can specify where to import the package. You can use this during initial imports when the application does not yet exist. You can specify the path to the application as follows:

<?xml version="1.0" encoding="UTF-8"?>
<udm.DeploymentPackage version="1.0" application="directory1/directory2/PetClinic">
    ...
</udm.DeploymentPackage>

In this example, Deploy will then try to import the package called PetClinic located at Applications/directory1/directory2/PetClinic. It will also perform the following checks:

  • The user should have the correct import permissions (import#initial or import#upgrade) for the directory.
  • The path should exist. Deploy will not create it.
  • If the application does not exist, Deploy will create for an initial import.
  • If Deploy finds an application called PetClinic in another path, it will fail the import as application names must be unique.