TIBCO Business Studio Command-Line Task Reference

Note: When you use context assist when editing a build file, all elements and attributes appear as lower case.

sds.addProjectDependency

Adds a dependency on a reference project to a source project.

Attribute Description
referenceProject The referenced SOA project.
sourceProject The SOA project to which to add the dependency.

Example

<sds.addProjectDependency sourceProject="MySoaProject" referenceProject="jv.helloworld.soa"/>

sds.createComponent

Creates a component from a component implementation. See component development manuals for configuration specific to each component type.

After creating the component and before creating a DAA from the composite containing the component, do the following:
  • If you import an implementation project and an SOA project containing a WSDL file, and create the component in another project that references the implementation and SOA projects, add a project dependency from the project containing the component to the implementation and the WSDL projects using the noPageCitation task.
  • If the component implementation has properties, promote the properties using the sds.promoteAll task.
Attribute or Element Description
componentName The name of the component to be created.
compositeName The name of the composite in which to create the component.
implementationLoc The path to the implementation file. For component type specific requirements on the path, see the appropriate component development guide.
projectName The name of the SOA project containing the composite in which to create the component.

Example

<sds.createComponent projectName="NewSoaProject" compositeName="MyComposite" 
componentName="MyComponent" implementationLoc="MyImpl">
</sds.createComponent>

sds.createComposite

Creates a composite in an SOA project.

Attribute Description
compositeName The name of the composite to be created.
projectName The name of the SOA project in which to create the composite.

Example

<sds.createComposite projectName="MySoaProject" compositeName="MyComposite"/>

sds.createDAA

Packages child elements into a distributed application archive.

Attribute or Element Description
daaLoc The location of the DAA file to be created. One of:
  • AppName.daa - Creates a DAA with the specified name in the first Deployment Artifacts folder in the projectName project. If no such folder exists the DAA is stored in the root of the projectName project. If the projectName project does not exist then the task fails.
  • Path/AppName.daa - Creates a DAA in the specified path within the projectName project. Fails if projectName is not specified. Creates any folders that don't exist in the specified path.
  • /ProjectName/Path/AppName.daa - Creates a DAA in the specified project and path in the workspace. Fails if the project does not exist. Creates any folders that don't exist in the specified path.
failOnUnresolvedReference Indicated whether the task should fail if any referenced objects cannot be resolved.
id Optional. An ID for the DAA.
includeApplicationReferences Optional. When true, all references to resource templates, features, and substitution variable files will be searched for in the scope of each application being packaged. If found and are unique, then the corresponding files will be packaged into the DAA. If not found or are not unique, then the packaging will proceed without packaging the referenced resource templates, features, and substitution variable files.

When false, then referenced resource templates, features, and substitution variables files will not be automatically packaged into the DAA. In this case you must explicitly specify the resource templates to package for each application using the appropriate nested child elements.

Default: true.
overwriteExistingDAA Optional. When true, if a DAA already exists in the location specified by the daaLoc attribute this file will be overwritten with the new DAA. When false, if a DAA already exists in the location specified by the daaLoc attribute then the createDAA task fails.

Default: true.

projectName The project name that resolves application elements specified by name. Required if one of the following is true:
  • An application element is referenced by name and does not have a projectName attribute
  • A fully qualified path is not provided for daaLoc
qualifier Optional. The value to use for the qualifier portion of the version.

A qualifier replacement.

Default: The qualifier replacement template 'v'yyyy-MM-DD-HHmm.

skipProjectBuild Indicate that you do not want to build the workspace each time the task is invoked. You can invoke the eclipse.incrementalBuild task to build projects incrementally.

Default: false.

version Optional. The version of the DAA. If not set then no version is assigned.
child elements One or more instances of:
  • application - Packages a composite or distribution and its referenced composite in the DAA.
  • feature - Packages a feature.
application Attributes
Attribute or Element Description
compositeName The name of the composite to package. This is the name stored in the name field of the composite, not the name of the composite file. In some cases this name will match the filename without the extension, but they may be different.

All composite files in Composites folders in the scope of projectName are searched. The scope is the projectName project itself and all referenced projects recursively. If the name is not unique within the scope, the createDAA task will fail.

