BLAManagement wsadmin scripting
- Overview
- deleteAsset
- editAsset
- exportAsset
- importAsset
- listAssets
- updateAsset
- viewAsset
- addCompUnit
- deleteCompUnit
- editCompUnit
- listCompUnits
- setCompUnitTargetAutoStart
- viewCompUnit
- createEmptyBLA
- deleteBLA
- editBLA
- getBLAStatus
- listBLAs
- listControlOps
- startBLA
- stopBLA
- viewBLA
Overview
Use the Jython scripting language to administer business-level applications with the wsadmin tool. Use the commands in the BLAManagement group to create, edit, export, delete, and query business-level applications in the configuration.
To administer business-level applications use the Configurator administrative role.
An asset represents one or more application binary files stored in an asset repository. Typical assets include application business logic such as enterprise archives, library files, and other resource files.
A business-level application is a configuration artifact that consists of zero or more composition units or other business-level applications. Business-level applications are administrative models that define an application, and can contain EAR files, shared libraries, PHP applications, and more.
A composition unit represents an asset in a business-level application. A composition unit enables the asset contents to interact with other assets in the application. It also enables the product run time to load and run asset contents.
deleteAsset
Remove an asset from a business-level application configuration. Before using this command, verify that no composition units are associated with the asset of interest. The command fails if the asset is associated with composition units.
Target object: None
Required parameters:
- -assetID
- Configuration ID of the asset to delete. The command accepts incomplete IDs for the assetID parameter, as long as the system can match the string to a unique asset. (String, required)
Optional parameters:
- -force
- Specifies whether to force the system to delete the asset, even if other assets depend on this asset. (Boolean, optional)
Return value.
The command returns the configuration ID of the deleted asset:
- WebSphere:assetname=asset2.zip
Batch mode example usage
- Use Jython string:
- AdminTask.deleteAsset('-assetID asset2.zip -force true')
- Use Jython list:
- AdminTask.deleteAsset(['-assetID', 'asset2.zip', '-force', 'true'])
Interactive mode example usage
- Use Jython:
- AdminTask.deleteAsset('-interactive')
editAsset
Modify additional asset configuration options. Use this command to modify the description, destination URL, asset relationships, file permissions, and validation settings.
Target object: None
Required parameters:
- -assetID
- Configuration ID of the asset to edit. This parameter accepts an incomplete configuration ID, as long as the system can match the string to a unique asset ID. (String, required)
Optional steps
For optional steps, use the .* characters to specify a read-only argument in the command syntax. Specify an empty string with the "" characters to keep the existing value of the argument. If we do not specify a value or an empty string for a writable argument, the command resets the argument to a null value.
- -AssetOptions
- Use the AssetOptions step and the following arguments to set additional properties for the asset.
- inputAsset (read-only)
- Source package of the asset.
- name (read-only)
- Name of the asset. The default value for this argument is the file name of the source package.
- defaultBindingProps (read-only)
- Default binding properties for the asset. This argument only applies to enterprise assets. For assets which are not enterprise assets, specify the asterisk character (*) for pattern matching. For enterprise assets, specify the .* value to set the argument as a non-empty value.
- description
- Description for the asset.
- destinationUrl
- The URL of the asset binaries to deploy.
- typeAspect
- Asset type aspect.
- relationship
- Asset relationship. Use the plus sign character (+) to add additional assets to the existing relationship. Use the number sign character (#) to delete an existing asset from the relationship. To replace the existing relationships, specify the same syntax as in the importAsset command. If the asset specified in the relationship does not exist for add or update, the command returns an exception.
- filePermission
- File permission configuration.
- validate
- Specifies whether to validate the asset. The default is false. The product does not save the value specified for validate. Thus, if we select to validate the asset (true) now and later edit the asset, when you edit the asset enable this setting again for the product to validate the updated files.
- -UpdateAppContentVersions
- For an EBA asset, use this step and the following arguments to select bundle versions for the asset.
Apply bundle changes to the asset by updating the composition unit. We do not need to restart the running business-level application. To update the composition unit, run the editCompUnit command with the CompUnitStatusStep parameter.
- bundle_name
- Name of the bundle.
- current_version
- Specifies either a bundle version number, for example 1.0.0, or NOT_DEPLOYED for shared bundles (that is, use bundles) that are declared in the application manifest but not deployed by the runtime environment. This argument describes the current configuration of the bundle, and is not used to change the configuration.
- update_preference
- New bundle version preference. This is either a bundle version number, for example 1.0.0, or NOT_DEPLOYED for shared bundles, or NO_PREF if we want the system to choose a bundle version for you. If we do not want to update the version for a given bundle, set this attribute to the same value that we are using for the current_version attribute.
- Include an entry (that is, the bundle_name current_version and update_preference) for each bundle listed in the application manifest between the application content header and the use bundle header. Include every bundle, whether or not we are updating the bundle version.
- Specify the syntax as
follows:
- AdminTask.editAsset('[
-assetID asset_name
-UpdateAppContentVersions [
[bundle_1_name current_version update_preference]
[bundle_2_name current_version update_preference]
[bundle_3_name current_version update_preference]
[bundle_4_name current_version update_preference]
[bundle_5_name current_version update_preference]
]]')
Return value.
The command returns the configuration ID of the asset of interest.
Batch mode example usage
Use the following examples to edit a non-enterprise asset:
- Use Jython string:
- AdminTask.editAsset('-assetID asset3.zip -AssetOptions [[.* asset3.zip * "asset for testing"
c:/installedAssets/asset3.zip/BASE/asset3.zip "" assetname=a.jar "" false]]')
- Use Jython list:
- AdminTask.editAsset(['-assetID', 'asset3.zip', '-AssetOptions', '[[.* asset3.zip * "asset for testing"
c:/installedAssets/asset3.zip/BASE/asset3.zip "" assetname=a.jar "" false]]'])
Use the following examples to edit an enterprise asset:
- Use Jython string:
- AdminTask.editAsset('-assetID defaultapp.ear -AssetOptions
[[.* defaultapp.ear .* "asset for testing" "" "" "" "" false]]')
- Use Jython list:
- AdminTask.editAsset(['-assetID', 'defaultapp.ear', '-AssetOptions',
'[[.* defaultapp.ear .* "asset for testing" "" "" "" "" false]]'])
Interactive mode example usage
- Use Jython:
- AdminTask.editAsset('-interactive')
exportAsset
Export an asset configuration to a file.
Target object: None
Required parameters:
- -assetID
- Configuration ID of the asset to export. This parameter accepts an incomplete configuration ID as long as the ID matches a unique asset. (String, required)
- -filename
- File name to which the system exports the asset configuration. (DownloadFile, required)
Return value. The command does not return output.
Batch mode example usage
- Use Jython string:
- AdminTask.exportAsset('-assetID asset2.zip -filename c:/temp/a2.zip')
- Use Jython list:
- AdminTask.exportAsset(['-assetID', 'asset2.zip', '-filename', 'c:/temp/a2.zip'])
Interactive mode example usage
- Use Jython:
- AdminTask.exportAsset('-interactive')
importAsset
Import an asset configuration to the asset repository. After importing assets, we can add the assets to business-level applications as composition units.
Target object: None
Required parameters:
- -source
- Name of the source file to import. (UploadFile, required)
Optional parameters:
- -storageType
- The way the system saves the asset in the asset repository. The default asset repository stores full binaries, metadata of binaries, or no binaries. Specify FULL to store full binaries. Specify METADATA to store the metadata portion of the binaries. Specify NONE to store no binaries in the asset repository. The default is FULL. (String, optional)
Optional steps
For optional steps, use the .* characters to specify a read-only argument in the command syntax. Specify an empty string with the "" characters to keep the existing value of the argument. If we do not specify a value or an empty string for a writable argument, the command resets the argument to a null value.
- -AssetOptions
- Use the AssetOptions step and the following arguments to set additional properties for the asset.
- inputAsset (read-only)
- Source package of the asset.
- name
- Name of the asset. The extension file name of the asset must match the extension file name of the source package. The default value for this argument is the file name of the source package.
- defaultBindingProps (read-only)
- Default binding properties for the asset. This argument only applies to enterprise assets. For assets which are not enterprise assets, specify the asterisk character (*) for pattern matching. For enterprise assets, specify the .* value to set the argument as a non-empty value.
- description
- Description for the asset.
- destinationUrl
- The URL of the asset binaries to deploy.
- typeAspect
- Asset type aspect. TypeAspect option in object name format, as the following syntax demonstrates: spec=xxx
- relationship
- Asset relationship. Use the plus sign character (+) to specify multiple asset relationships. The command returns an exception if we specify assets in the relationship that do not exist.
- filePermission
- File permission configuration.
OSGi applications do not use a filePermission value.
- validate
- Specifies whether to validate the asset. The default is false. The product does not save the value specified for validate. Thus, if we select to validate the asset
(true) now and later edit the asset, when you edit the asset enable this setting again for the product to validate the updated files.
OSGi applications do not use a validate value.
Return value.
The command returns the configuration ID of the asset the system creates:
- WebSphere:assetname=asset2.zip
Batch mode example usage
Use the following examples to import a non-enterprise asset:
- Use Jython string:
- AdminTask.importAsset('-source c:\ears\asset1.zip -storageType NONE')
- Use Jython list:
- AdminTask.importAsset(['-source', 'c:\ears\asset1.zip', '-storageType', 'NONE'])
Use the following examples to import a non-enterprise asset, set asset2.zip as the asset name, save the metadata binaries in the asset repository, and set the destination directory of the binaries to deploy:
- Use Jython string:
- AdminTask.importAsset('-source c:\ears\asset1.zip -storageType METADATA -AssetOptions
[[.* asset2.zip .* "asset for testing" c:/installedAssets/asset2.zip/BASE/asset2.zip "" "" "" "" false]]')
- Use Jython list:
- AdminTask.importAsset(['-source', 'c:\ears\asset1.zip', '-storageType', 'METADATA', '-AssetOptions',
'[[.* asset2.zip .* "asset for testing" c:/installedAssets/asset2.zip/BASE/asset2.zip "" "" "" "" false]]')
Use the following examples to import a non-enterprise asset, and specifies asset relationships with the a.jar and b.jar assets:
- Use Jython string:
- AdminTask.importAsset('[-source c:\ears\asset3.zip -storageType FULL -AssetOptions
[[.* asset3.zip .* "asset for testing" "" spec=zip assetname=a.jar+assetname=b.jar "" false]]]')
- Use Jython list:
- AdminTask.importAsset(['-source', 'c:\ears\asset3.zip', '-storageType', 'FULL', '-AssetOptions',
'[[.* asset3.zip .* "asset for testing" "" spec=zip assetname=a.jar+assetname=b.jar "" false]]'])
Use the following examples to import an enterprise asset:
- Use Jython string:
- AdminTask.importAsset('-source c:\ears\defaultapplication.ear -storageType FULL -AssetOptions
[[.* defaultapp.ear .* "desc" "" "" "" false]]')
- Use Jython list:
- AdminTask.importAsset(['-source', 'c:\ears\defaultapplication.ear', '-storageType',
'FULL', '-AssetOptions', '[[.* defaultapp.ear .* "desc" "" "" "" false]]'])
Interactive mode example usage
- Use Jython:
- AdminTask.importAsset('-interactive')
listAssets
Display the configuration ID of each asset within the cell.
Target object: None
Optional parameters:
- -assetID
- Configuration ID of the asset of interest. This parameter accepts an incomplete configuration ID as long as the ID matches a unique asset. (String, optional)
- -includeDescription
- Specifies whether to include the a description of each asset that the command returns. Specify true to display the asset descriptions. (String, optional)
- -includeDeplUnit
- Specifies whether to display the deployable units for each asset that the command returns. Specify true to display the deployable units. (String, optional)
Return value.
The command returns a list of configuration IDs for the assets of interest. Depending on the parameter values specified, the command might display the description and deployable composition units for each asset:
- WebSphere:assetname=asset1.zip
"asset for testing"
WebSphere:assetname=asset2.zip
"second asset for testing"
a.jar
WebSphere:aasetname=asset3.zip
"third asset for testing"
a1.jar+a2.jar
WebSphere:assetname=a.jar0
"a.jar for sharedlib"
WebSphere:assetname=b.jar
"b.jar for sharedlib"
WebSphere:assetname=defaultapp.ear
"default app"
Batch mode example usage
Use the following examples to list each asset in the cell:
- Use Jython:
- AdminTask.listAssets()
Use the following examples to list each asset in the cell:
- Use Jython string:
- AdminTask.listAssets('-assetID asset1.zip')
- Use Jython list:
- AdminTask.listAssets(['-assetID asset1.zip'])
Use the following examples to list each asset, asset description, and deployable composition units in the cell:
- Use Jython string:
- AdminTask.listAssets('-includeDescription true -includeDeplUnit true')
- Use Jython list:
- AdminTask.listAssets(['-includeDescription', 'true', '-includeDeplUnit', 'true')
Interactive mode example usage
- Use Jython:
- AdminTask.listAssets('-interactive')
updateAsset
Modify one or more files or module files of an asset. The command updates the asset binary file, but does not update the composition units the system deploys with the asset as a backing object.
Target object: None
Required parameters:
- -assetID
- Configuration ID of the asset to update. This parameter accepts an incomplete configuration ID as long as the ID matches a unique asset. (String, required)
- -operation
- Operation to invoke on the asset of interest. (String, required)
- The following table displays each operation that we can invoke on an asset:
Operation Description replace The replace operation replaces the contents of the asset of interest. merge The merge operation updates multiple files for the asset, but does not update all files. add The add operation adds a new file or module file. addupdate The addupdate operation adds or updates one file or module file. If the file does not exist, the system adds the contents. If the file exists, the system updates the file. update The update operation updates one file or module file. delete The delete operation deletes a file or module file. - -contents
- File containing the content to add or update. This parameter is not required for the delete operation. (UploadFile, optional)
Optional parameters:
- -contenturi
- The Uniform Resource Identifier (URI) of the file to add, update, or remove from the asset. This parameter is not required for the merge or replace operations. (String, optional)
Optional steps
For optional steps, use the .* characters to specify a read-only argument in the command syntax. Specify an empty string with the "" characters to keep the existing value of the argument. If we do not specify a value or an empty string for a writable argument, the command resets the argument to a null value.
- -AssetOptions
- Use the AssetOptions step and the following arguments to set additional properties for the asset.
- name (read-only)
- Name of the asset. The default value for this argument is the file name of the source package.
- defaultBindingProps (read-only)
- Default binding properties for the asset. This argument only applies to enterprise assets. For assets which are not enterprise assets, specify the asterisk character (*) for pattern matching. For enterprise assets, specify the .* value to set the argument as a non-empty value.
- description
- Description for the asset.
- destinationUrl
- The URL of the asset binaries to deploy.
- typeAspect
- Asset type aspect.
- relationship
- Asset relationship. Use the plus sign character (+) to add additional assets to the existing relationship. Use the number sign character (#) to delete an existing asset from the relationship. To replace the existing relationships, specify the same syntax as in the importAsset command. If the asset specified in the relationship does not exist for add or update, the command returns an exception.
- filePermission
- File permission configuration.
- validate
- Specifies whether to validate the asset. The default is false. The product does not save the value specified for validate. Thus, if we select to validate the asset (true) now and later edit the asset, when you edit the asset enable this setting again for the product to validate the updated files.
- updateAssociatedCUs
- Specifies whether to update the composition units associated with an enterprise (Java EE) asset. This argument applies to enterprise assets only.
The default is none. Specify all to update all of the composition units associated with the enterprise asset.
For the replace operation, specify values for the AssetOptions name, defaultBindingProps, description, destinationUrl, typeAspect, relationship, filePermission, validate, and updateAssociatedCUs arguments. For operations other than replace, specify values for the AssetOptions name and updateAssociatedCUs arguments.
Return value.
The command returns the configuration ID of the asset of interest.
Batch mode example usage
The following example replaces the contents of a non-enterprise asset:
- Use Jython string:
- AdminTask.updateAsset('-assetID asset1.zip -operation replace -contents c:/temp/a.zip')
- Use Jython list:
- AdminTask.updateAsset(['-assetID', 'asset1.zip', '-operation', 'replace', '-contents', 'c:/temp/a.zip'])
The following example partially updates the files of a non-enterprise asset:
- Use Jython string:
- AdminTask.updateAsset('-assetID asset1.zip -operation merge -contents c:/temp/p.zip')
- Use Jython list:
- AdminTask.updateAsset(['-assetID', 'asset1.zip', '-operation', 'merge', '-contents', 'c:/temp/p.zip'])
The following example updates an enterprise asset with an EJB module file:
- Use Jython string:
- AdminTask.updateAsset('-assetID defaultapp.ear -operation add -contents
c:/temp/filename.jar -contenturi filename.jar')
- Use Jython list:
- AdminTask.updateAsset(['-assetID', 'defaultapp.ear', '-operation', 'add', '-contents',
'c:/temp/filename.jar', '-contenturi', 'filename.jar'])
The following example replaces an enterprise asset and its associated composition units using a replace operation:
- Use Jython string:
- AdminTask.updateAsset('-assetID defaultapp.ear -operation replace -contents
c:/temp/newapp.ear -AssetOptions [[defaultapp.ear .* newdesc "" "" "" "" false all]]')
- Use Jython list:
- AdminTask.updateAsset(['-assetID', 'defaultapp.ear', '-operation', 'replace', '-contents',
'c:/temp/newapp.ear', '-AssetOptions [[defaultapp.ear .* newdesc "" "" "" "" false all]]'])
The following example updates an enterprise asset and its associated composition units using a merge operation:
- Use Jython string:
- AdminTask.updateAsset('-assetID defaultapp.ear -operation merge -contents
c:/temp/newapp.ear -AssetOptions [[defaultapp.ear all]]')
- Use Jython list:
- AdminTask.updateAsset(['-assetID', 'defaultapp.ear', '-operation', 'merge', '-contents',
'c:/temp/newapp.ear', '-AssetOptions [[defaultapp.ear all]]'])
Interactive mode example usage
- Use Jython:
- AdminTask.updateAsset('-interactive')
viewAsset
Display additional asset configuration options and configured values.
Target object: None
Required parameters:
- -assetID
- Configuration ID of the asset of interest. This parameter accepts an incomplete configuration ID as long as the ID matches a unique asset. (String, required)
Optional parameters: None
Return value.
The command returns configuration data for the asset of interest:
- Specify Asset options (AssetOptions)
Specify options for Asset.
*Asset Name (name): [defaultapp.ear]
Default Binding Properties (defaultBindingProps):
[defaultbinding.ejbjndi.prefix#defaultbinding.datasource.jndi#defaultbinding.datasource.username
#defaultbinding.datasource.password#defaultbinding.cf.jndi
#defaultbinding.cf.resauth#defaultbinding.virtual.host#defaultbinding.force]
Asset Description (description): []
Asset Binaries Destination Url (destination): [${USER_INSTALL_ROOT}/installedAssets/defaultapp.ear/BASE/defaultapp.ear]
Asset Type Aspects (typeAspect): [WebSphere:spec=j2ee_ear]
Asset Relationships (relationship): []File Permission (filePermission): [.*\\.dll=755#.*\\.so=755#.*\\.a=755#.*\\.sl=755]
Validate asset (validate): [false]
Batch mode example usage
- Use Jython string:
- AdminTask.viewAsset('-assetID asset3.zip')
- Use Jython list:
- AdminTask.viewAsset(['-assetID', 'asset3.zip'])
Interactive mode example usage
- Use Jython:
- AdminTask.viewAsset('-interactive')
addCompUnit
Add a composition unit to a specific business-level application. A composition unit represents an asset in a business-level application, and enables the asset contents to interact with other assets in the application. It also enables the product run time to load and run asset contents.
Target object: None
Required parameters:
- -blaID
- Configuration ID of the business-level application of interest. (String, required)
- -cuSourceID
- Source configuration ID for the composition unit to add. We can specify an asset ID or a business-level application ID. (String, required)
Optional parameters:
- -deplUnits
- Deployable units to deploy for the asset. We can specify a subset of deployable units, all deployable units, or use the default as a shared library. If not specified, the system deploys each deployable unit. (String, optional)
- For Java EE assets, the system ignores this -deplUnits parameter and, regardless of the value specified, can add Java EE assets as part of this command.
- -cuConfigStrategyFile
- Fully qualified file path for custom default binding properties. This parameter only applies to enterprise assets. (String, optional)
- -defaultBindingOptions
- Optional JNDI binding properties for an enterprise asset. The binding properties available depend upon the type of enterprise asset. Use the format property=value to specify a default binding property. To specify more than one property, separate each property=value statement by the delimiter #.
- We can specify binding properties now, when creating the asset, or later, when adding the asset as a composition unit to a business-level application. If we specify binding properties later, when adding the asset to a business-level application, then we can use a strategy file to specify the binding properties. (String, optional)
- Use the following options with the defaultBindingOptions parameter:
enterprise asset type Supported binding properties Enterprise bean (EJB) defaultbinding.ejbjndi.prefix
defaultbinding.force
Data source defaultbinding.datasource.jndi
defaultbinding.datasource.username
defaultbinding.datasource.password
defaultbinding.force
Connection factory defaultbinding.cf.jndi
defaultbinding.cf.resauth
defaultbinding.force
Virtual host defaultbinding.virtual.host
defaultbinding.force
Optional steps
We can also specify values for optional steps to set additional properties for the new composition unit. These steps do not apply to enterprise assets. For optional steps, use the .* characters to specify a read-only argument in the command syntax. Specify an empty string with the "" characters to keep the existing value of the argument. If we do not specify a value or an empty string for a writable argument, the command resets the argument to a null value.
- -CUOptions
- Specifies additional properties for the composition unit. Specify the following options with the CUOptions step:
- parentBLA (read-only)
- Parent business-level application for the new composition unit.
- backingID (read-only)
- Composition unit source ID.
- name
- Name of the composition unit.
- description
- Description of the composition unit.
- startingWeight
- Starting weight of the composition unit. Supported values are from 1 to 2147483647, the maximum Integer value.
- startedOnDistributed
- Specifies whether to start the composition unit after distributing changes to the target nodes. The default is false.
- restartBehaviorOnUpdate
- Nodes to restart after editing the composition unit. Specify ALL to restart each target node. Specify DEFAULT to restart the nodes controlled by the sync plug-ins. Specify NONE to prevent the system from restarting nodes.
- For example, specify the syntax of this step as -CUOptions [[.* .* cu4 "cu4 desc" 0 false DEFAULT]]
- -MapTargets
- Specifies additional properties for the composition unit target mapping. Specify the following options with the MapTargets step:
- deplUnit (read-only)
- Deployable unit Uniform Resource Identifier (URI).
- For an enterprise bundle archive (EBA) asset, this URI is ebaDeploymentUnit.
- server
- Target or targets to deploy the composition units. The default is the server1 server. Use the plus sign character ( + ) to specify multiple targets. Use the plus sign character ( + ) as a prefix to add an additional target. Specify the complete object name format for each server that is not aWebSphere Application Server server.
- For example, specify the syntax of this step as -MapTargets [[a1.jar cluster1+cluster2] [a2.jar +server2]]
- -ActivationPlanOptions
- Specifies additional properties for the composition unit activation plan. Specify the following options with the ActivationPlanOptions step:
- deplUnit (read-only)
- Deployable unit Uniform Resource Identifier (URI).
- activationPlan
- List of runtime components as the activation plan. Specify each activation plan in the format specName=xxx,specVersion=yyy, where specName represents the name of the specification and is required. Use the plus sign character ( + ) to specify multiple activation plans.
- For example, specify the syntax of this step as -ActivationPlanOptions [[a1.jar specname=actplan0+specname=actplan1] [a2.jar specname=actplan1+specname=actplan2]]
- For an EBA asset, use the following default values: -ActivationPlanOptions [[default ""]]
- -CreateAuxCUOptions
- Specifies additional properties for an auxiliary composition unit. Use this step if the composition unit source is an asset that corresponds to an asset that does not have a matching
composition unit in the business-level application. Specify the following options with the CreateAuxCUOptions step:
- deplUnit (read-only)
- Deployable unit Uniform Resource Identifier (URI).
- inputAsset (read-only)
- Specifies composition unit source ID.
- cuID
- Composition unit ID the system creates for the asset. If we do not want to create a new composition unit, do not specify this argument.
- matchTarget
- Specifies whether to match the targets of the dependency auxiliary composition unit with the targets of the new composition unit. Default is true.
- The product does not save the value specified for matchTarget. Thus if we select to not match the target (false) now and later edit the composition unit, when you edit the composition unit we must disable this setting again for the product to not match the targets.
- For example, specify the syntax of this step as -CreateAuxCUOptions [[a1.jar a.jar auxCU true] [a2.jar a.jar defaultCU false]]
- -RelationshipOptions
- Specifies additional properties for relationships between assets, composition units, and business-level applications. Use this step if the source ID of the composition unit is an asset that has a matching composition unit in the business-level application. Specify the following options
with the RelationshipOptions step:
- deplUnit (read-only)
- Deployable unit Uniform Resource Identifier (URI).
- relationship
- Defines the composition unit relationships. Specify the composition unit object name in the format: cuName=xxx. Use the plus sign character (+) to specify multiple composition unit object names in the relationship. If the composition unit specified in the relationship does not exist under the same business-level application, the system returns an error.
- matchTarget
- Specifies whether to match the targets of the composition unit relationship with the targets of the new composition unit. Default is true.
- The product does not save the value specified for matchTarget. Thus if we select to not match the target (false) now and later edit the composition unit, when you edit the composition unit we must disable this setting again for the product to not match the targets.
- For example, specify the syntax of this step as -RelationshipOptions [[a1.jar a.jar auxCU true] [a2.jar a.jar defaultCU false]]
- -ContextRootStep
- For an EBA asset, context roots determine where the web pages of a particular web application bundle (WAB) are found at run time.
- The context root specified here is combined with the defined server mapping to compose the full URL that you enter to access the pages of the WAB. For example, if the application server default host is www.example.com:8080 and the context root of the WAB is /sample, the web pages are available at www.example.com:8080/sample.
- We should list the context roots for all the WAB modules contained in the OSGi application.
- Specify the syntax of this step as
follows:
- -ContextRootStep [
[bundle_symbolic_name_1 bundle_version_1 context_root_1]
[bundle_symbolic_name_2 bundle_version_2 context_root_2]]
- For example, for an EBA file containing two WABs
(com.ibm.ws.eba.helloWorldService.web at version 1.0.0, which is to be mapped
to /hello/web, and com.ibm.ws.eba.helloWorldService.withContextRoot at version 0.9.0, which is to be mapped to /hello/service), this aspect of the command is as
follows:
- -ContextRootStep [
[com.ibm.ws.eba.helloWorldService.web 1.0.0 "/hello/web"]
[com.ibm.ws.eba.helloWorldService.withContextRoot 0.9.0 "/hello/service"]]
- -VirtualHostMappingStep
- For an EBA asset, we use a virtual host to associate a unique port with a module or application. The aliases of a virtual host identify the port numbers defined for that virtual host. A port number specified in a virtual host alias is used in the URL used to access artifacts such as servlets and JavaServer Page (JSP) files in a web module. For example, the alias myhost:8080 is the host_name:port_number portion of the URL http://myhost:8080/sample.
- Each WAB contained in a deployed asset must be mapped to a virtual host. WABs can be installed on the same virtual host, or dispersed among several virtual hosts.
- If we specify an existing virtual host in the ibm-web-bnd.xml or .xmi file for a given WAB, the specified virtual host is set by default.
Otherwise, the default virtual host setting is default_host, which
provides several port numbers through its aliases:
- 80
- An internal, insecure port used when no port number is specified
- 9080
- An internal port
- 9443
- An external, secure port
- Unless we want to isolate your WAB from other WABs or resources on the same node (physical machine), default_host is a suitable virtual host. In addition to default_host, WAS provides admin_host, which is the virtual host for the administrative console system application. admin_host is on port 9060. Its secure port is 9043. Do not select admin_host unless the WAB relates to system administration.
- Specify the syntax of this step as
follows:
- -VirtualHostMappingStep [
[bundle_symbolic_name_1 bundle_version_1
web_module_name_1 virtual_host_1]
[bundle_symbolic_name_2 bundle_version_2
web_module_name_2 virtual_host_2]]
- For example, for an EBA file containing two WABs
(com.ibm.ws.eba.helloWorldService.web at version 1.0.0, which is to be mapped
to default_host, and com.ibm.ws.eba.helloWorldService.withContextRoot at version 0.9.0, which is to be mapped to test_host), this aspect of the command is as
follows:
- -VirtualHostMappingStep [
[com.ibm.ws.eba.helloWorldService.web 1.0.0 "HelloWorld service" default_host]
[com.ibm.ws.eba.helloWorldService.withContextRoot 0.9.0 "HelloWorld second service" test_host]]
- -MapRolesToUsersStep
- For an EBA asset, use this step to map security roles to users or groups.
- Specify the syntax of this step as
follows:
- -MapRolesToUsersStep [
[role_name everyone?
all_authenticated_in_realm?
usernames groups all_authenticated_in_trusted_realms?]]
Key:
- role_name is a role name defined in the application.
- everyone? is set to Yes or No, to specify whether or not everyone is in the role.
- all_authenticated_in_realm? is set to Yes or No, to specify whether or not all authenticated users can access the application realm.
- usernames is a list of WAS user names, separated by the "|" character.
- groups is a list of WAS groups, separated by the "|" character.
all_authenticated_in_trusted_realms? optionally set to Yes or No, to specify whether all users authenticated in a trusted
realm can access the resource.
For usernames, and groups, the empty string "" means "use the default or existing value". The default is usually that no users or groups are bound to the role. However, when an application contains an ibm-application-bnd.xmi file, the default value for usernames is obtained from this file. If we are deploying an application containing an ibm-application-bnd.xmi file, and we want to remove the bound users, specify just the "|" character (which is the separator for multiple user names). This explicitly specifies "no users", and therefore guarantees that no users are bound to the role.
- For
example:
- -MapRolesToUsersStep [
[ROLE1 No Yes "" ""]
[ROLE2 No No WABTestUser1 ""]
[ROLE3 No No "" WABTestGroup1]
[ROLE4 Yes No "" ""]]
- -BlueprintResourceRefBindingStep
- For an EBA asset, Blueprint components can access WAS resource references. Each reference is declared in a Blueprint XML file, and can be secured using a Java EE Connector Architecture (JCA) authentication alias. Each bundle in an OSGi application can contain any number of resource reference declarations in its various Blueprint XML files.
- When we secure resource references, those resource references can be bound only to JCA authentication aliases that exist on every server or cluster that the OSGi application is deployed to. An OSGi application can be deployed to multiple servers and clusters in the same security domain. Therefore, each JCA authentication alias must exist in either the security domain of the target servers and clusters, or the global security domain.
- Specify the syntax of this step as
follows:
- -BlueprintResourceRefBindingStep [
[
bundle_symbolic_name
bundle_version
blueprint_resource_reference_id
interface_name
jndi_name
authentication_type
sharing_setting
authentication_alias_name
]]
The value for jndi_name must match the jndi name that you declare in the filter attribute of the resource reference element in the Blueprint XML file.
- For example, for an EBA file containing a bundle
com.ibm.ws.eba.helloWorldService.properties.bundle.jar at Version 1.0.0, which
is to be bound to authentication alias alias1, the command is as
follows:
- -BlueprintResourceRefBindingStep[
[com.ibm.ws.eba.helloWorldService.properties.bundle 1.0.0 resourceRef
javax.sql.DataSource jdbc/Account Container Shareable alias1]]
- -WebModuleMsgDestRefs
- For an EBA asset, binding a resource reference maps a resource dependency of the web application to an actual resource available in the server runtime environment. At a minimum, this can be achieved using a mapping that specifies the JNDI name under which the resource is known in the runtime environment. By default, the JNDI name is the resource ID specified in the web.xml file during development of the web application bundle (WAB). Use this option to bind resources of type message-destination-ref (message destination reference) or resource-env-ref (resource environment reference), as defined in the Java specification JSR-250: Common Annotations for the Java Platform.
- Specify the syntax of this step as
follows:
- -WebModuleMsgDestRefs [
[
bundle_symbolic_name
bundle_version
resource_reference_id
resource_type
target_jndi_name
]]
- For
example:
- -WebModuleMsgDestRefs [
[com.ibm.ws.eba.helloWorldService.web 1.0.0
jms/myQ javax.jms.Queue jms/workQ]
[com.ibm.ws.eba.helloWorldService.web 1.0.0
jms/myT javax.jms.Topic jms/notificationTopic]]
- -WebModuleResourceRefs
- For an EBA asset, binding a resource reference maps a resource dependency of the web application to an actual resource available in the server runtime environment. At a minimum, this can be achieved using a mapping that specifies the JNDI name under which the resource is known in the runtime environment. By default, the JNDI name is the resource ID specified in the web.xml file during development of the web application bundle (WAB). Use this option to bind resources of type resource-ref (resource reference), as defined in the Java specification JSR-250: Common Annotations for the Java Platform.
- Specify the syntax of this step as
follows:
- -WebModuleResourceRefs [
[
bundle_symbolic_name
bundle_version
resource_reference_id
resource_type
target_jndi_name
login_configuration
login_properties
extended_properties
]]
- For
example:
- -WebModuleResourceRefs [
[com.ibm.ws.eba.helloWorldService.web 1.0.0 jdbc/jtaDs javax.sql.DataSource
jdbc/helloDs "" "" ""]
[com.ibm.ws.eba.helloWorldService.web 1.0.0 jdbc/nonJtaDs javax.sql.DataSource
jdbc/helloDsNonJta "" "" "extprop1=extval1"]]
If we use multiple extended properties, the jython syntax is "extprop1=extval1,extprop2=extval2".
Return value.
The command returns the configuration IDs of the composition unit and the new composition unit created for the asset in the asset relationship:
- WebSphere:cuname=cu4
WebSphere:cuname=cua
WebSphere:cuname=cud
Batch mode example usage
Use the following examples to add a non-enterprise asset:
- Use Jython string:
- AdminTask.addCompUnit('-blaID myBLA -cuSourceID assetname=asset1.zip -CUOptions
[[.* .* cu1 "cu1 desc1" 0 false DEFAULT]] -MapTargets [[.* server1]] -ActivationPlanOptions
[.* specname=actplan0+specname=actplan1]')
- Use Jython list:
- AdminTask.addCompUnit(['-blaID', 'myBLA', '-cuSourceID', 'assetname=asset1.zip', '-CUOptions',
'[[.* .* cu1 "cu1 desc1" 0 false DEFAULT]]', '-MapTargets', '[[.* server1]]', '-ActivationPlanOptions',
'[.* specname=actplan0+specname=actplan1]'])
Use the following examples to add a business-level application composition unit:
- Use Jython string:
- AdminTask.addCompUnit('-blaID myBLA -cuSourceID yourBLA -CUOptions [[.* .* cu3 "cu3 desc3" 0 false DEFAULT]]')
- Use Jython list:
- AdminTask.addCompUnit(['-blaID', 'myBLA', '-cuSourceID', 'yourBLA', '-CUOptions',
'[[.* .* cu3 "cu3 desc3" 0 false DEFAULT]]'])
Use the following example to create an EBA composition unit and add it to a business-level application.
- AdminTask.addCompUnit('[
-blaID WebSphere:blaname=helloWorldService
-cuSourceID WebSphere:assetname=com.ibm.ws.eba.helloWorldService.eba
-CUOptions [
[WebSphere:blaname=helloWorldService.eba
WebSphere:assetname=com.ibm.ws.eba.helloWorldService.eba
com.ibm.ws.eba.helloWorldService_0001.eba "" 1 false DEFAULT]]
-MapTargets [[ebaDeploymentUnit WebSphere:node=node01,server=server1]]
-ActivationPlanOptions [[default ""]]
-ContextRootStep [
[com.ibm.ws.eba.helloWorldService.web 1.0.0 "/hello/web"]
[com.ibm.ws.eba.helloWorldService.withContextRoot 0.9.0 "/hello/service"]]
-VirtualHostMappingStep [
[com.ibm.ws.eba.helloWorldService.web 1.0.0
"HelloWorld service" default_host]
[com.ibm.ws.eba.helloWorldService.withContextRoot 0.9.0
"HelloWorld second service" test_host]]
-MapRolesToUsersStep [
[ROLE1 No Yes "" ""]
[ROLE2 No No WABTestUser1 ""]
[ROLE3 No No "" WABTestGroup1]
[ROLE4 Yes No "" ""]]
-BlueprintResourceRefBindingStep[
[com.ibm.ws.eba.helloWorldService.properties.bundle 1.0.0 resourceRef
javax.sql.DataSource jdbc/Account Container Shareable alias1]]
-WebModuleMsgDestRefs [
[com.ibm.ws.eba.helloWorldService.web 1.0.0
jms/myQ javax.jms.Queue jms/workQ]
[com.ibm.ws.eba.helloWorldService.web 1.0.0
jms/myT javax.jms.Topic jms/notificationTopic]]
-WebModuleResourceRefs [
[com.ibm.ws.eba.helloWorldService.web 1.0.0 jdbc/jtaDs javax.sql.DataSource
jdbc/helloDs "" "" ""]
[com.ibm.ws.eba.helloWorldService.web 1.0.0 jdbc/nonJtaDs javax.sql.DataSource
jdbc/helloDsNonJta "" "" "extprop1=extval1"]]
]')
Use the following examples to add a composition unit for a non-enterprise asset and deploy the composition unit to multiple targets:
- Use Jython string:
- AdminTask.addCompUnit('-blaID theirBLA -cuSourceID asset2.zip -CUOptions
[[.* .* cu2 "cu2 desc" 0 false DEFAULT]] -MapTargets [[.* server1+server2]]')
- Use Jython list:
- AdminTask.addCompUnit(['-blaID', 'theirBLA', '-cuSourceID', 'asset2.zip', '-CUOptions',
'[[.* .* cu2 "cu2 desc" 0 false DEFAULT]]', '-MapTargets', '[[.* server1+server2]]'])
Use the following examples to add a composition unit that is a non-enterprise asset with a deployable unit:
- Use Jython string:
- AdminTask.addCompUnit('-blaID yourBLA -cuSourceID asset2.zip -deplUnits a.jar -CUOptions
[[.* .* cu3 "cu3 desc" 0 false DEFAULT]] -MapTargets [[a.jar server1]] -ActivationPlanOptions
[[a.jar specname=actplan1]]')
- Use Jython list:
- AdminTask.addCompUnit(['-blaID', 'yourBLA', '-cuSourceID', 'asset2.zip', '-deplUnits', 'a.jar', '-CUOptions',
'[[.* .* cu3 "cu3 desc" 0 false DEFAULT]]', '-MapTargets', '[[a.jar server1]]', '-ActivationPlanOptions',
'[[a.jar specname=actplan1]]'])
Use the following examples to add a composition unit for a non-enterprise asset as a shared library:
- Use Jython string:
- AdminTask.addCompUnit('-blaID ourBLA -cuSourceID b.jar -deplUnits default -CUOptions
[[.* .* cub "cub desc" 0 false DEFAULT]] -MapTargets [[default server1]]')
- Use Jython list:
- AdminTask.addCompUnit(['-blaID', 'ourBLA', '-cuSourceID', 'b.jar', '-deplUnits', 'default', '-CUOptions',
'[[.* .* cub "cub desc" 0 false DEFAULT]]', '-MapTargets', '[[default server1]]'])
Use the following examples to add a composition unit for a non-enterprise asset with a dependency. For this example, the cub composition unit exists as a shared library of the ourBLA business-level application:
- Use Jython string:
- AdminTask.addCompUnit('-blaID ourBLA -cuSourceID asset3.zip -deplUnits a1.jar -CUOptions
[[.* .* cu4 "cu4 desc" 0 false DEFAULT]] -MapTargets [[a1.jar cluster1+cluster2]] -CreateAuxCUOptions
[[a1.jar a.jar cua true]] -RelationshipOptions [[a1.jar cuname=cub true]]')
- Use Jython list:
- AdminTask.addCompUnit(['-blaID', 'ourBLA', '-cuSourceID', 'asset3.zip', '-deplUnits', 'a1.jar', '-CUOptions',
'[[.* .* cu4 "cu4 desc" 0 false DEFAULT]]', '-MapTargets', '[[a1.jar cluster1+cluster2]]', '-CreateAuxCUOptions',
'[[a1.jar a.jar cua true]]', '-RelationshipOptions', '[[a1.jar cuname=cub true]]'])
Use the following examples to add an enterprise asset:
- Use Jython string:
- AdminTask.addCompUnit('[-blaID yourBLA -cuSourceID defaultapp.ear -defaultBindingOptions
defaultbinding.ejbjndi.prefix=ejb# defaultbinding.virtual.host=default_host#
defaultbinding.force=yes -AppDeploymentOptions [-appname defaultapp -installed.ear.destination
application_root/myCell/defaultapp.ear] -MapModulesToServers
[[defaultapp.war .* WebSphere:cell=cellName,node=nodeName,server=server1]
[Increment.jar .* WebSphere:cell=cellName,node=nodeName,server=server2]] -CtxRootForWebMod
[[defaultapp.war .* myctx/]]]')
- Use Jython list:
- AdminTask.addCompUnit(['-blaID', 'yourBLA', '-cuSourceID', 'defaultapp.ear', '-defaultBindingOptions',
'defaultbinding.ejbjndi.prefix=ejb# defaultbinding.virtual.host=default_host# defaultbinding.force=yes',
'-AppDeploymentOptions', '[-appname defaultapp -installed.ear.destination application_root/myCell/defaultapp.ear]',
'-MapModulesToServers', '[[defaultapp.war .* WebSphere:cell=cellName,node=nodeName,server=server1]
[Increment.jar .* WebSphere:cell=cellName,node=nodeName,server=server2]]', '-CtxRootForWebMod',
'[[defaultapp.war .* myctx/]]'])
Interactive mode example usage
- Use Jython:
- AdminTask.addCompUnit('-interactive')
deleteCompUnit
Eemove a composition unit. Both parameters for this command accept incomplete configuration IDs, as long as the system can match the string to a unique ID.
Target object: None
Required parameters:
- -blaID
- Configuration ID of the business-level application of interest. (String, required)
- -cuID
- Configuration ID of the composition unit to delete. (String, required)
Optional parameters:
- -force
- Specifies whether to force the system to delete the composition unit, even if other composition units depend on this composition unit. (Boolean, optional)
Return value.
The command returns the configuration ID of the composition unit the system deleted:
- WebSphere:cuname=cu1
Batch mode example usage
- Use Jython string:
- AdminTask.deleteCompUnit('-blaID myBLA -cuID cu1 -force true')
- Use Jython list:
- AdminTask.deleteCompUnit(['-blaID', 'myBLA', '-cuID', 'cu1', '-force', 'true'])
Interactive mode example usage
- Use Jython:
- AdminTask.deleteCompUnit('-interactive')
editCompUnit
Modify additional composition unit options. Use this command to modify the starting weight of the composition unit, deployment targets, activation plan options, and relationship settings.
Target object: None
Required parameters:
- -blaID
- Configuration ID of the business-level application of interest. (String, required)
- -cuID
- Configuration ID of the composition unit to edit. (String, required)
Optional steps
We can also specify values for optional steps to edit properties of the composition unit. These steps do not apply to enterprise assets. For optional steps, use the .* characters to specify a read-only argument in the command syntax. Specify an empty string with the "" characters to keep the existing value of the argument. If we do not specify a value or an empty string for a writable argument, the command resets the argument to a null value.
- -CUOptions
- Specifies additional properties for the composition unit. Specify the following options with the CUOptions step:
- parentBLA (read-only)
- Parent business-level application for the composition unit.
- backingID (read-only)
- Composition unit source ID.
- name (read-only)
- Name of the composition unit.
- description
- Description of the composition unit.
- startingWeight
- Starting weight of the composition unit. Supported values are from 1 to 2147483647, the maximum Integer value.
- startedOnDistributed
- Specifies whether to start the composition unit after distributing changes to the target nodes. The default is false.
- restartBehaviorOnUpdate
- Nodes to restart after editing the composition unit. Specify ALL to restart each target node. Specify DEFAULT to restart the nodes controlled by the sync plug-ins. Specify NONE to prevent the system from restarting nodes.
- For example, specify the syntax for this step as -CUOptions [[.* .* cu4 "cu4 description" 0 false DEFAULT]]
- -MapTargets
- Specifies additional properties for the composition unit target mapping. Specify the following options with the MapTargets step:
- deplUnit (read-only)
- Deployable unit Uniform Resource Identifier (URI).
- For an enterprise bundle archive (EBA) asset, this URI is ebaDeploymentUnit.
- server
- Target or targets to deploy the composition units. The default is the server1 server. Use the plus sign character ( + ) to specify multiple targets. Use the plus sign character ( + ) as a prefix to add an additional target. Specify the complete object name format for each server that is not a WAS server.
- For example, specify the syntax of this step as -MapTargets [[a1.jar cluster1+cluster2] [a2.jar server1+server2]]
- -ActivationPlanOptions
- Specifies additional properties for the composition unit activation plan. Specify the following options with the ActivationPlanOptions step:
- deplUnit (read-only)
- Deployable unit Uniform Resource Identifier (URI).
- activationPlan
- List of runtime components as the activation plan. Specify each activation plan in the format specName=xxx,specVersion=yyy, where specName represents the name of the specification and is required. Use the plus sign character ( + ) to specify multiple activation plans.
- For example, specify the syntax of this step as -ActivationPlanOptions [[a1.jar specname=actplan0+actplan1] [a2.jar specname=actplan1+specname=actplan2]]
- For an EBA asset, do not modify the activation plan. Keep the following default values that were set when the composition unit was added: -ActivationPlanOptions [[default ""]]
- -RelationshipOptions
- Specifies additional properties for relationships between assets, composition units, and business-level applications. Use this step if the source ID of the composition unit is an asset that has a matching composition unit in the business-level application. Specify the following options
with the RelationshipOptions step:
- deplUnit (read-only)
- Deployable unit Uniform Resource Identifier (URI).
- relationship
- Defines the composition unit relationships. Specify the composition unit object name in the format: cuName=xxx. Use the plus sign character (+) to specify multiple composition unit object names in the relationship. If the composition unit specified in the relationship does not exist under the same business-level application, the system returns an error.
- matchTarget
- Specifies whether to match the targets of the composition unit relationship with the targets of the new composition unit. Default is true.
- The product does not save the value specified for matchTarget. Thus if we select to not match the target (false) now and later edit the composition unit, when you edit the composition unit we must disable this setting again for the product to not match the targets.
- For example, specify the syntax of this step as -RelationshipOptions [[a1.jar a.jar auxCU true] [a2.jar a.jar defaultCU false]]
- -ContextRootStep
- For an EBA asset, context roots determine where the web pages of a particular web application bundle (WAB) are found at run time.
- The context root specified here is combined with the defined server mapping to compose the full URL that you enter to access the pages of the WAB. For example, if the application server default host is www.example.com:8080 and the context root of the WAB is /sample, the web pages are available at www.example.com:8080/sample.
- We should list the context roots for all the WAB modules contained in the OSGi application.
- Specify the syntax of this step as
follows:
- -ContextRootStep [
[bundle_symbolic_name_1 bundle_version_1 context_root_1]
[bundle_symbolic_name_2 bundle_version_2 context_root_2]]
- For example, for an EBA file containing two WABs
(com.ibm.ws.eba.helloWorldService.web at version 1.0.0, which is to be mapped
to /hello/web, and com.ibm.ws.eba.helloWorldService.withContextRoot at version 0.9.0, which is to be mapped to /hello/service), this aspect of the command is as
follows:
- -ContextRootStep [
[com.ibm.ws.eba.helloWorldService.web 1.0.0 "/hello/web"]
[com.ibm.ws.eba.helloWorldService.withContextRoot 0.9.0 "/hello/service"]]
- -VirtualHostMappingStep
- For an EBA asset, we use a virtual host to associate a unique port with a module or application. The aliases of a virtual host identify the port numbers defined for that virtual host. A port number specified in a virtual host alias is used in the URL used to access artifacts such as servlets and JavaServer Page (JSP) files in a web module. For example, the alias myhost:8080 is the host_name:port_number portion of the URL http://myhost:8080/sample.
- Each WAB contained in a deployed asset must be mapped to a virtual host. WABs can be installed on the same virtual host, or dispersed among several virtual hosts.
- If we specify an existing virtual host in the ibm-web-bnd.xml or .xmi file for a given WAB, the specified virtual host is set by default.
Otherwise, the default virtual host setting is default_host, which
provides several port numbers through its aliases:
- 80
- An internal, insecure port used when no port number is specified
- 9080
- An internal port
- 9443
- An external, secure port
- Unless we want to isolate your WAB from other WABs or resources on the same node (physical machine), default_host is a suitable virtual host. In addition to default_host, WAS provides admin_host, which is the virtual host for the administrative console system application. admin_host is on port 9060. Its secure port is 9043. Do not select admin_host unless the WAB relates to system administration.
- Specify the syntax of this step as
follows:
- -VirtualHostMappingStep [
[bundle_symbolic_name_1 bundle_version_1
web_module_name_1 virtual_host_1]
[bundle_symbolic_name_2 bundle_version_2
web_module_name_2 virtual_host_2]]
- For example, for an EBA file containing two WABs
(com.ibm.ws.eba.helloWorldService.web at version 1.0.0, which is to be mapped
to default_host, and com.ibm.ws.eba.helloWorldService.withContextRoot at version 0.9.0, which is to be mapped to test_host), this aspect of the command is as
follows:
- -VirtualHostMappingStep [
[com.ibm.ws.eba.helloWorldService.web 1.0.0 "HelloWorld service" default_host]
[com.ibm.ws.eba.helloWorldService.withContextRoot 0.9.0 "HelloWorld second service" test_host]]
- -MapRolesToUsersStep
- For an EBA asset, use this step to map security roles to users or groups.
- Specify the syntax of this step as
follows:
- -MapRolesToUsersStep [
[role_name everyone?
all_authenticated_in_realm?
usernames groups]]
Key:
- role_name is a role name defined in the application.
- everyone? is set to Yes or No, to specify whether or not everyone is in the role.
- all_authenticated_in_realm? is set to Yes or No, to specify whether or not all authenticated users can access the application realm.
- usernames is a list of WAS user names, separated by the "|" character.
- groups is a list of WAS groups, separated by the "|" character.
For usernames, and groups, the empty string "" means "use the default or existing value". The default is usually that no users or groups are bound to the role. However, when an application contains an ibm-application-bnd.xmi file, the default value for usernames is obtained from this file. If we are deploying an application containing an ibm-application-bnd.xmi file, and we want to remove the bound users, specify just the "|" character (which is the separator for multiple user names). This explicitly specifies "no users", and therefore guarantees that no users are bound to the role.
- For
example:
- -MapRolesToUsersStep [
[ROLE1 No Yes "" ""]
[ROLE2 No No WABTestUser1 ""]
[ROLE3 No No "" WABTestGroup1]
[ROLE4 Yes No "" ""]]
- -BlueprintResourceRefPostDeployStep
- For an EBA asset, Blueprint components can access WAS resource references. Each reference is declared in a Blueprint XML file, and can be secured using a Java EE Connector Architecture (JCA) authentication alias. Each bundle in an OSGi application can contain any number of resource reference declarations in its various Blueprint XML files.
- When we secure resource references, those resource references can be bound only to JCA authentication aliases that exist on every server or cluster that the OSGi application is deployed to. An OSGi application can be deployed to multiple servers and clusters in the same security domain. Therefore, each JCA authentication alias must exist in either the security domain of the target servers and clusters, or the global security domain.
- Specify the syntax of this step as
follows:
- -BlueprintResourceRefPostDeployStep [
[
bundle_symbolic_name
bundle_version
blueprint_resource_reference_id
interface_name
jndi_name
authentication_type
sharing_setting
authentication_alias_name
]]
The value for jndi_name must match the jndi name that you declare in the filter attribute of the resource reference element in the Blueprint XML file.
- For example, for an EBA file containing a bundle
com.ibm.ws.eba.helloWorldService.properties.bundle.jar at Version 1.0.0, which
is to be bound to authentication alias alias1, the command is as
follows:
- -BlueprintResourceRefPostDeployStep[
[com.ibm.ws.eba.helloWorldService.properties.bundle 1.0.0 resourceRef
javax.sql.DataSource jdbc/Account Container Shareable alias1]]
- -WebModuleResourceRefs
- For an EBA asset, binding a resource reference maps a resource dependency of the web module to an actual resource available in the server runtime environment. At a minimum, this can be achieved using a mapping that specifies the JNDI name under which the resource is known in the runtime environment. By default, the JNDI name is the resource ID specified in the web.xml file during development of the web application bundle (WAB).
- Specify the syntax of this step as
follows:
- -WebModuleResourceRefs [
[
bundle_symbolic_name
bundle_version
resource_reference_id
resource_type
target_jndi_name
login_configuration
login_properties
extended_properties
]]
- For
example:
- -WebModuleResourceRefs [
[com.ibm.ws.eba.helloWorldService.web 1.0.0 jdbc/jtaDs javax.sql.DataSource
jdbc/helloDs "" "" ""]
[com.ibm.ws.eba.helloWorldService.web 1.0.0 jdbc/nonJtaDs javax.sql.DataSource
jdbc/helloDsNonJta "" "" "extprop1=extval1"]]
If we use multiple extended properties, the jython syntax is "extprop1=extval1,extprop2=extval2".
Return value.
The command returns the configuration ID of the composition unit the system edits.
Batch mode example usage
Use the following examples to edit a composition unit of an asset and replace the target from existing targets:
- Use Jython string:
- AdminTask.editCompUnit('-blaID myBLA -cuID cu1 -CUOptions [[.* .* cu1 cudesc 1 false DEFAULT]] -MapTargets
[[.* server2]] -ActivationPlanOptions [.* #specname=actplan0+specname=actplan2]')
- Use Jython list:
- AdminTask.editCompUnit(['-blaID', 'myBLA', '-cuID', 'cu1', '-CUOptions',
'[[.* .* cu1 cudesc 1 false DEFAULT]]', '-MapTargets', '
[[.* server2]]', '-ActivationPlanOptions', '[.* #specname=actplan0+specname=actplan2]'])
Use the following examples to edit a composition unit of an asset and its relationships:
- Use Jython string:
- AdminTask.editCompUnit('-blaID ourBLA -cuID cu4 -CUOptions [[.* .* cu4 "new cu desc" 1 false DEFAULT]]
-MapTargets [[a1.jar server1+server2]] -RelationshipOptions [[a1.jar cuname=cub true]]')
- Use Jython list:
- AdminTask.editCompUnit(['-blaID', 'ourBLA', '-cuID', 'cu4', '-CUOptions', '
[[.* .* cu4 "new cu desc" 1 false DEFAULT]]', '-MapTargets', '[[a1.jar server1+server2]]', '-RelationshipOptions',
'[[a1.jar cuname=cub true]]'])
Use the following examples to edit a composition unit by adding a new relationship to the existing relationship:
- Use Jython string:
- AdminTask.editCompUnit('[-blaID ourBLA -cuID cu4 -CUOptions [[.* .* cu4 "new cu desc" 1 false DEFAULT]]
-MapTargets [[a1.jar server1+server2]] -RelationshipOptions [[a1.jar +cuname=cuc true]] -ActivationPlanOptions
[a1.jar +specname=actplan2#specname=actplan1]]')
- Use Jython list:
- AdminTask.editCompUnit(['-blaID', 'ourBLA', '-cuID', 'cu4', '-CUOptions', '
[[.* .* cu4 "new cu desc" 1 false DEFAULT]]', '-MapTargets', '[[a1.jar server1+server2]]', '-RelationshipOptions',
'[[a1.jar +cuname=cuc true]]', '-ActivationPlanOptions', '[a1.jar +specname=actplan2#specname=actplan1]'])
Use the following examples to edit an enterprise composition unit configuration:
- Use Jython string:
- AdminTask.editCompUnit('-blaID yourBLA -cuID defaultapp -MapModulesToServers
[[defaultapp.war .* WebSphere:cluster=cluster1][Increment.jar .* WebSphere:cluster=cluster2]]
-CtxRootForWebMod [[defaultapp.war .* /]] -MapWebModToVH [[defaultapp.war .* vh1]]')
- Use Jython list:
- AdminTask.editCompUnit(['-blaID', 'yourBLA', '-cuID', 'defaultapp', '-MapModulesToServers',
'[[defaultapp.war .* WebSphere:cluster=cluster1][Increment.jar .* WebSphere:cluster=cluster2]]', '-CtxRootForWebMod',
'[[defaultapp.war .* /]]', '-MapWebModToVH', '[[defaultapp.war .* vh1]]'])
Interactive mode example usage
- Use Jython:
- AdminTask.editCompUnit('-interactive')
listCompUnits
Display each composition unit associated with a specific business-level application.
Target object: None
Required parameters:
- -blaID
- Configuration ID of the business-level application of interest. (String, required)
Optional parameters:
- -includeDescription
- Specifies whether to include a description of each asset that the command returns. (String, optional)
- -includeType
- Specifies whether to include the type for each asset that the command returns. (String, optional)
Return value.
The command returns a list of configuration IDs and the type for each composition unit:
- WebSphere:cuname=cu1
asset
"description for cu1"
WebSphere:cuname=cu4
bla
"description for cu4"
WebSphere:cuname=defaultapp
Java EE "description for defaultapp"
Batch mode example usage
- Use Jython string:
- AdminTask.listCompUnits('-blaID blaname=theirBLA')
- Use Jython list:
- AdminTask.listCompUnits(['-blaID', 'blaname=theirBLA'])
Interactive mode example usage
- Use Jython:
- AdminTask.listCompUnits('-interactive')
setCompUnitTargetAutoStart
Enable or disable automatic starting of composition units. If we enable this option, the system automatically starts the composition unit when the composition unit target starts.
Target object: None
Required parameters:
- -blaID
- Configuration ID of the business-level application of interest. The command accepts an incomplete configuration ID if the system matches it to a unique business-level application ID. (String, required)
- -cuID
- Composition unit of interest. The command accepts an incomplete configuration ID if the system matches it to a unique composition unit ID. (String, required)
- -targetID
- Name of the target of interest. For example, specify the server name to set the target to a specific server. (String, required)
- -enable
- Specifies whether to automatically start the composition unit of interest when the specified target starts. Specify true to start the composition unit automatically. If we do not specify true, the system will not start the composition unit when the target starts. Default is true. (String, required)
Return value. The command does not return output.
Batch mode example usage
- Use Jython string:
- AdminTask.setCompUnitTargetAutoStart('-blaID bla1 -cuID cu1 -targetID server1 -enable true')
- Use Jython list:
- AdminTask.setCompUnitTargetAutoStart(['-blaID', 'bla1', '-cuID', 'cu1', '-targetID',
'server1', '-enable', 'true'])
Interactive mode example usage
- Use Jython string:
- AdminTask.setCompUnitTargetAutoStart('-interactive')
viewCompUnit
Display configuration information for a composition unit that belongs to a specific business-level application.
Target object: None
Required parameters:
- -blaID
- Configuration ID of the business-level application of interest. This parameter accepts an incomplete configuration ID if the system matches it to a unique business-level application ID. (String, required)
- -cuID
- Configuration ID of the composition unit of interest. This parameter accepts an incomplete configuration ID if the system matches it to a unique composition unit ID. (String, required)
Optional parameters: None
Return value.
The command returns configuration information for the composition unit of interest:
- Specify Composition Unit options (CUOptions)
Specify name, description options for Composition Unit.
Parent BLA (parentBLA): [WebSphere:blaname=myBLA]
Backing Id (backingId): [WebSphere:assetname=asset1.zip]
Name (name): [cu1]
Description (description): [cuDesc]
Starting Weight (startingWeight): [0]
Started on distributed (startedOnDistributed): [false]
Restart behavior on update (restartBehaviorOnUpdate): [DEFAULT]
Specify servers (MapTargets)
Specify targets such as application servers or clusters of application servers where we want
to deploy the cu contained in the application.
Deployable Unit (deplUnit): [default]
*Servers (server): [WebSphere:node=myNode,server=server1]
Specify Composition Unit activation plan options (ActivationPlanOptions)
Specify CU activation plan optionsDeployableUnit Name (deplUnit): [default]
Activation Plan (activationPlan): [WebSphere:specname=actplan0+WebSphere:specname=actplan1]
If the composition unit contains an enterprise bundle archive (EBA) asset, the composition unit status is also displayed. This status is one of the following values:
- Use latest OSGi application deployment.
- New OSGi application deployment not yet available because it requires bundles that are still downloading.
- New OSGi application deployment available.
- New OSGi application deployment cannot be applied because bundle downloads have failed.
Batch mode example usage
The following example displays configuration information for a non-enterprise asset:
- Use Jython string:
- AdminTask.viewCompUnit('-blaID myBLA -cuID myCompUnit')
- Use Jython list:
- AdminTask.viewCompUnit(['-blaID', 'myBLA', '-cuID', 'myCompUnit'])
The following example displays configuration information for an enterprise asset:
- Use Jython string:
- AdminTask.viewCompUnit('-blaID myBLA -cuID defaultApplication')
- Use Jython list:
- AdminTask.viewCompUnit(['-blaID', 'myBLA', '-cuID', 'defaultApplication'])
Interactive mode example usage
- Use Jython:
- AdminTask.viewCompUnit('-interactive')
createEmptyBLA
Create an empty business-level application. After creating a business-level application, we can add assets or other business-level applications as composition units to the application.
Target object: None
Required parameters:
- -name
- Unique name for the new business-level application. (String, required)
Optional parameters:
- -description
- Description of the new business-level application. (String, optional)
Return value.
The command returns the configuration ID of the new business-level application:
- WebSphere:blaname=myBLA
Batch mode example usage
- Use Jython string:
- AdminTask.createEmptyBLA('-name myBLA -description "my description for BLA"')
- Use Jython list:
- AdminTask.createEmptyBLA(['-name', 'myBLA', '-description', '"my description for BLA"'])
Interactive mode example usage
- Use Jython:
- AdminTask.createEmptyBLA('-interactive')
deleteBLA
Remove a business-level application from the configuration. Before deleting a business-level application, use the deleteCompUnit command to remove each composition unit associated with the business-level application. Verify that no other business-level applications reference the business-level application to delete.
Target object: None
Required parameters:
- -blaID
- Configuration ID of the business-level application of interest. The command accepts an incomplete ID for the blaID parameter, as long as the system can match the string to a unique identifier. For example, we can specify the myBLA partial ID to identify the WebSphere:blaname=myBLA configuration ID. (String, required)
Optional parameters: None
Return value.
The command returns the configuration ID of the deleted business-level application:
- WebSphere:blaname=myBLA
Batch mode example usage
- Use Jython string:
- AdminTask.deleteBLA('-blaID myBLA')
- Use Jython list:
- AdminTask.deleteBLA(['-blaID', 'myBLA'])
Interactive mode example usage
- Use Jython:
- AdminTask.deleteBLA('-interactive')
editBLA
Modify the description of a business-level application.
Target object: None
Required parameters:
- -blaID
- Configuration ID of the business-level application of interest. (String, required)
Optional steps
For optional steps, use the .* characters to specify a read-only argument in the command syntax. Specify an empty string with the "" characters to keep the existing value of the argument. If we do not specify a value or an empty string for a writable argument, the command resets the argument to a null value.
- -BLAOptions
- Use the BLAOptions step to specify a new description for the business-level application of interest.
- name (read-only)
- Name of the business-level application.
- description
- Description of the business-level application.
Return value. The command does not return output.
Batch mode example usage
- Use Jython string:
- AdminTask.editBLA('-blaID DefaultApplication -BLAOptions [[.* "my new description"]]')
- Use Jython list:
- AdminTask.editBLA(['-blaID', 'DefaultApplication', '-BLAOptions', '[[.* "my new description"]]'])
Interactive mode example usage
- Use Jython:
- AdminTask.editBLA('-interactive')
getBLAStatus
Display whether a business-level application or composition unit is running or stopped.
Target object: None
Required parameters:
- -blaID
- Configuration ID of the business-level application of interest. Use the listBLAs command to display a list of business-level application configuration IDs. (String, required)
Optional parameters:
- -cuID
- Configuration ID of the composition unit of interest. Use the listCompUnits command to display a list of composition unit configuration IDs. (String, optional)
Return value.
The command returns the status of the business-level application or composition unit of interest.
Batch mode example usage
- Use Jython string:
- AdminTask.getBLAStatus('-blaID WebSphere:blaname=myBLA -cuID WebSphere:cuname=cu1')
- Use Jython list:
- AdminTask.getBLAStatus(['-blaID', 'WebSphere:blaname=myBLA', '-cuID', 'WebSphere:cuname=cu1'])
Interactive mode example usage
- Use Jython:
- AdminTask.getBLAStatus('-interactive')
listBLAs
Display the business-level applications in the configuration.
Target object: None
Optional parameters:
- -blaID
- Configuration ID of the business-level application of interest. (String, optional)
- -includeDescription
- Specifies whether to include a description of each business-level application that the command returns. Specify true to display the business-level application descriptions. (String, optional)
Return value.
The command returns a list of configuration IDs for each business-level application in the configuration:
- WebSphere:blaname=myBLA
WebSphere:blaname=yourBLA
Batch mode example usage
The following example lists each business-level application in the configuration:
- Use Jython:
- AdminTask.listBLAs()
Use the following examples to list each business-level application in the configuration:
- Use Jython string:
- AdminTask.listBLAs('-blaID myBLA')
- Use Jython list:
- AdminTask.listBLAs(['-blaID', 'myBLA'])
Use the following examples to list each business-level application and the corresponding descriptions:
- Use Jython string:
- AdminTask.listBLAs('-includeDescription true')
- Use Jython list:
- AdminTask.listBLAs(['-includeDescription', 'true'])
Interactive mode example usage
- Use Jython string:
- AdminTask.listBLAs('-interactive')
listControlOps
Display the control operations for a business-level application and the corresponding composition units.
Target object: None
Required parameters:
- -blaID
- Configuration ID of the business-level application of interest. (String, required)
Optional parameters:
- -cuID
- Composition unit of interest. (String, optional)
- -opName
- Operation name of interest. (String, optional)
- -long
- Specifies whether to include additional configuration information in the command output. (String, optional)
Return value.
The command returns a list of operations, operation descriptions, and parameter descriptions for the query scope:
- "Operation: start"
"Description: Start operation"
"Operation handler ID: com.mycompany.myasset.ControlOpHandler"
"Operation handler data URI: None"
"Operation: stop"
"Description: Stop operation"
"Operation handler ID: com.mycompany.myasset.ControlOpHandler"
"Operation handler data URI: None"
"Operation: clearCache"
"Description: Clears specified cache or all caches"
"Operation handler ID: com.mycompany.myasset.ControlOpHandler"
"Operation handler data URI: None"
"Parameter: cacheName"
"Description: Name of cache to clear. If not specified, all caches are cleared."
Batch mode example usage
- Use Jython string:
- AdminTask.listControlOps('-blaID myBLA -cuID myservice.jar -long true')
- Use Jython list:
- AdminTask.listControlOps(['-blaID', 'myBLA', '-cuID', 'myservice.jar', '-long true'])
Interactive mode example usage
- Use Jython:
- AdminTask.listControlOps('-interactive')
startBLA
Start the business-level application of interest.
Target object: None
Required parameters:
- -blaID
- Configuration ID of the business-level application to start. The command accepts an incomplete configuration ID if the system matches the string to a unique ID in the configuration. (String, required)
Return value.
The command returns a status message if the business-level application starts. If the business-level application does not start, the command does not return output. The following example displays the status message output:
- BLA ID of started BLA if the BLA was not already running.
Batch mode example usage
- Use Jython string:
- AdminTask.startBLA('-blaID myBLA')
- Use Jython list:
- AdminTask.startBLA(['-blaID', 'myBLA'])
Interactive mode example usage
- Use Jython:
- AdminTask.startBLA('-interactive')
stopBLA
Stop the business-level application of interest.
Target object: None
Required parameters:
- -blaID
- Configuration ID of the business-level application to stop. The command accepts an incomplete configuration ID if the system matches the string to a unique ID in the configuration. (String, required)
Return value.
The command returns a status message if the business-level application stops. If the business-level application does not stop, the command does not return output. The following example displays the status message output:
- BLA ID of stopped BLA if the BLA was not already stopped.
Batch mode example usage
- Use Jython string:
- AdminTask.stopBLA('-blaID myBLA')
- Use Jython list:
- AdminTask.stopBLA(['-blaID', 'myBLA'])
Interactive mode example usage
- Use Jython:
- AdminTask.stopBLA('-interactive')
viewBLA
Display the name and description of the business-level application of interest.
Target object: None
Required parameters:
- -blaID
- Configuration ID of the business-level application of interest. The command accepts an incomplete configuration ID if the system matches the string to a unique business-level application. (String, required)
Optional parameters: None
Return value.
The command returns configuration information for the business-level application of interest, as the following example displays:
- Specify BLA options (BLAOptions)
Specify options for BLA
*BLA Name (name): [DefaultApplication]
BLA Description (description): []
Batch mode example usage
- Use Jython string:
- AdminTask.viewBLA('-blaID DefaultApplication')
- Use Jython list:
- AdminTask.viewBLA(['-blaID', 'DefaultApplication'])
Interactive mode example usage
- Use Jython:
- AdminTask.viewBLA('-interactive')
Related: