# Preface

This document describes the functionality provided by the File Plugin.

Refer to the Deployit Reference Manual for background information on Deployit and deployment concepts.

# Overview

In many cases, an application depends on external resources for its configuration. The application accesses these resources from a predefined location or using a predefined mechanism. In the simplest of forms, a resource can be described as a file, an archive or a folder (collection of files). The File Plugin enables the definition of such resources in a deployment package and subsequently managing them on a target host. The resources can contain placeholders that the plugin will replace when targeting to the specific host, thus allowing resources to be defined independent of their environment.

## Features

- Deploy, upgrade, and undeploy of a file based resource on a Host.
  - File
  - Folder
  - Archive

# Requirements

This plugin requires:

- Deployit: version 3.5+

# Usage in Deployment Packages

Please refer to Packaging Manual for more details about the DAR packaging format.

Sample DAR MANIFEST.MF entries defining a file, folder and archive resource

    Manifest-Version: 1.0
    Deployit-Package-Format-Version: 1.3
    CI-Application: FilePluginSample
    CI-Version: 1.0

    Name: sampleFile.txt
    CI-Name: sampleFile
    CI-Type: file.File

    Name: sampleArchive.zip
    CI-Name: sampleArchive
    CI-Type: file.Archive

    Name: sampleFolder
    CI-Name: sampleFolder
    CI-Type: file.Folder

# Using the deployables and deployeds

## Deployable vs. Container Table

The following table describes which deployable / container combinations are possible. Note that the CIs can only be targeted to containers derived from Host.

Deployables | Containers | Generated Deployed
--- | --- | ---
file.File file.Archive | overthere.Host | file.DeployedFile file.DeployedArchive
file.Folder | overthere.Host | file.DeployedFolder

## Deployed Actions Table

The following table describes the effect a deployed has on its container.

Deployed | Create | Destroy | Modify
--- | --- | --- | ---
file.DeployedFile file.DeployedArchive | Create target path on host, if needed Copy file to target path on host | Delete file from host | Delete old file from host Copy modified file to target path on host
file.DeployedFolder | Create target folder on host, if needed Copy folder content to target folder on host | Delete folder content from host If folder is not a shared folder, the folder itself is deleted from host | Perform actions as described by Destroy for old folder Perform actions as described by Create for modified folder

# CI Reference

## Configuration Item Overview

### Deployables

### Deployeds

### Other Configuration Items

## Configuration Item Details

### file.Archive

Type Hierarchy | udm.BaseDeployableArchiveArtifact >> udm.BaseDeployableFileArtifact >> udm.BaseDeployableArtifact >> udm.BaseDeployable >> udm.BaseConfigurationItem
Interfaces | udm.Taggable, udm.Deployable, udm.SourceArtifact, udm.ArchiveArtifact, udm.Artifact, udm.DeployableArtifact, udm.ConfigurationItem, udm.FileArtifact

An archive (zip, jar, tar, etc) artifact that can be packaged in a Deployment Package

|  | Public Properties
--- | --- | ---
|  | checksum : STRING
|  | The checksum used to detect differences on the artifact. If not provided, it will be calculated by Deployit.
|  | createTargetPath : STRING
|  | Create the targetPath on the host if it does not exist.
|  | excludeFileNamesRegex : STRING
|  | Regular expression that matches file names that must be excluded from scanning
|  | placeholders : SET_OF_STRING
|  | Placeholders detected in this artifact
|  | scanPlaceholders : BOOLEAN = false
|  | Whether to scan this artifact for placeholders when it is imported
|  | tags : SET_OF_STRING
|  | If set, this deployable will only be mapped automatically to containers with the same tag.
|  | targetFileName : STRING
|  | Name of the artifact on the host.
|  | targetPath : STRING
|  | Path to which artifact must be copied to when being deployed.
|  | targetPathShared : STRING
|  | Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.

|  | Hidden Properties
--- | --- | ---
|  | textFileNamesRegex : STRING = .+\.(cfg | conf | config | ini | properties | props | txt | asp | aspx | htm | html | jsf | jsp | xht | xhtml | sql | xml | xsd | xsl | xslt)
|  | Regular expression that matches file names of text files
|  | delimiters : STRING = {{ }}
|  | The delimiters used indicate placeholders, defaults to '{{ }}'. This is a 5 character string with a space in the middle, the first two are the leading delimiter, the last two are the closing delimiter

### file.DeployedArchive