Mutually exclusive with the location attribute.

location The location in the workspace of a composite or distribution file to package.

Mutually exclusive with the compositeName and projectName attributes.

projectName The name of the project in whose scope the composite specified by the compositeName attribute will be searched for. This is the name of the project as specified in the .project file, not the name of the folder in the filesystem path. In some cases this name will match the folder name, but they may be different.

Required when compositeName is specified and projectName is not specified in the createDAA element.

Mutually exclusive with the location attribute.

resourceTemplate Packages a resource template.
feature Attributes and Subelements
Attribute or Element Description
exclude Optional. Indicate that the specified feature should not be packaged. Use if you want to specify includeApplicationReferences="true" and exclude one or more features. The only valid value for this attribute is true.
id The ID of the feature to package or exclude. All open projects in the workspace will be searched for a feature project or a custom feature file with a matching ID. If not found or if more than one match is found, the createDAA task will fail.
packagePlugin Package a pre-built bundle referenced by the feature. To package one bundle you can use either the path element or the location attribute; path and location cannot both used.
packagePlugin Attributes and Subelements
Attribute or Element Description
location The fully-qualified path to the bundle.
path A string containing paths to one or more bundles. You can use ";"  or ":"  as path separators and Ant will convert it to the platform's local conventions.
updateBundleVersion Overwrites the version of the bundle. Useful to replace "snapshot" when the bundle was built by Maven.
updateQualifier Overwrites the qualifier of the bundle. Useful to replace "snapshot" when the bundle was built by Maven.

A qualifier replacement.

path Attributes and Subelements
Attribute or Element Description
id The name of the Ant property that stores the list of paths specified by the path element. For further information, see resource collections.
dirset A set of directories.
fileset A set of files.
dir The fully-qualified path to the root of the dirset set of directories or the fileset set of files.
include A pattern that specifies the files to include.
exclude A pattern that specifies the files to exclude.
resourceTemplate Attributes
Attribute Description
exclude Optional. A resource template to exclude from being packaged. Use if you want to specify includeApplicationReferences="true" in the createDAA task and then exclude one or more resource templates. The only valid value for this attribute is true.
name The name of the resource template to package. This is the name stored in the name field of the resource template not the name of the resource template file. In some cases this name will match the filename without the extension, but they may be different.

All resource template files in all Resource Templates folders in the scope of projectName will be searched. The scope is the projectName project itself and all referenced projects recursively. If the name is not unique within the scope, the createDAA operation will fail.

Note: You can only list resource templates that are referenced from the composite being packaged. If you list a resource template that is not referenced the createDAA operation will fail.

Example

<sds.createDAA projectName="MyProject" daaLoc="/MyProject/Deployment Artifacts/MyApp.daa" 
includeApplicationReferences="false" overwriteExistingDAA="false" qualifier="20121010" >

	<application compositeName="MyFirstApp" projectName="MyFirstProject"/>

	<application location="/SomeOtherProject/Composites/MyApp.composite">
		<resourcetemplate name="MySMTP"/>
		<resourcetemplate name="SomeHTTP"/>
	</application>

	<application location="/MyProject/Composites/MyOtherApp.dist"/>
  
	<feature id="com.sample.myfeature">
		<packagePlugin updateBundleVersion="2.6.0.qualifier" updateQualifier="20121010">                         
			<path id="includePlugin">                          
				<fileset dir="/ImplJars">
					<include name="*/.jar"/>
				</fileset>                        
			</path>
		</packagePlugin>
	</feature>         
	<feature id="com.sample.myfirstfeature"> 
</sds.createDAA>

sds.createSoaProject

Creates an empty SOA project.

Attribute Description
projectName The name of the SOA project to create.

Example

<sds.createSoaProject projectName="MySoaProject"/>

sds.generateDeploymentScript

Generate an Administrator CLI script (see Administrator Command-Line Interface) to deploy a DAA into a remote Administrator server. It generates a deployment script (that is, a build file and a data file) from a DAA that only contains custom features using TIBCO ActiveMatrix Administrator CLI format.

