The Business Transaction Management Command Line Interface (CLI) allows you to issue management commands from the command line or through the use of scripts (in bash, perl, ruby, DOS). You can use the CLI from the Unix and DOS command lines, and any other environments that work with your Business Transaction Management installation.
CLI commands allow you to configure the system, manage DNS aliases, resolve replication issues, register services, manage metadata, control monitoring, apply policies, migrate data, or generate data needed for reporting.
The CLI executable (btmcli.bat on Windows and btmcli.sh on Unix-like systems) is located in the BTM_Install_Directory/tools directory. On Windows platforms, the CLI uses the JRE bundled with Business Transaction Management. On Unix-like systems, you must specify a JRE to use by doing one of the following:
set the JAVA_HOME environment variable and remove the BTMi_nstall_dir/_server/jre directory
replace BTM_install_dir/server/jre with a link to a valid JRE directory
There are several command line utilities for performing additional actions. See About Command Line Utilities for more information.
To get a list of all CLI commands with a brief help summary, enter the following command:
C: > btmcli help
To get detailed help for an individual command, enter a command like the following:
C: > btmcli help commandName
To get version information, use the following command:
C: > btmcli -v
You can execute a Business Transaction Management CLI command or script in any command shell using the following syntax:
btmcli commandName commandFlags
To execute a single command, specify the command and its parameters at the command prompt. For example:
C: btmcli encryptPassword -password "abracadabra"
To execute a script, specify the name of the script at the command prompt. For example:
C: > myBTMScript.cmd
The script can contain any Business Transaction Management CLI commands.
The name of your script file should have an extension that is appropriate for your operating system (.cmd, .bat, .sh).
Script comments should be formatted as appropriate for your operating system.
The script can make use of the environment variables described in Environment Variables.
Nearly all CLI commands require that you provide a credential in the form of username:password to execute the command.
You can provide this credential in one of two ways:
Using the -l flag to the command.
Setting the AP_USER_LOGIN environment variable to the value of the credential. In this case, you do not have to specify the -l flag.
Whether you use the -l flag or the environment variable, you can specify the credential in one of two ways:
by providing the user name and password directly when you enter the command, or by setting the AP_USER_LOGIN environment variable to that username:password value.
by creating a username:password credential in a credential store, and passing the credential name to the command or by setting the AP_USER_LOGIN environment variable to the value of that credential name.
The following examples use the btmcli configure command to illustrate each case:
In the following command, the -l flag is used to specify a user name and password.
btmcli configure -i myConfigureFile -s http://uitst3:8080/btmcentral/sphere/ -l joanna:abracadabra
In the following command, no -l flag is specified because the AP_USER_LOGIN environment variable has been set to joanna:abracadabra.
btmcli configure -i myConfigureFile -s http://uitst3:8080/btmcentral/sphere
In the following command, the credential JoannaCred has been defined by the credStoreTool command as follows:
btmcli credStoreTool -createCred JoannaCred -credType up -credValue joanna:abracadabra
The configure command will then look like this:
btmcli configure -i myConfigureFile -s http://uitst3:8080/btmcentral/sphere/ -l JoannaCred
In the following command, the credential JoannaCred has been defined by the credStoreTool command as follows:
btmcli credStoreTool -createCred JoannaCred -credType up -credValue joanna:abracadabra
The AP_USER_LOGIN environment variable has then been set to JoannaCred=joanna:abracadabra. The configure command will then look like this:
btmcli configure -i myConfigureFile -s http://uitst3:8080/btmcentral/sphere/
The following table lists CLI commands in alphabetical order and provides a summary of the command action.
| Command Name | Description |
|---|---|
| addBaseAddressAlias | Add the specified alias for the entry point with the given base address. If another entry point with this alias as its base address is already known to the sphere, the two entry points and their contents are merged, and duplicate WSDLs and endpoints are removed. |
| addNodeAlias | Add network aliases to an already registered node. |
| addPathAlias | Use the addPathAlias command to add an alias representing an alternative URL path that can be used to access the specified WSDL or endpoint. Specifying this alias can help prevent duplicate artifacts from being created during discovery. |
| configure | Read a configuration xml file and use the information to configure the installation associated with the given sphere URL. |
| configureAlivenessCheck | Specify the preferred method for the sphere to check the aliveness of endpoints, rather than using the default ping. |
| createOrUpdateGenre | Specifies the name of a new service or endpoint genre, and identifies a custom icon to be used in representing the new genre. |
| createOrUpdatePolicy | Create or update the specified policy directly in the sphere. |
| createSettingsDocument | Use the createSettingsDocument command to create a settings document for input to the createOrUpdatePolicy command. |
| credStoreTool | Creates, obtains, or deletes the specified type of credential from the credential store. |
| deleteAll | Deletes discovered objects along with related artifacts such as transactions, properties, registered services, and containers. Also deletes historical data associated with deleted items. |
| encryptPassword | Convert the specified text string using the Business Transaction Management encryption engine. The resulting cipher text appears in the command output. |
| exportBusinessObjects | Create a settings document for input to the createOrUpdatePolicy command. |
| exportMessages | Export messages for an endpoint for a specified period of time. Exporting messages can be useful in testing and debugging.
You have the option of exporting messages to a file; whether you do or not, output is always sent to the Console. |
| exportPolicies | Export the specified policies either to stdout, or to the named output file. Policies can be exported by name, type, or by means of a query that defines a set of policies. |
| exportPolicyTemplates | Export the specified policy templates either to stdout, or to the named output file. Policies templates can be exported by name, type, or by means of a query that defines a set of policies. |
| exportProfile | Export the profile values for the specified object(s) either to stdout, or to the named output file. Profiles can be exported by name or id. |
| exportSchedules | Export schedules from the target sphere. You can output the schedules to a file or to stdout. Schedules can be exported by name or by means of a query that defines a set of policies. |
| exportTransactionDefns | Export the specified transaction definitions. If you do not specify an output file, the definition is sent to stdout. |
| getSetupData | Write the setup file for the specified service to standard output. You can use this setup file as input for the putSetupData command. |
| importBusinessObjects | Import one or more of the specified business objects described by the specified XML file into the target sphere. By default, this command replaces all existing objects that are older than the imported objects. |
| importPolicies | Import the policies contained in a previously created export file. The policies to be imported will be taken from the file specified by the -i parameter, or from stdin, if no such file is specified. |
| importPolicyTemplates | Import the policy templates contained in a previously created export file. The policy templates to be imported will be taken from the file provided by the -i parameter or from stdin if no such file is specified. |
| importProfile | Import a previously exported object profile into the system. Note that importing a profile does not cause new objects to be created, it only updates the profile attributes of existing objects. |
| importSchedules | Import previously exported schedules to the target sphere. By default, this command replaces all existing schedules that are older than imported schedules. |
| importTransactionDefns | Import previously exported transaction definitions to the specified sphere. By default, this command replaces all existing definitions that are older than imported definitions. |
| listInstruments | List the instruments defined by the policy templates in the system, as well as the attribute names and segments for each. You can use this information as arguments for the retrieveObjectData command. |
| listNodeAliases | List all the aliases for a single network node, or for all known network nodes. |
| mergeServices | Merge two versions of the specified service. This command removes the source version and moves its endpoints to the target version.
After the merge, the target version contains all the endpoints from both versions. If the source version has any profile attributes or message properties that you want to retain for the merged versions, you must recreate these on the target version. |
| moveEndpoints | Move one or more endpoints from the source version to the target version of the specified service. |
| moveMeasurements | Move the measurements collected for a service or endpoint that has been deleted from the sphere to another endpoint or service that is its logical successor. |
| putSetupData | Read the setup file from a named file or from standard input and save it as the setup data for the specified service. |
| registerDevice | Register a management device with the sphere. Currently, hardware and software load balancers are the only supported device type, and the F5 BigIP is the only fully-supported load-balancer.
If you register multiple devices, you can use the |
| registerExternalContainer | Group the endpoints of one or more entry points (not part of an observed container) into their own external container. This is only necessary for manually-registered endpoints. |
| registerMonitor | Register a monitor agent with Business Transaction Management. |
| removeBaseAddressAlias | Remove the specified alias to the entry point with the given base address. The alias must be defined locally for this entry point only. Aliases defined at the network node level must be removed using the removeNodeAlias command. |
| removeDuplicateEndpoint | Remove the specified duplicate endpoint. Typically, you would use this command when the system discovers two endpoints with the same path but different host names due to a DNS alias that was not known to the system. Executing this command also adds the missing alias to make sure that future discoveries do not result in recreating the duplicate endpoint. |
| removeNode | Remove a network node from the sphere. |
| removeNodeAlias | Remove aliases from a registered node. |
| removePathAlias | Remove an alias representing an alternative URL path that can be used to access the specified WSDL or endpoint. Any future registration or discovery will again treat the two paths as distinct. |
| removePolicy | Remove an applied policy and optionally wait for the removal of the policy to complete. |
| removePolicyTemplate | Removes the specified policy template from the system. |
| renameEndpoint | Change the specified endpoint's friendly name in the sphere. |
| resetSphereUrl | Make sure the sphere URL for container services currently registered with this sphere matches the current sphere URL. You might need to use this command if the base address of the sphere changes. |
| retrieveObjectData | Retrieve profile and measurement data for one or more objects. You can use this data as input to a reporting tool. |
| sendEventNotification | Create and send an event notification using the Notifier Service. How the notification is handled is determined by the currently active subscriptions. |
| sendToNotifier | Send commands to the Notifier Service for processing. The commands are specified in the XML input file. The command returns the response document returned by the Notifier Service. |
| setBaselines | Set baselines for managed objects. The input document format is the same as the output of the retrieveObjectData command. |
| setDefaultLoadBalancer | Set the default device used to model routing entry points discovered from observed message traffic.
In a simple environment with only one known load-balancer, that device is automatically used as the default. If you register additional devices, use this command to set which device should be used to model routing entry points. |
| showService | Show the structure of the service specified by the friendly name, qualified name, or URL of any endpoint for this service. You can also specify a single version of the service (-version) or the display of more detailed information (-verbose). |
| unmonitorEndpoint | Stop monitoring the specified endpoint with the monitor agent where it is registered. Once monitoring stops, no performance measurements are recorded, no messages are logged, and no transactions are traced. |
| unregister | Unregister the service, WSDL, or endpoint from the sphere. |
| unregisterContainer | Unregisters the specified container. |
| unregisterMonitor | Unregister the specified monitor agent from the sphere. Use this command only when the monitor has been taken offline permanently. Monitors must be offline long enough for the system to mark them down before you can unregister them. |
| updateProfileData | Update profile attribute data for the specified set of objects. This command only updates existing objects; if it cannot find the specified objects, it returns an error. |
The following table describes environment variables that you can define for use with the Business Transaction Management commands in the place of commonly used command flags.
| Environment Variable | Flag Name Equivalen | Flag Long Name Equivalent | Description |
|---|---|---|---|
AP_SPHERE_URL |
-s |
-sphereUrl |
The URL for the sphere. http://hostname:port/apcentral/sphere/
.NET example: |
AP_USER_LOGIN |
-l |
-userLogin |
The log-in credentials for the sphere, in one of the following formats:
credName=myCredentialName Typically these would be the credentials of a user with administrative privileges. See Authentication and Role Mapping for more information. You can encrypt passwords for use with the CLI using the |
A number of CLI commands require that you pass an attribute name as a flag value. This section lists valid attribute names for different object types.
| Name | Name | Name |
|---|---|---|
| aliases | friendlyName | operationsNote |
| binding | gateway | qualifiedName |
| businessContact | genericNote | relativeLocation |
| businessNote | genre | service |
| contact | interface | serviceQName |
| container | isAlive | relativeLocation |
| defaultCredentials | lastIsAliveChangeDate | service |
| dependsOnEndpoint | lastManagementChangeDate | serviceQName |
| deployment | lastManagementChangeIdentity | serviceDescriptionURL |
| description | lastUpdateIdentity | supportContact |
| endpointAppProtocol | lastUpdateMarker | supportNote |
| endpointSoftwareType | location | targetEndpoint |
| endpointSource | managingIntermediaries | technicalContact |
| endpointTransportProtocol | note | technicalNote |
| endpointType | operations | testingNote |
| firstRegistryDate | operationsContact | uddiBusinessKey |
| -- | -- | uddiKey |
| Name |
|---|
| dependsOn |
| operationName |
| operationType |
| propertyOverrides |
| Name | Name | Name |
|---|---|---|
| businessContact | name | supportNote |
| businessNote | namespace | technicalContact |
| classifications | note | technicalNote |
| contact | operations | testingNote |
| description | operationsContact | uddiBusinessKey |
| friendlyName | operationsNote | uddiKey |
| genericNote | owningEndpoint | -- |
| lastUpdateIdentity | sourceType | -- |
| lastUpdateMarker | supportContact | -- |
Interface Operation Attributes
| Name |
|---|
| classification |
| documentation |
| operationName |
| operationType |
| properties |
| sampleMessageNotes |
| Name | Name | Name |
|---|---|---|
| alive | lastIsAliveChangeDate | serviceSource |
| applicationGroup | lastManagementChangeDate | serviceType |
| businessContact | lastManagementChangeIdentity | supportContact |
| businessNote | lastUpdateIdentity | supportNote |
| category | lastUpdateMarker | technicalContact |
| contact | managedDescriptionURL | technicalNote |
| deploymentNames | note | testingContact |
| description | operations | testingNote |
| documentation | operationsContact | uddiBusinessKey |
| endpoints | operationsNote | uddiKey |
| firstRegistryDate | organization | version |
| friendlyName | originalDescriptionURL | -- |
| lastDeployDate | primaryDeploymentName | -- |
| lastDeployIdentity | qualifiedName | -- |
The only transaction attribute is friendlyName.
| Name | Name | Name |
|---|---|---|
| administratorUI | lastIsAliveChangeDate | phaseInLifeCycle |
| baseAddress | lastDeployIdentity | supportContact |
| businessContact | lastDiscoveryDate | supportNote |
| businessNote | lastManagementChangeDate | technicalContact |
| connectionLimit | lastManagementChangeIdentity | technicalNote |
| contact | lastUpdateIdentity | testingContact |
| containerInfo | lastUpdateMarker | testingNote |
| firstRegistryDate | note | uddiBusinessKey |
| friendlyName | operationsContact | uddiKey |
| genericNote | operationsNote | -- |
| hostName | osName | -- |
| implementationType | osVersion | -- |
| ipAddress | owner | -- |
| isAlive | performanceRating | -- |
| Name | Name | Name |
|---|---|---|
| businessContact | isAlive | supportContact |
| businessNote | lastDeploymentDate | supportNote |
| contact | lastDeploymentIdentity | technicalContact |
| container | lastIsAliveChangeDate | technicalNote |
| deploymentCategory | lastUpdateIdentity | testingContact |
| deploymentStatus | lastUpdateMarker | testingNote |
| deploymentType | note | uddiBusinessKey |
| description | operationsContact | uddiKey |
| firstRegistryDate | operationsNote | -- |
| friendlyName | pluginAgentPossible | -- |
| genericNote | pluginAgentPossibleText | -- |
| Name |
|---|
| emailAddress |
| informationURL |
| name |
| phoneNumber |
| usage |
Includes two attribute names: theNote and usage.
Includes two attribute names: contacts and notes.