Type Hierarchy | file.DeployedArtifactOnHost >> udm.BaseDeployedArtifact >> udm.BaseDeployed >> udm.BaseConfigurationItem
Interfaces | udm.EmbeddedDeployedContainer, udm.Artifact, udm.Deployed, udm.ConfigurationItem, udm.DerivedArtifact

The archive as deployed on the Host.

|  | Parent
--- | --- | ---
|  | container : CI<udm.Container>
|  | The container on which this deployed runs.

|  | Public Properties
--- | --- | ---
|  | targetPath : STRING
|  | Path to which artifact must be copied to on the host.
|  | createTargetPath : BOOLEAN = false
|  | Create the targetPath on the host if it does not exist.
|  | deployable : CI<udm.Deployable>
|  | The deployable that this deployed is derived from.
|  | placeholders : MAP_STRING_STRING
|  | A Map containing all the placeholders mapped to their values. Special values are <ignore> or <empty>
|  | targetFileName : STRING
|  | Name of the artifact on the host.
|  | targetPathShared : BOOLEAN = true
|  | Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.

|  | Hidden Properties
--- | --- | ---
|  | targetPathSharedSubDirectories : BOOLEAN = false
|  | The sub directories on the target machine are not deleted if files other than that copied by Deployit are present.

### file.DeployedArtifactOnHost

Virtual Type
Type Hierarchy | udm.BaseDeployedArtifact >> udm.BaseDeployed >> udm.BaseConfigurationItem
Interfaces | udm.EmbeddedDeployedContainer, udm.Artifact, udm.Deployed, udm.ConfigurationItem, udm.DerivedArtifact

Abstract deployed that can target any DeployableArtifact to a Host.

|  | Parent
--- | --- | ---
|  | container : CI<udm.Container>
|  | The container on which this deployed runs.

|  | Public Properties
--- | --- | ---
|  | targetPath : STRING
|  | Path to which artifact must be copied to on the host.
|  | createTargetPath : BOOLEAN = false
|  | Create the targetPath on the host if it does not exist.
|  | deployable : CI<udm.Deployable>
|  | The deployable that this deployed is derived from.
|  | placeholders : MAP_STRING_STRING
|  | A Map containing all the placeholders mapped to their values. Special values are <ignore> or <empty>
|  | targetFileName : STRING
|  | Name of the artifact on the host.
|  | targetPathShared : BOOLEAN = true
|  | Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.

|  | Hidden Properties
--- | --- | ---
|  | targetPathSharedSubDirectories : BOOLEAN = false
|  | The sub directories on the target machine are not deleted if files other than that copied by Deployit are present.

### file.DeployedFile

Type Hierarchy | file.DeployedArtifactOnHost >> udm.BaseDeployedArtifact >> udm.BaseDeployed >> udm.BaseConfigurationItem
Interfaces | udm.EmbeddedDeployedContainer, udm.Artifact, udm.Deployed, udm.ConfigurationItem, udm.DerivedArtifact

The file as deployed on the Host.

|  | Parent
--- | --- | ---
|  | container : CI<udm.Container>
|  | The container on which this deployed runs.

|  | Public Properties
--- | --- | ---
|  | targetPath : STRING
|  | Path to which artifact must be copied to on the host.
|  | createTargetPath : BOOLEAN = false
|  | Create the targetPath on the host if it does not exist.
|  | deployable : CI<udm.Deployable>
|  | The deployable that this deployed is derived from.
|  | placeholders : MAP_STRING_STRING
|  | A Map containing all the placeholders mapped to their values. Special values are <ignore> or <empty>
|  | targetFileName : STRING
|  | Name of the artifact on the host.
|  | targetPathShared : BOOLEAN = true
|  | Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.

|  | Hidden Properties
--- | --- | ---
|  | targetPathSharedSubDirectories : BOOLEAN = false
|  | The sub directories on the target machine are not deleted if files other than that copied by Deployit are present.

### file.DeployedFolder

Type Hierarchy | file.DeployedArtifactOnHost >> udm.BaseDeployedArtifact >> udm.BaseDeployed >> udm.BaseConfigurationItem
Interfaces | udm.EmbeddedDeployedContainer, udm.Artifact, udm.Deployed, udm.ConfigurationItem, udm.DerivedArtifact

The folder as deployed on the Host.

|  | Parent
--- | --- | ---
|  | container : CI<udm.Container>
|  | The container on which this deployed runs.