Attribute or Element Description
adminServer Optional. The configuration information for the Administrator server.
appConfig Required. The configuration information for the application created from the DAA. Either singleNodeName or hostAppName is required.
createSVars Optional. Overrides substitution variable values in the generated CLI scripts. To override, enable the generation of <SVar> elements in the deployment-config.xml file, allowing you to manually change the <SVar> values.

Default: False.

daaLoc The absolute path in the workspace to the DAA.
includeCleanupTasks Optional. If true, the generated script will contain delete and undeploy tasks.

Default: false.

outputLoc The folder to contain the generated script files.

Default: The folder containing the DAA.

projectName The name of the SOA project containing the DAA.
tokenizeScript Optional. Indicate whether some object attributes, such as the deployment environment and node names, application name and version, and property values, should be externalized into a properties file so that you can optionally update them each time you run the build file.

Default: false.

excludeVersionQualifier

Optional. Includes or excludes the application template and feature version qualifiers in the 'Administrator CLI Script Generation' wizard.

Default: True

Using excludeVersionQualifier=false generates the configuration file with qualifiers.

For example,
  • if you set excludeVersionQualifier to true, version is stored as 1.0.0
  • If you set excludeVersionQualifier to false, version is stored as 1.0.0.v2014-05-20-1409
adminServer Attributes
Attribute Description
URL The URL of the offline server.

Default: http://localhost:8120.

username Name of the Administrator user who is executing the task. The user must have the permissions required to execute the actions in the script.

Default: root.

password Password of the Administrator user executing the task.

Default: t.

appConfig Attributes
Attribute Description
appName The name of the application. Application names cannot contain the characters \, /, :, *, ?, ", <, >, |, whitespace, %, #, &, (, ), or comma.

Default: The name of the DAA.

environmentName The environment in which to deploy the application.

Default: DevEnvironment.

singleNodeName The node on which to deploy all application fragments.
multipleNodeNames List of comma-separated Nodes on which to deploy all application fragments.
hostAppName The name of the application with which to deploy the application.

Example 1

The following example deploys MyApp on the DevNode in the DevEnvironment.

<sds.generateDeploymentScript daaLoc="/MyProject/Deployment Artifacts/MyApp.daa" projectName="MyProject" >
<appconfig appName="MyApp" singleNodeName="DevNode" environmentName="DevEnvironment" />
</sds.generateDeploymentScript>

The following example deploys the sample application on multiple Nodes: DevNodeA, DevNodeB, and DevNodeC.

<sds.generateDeploymentScript daaLoc="/MyProject/Deployment Artifacts/MyApp.daa" projectName="MyProject" >
<appconfig appName="MyApp"  multipleNodeNames="DevNodeA,DevNodeB,DevNodeC"  environmentName="DevEnvironment" />
</sds.generateDeploymentScript>

Example 2

sds.generateDeploymentScript daaloc="/path/to/MyApplication.daa" 
     outputloc="/path/to/generate/deployment/scripts" tokenizescript="false" 
     excludeVersionQualifier="true" includeCleanupTasks="false">
  
  <featureconfig environmentName="DevEnvironment" nodeNames="DevNode"
        syncNodes="true" upgrade="true"/>

  <adminserver version="<version_number>" url="http://localhost:8120" 
      username="root" password="test"/>
</sds.generateDeploymentScript>

Generating a Deployment Script with Custom Features

You can generate a deployment script from a DAA that only contains custom features. This capability is only available via headless mode (sds.generateDeploymentScript target of TIBCO Business Studio CLI). This generates a build file and a data file using TIBCO ActiveMatrix Administrator CLI format.

Sample TIBCO Business Studio CLI script for a deployment script generation:

<sds.generateDeploymentScript
daaloc="/path/to/MyApplication.daa" 
outputloc="/path/to/generate/deployment/scripts"
tokenizescript="false" 
excludeVersionQualifier="true"
includeCleanupTasks="false">
<featureconfig environmentName="DevEnvironment"
nodeNames="DevNode"
syncNodes="true" upgrade="true"/>
<adminserver version="<version_number>" url="http://localhost:8120" 
username="root" password="test"/>
</sds.generateDeploymentScript>

