Work with configuration items in the XL Deploy CLI

When using the XL Deploy command-line interface (CLI) with configuration items (CIs), the main objects you will use are:

  • The factory object, which is used to create a CI
  • The repository object, which allows you to store a CI in the XL Deploy repository

Explore CI types and their properties

To get the CI types that are available, execute:

factory.types()

The CLI displays an overview of the CI types that are available, including types that are defined by plugins.

Get information about a CI type

To get information about a type, such as the required properties, execute the describe method on the deployit object with the qualified type name as its parameter.

Example of a command:

deployit.describe('udm.Dictionary')

Example of an output of this command:

ConfigurationItem udm.Dictionary:
Description: A Dictionary contains key-value pairs that can be replaced
Control tasks:
Properties:
    - entries(MAP_STRING_STRING): The dictionary entries
    - encryptedEntries(MAP_STRING_STRING): The encrypted dictionary entries
    - restrictToContainers(Set<udm.Container>): Only apply this dictionary to the containers mentioned
    - restrictToApplications(Set<udm.Application>): Only apply this dictionary to the applications mentioned

Properties marked with a '!' are required for discovery.
Properties marked with a '*' are required.

Get attributes of a specific CI

To get the attributes of a specific CI, such as when it was created or when it was last modified, execute the read method on the repository object.

Example of a command:

ci=repository.read("Applications/Sample Apps/BookStore/1.0.0")
ci._ci_attributes.createdAt

Example of an output of this command:

DateTime: 2016-05-13T10:07:25.312Z

Create CIs

These examples show how to create some commonly used CIs.

Create an SSH host CI

To create an SSH host CI, execute:

sampleHost = factory.configurationItem('Infrastructure/sampleHost', 'overthere.SshHost', { 'os': 'UNIX', 'address': 'localhost', 'username': 'scott' })

To save the CI in the repository, execute:

repository.create(sampleHost)

Create a dictionary CI

To create a dictionary CI, execute:

sampleDict = factory.configurationItem('Environments/myDict', 'udm.Dictionary')
sampleDict.entries = { 'a': '1', 'b': '2' }

To save the CI in the repository, execute:

repository.create(sampleDict)

Create an environment CI

To create an environment CI and add a host and dictionary to it, execute:

sampleEnv = factory.configurationItem('Environments/sampleEnv', 'udm.Environment')
sampleEnv.dictionaries = [ sampleDict.id ]
sampleEnv.members = [ sampleHost.id ]

To save the CI in the repository, execute:

repository.create(sampleEnv)

Move and rename CIs

You can use the CLI to move or rename CIs in the repository. A CI can only be moved within the root node in which it was created. Example: A CI under Applications can only be moved to another location in the Applications tree.

Move a CI

This example shows how to create a directory CI under the Environments node and then move an environment CI into it.

To create the directory CI and save it to the repository, execute:

directory = factory.configurationItem('Environments/ciGroup', 'core.Directory')
repository.create(directory)

To move the environment CI into the directory:

repository.move(sampleEnv, directory.id + '/sampleEnv')
sampleEnv = repository.read('Environments/ciGroup/sampleEnv')

Rename a CI

This example shows how to rename a directory CI:

repository.rename(directory, 'renamedCiGroup')
sampleEnv = repository.read('Environments/renamedCiGroup/sampleEnv')

References to renamed or moved CIs are kept up-to-date. Example: The sampleHost CI is a member of the sampleEnv environment. If you rename sampleHost to renamedSampleHost, then sampleEnv will refer to renamedSampleHost.

sampleHost = repository.read('Infrastructure/sampleHost')
repository.rename(sampleHost, 'renamedSampleHost')
sampleEnv = repository.read('Environments/renamedCiGroup/sampleEnv')
sampleHost = repository.read(sampleEnv.members[0])

Search a CI

To search CIs by name:

repository.searchByName("1.0")

To search CIs by type and parent name:

repository.search('udm.Application', 'Applications')

Delete a CI

To delete a CI by ID:

repository.delete("/Applications/TestApp/1.0")

To delete a list of CIs by a list of IDs:

repository.deleteList(["/Applications/TestApp/2.0", "/Applications/TestApp/3.0"])

Check if CI exists

To check by ID if CI exists:

repository.exists("/Applications/TestApp/1.0")

Note: Do not move or rename CIs while deployments are in progress or while the CIs are being used by the GUI or the CLI client.