|  | Public Properties
--- | --- | ---
|  | targetPath : STRING
|  | Path to which artifact must be copied to on the host.
|  | createTargetPath : BOOLEAN = false
|  | Create the targetPath on the host if it does not exist.
|  | deployable : CI<udm.Deployable>
|  | The deployable that this deployed is derived from.
|  | placeholders : MAP_STRING_STRING
|  | A Map containing all the placeholders mapped to their values. Special values are <ignore> or <empty>
|  | targetPathShared : BOOLEAN = true
|  | Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.

|  | Hidden Properties
--- | --- | ---
|  | targetFileName : STRING
|  | Not applicable for this type.
|  | targetPathSharedSubDirectories : BOOLEAN = false
|  | The sub directories on the target machine are not deleted if files other than that copied by Deployit are present.

### file.File

Type Hierarchy | udm.BaseDeployableFileArtifact >> udm.BaseDeployableArtifact >> udm.BaseDeployable >> udm.BaseConfigurationItem
Interfaces | udm.Taggable, udm.Deployable, udm.SourceArtifact, udm.Artifact, udm.DeployableArtifact, udm.ConfigurationItem, udm.FileArtifact

A single file artifact that can be packaged in a Deployment Package

|  | Public Properties
--- | --- | ---
|  | checksum : STRING
|  | The checksum used to detect differences on the artifact. If not provided, it will be calculated by Deployit.
|  | createTargetPath : STRING
|  | Create the targetPath on the host if it does not exist.
|  | excludeFileNamesRegex : STRING
|  | Regular expression that matches file names that must be excluded from scanning
|  | placeholders : SET_OF_STRING
|  | Placeholders detected in this artifact
|  | scanPlaceholders : BOOLEAN = true
|  | Whether to scan this artifact for placeholders when it is imported
|  | tags : SET_OF_STRING
|  | If set, this deployable will only be mapped automatically to containers with the same tag.
|  | targetFileName : STRING
|  | Name of the artifact on the host.
|  | targetPath : STRING
|  | Path to which artifact must be copied to when being deployed.
|  | targetPathShared : STRING
|  | Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.

|  | Hidden Properties
--- | --- | ---
|  | textFileNamesRegex : STRING = .+\.(cfg | conf | config | ini | properties | props | txt | asp | aspx | htm | html | jsf | jsp | xht | xhtml | sql | xml | xsd | xsl | xslt)
|  | Regular expression that matches file names of text files
|  | delimiters : STRING = {{ }}
|  | The delimiters used indicate placeholders, defaults to '{{ }}'. This is a 5 character string with a space in the middle, the first two are the leading delimiter, the last two are the closing delimiter

### file.Folder

Type Hierarchy | udm.BaseDeployableFolderArtifact >> udm.BaseDeployableArtifact >> udm.BaseDeployable >> udm.BaseConfigurationItem
Interfaces | udm.Taggable, udm.Deployable, udm.SourceArtifact, udm.Artifact, udm.DeployableArtifact, udm.ConfigurationItem, udm.FolderArtifact

A folder artifact that can be packaged in a Deployment Package

|  | Public Properties
--- | --- | ---
|  | checksum : STRING
|  | The checksum used to detect differences on the artifact. If not provided, it will be calculated by Deployit.
|  | createTargetPath : STRING
|  | Create the targetPath on the host if it does not exist.
|  | excludeFileNamesRegex : STRING
|  | Regular expression that matches file names that must be excluded from scanning
|  | placeholders : SET_OF_STRING
|  | Placeholders detected in this artifact
|  | scanPlaceholders : BOOLEAN = true
|  | Whether to scan this artifact for placeholders when it is imported
|  | tags : SET_OF_STRING
|  | If set, this deployable will only be mapped automatically to containers with the same tag.
|  | targetFileName : STRING
|  | Name of the artifact on the host.
|  | targetPath : STRING
|  | Path to which artifact must be copied to when being deployed.
|  | targetPathShared : STRING
|  | Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.

|  | Hidden Properties
--- | --- | ---
|  | textFileNamesRegex : STRING = .+\.(cfg | conf | config | ini | properties | props | txt | asp | aspx | htm | html | jsf | jsp | xht | xhtml | sql | xml | xsd | xsl | xslt)
|  | Regular expression that matches file names of text files
|  | delimiters : STRING = {{ }}
|  | The delimiters used indicate placeholders, defaults to '{{ }}'. This is a 5 character string with a space in the middle, the first two are the leading delimiter, the last two are the closing delimiter