The generated build file has the following targets:

  • upload.daa: Uploads the DAA containing features to Administrator.
  • addOrUpgrade.features or enable.features:
    • If upgrade is set to true, the generated target is called addOrUpgrade.features. This target replaces old features on a node with new ones from the DAA. More details are provided below.
    • If upgrade is set to false, the generated target is called enable.features. This target only adds the new features from the DAA but leaves the old features on the node as is.

    The addOrUpgrade CLI action has been added for the <Node> and <Feature> elements. The Studio CLI uses this action. This action adds the features from your data file to the nodes. For example, feature com.acme.myapp.feature 1.5.0 gets added to DevNode with status Marked for Install. This action also removes any other versions of the same feature, if they were present on the nodes. Features with a different major version are not affected. For example, feature com.acme.myapp.feature 1.0.0 and 1.6.0 are changed to status Marked for Uninstall, since any version not matching "1.5.0" will be marked for removal. However, feature com.acme.myapp.feature 2.0.0 is left as is, because it has a different major version.

  • reprovision.nodes: Applies feature changes to runtime in resolve mode, which restarts the nodes to rewire existing applications to use the new versions of features. If syncNodes is set to false, this target is not generated in the build file.

sds.generateDistribution

Generates a default distribution, with all elements mapped to node Node1.

Attribute Description
compositeName The name of the composite to distribute.
distributionName The name of the distribution.
projectName The name of the SOA project containing the composite in which the component is located.

Example

<sds.generateDistribution projectName="jv.helloworld.soa compositeName="MyComposite" 
distributionName="MyDistribution" />

tbs.importProjects

Imports one or more Eclipse projects (including ActiveMatrix BPM, SOA, Implementation, Java, and so on) from archives (.zip, .tar, .tar.gz) or project folder structures.

Tip: We recommend that you use tbs.importProjects rather than sds.importProject for TIBCO ActiveMatrix BPM projects, as it provides far more stable post import migration and building.

Two approaches can be adopted when importing projects using this task:

  • A simple, attribute-only based, approach suitable for basic scenarios
  • A more flexible approach making use of the pre-existing nested Ant tasks, FileSet and DirSet

A single invocation of the task must be configured to import projects from either folder-based structures or archives, but not both.

Attribute Description
dir Optional. The root directory to use for simple format folder structure imports.
Note: dir and file are mutually exclusive.
file
Optional. The archive file to use for simple format archive imports (including .zip, .tar, .tar.gz)
Note: dir and file are mutually exclusive.
copyProjects Optional. Ensures a copy of any imported project is made to the workspace. Applicable only to folder structure imports.

Default: true

useArchives Optional. Ensures archive import is attempted when using nested element format.

When a simple format archive import (using the file attribute) is used, the useArchives attribute is not required. It is implicitly set to true.

Default: false

skipPostImportTask Optional. Post import tasks are skipped when set to true.

Default: false

When importing a single archive from a known location, the simple task format can be used. In this case, the task declaration includes the file attribute. The dir attribute cannot be used for archive importing.

For example, to import projects from a specific archive (C:\project_archives\testprojs.zip), the following simple task declaration can be used:

<tbs.importProjects file="C:\project_archives\testprojs.zip"/> 

For more flexible archive importing, the task's nested format can be used. This permits the importing of multiple archives and a more flexible way to describe the locations of the archives to be imported. To do this, the useArchives attribute needs to be set to true and one or more of the supported nested elements must be declared to describe candidate archive locations. Both types of nested elements (FileSet and DirSet) can be used for archive importing.

For example, to import projects from a specific archive (C:\project_archives\testprojs.zip), the nested FileSet element can be used as follows:

<tbs.importProjects useArchives="true"> <fileset
dir="C:\src\projects" includes="testproj.zip"/>
</tbs.importProjects>

A more useful implementation of the nested element format can be seen in the following example where importing is set up to be selective for tar archives:

<tbs.importProjects useArchives="true"> <fileset
dir="C:\src\projects" includes="**/*.tar"/>
</tbs.importProjects>

When importing a project or a set of projects contained within a single directory structure, the task's simple format can be used. This, however, does not allow you to be selective about which projects within the directory structure are imported; all identified projects are imported. To use the simple format, the task declaration needs to include the dir attribute.

For example, to import all folder-based projects contained within a directory, the following format can be used:

<tbs.importProjects dir="C:\folder_projects" /> 

For more flexible folder-based project importing, the task's nested format can be used where one or more DirSet elements can be declared to specify the directories to search.

Using the nested format, the previous example could be expressed as:

<tbs.importProjects> <dirset dir="C:\src\projects"/>
</tbs.importProjects> 

A more useful application of the nested element format could be the following, where only projects contained within directories having a certain substring in their name are considered:

<tbs.importProjects> <dirset dir="C:\src\projects">
<include name="**/*bpmproj"/> </dirset>
</tbs.importProjects> 

Optionally, the copyProjects attribute can also be used with project folder imports. When set to false, no copy of the imported projects is made to the workspace.

Imports one or more Eclipse projects (including ActiveMatrix BPM, SOA, Implementation, Java, and so on) into a workspace. To import one project you can use either the path element or the projectLoc attribute; path and projectLoc cannot both used.
Note: This function is included for backward compatibility and tbs.importProjects is recommended for new scripts.
Attribute or Element Description
copyFiles Optional. Indicate whether to copy the project files into the workspace.

Default: false.

overwrite Optional. Indicate whether to overwrite a project that already exists in the workspace. If set to false, and the project already exists in the workspace, the task will report an error.

Default: false.

path A string containing paths to one or more projects. You can use ";"  or ": " as path separators and Ant will convert it to the platform's local conventions.
projectLoc The fully-qualified path to the project.
path Attributes and Subelements
Attribute or Element Description
id The name of the Ant property that stores the list of paths specified by the path element. For further information, see resource collections.
dirset A set of directories.
fileset A set of files.
dir The fully-qualified path to the root of the dirset set of directories or the fileset set of files.
include A pattern that specifies the files to include.
exclude A pattern that specifies the files to exclude.

Example

<sds.importProject overwrite="true">  copyFiles="true">
	<path id="projectsToImport"> 
		<dirset dir="C:/helloworld1/jv.helloworld.soa"/>  
		<dirset dir="C:/helloworld1/jv.helloworld.jv"/>  
	</path>  
</sds.importProject>

Example

<sds.importProject projectLoc="C:/helloworld1/jv.helloworld.soa" />
library Attributes
Attribute Description
jarworkspacepath The workspace-qualified path to a library JAR file.
overwriteifexists Optional. Indicate whether to overwrite a library that already exists in the workspace. If set to false, and the library already exists in the workspace, the task will report an error.
type The type of data binding technology:
  • Beans
  • Interface
wsdlorschemaworkspacepath The workspace-qualified path to a WSDL or schema file.

Example

<sds.javait.regenerateLibraries>  
	<library jarworkspacepath="/Schemas.libs/libs/BaseTypes.xsd.jar" 
		overwriteifexists="true" type="Beans" 
		wsdlorschemaworkspacepath="/Schemas/base/BaseTypes.xsd"/>  
	<library jarworkspacepath="/Schemas.libs/libs/CompanyTypes.xsd.jar"
		overwriteifexists="true" type="Beans"
		wsdlorschemaworkspacepath="/Schemas/base/CompanyTypes.xsd"/>  
</sds.javait.regenerateLibraries>  

sds.promoteAll

Promotes all a component's unwired services and references to the composite level.

Attribute Description
componentName The name of the component.
compositeName The name of the composite containing the component.
projectName The name of the SOA project containing the composite in which the component is located.

Example

<sds.promoteAll projectName="MySoaProject" compositeName="MyComposite" componentName="MyComponent"/>

sds.wire

Wires a component reference to a component service.

Attribute Description
compositeName The name of the composite containing the service and reference.
projectName The name of the SOA project containing the composite in which the component is located.
source The service in the format componentName/serviceName.
target The reference in the format componentName/referenceName.

Example

<sds.wire projectName="MySoaProject" compositeName="MyComposite" 
source="MyComponent/MyService" target="MyComponent/MyReference"/>