This chapter introduces the Business Transaction Management command line interface (CLI), which you can use to execute commands as well as scripts. It explains how you use the CLI, how you get help and version information, how you can execute commands securely, and it describes the system variables you can set to use with commands. It includes the following sections:
In addition to commands, Business Transaction Management also provides several utilities. These are described in Chapter 11, "Utilities."
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 Section 11.1, "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 Section 10.1.5, "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, both hardware and software load balancers are supported device types.
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 Section 12.3.1, "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.
Use the addBaseAddressAlias command to 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 removed.
The addBaseAddressAlias command accomplishes the same thing as the command removeDuplicateEndpoint when that command is given two endpoints that differ only in their base address.
Using the -force option creates an entry point and its alias before any endpoints corresponding to that entry point are discovered or registered, thus preventing duplicates from being (mistakenly) created in the first place.
Unlike the aliases created by the addNodeAlias command, aliases created by the addBaseAddressAlias command or the removeDuplicateEndpoint command apply to a single entry point. If the same alias is added at the network node level, either automatically by message observation or discovery, or manually by the addNodeAlias command, it will supercede the locally-defined alias for the entry point, and it will not be possible to delete that alias using the removeBaseAddressAlias command.
You can preview the results of this command before committing to the changes it defines. After previewing, you must run the command again without the -P option to actually make the changes.
Use the removeBaseAddressAlias command to remove an alias created with the addBaseAddressAlias command.
Section 12.7, "Resolving Discovery Issues" describes the use of this command in resolving discovery issues.
btmcli addBaseAddressAlias -baseAddress address -alias address [-P] [-f] -s sphereURL -l username:password
| Name | Long Name | Description |
|---|---|---|
| -baseAddress | -- | The base address of an existing entry point in the sphere. Use the format scheme://host:port/ |
| -alias | -- | The base address to use as an alias for the above entry point. |
| -P | -preview | Preview the result of the command, but do not actually make any changes to the model. |
| -f | -force | Create an entry point with the given base address if it does not yet exist. Use this option to prime the system with aliases before duplicate endpoints are discovered. |
| -s | -sphereUrl | The URL of the sphere. http://hostname:port/btmcentral/sphere/
This flag is not required if you have set the |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the addBaseAddressAlias command.
btmcli addBaseAddressAlias -baseAddress http://jbujes:8080
-alias http://1.2.3.4:8080 -s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the addNodeAlias command to add the specified alias to the network node identified by the canonical name. If the node does not exist, the alias is not added unless you also specify the -force option, in which case the node is created as well.
Use the removeNodeAlias command to delete an alias created with the addNodeAlias command.
See Section 12.7, "Resolving Discovery Issues" for a discussion of the use of this command in resolving discovery issues.
btmcli addNodeAlias -n nodeName -alias aliasName [-f] -s sphereURL -l username:password
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The canonical name of the network node. Typically a fully-qualified domain name. For example, jbujes-myPC.edgility.com |
| -alias | -alias | An alias for the network node. This can be a domain name or a static IP address. |
| -f | -- | Force the alias to be created (as well as its canonical network node) even if the network node is unknown. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the addNodeAlias command.
btmcli addNodeAlias -n jbujesPC.edgility.com -alias Athena
-s http://localhost:8080/btmcentral/sphere/ -l admin:abracadabra
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.
Normally, path aliases are added automatically in one of two ways:
The register command detects an HTTP redirect and adds the original URL as an alias to the service descriptor created with the redirected URL.
The user uses the removeDuplicateEndpoint command to remove an unwanted duplicate created due to message traffic being observed at a non-canonical URL for an existing endpoint.
In the second case, adding the alias when the original endpoint is registered or discovered will prevent the duplicate from ever being created. So, you might add the addPathAlias command to a script used to recreate an environment that was observed in testing to have this problem.
Use the removePathAlias command to delete an alias you created with the addPathAlias command.
See also addNodeAlias for host name aliases and addBaseAddressAlias for other aliases in the authority part of the WSDL's URL.
See the section "Resolving Discovery Issues" for a discussion of the use of this command.
btmcli addPathAlias -s wsdlUrl | -e endpointUrl -alias pathAlias -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -w | -wsdlUrl | The full URL of the WSDL (service descriptor) for which you want to add an alias. |
| -e | -endpointUrl | The full URL of the endpoint(s) for which to add the alias. If multiple endpoints are matched, they will all be given the alias. |
| -alias | -- | The alternate path to map to the same descriptor or endpoint. This should be just the path portion of the URL, starting with "/". |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the addPathAliascommand.
btmcli addPathAlias -e http://jbujes:7001/bookmart/credit/CreditService
-alias /bookmart/amex/CreditService
-s http://jbujes:8080/btmcetnral/sphere/ -l admin:abracadabra
Use the configure command to configure Business Transaction Management as an alternative to using the browser-based Configuration Wizard for initial configuration. You use the configure command in conjunction with an input file that contains specifications for various Business Transaction Management settings.
Before executing the configure command, you must decide whether you want to store information in an embedded database, or in an Oracle database. If you want to store information in an Oracle database, you will need to install and set up the database before running the configure command.
The sections following the syntax description provide additional information about the configuration process and the input file.
btmcli configure -i inputFile -sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -i | -inputFile | The path to the configuration file to use to configure a Business Transaction Management installation. |
| -s | -sphereUrl | The URL of the sphere you want to configure.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the configure command.
btmcli configure -i myConfigFile.xml -s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
The configure command checks every Business Transaction Management service for its current configuration state. If all services are in a configured state, the command exits and informs you that Business Transaction Management is configured. If there is a mix of configured and unconfigured services, the configure command attempts to configure the unconfigured services. If an error or exception occurs, Business Transaction Management logs the error and the configuration continues. When the configure command completes, it returns a message that describes all successful and unsuccessful service configurations.
If all Business Transaction Management services are configured successfully, the command returns a "configured" message.
You can run the configure command again following a configuration attempt where an error occurs, and the system will attempt to configure the service(s) that returned an error during the previous configuration attempt. The configure command does not try to reconfigure a service that reports a successful configuration.
If you would like to reconfigure a service that has been configured successfully, you can run the getSetupData and putSetupData commands.
Any reconfiguration of Business Transaction Management services requires a restart of the server.
When you install and configure Business Transaction Management using the browser-based configuration wizard, a configuration file called essentialConfiguration.xml is created. (See Section 12.4, "Backing up and Restoring Business Transaction Management," for information on its location on different platforms.) You can use this file as a starting point to initialize a new Business Transaction Management system; you will need to change the contents of the file to specify your desired settings. This then becomes the input file to the configure command. The preference names in the configuration file, and their values, are both case sensitive.
Unlike the Configuration Wizard, the configure command does not allow you to stop midway through the configuration and then resume configuration at a later time. The configure command requires a complete configuration file -- if required parameters are missing from the file, the configure command returns an error.
To supply an encrypted password for the configuration file, run the encryptPassword command and then copy and paste the resulting value into the configuration file.
If you use a clear text password in the configuration file, Business Transaction Management encrypts the password when it stores the configuration information in the setup data of the appropriate system services.
The following table lists the parameters to use in the configure command configuration file.
You can specify alias values for the nodes running Business Transaction Management central services: sphere, performance, and transaction monitoring. In each case the preference value is a comma-separated list of alternative DNS names/IP addresses that can be used to access services on the respective server.
For example, if the sphere URL is http://server1:8080/apcentral/sphere/, but the machine server1 also has the DNS alias spherehost, you can set sphereAliases to spherehost to reflect that. If the machine's primary IP address is 10.10.22.44, but the sphere's container is listening on all lP addresses and the machine has a second network interface running on 10.10.22.47, you could set sphereAliases to spherehost, 10.10.22.47 to reflect both these aliases.
If all Business Transaction Management central services are running in the same container (the demo case), the performanceAliases and transactionAliases are ignored. If the servers are running in different containers but on the same machine as the sphere, the aliases are applied to the same node definition. So, in effect, the performance and transaction aliases are added to those for the sphere, rather than tracked separately.
Note: All parameters are type=string, except for the acceptLicenseTerms parameter, which is type=boolean.
| Parameter Name | Required | Description |
|---|---|---|
| sphereUrl | YES | URL of the sphere you are configuring. The sphere is deployed in btmMain.
The value should be the same value provided in the -s flag for the configure command. http://hostname:port/btmcentral/sphere/ |
| databaseChoice | YES | Indicates the type of database to use for the Business Transaction Management databases.
Use one of the following:
If you specify embedded, ignore all subsequent database settings. |
| nodeAliases | No | Aliases for the node running the sphere.
See discussion of Alias preferences, above. |
| performance.nodeAliases | No | Aliases for the node running the performance server (btmperformance.war).
See discussion of Alias preferences, above. |
| transaction.nodeAliases | No | Aliases for the node running the transaction server (btmexmrt.war).
See discussion of Alias preferences, above. |
| deploymentUsername, deploymentPassword | YES | Some Business Transaction Management services communicate with the application server to perform discovery; these services require a set of administrative credentials mapped to an administrative user for the application server
This is required for all application servers except Tomcat |
| agentServiceDB_databaseUrl, agentServiceDB_provider, agentServiceDB_userName, agentServiceDB_password | NO | Agent message log database. By default, all agents in a container log to this database. You can override the behavior after initial configuration. See Section 12.2.2, "Setting up the Message Log Database."
This is required if databaseChoice is Embedded. |
| sphereServiceDB_databaseUrl, sphereServiceDB_provider, sphereServiceDB_userName, sphereServiceDB_password | NO | Sphere database settings.
Required if databaseChoice != Embedded |
| exmServiceDB_databaseUrl, exmServiceDB_provider, exmServiceDB_userName, exmServiceDB_password | Required if databaseChoice != Embedded | Exception management component database settings.
Required if databaseChoice != Embedded |
| performanceDB_databaseUrl, performanceDB_provider, performanceDB_userName, performanceDB_password | Required if databaseChoice != Embedded | Performance component (SLM) database settings.
Required if databaseChoice != Embedded |
| performanceUrl | YES | The URL to use to contact the performance (SLM) component of Business Transaction Management (this component is deployed in btmPerformanceServer). The performance component must be running at the time of configuration.
btmPerformanceServer is typically deployed in a separate container than the sphere. When you specify an performanceURL on a different node that the sphere, Business Transaction Management also registers the remote container with the sphere. |
| transactionURL | NO | The URL to use to contact the transaction component of Business Transaction Management (this component is deployed in btmTransactionServer). The transaction component must be running at the time of configuration.
btmTransactionServer is typically deployed in a separate container than the sphere. When you specify an transactionURL on a different node that the sphere, Business Transaction Management also registers the remote container with the sphere. |
| base_locationType, base_directory,
base_maxDuration, base_maxSize, base_numFiles |
Optional | By default, trace log files are stored in the directory BTMStorageRoot/deployment_name/system_service/logdir
BTMStorageRoot varies with the application server; for more information, see Section 12.4, "Backing up and Restoring Business Transaction Management.". If you wish to store trace log files in a different location, use the parameters described below. Note: These parameters will not affect the trace log file settings for the following system services: aqms, notifier, and domain.
Note: If you change the directory location using the above parameters, you are required to also include the base_maxDuration, base_maxSize and base_numFiles parameter settings.
|
Use the configureAlivenessCheck command to specify whether the sphere checks the aliveness of containers or endpoints and the preferred method for doing so.
btmcli configureAlivenessCheck -baseAddress baseAddress | -e epUrl1 [[epUrl2]...] -method standard | skip | getwsdl |geturl | ping [-alternateUrl alternateUrl] [-endpointDreds username:password] [-pingHostPort host:port] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -baseAddress | -- | The base address for which to configure aliveness check. The effect of this flag depends on the setting of the -method flag:
If -method is set to standard, geturl, or ping, the base address is tested only once and all endpoints under this base address inherit its aliveness value. If -method is set to getwsdl, each endpoint with the specified base address has its WSDL fetched. If -method is set to skip, no aliveness checking is performed for this base address, but endpoints with this base address might be checked individually if specified with the -e or -alternateUrl flags. |
| -e | -endpointUrl | One or more endpoint URLs for which to configure aliveness checking. All endpoints with the given URLs are configured identically. |
| -method | -- | The method to be used for aliveness checking. Choose one of the following: standard: open and close a socket to the given host:port
See below for more details. |
| -alternateUrl | -- | The URL to use in place of the base address or endpoint URL. This flag is required when the geturl method is used. |
| -endpointCreds | -- | Authentication credentials (username:password) to use when fetching the alternate URL for an endpoint. It is ignored for any other configuration. |
| -pingHostPort | -- | The host and port to ping in place of the actual base address of the endpoint URL. This flag is required only when the method ping is specified. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on the various options available for furnishing login credentials. You can encrypt passwords using the |
Choose the method that best suits the endpoint you are monitoring. For example, for WebLogic JAX_RPC or JAX-WS services, fetching the generated WSDL will succeed if the container is up and the service is deployed and running, so it is as good an aliveness check as actually calling the service without the inconvenience of having a sample message to send that is both valid and harmless. The advantage of the getwsdl method compared to the arbitrary http fetch (geturl) is that you can specify it at the base address level and get the effect of configuring the aliveness check for every endpoint in that base address to fetch its own wsdl without running a separate configureAlivenessCheck command for each of them. However, there are possible disadvantages:
loss of efficiency (WSDL may be large and generating it resource-intensive)
inappropriate for endpoints registered from a copy of the WSDL that was hand-created and/or copied from another server, since you are then checking the aliveness of that HTTP server instead of the endpoint
inappropriate for observer-discovered endpoints whose WSDL is saved as text in the sphere, since you are then checking the aliveness of the sphere.
The following example shows the configureAlivenessCheck command with the getwsdl method for performing the aliveness check.
btmcli configureAlivenessCheck -baseAddress http://jbujesPC:8080 -method getwsdl
-s http://localhost:8080/btmcentral/sphere/ -l admin:abracadabra
Use the createOrUpdateGenre command to create or update the definition of the indicated service or endpoint genre in the sphere. The genre object provides the information needed to properly display service and endpoint type information such as friendly name and icon.
In general, this command will be used when an observer is released off-cycle. At such times, explicit instructions will be provided about the createOrUpdateGenre command to use to teach your current system how to recognize the new genre and how to display services or endpoints of that type.
btmcli createOrUpdateGenre -n name -id id
-t service | endpoint [iconUrl iconUrl]
-overwrite
-sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The user visible or friendly name of the genre. By convention this is often the local name of the qualified name used as the genre's id (when the id is given as a QName).
The value specified will be used as the string to display in the Type field for services and endpoints.; for example, WEB_SERVICE, JAXRPC, DATABASE. |
| -id | -- | The unique identifier for the genre. By convention this is often given as a qualified name with a namespace of urn:com.amberpoint.servicegenres. This value must match the genre identifier returned by the observer when discovering services and/or endpoints. For example: urn:com.amberpoint.servicegenres:JAXRPC |
| -t | -type | Indicates whether this genre represents a service type or an endpoint type. |
| -iconUrl | -- | The URL where the system can find the icon used to represent the genre in the management console.
There will be two icon files for any genre. The file names will be greyTypeIcon.ext and greyTypeOperationIcon.ext, where the value of ext specifies the type of the icon file: gif, bmp, jpeg, or png. The value of Type is either Endpoint of Service.
|
| -overwrite | -- | A switch that specifies whether it is permissible to replace any existing genre of the same id. You must specify this switch when doing an update. |
| -s | -sphereUrl | The URL of the sphere where the service whose setup data you want to get is registered. http://hostname:port/btmcentral/sphere/
This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the createOrUpdateGenre command used to create the endpoint type MyGenre.
btmcli createOrUpdateGenre -name MyGenre
-id urn:com.aberpoint.servicegenres:MyGenre
-s http://localhost:8080/btmcentral/sphre/
-l admin:abracadabra
Use the createOrUpdatePolicy command to create or update the specified policy directly in the sphere.
Creating or updating a policy might involve the following three steps:
Generate the template settings document using the createSettingsDocument command.
Edit the generated document to provide the specific values required for the policy being created.
Create the policy using the createOrUpdatePolicy command, providing the settings document created in Step 2.
To create a new policy, you need to supply only a template name, type, and name. If the policy requires settings, you must also provide a settings document. You can provide additional information to more precisely identify the source template to specify the initial state of the policy, but these are not required.
To update a policy, you must provide a name, type, the -overwrite flag, and any arguments for elements you want to update. Any values you do not specify remain unchanged. Because the policy name and version identify the policy, you cannot use this command to change either. Instead, create a new policy with the desired name and/or version.
btmcli createOrUpdatePolicy [-templateName templateName] [-t type][-subType subType] [-templateVersion version] -n name [-V version] [-desc description] [-settings settingsDocument] [-criteria criterion1 [criterion2]...] [-enable] | [-disable] [-overwrite] [-f] [-s sphereUrl] -l username:password
| Name | Long Name | Description |
|---|---|---|
| -templateName | -- | The name of the template on which to base the new policy.
This parameter is ignored when performing an update. |
| -t | -type | The policy type for the new policy.
This parameter is also used to determine if the specified policy already exists. |
| -subType | -- | The policy sub type for the new policy.
This parameter is also used to determine if the specified policy already exists. |
| -templateVersion | -- | The version of the template on which to base the created policy.
This parameter is ignored when performing an update. |
| -n | -name | The name of the new policy.
This parameter is also used to determine if the specified policy already exists. |
| -V | -version | The version of the new policy.
This parameter is also used to determine if the specified policy already exists. |
| -desc | -description | A description of the policy. |
| -settings | -settingsDocument | The policy's settings document, created with the createSettingsDocument command. |
| -criteria | -- | A list of application criteria for the policy. The form of each criterion is described below. |
| -enable | -- | Marks the policy as enabled. |
| -disable | -- | Marks the policy as disabled. |
| -overwrite | -- | Indicates that if the policy already exists, it should be updated with the specified information. |
| -f | -force | Update the policy even if it is marked internally as "cannot be updated." |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
When creating or modifying a policy, you can specify a set of criteria to be used in determining the monitored objects to which the policy can be applied. The format of each criterion in the set is as follows:
monitoredObjectType [;query [,{UNION | EXCLUDE}]]+
For detailed information on how to specify criteria visit http://www.oracle.com/support/contact.html or visit http://www.oracle.com/accessibility/support.html if you are hearing impaired.
The following example shows the createOrUpdatePolicy command used to enable the enforcement of a pre-existing policy, MyPolicy.
btmcli createOrUpdatePolicy -name MyPolicy -enable
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the createSettingsDocument command to create a settings document for input to the createOrUpdatePolicy command.
A settings document is an XML file. The source of the settings document can be a policy template or an existing policy.
If you specify a policy template, the command returns the default settings document for the policy template.
If you specify a policy, the command returns a settings document with the settings for the current policy instance. You can edit the values in the settings document before submitting it to the createOrUpdatePolicy command.
To determine the type and subtype of a policy or policy template, select the appropriate object in the Navigator. The type and subtype for each policy or policy template is displayed in the summary pane.
btmcli createSettingsDocument -n name [-t type] [-subType subType[ [-V version]
-fromPolicy [-o outputFile]
-s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The name of the template or policy whose settings document you want to use. |
| -t | -type | The type of the policy template or policy whose settings document you want to use. |
| -subType | -- | The subtype of the policy template or policy whose settings document you want to use. |
| -V | -version | The version of the policy template or policy whose settings document you want to use. |
| -fromPolicy | -- | Indicates that the settings document should be constructed using a pre-existing policy instance and not a template. |
| -o | -outputFile | The file where the settings document is written. If this is not specified, the settings document is sent to standard output. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the createSettingsDocument command used to create the settings document MySettingsDoc.
btmcli createSettingsDocument -namemySecurePolicy -o mySettingsDoc
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the credStoreTool command to create, obtain, or delete a credential from the credential store. This command allows you to create three different types of credentials:
credentials based on a username:password format.
You use these credentials to access btmcli commands. Nearly all commands require a user name and password.
credentials based on a trusted issuer and secret
Business Transaction Management components use this type of credential to establish trust relationships between them.
binary credentials (AES keys for the System Default Encryption Key).
An AES encryption key is used to encrypt sensitive data that is transmitted from one Business Transaction Management component to another or when that sensitive data is stored in a database or on disk.
Before you can use this command, you must install and configure the Oracle Java Platform Security classes as described in the Business Transaction Management Installation Guide.
The syntax of the credStoreTool command varies depending on the type of credential you are working with. The sections that follow provide syntax and parameter information for each kind of credential.
In all cases, the commands allow you to create a credential, to obtain a credential if you need to copy it to other servers, and to delete a credential.
This option is more secure than specifying the user name and password on the command line itself or in a script. For additional information in how you use this credential to access btmcli commands, see Section 10.1.3, "Security Options in Accessing CLI Commands."
btmcli credStoreTool -createCred credName [-credType up] [credValue username:password] btmcli credStoreTool -getCred credName [-credType up] [-showPwd] btmcli credStoreTool -deleteCred credName [-credType up]
| Name | Description |
|---|---|
| -createCred | Specifies the name of the credential to be created. |
| -getCred | Specifies the name of the credential to be obtained. |
| -deleteCred | Specifies the name of the credential to be deleted. |
| -credType | The kind of credential to be created, obtained, or deleted.
The default is up. |
| -credValue | If you do not specify this option, you will be prompted for a user name and password. The password entered will be masked with asterisks. |
| -showPwd | For the getCred option, asks that the user name and password be displayed. |
Business Transaction Management components use this type of credentials to establish a trust relationship. When a component receives a request for a service, before it acts, it checks that it came from one of its trusted cohorts.
btmcli credStoreTool -createCred credName credType is [-credValue issuer:secret] btmcli credStoreTool -getCred credName -credType is [-showSecret] btmcli credStoreTool -deleteCred credName -cretType is
| Name | Description |
|---|---|
| -createCred | Specifies the name of the credential to be created. |
| -getCred | Specifies the name of the credential to be obtained. |
| -deleteCred | Specifies the name of the credential to be deleted. |
| -credType | The kind of credential to be created, obtained, or deleted. |
| -credValue | If you do not specify this option, you will be prompted for an issuer and secret. The secret entered will be masked with asterisks. |
| -showSecret | For the getCred option, asks that the issuer and secret be displayed. |
An AES encryption key is used to encrypt sensitive data that is transmitted from one Business Transaction Management component to another or when it stored in a database or on disk.
btmcli credStoreTool -createCred credName -credType bin {credValue Base64-encoded-bytes | -genKey AlgName:KeySize} btmcli credStoreTool -getCred credName credType bin [-showSecret] btmcli credStoreTool -deleteCred credName -credType bin
| Name | Description |
|---|---|
| -createCred | Specifies the name of the credential to be created. |
| -getCred | Specifies the name of the credential to be obtained. |
| -deleteCred | Specifies the name of the credential to be deleted. |
| -credType | The kind of credential to be created, obtained, or deleted. |
| -credValue | Specify a set of bytes (base-64 encoded). These bytes might or might not represent a valid encryption key. |
| -genKey | AlgName refers to the JCE (Java Cryptographic Extension) reserved algorithm name. Currently only AES is supported.
The KeySize is the size of the key that you want to generate. Different algorithms have different allowable key sizes. For AES, these are 128, 192, and 256, which refer to bits (not bytes). 128 is recommended because this is supported in all of the underlying platform's cryptographic implementations. |
| -showSecret | For the getCred option, asks that the size (in bytes) of the binary credential be displayed along with the base-64 encoded bytes themselves. For example,
16 bytes long ... Base-64 = [qvw1wEOxprSeJf2TbtuK5w==] If you do not specify this parameter, the bytes will not be displayed. |
Use the deleteAll command to delete objects already discovered along with related artifacts such as transactions, properties, registered services, devices, and containers.
This is useful when initial discovery configuration results in the discovery of too many objects or of objects that are not of interest. Using this command allows you to start over without having to reinstall the system or to manually remove all observed entities and related artifacts.
Caution:
ThedeleteAll command gives you a clean slate and should be used judiciously to avoid unwanted loss of data, which includes historical data related to observed objects. It is best used when you start working with BTM and are fine tuning your discovery scheme. It should never be used in a production environment.Run the command with the -preview option to determine what objects will be deleted. Run the command again without the -preview option to actually delete these objects.
After you use this command, you can adjust your discovery configuration and then run more traffic to produce the desired results.
deleteAll [-f][-P]-s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
-f |
-force | Forces the deletion of any existing transaction definitions. To retain definitions, you should export them before using the deleteAll command, and reimport them after you re-define your discovery configuration. See the discussion below for more information. |
| -P | -preview | Shows the effect of the command by displaying a list of objects to be deleted, without executing the command. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
When you start working with BTM, figuring out a good discovery configuration might take several tries. The deleteAll command makes it easy to start over.
There are a number of cases in which discovery results might prove overwhelming or uninteresting. Generally this happens when you accept default probe settings, which enable the monitoring of SOA based applications or OSB environments.
SOA-based applications depend upon a large number of internal interconnected EJB components.
OSB WebLogic application server hosts a large number of servlets which, in turn, invoke EJB's or other components.
Equally, WEB_APP and EJB probes are also enabled by default which, after a short time, results in discovering more than what you expected..
Making all these components visible is likely to produce too much information. You want to scale back the picture to the elements of interest.
Other factors might also contribute to producing confusing observation results:
You install an observer where it does not belong. Services and endpoints are discovered that you are not interested in.
It is not always obvious how to optimize the use of BTM monitors until you get to know how BTM works. You might decide to add a monitor and to reassign different probes to different monitors. Objects discovered before and after this change are both now visible.
You update deployments, which results in seemingly redundant service or endpoint registrations.
In sum, you want to start over completely without having to reinstall the system or to manually remove all observed entities and related artifacts. The deleteAll command allows you to do just this.
The deleteAll command deletes data about the following:
non-system containers
user services and service interfaces
Both user-registered endpoints and discovered endpoints are deleted.
devices
dependencies
properties
transaction definitions (using the -f option)
observers and their probes (not the installed bits, just their representation in the Sphere)
persisted runtime data related to the items listed above
This includes measurements and captured message data.
To ensure that you do not lose transaction definitions that you might need later, the deleteAll command requires that you use the -force option to force their deletion. If you want to use these definitions in the future, you should export the transactions and then re-import them after you have redefined your discovery configuration. If you have used properties to enable manual correlation, BTM will re-create these properties to specify those dependencies.
The deleteAll command does not delete data about the following:
system and user policies.
These will be reapplied to newly discovered and registered entities. If you created policies that no longer apply to anything newly discovered, you will need to remove them.
consumers
schedules
alerts
system configuration
The following example show how you use the deleteAll command to delete all discovered and associated artifacts from your system. Sample output follows the command:
btmcli deleteAll
Warning: This command will delete your discovered / registered items in BTM. Continue? (y/n) [n]: y
Deleted Services:
OrderService
ShippingService
bookmartClient
PurchasingDB
CreditService
WarehouseService
Deleted Containers:
jmeredit-lap:9200
Deleted Observer Probes:
Web Application
Servlet
Web Service
JAX-RPC
Database
JDBC
JMS Message Consumer
JMS
Use the encryptPassword command to convert the specified text string using the Business Transaction Management encryption engine and to write the resulting encrypted password to standard output.
You can then copy and paste the output string to provide credentials to commands that require them.
btmcli encryptPassword -password aPlainTextPswd
| Name | Long Name | Description |
|---|---|---|
| -password | -- | A text string that you want to encrypt using the Business Transaction Management encryption engine.
Each encrypted output of the same text string provides a unique ciphertext string. |
btmcli encryptPasword -password "abracadabra"
The exportBusinessObjects command exports one or more of the specified business objects from the target sphere. The command outputs an XML document that you can use to import the business objects into another target sphere.
You can specify the objects to be exported using the -query flag or the -exportAll flag.
btmcli exportBusinessObjects [-exportAll] | [-query filterQuery ] [-o outputFile ] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -exportAll | -- | Export all objects of the appropriate type. |
| -query | -filterQuery | Export only those objects that match the criteria expressed by the filterQuery expression.
Use the Filter tool to construct the query, and then copy and paste the query into the command line. |
| -o | -outputfile | The name of the XML file where the data is written. If you omit this flag, the data is written to standard output. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the exportBusinessObject command used to output data to MyConsumers.
btmcli exportBusinessObject -exportAll -o MyConsumers
-s http://localhost:8080/btmcentral/sphere/
-l admin:password
Use the exportMessages command to export (request and reply) messages for an endpoint for the period during which logging has been turned on. Exporting messages can be useful in testing and debugging.
You have the option of exporting messages to an XML file. If you do not specify a file, output is sent to the stdout.
IMPORTANT: Message logging must be turned on for this command to work. See Section 5.4, "Defining, Modifying, and Deleting Transactions," for information about message logging.
btmcli exportMessages -name name | -e endpointUrl
[-bn bindingName]
-baseDate date -baseTime time -duration minutes
[-outputFile outputFile]
[-max numberOfMessages]
-sphereUrl sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The friendly name of the endpoint for which messages are exported. See the discussion below. |
| -e | -endpointURL | The endpoint URL. If this is a web service, you can supply the actual URL to reach the endpoint. If this is another type of component, look in the Profile tab in the management console to determine the endpoint's URL.
See also the discussion below. |
| -bn | -bindingName | The binding for the endpoint (for example, SOAP/HTTP). Use this parameter to disambiguate endpoint URLs with multiple bindings. |
| -baseDate | -- | The start timestamp (date) in the format yyyy-MM-dd when messages are to be exported. |
| -baseTime | -- | The start timestamp (time) in the format hh:mm:ss when messages are to be exported. |
| -duration | -- | The time in minutes, starting from the base time during which logged messages are exported. Messages might be exported for a shorter time if the number of messages exported during the stated interval exceeds the value specified with the -max option. |
| -o | -outputFile | The path name of the file where messages are to be exported. The command fails if the output file already exists.
It is recommended that you specify an absolute path. If you specify a filename only, the file is created in the directory from where the host application server is launched. IMPORTANT: If you specify a path, the command will work only if the process hosting Business Transaction Management has write access to the specified directory. |
| -max | -- | The maximum number of messages to export. If you don't specify a value, all messages will be exported for the specified interval. |
| -s | -sphereURL | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
You can specify the endpoint for which messages should be exported in the following ways:
Use the -e option if the endpoint URL is uniquely associated with a single endpoint.
The -e option is also useful to identify an endpoint that belongs to a replicated service; in this case, the endpoint name would not be unique, but the endpoint URL would.
Use the -n option to specify the friendly name of the endpoint. This is the preferred option if the specified name can uniquely identify the endpoint
The following command exports messages for the service MyShippingService.
btmcli exportMessages -name MyShippingService
-baseDate 2010-3-15 -baseTime 12:15:30 -duration 10
-s http://localhost:8080/btmcentral/sphere/ -l admin:passme
Use the exportPolicies command to export the selected policies either to stdout or to the given output file. You specify the policy to export in one of two ways:
The name of the policy - you can further qualify this with type, sub-type and/or version.
The type of the policy - you can further qualify this with sub-type and/or version.
To determine the type and subtype of a policy, select Policies in the Navigator. The type and subtype for each policy is displayed in the summary pane.
After exporting policies, you can use the importPolicies command to import them to another sphere.
Not all files can be exported. Data that you cannot migrate between sphere environments includes the following items:
Logging policy data collected by your transaction management database.
You cannot migrate information that has been collected and written to either file or database storage through the application of logging policies on your managed services.
Instance data for exceptional conditions that have occurred in your transactions.
You cannot migrate information that has been collected by the transaction management component of AMS.
btmcli exportPolicies
[[-n PName] [-t PType] [-subType PSubType] [-v Version]|[-exportAll]]
[-o fileName]
-s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The name of the policy to export. |
| -t | -type | The type of the policy to export. |
| -subType | -- | The sub-type of the policy to export. |
| -v | -version | The version of the policy to export. |
| -exportAll | -- | Specifies that all policies should be exported. |
| -o | -outputFile | Specifies a file into which the results of the export will be placed. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following command exports all policies known to the specified sphere to the file MyPolicies.
btmcli exportPolicies -exportAll -o C:\Home|MyPolicies
-s http://localhost:8080/btmcentral/sphere/
-l admin abracadabra
Use the exportPolicyTemplates command to export the selected policy templates either to stdout or to the given output file. You specify the policy template to export in one of two ways:
The name of the policy template - you can further qualify this with type, sub-type and/or version information.
The type of the policy template - you can further qualify this type with sub-type and/or version.
To determine the type and subtype of a policy template, select Policy Templates in the Navigator. The type and subtype for each policy template are displayed in the summary pane.
btmcli exportPolicyTemplates
[[-n Name][-t Type] [-subType subType][-v TmplVersion]]| -exportAll
[-o fileName]
-s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The name of the policy template to export. |
| -t | -type | The type of the policy template to export. |
| -subType | -- | The sub-type of the policy template to export. |
| -v | -version | The version of the policy template to export. |
| -exportAll | -- | Specifies that all policy templates should be exported. |
| -o | -outputFile | Specifies a file into which the exported data is placed. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following command exports all the policy templates to the output file MyPolicyTemplates
btmcli exportPolicyTemplates -exportAll -o C:\Home\MyPolicyTemplates
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the exportProfile command to export the profile values for the specified object(s). The resulting profile information is either written to the specified file, or to stdout if no file is provided. Specify the object(s) to be exported by specifying their type and then either their name or id.
You can use the importProfile command to import the resulting XML file into another sphere.
btmcli exportProfile -t objectType [-n name] [-v version] | [-id id] [-o fileName] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The name of the object whose profile you want to export. |
| -t | -type | The type of the object whose profile you want to export. Type can be one of the following: deployment, service, interface, endpoint, container, DEPLOYMENT, SERVICE, INTERFACE, ENDPOINT, or CONTAINER. |
| -V | -version | The version of the service object whose profile you want to export. |
| -id | -- | The sphere ID of the object whose profile data you want to export. |
| -o | -outputFile | Specifies a file into which the results of the export will be placed. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following command exports profile information for all containers.
btmcli exportProfile -t CONTAINER -o C:\Home|myContainers
-s http://localhost:8080/btmcentral/sphere/ -l admin:pass
Use the exportSchedules command to export schedules from the target sphere. You can output the schedules to a file or to stdout.
You can specify all schedules, a specific schedule, or schedules of a certain type.
After export, you can use the importSchedules command to import the schedules to a different sphere.
btmcli exportSchedules -n Name | -query filterQuery | -exportAll [-o fileName] -s sphereUrl sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The name of the schedule to export. |
| -query | -filterQuery | An AQL query specifying the set of schedules to export.
Use the Filter tool to construct the query, and then copy and paste the query into the command line. |
| -exportAll | -- | Specifies that all schedules should be exported. |
| -o | -outputFile | Specifies a file into which the results of the export will be placed. If this flag is not used, output goes to stdout. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following command exports all schedules known to the specified sphere to the file MySchedules.
btmcli exportSchedules -exportAll -o C:\Home\MySchedules
-s http://localhost/btmcentral/sphere/ -l admin:pass
Use the exportTransactionDefns command to export transaction definitions known to the target sphere. If you do not specify an output file, the definition is sent to stdout.
You can import exported definitions using the importTransactionDefns command.
btmcli exportTransactionDefns [-n Name] [-o fileName] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The name of the transaction to export. If you do not provide this value, all existing transaction definitions are exported. |
| -o | -outputFile | Specifies a file into which the results of the export will be placed. If you do not provide this value, the output is sent to stdout. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following command exports all transaction definitions to the file MyTransactions.
btmcli exportTransactionDefns -o C:\Home\MyTransactions
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the getSetupData command to write the setup file for a system service to standard output.
You can redirect output to a file, modify the file, and then use that file as input to the putSetupData command to save the service setup data.
You can also get the setup data from one service and transfer it to another. This command does not verify that the target service has been initially configured.
See Section 12.4, "Backing up and Restoring Business Transaction Management," for a discussion of the use of this command in backing up the system.
btmcli getSetupData -e endpointUrl -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -e | -endpointUrl | The location (URL) for the system service. |
| -s | -sphereUrl | The URL of the sphere where the service whose setup data you want to get is registered. http://hostname:port/btmcentral/sphere/
This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the getSetupData command.
btmcli getSetupData -e http://localhost:8080/apcentral/policyManager
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
The importBusinessObjects command imports one or more of the specified business objects described by the specified XML file into the target sphere. Currently, the only business object defined is the consumer business object, which is the means used to segment transaction information by consumer.
By default, this command replaces all existing objects that are older than the imported objects. You might use this command to migrate data from one environment to another or to populate your environment with a set of consumers.
You provide the data to import using the -inputFile argument or standard input. The objects you import must have first been exported using the exportBusinessObjects command.
If you are using this command to populate your environment with a set of consumers, the trickiest part is to create a valid input file. Here's a way to do this without having to guess at how to format your input file properly:
If needed, customize the business object by adding custom attributes.
Use the management console to create a consumer.
Use the exportBusinessObject command, specifying the name of an output file. Data about the consumer you created in Step 2 will be exported to an XML file.
Examine the output XML file. Using the format shown in the file, expand the file to add more consumers.
See Section 7.1, "About Consumers," for information on working with consumers.
btmcli importBusinessObjects [-i inputFile] [-replace ALL | all | NEWER | newer | NONE | cleaned | CLEANED] [-v] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -i | -inputFile | The name of the file containing the data to be imported.
The input file must contain at least one business object to import. |
| -replace | -replacementLevel | Determines the outcome when an imported object matches an existing object in the system:
ALL: replace all existing objects NEWER: replace existing objects that are older than imported objects. (Default) CLEANED: remove all existing business objects and then import the new business objects. NONE: do not replace any existing objects. |
| -v | -verbose | Display more detailed information about command execution. |
| -s | -sphereUrl | The URL of the sphere. http://hostname:port/btmcentral/sphere/
This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the importBusinessObject command used to import data from the file MyConsumers.
btmcli importBusinessObject -inputFile MyConsumers -replace ALL
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the importPolicies command to import previously exported policies.
The imported policies are taken from the file to which they were exported (-inputFile parameter), or from stdin if no such file is specified.
Not all files can be imported. Data that you cannot migrate between sphere environments includes the following:
Logging policy data collected by your transaction management database.
You cannot migrate information that has been collected and written to either file or database storage through the application of logging policies on your managed services.
Instance data for exceptional conditions that have occurred in your transactions.
You cannot migrate information that has been collected by the transaction management component of Business Transaction Management.
By default, this command replaces all existing policies that are older than the imported policies.
btmcli importPolicies [-i inputFile] [-replace ALL | all | NEWER | newer | NONE | none] [-v] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -i | -inputFile | The name of the file containing the data to be imported. |
| -replace | -replacementLevel | Determines the outcome when an imported policy matches an existing policy in the system:
ALL: replace all existing policies NEWER: replace existing policies that are older than the imported policies. (Default) NONE: do not replace any existing policies. |
| -v | -verbose | Display more detailed information about command execution. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the importPolicies command used to import data from the file MyPolicies.
btmcli importPolicies -inputFile MyPolicies -replace ALL
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the importPolicyTemplates command to import the policy templates contained in a previously created export file. The policy templates to import are taken from the file provided by the -i parameter, or from stdin if no such file is specified.
By default, this command replaces all existing templates that are older than the imported templates.
Command syntax
btmcli importPolicyTemplates [-i inputFile] [-replace ALL | all | NEWER | newer | NONE | none] [-v] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -i | -inputFile | The name of the file containing the data to be imported. |
| -replace | -replacementLevel | Determines the outcome when an imported policy template matches an existing policy template in the system:
ALL: replace all existing policy templates. NEWER: replace existing policies that are older than imported policy templates. (Default.) NONE: do not replace any existing policy templates. |
| -v | -verbose | Display more detailed information about command execution. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the importPolicyTemplates command used to import data from MyPolicyTemplates.
btmcli importPolicyTemplate -inputFile MyPolicyTemplates -replace NONE
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the importProfile command to import a previously object profile into the system. The profile data to import is taken from the specified input file or from stdin if no file is specified.
Importing a profile does not cause new objects to be created, but only updates the profile attributes of existing objects. For example, importing a service profile does not create the service or register it with the system, it only updates the profile for a service that has already been registered (by virtue of discovery or manual registration).
btmcli importProfile [-i importFile] [-m EXACT | BEST_FIT}
-s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -i | -inputFile | The name of the file containing the profile data to be imported. If not specified, the command imports data from stdin. |
| -- | -match | Use when importing the profile for a set of related objects to specify how closely the imported set must match the objects that currently exist in the system. The possible values are:
|
| -s | -sphereUrl | The URL of the sphere. http://hostname:port/btmcentral/sphere/
This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the importProfile command used to import data from MyContainers.
btmcli importProfile -inputFile MyContainers -match EXACT
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the importSchedules command to import previously exported schedules to the target sphere.
By default, this command replaces all existing schedules that are older than the imported schedules.
btmcli importPolicyTemplates [-i inputFile] [-replace ALL | all | NEWER | newer | NONE | none] [-v] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -i | -inputFile | The name of the file containing the data to be imported. If this is not specified, data is imported from stdin. |
| -replace | -replacementLevel | Determines the outcome when an imported schedule matches an existing schedule in the system:
ALL: replace all existing schedules. NEWER: replace existing schedules that are older than imported schedules. (Default) NONE: do not replace any existing schedules. |
| -v | -verbose | Display more detailed information about command execution. |
| -s | -sphereUrl | The URL of the sphere. http://hostname:port/btmcentral/sphere/
This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example imports schedules from the file MySchedules and replaces all existing schedules.
btmcli importSchedules -inputFile MySchedules -replace ALL
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the importTransactionDefns command to import previously exported transaction definitions to the specified sphere.
By default, this command replaces all existing definitions that are older than the imported definitions and it recreates any missing properties that are needed to define the transaction.
Normally if a transaction contains errors, you cannot import it. Setting the -importWithErrors flag allows you to import the transaction anyway, but in a disabled state. You can then use console tools to fix the errors. Errors are displayed in the transaction's Profile tab.
It is possible that a transaction depends on one or more properties (for example, if these properties are used for correlation). In this case, the system will recreate the properties if any have been deleted before the transaction is imported. The system does not recreate the property if the transaction does not need it. You can specify the -failOnMissingProperty flag to have the import fail if it cannot recreate all the properties needed by the transaction. To take an example:
You create property X on operation A, and you use this property to correlate two operations in a transaction.
You create property Y on operation B. This property is not needed by the transaction; it might be useful to surface a particular value.
When you export the transaction, the system makes a copy of any properties that affect the transaction definition.
You now delete property X.
When you re-import the transaction, the system knows that a property needed for the transaction definition is missing. By default, it recreates the missing property. If you specify the -failOnMissingProperty flag, the import operation will fail.
Because the transaction does not depend on property Y, the system does not make a copy of it. This property is lost during the export/import process. You can recreate it after you import the transaction. Or you can use the exportProfile and importProfile commands to have the system automatically recreate any such non-definitional properties.
btmcli importTransactionDefns [-i inputFile] [-replace ALL | all | NEWER | newer | NONE |none] [-failOnMissingProperty] [-importWithErrors] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -i | -inputFile | The name of the file containing the data to be imported. |
| -replace | -replacementLevel | Determines the outcome when an imported transaction definition matches an existing definition in the system:
ALL: replace all existing definitions. NEWER: replace existing definitions that are older than imported definitions. (Default) NONE: do not replace any existing definitions. |
| -- | -failOnMissingProperty | By default, the system recreates a missing property if the transaction depends on it. Specify this flag if you want the import to fail if a property is missing. |
| -- | -importWithErrors | Specify to have the command save the imported transaction even if it has errors.
Setting this flag allows you to correct the errors in the console. Normally any error in the definition will cause the import to fail. With this flag, the import will succeed, but the imported transaction will be in the disabled state. You can then use console tools to view and correct the errors. Errors are displayed in the Profile tab of the transaction. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the importTransactionDefns command used to import data from the file MyTxDefns.
btmcli importTransactionDefns -i MyTxDefns -replace NONE -failOnMissingProperty
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the listInstruments command to 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.
btmcli listInstruments -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
Here is some sample output for the listInstruments command.
Avg Response Time
Attribute Name: averageResponseTime
Description: The average amount of time a transaction requires to complete,
or a service/operation requires to respond.
Segmented By:
operation
containingManagedObjectId
clientAddress
clientName
businessObjectId
businessObjectKey
Faults
Attribute Name: faultCount
Description: The number of faults generated by a service or operation.
Segmented By:
operation
containingManagedObjectId
clientAddress
clientName
faultCode
businessObjectId
businessObjectKey
The following example shows the listInstruments command.
btmcli listInstruments -s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the listNodeAliases command to list the aliases for all known nodes or for the specified node.
btmcli listNodeAlias [ n nodeName] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The canonical name of the network node. Typically a fully-qualified domain name. For example, jbujes-myPC.edgility.com
If you do not specify this flag, aliases for all known nodes are displayed. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the listNodeAlias command.
btmcli listNodeAliases -n jbujesPC.edgility.com
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the mergeServices command to merge two services (thus removing duplicates). This command removes the source version specified with the -V flag and moves its endpoints to the target version specified with the -T flag. See Section 12.7, "Resolving Discovery Issues," for a discussion of the discovery issues that might require you merge two endpoints.
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.
Any historical data maintained for the source version is merged into the data maintained for the target version. Once the merge is completed, it is not possible to return to two distinct aggregated data sets for the two service versions.
You can preview the results of this command before committing to the changes it defines. After previewing, you must run the command again without the -P option to actually make the changes.
Use the moveEndpoints command to move selected endpoints from one service version to another.
btmcli mergeServices -n friendlyName | -qname qname -V version -T targetVersion [-P] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The friendly name of the service for which versions should be merged.
If two versions do not have the same friendly name, you must use the |
| -qname | -- | The qualified name of the service for which versions should be merged.
The qualified name has the form WSDLtargetNamespace:serviceName. For example: http://amberpoint.com/orderService:CreditServiceSOAP. |
| -V | -version | The version of the service that will be merged into the specified target.
Use the "-" string to represent the default, unnamed version. |
| -T | -targetVersion | The target service version in which to merge the source version (-V). After the merge, this version will contain the endpoints from both versions. |
| -P | -preview | Specify this flag to preview the results of the merge without actually performing the merge. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the mergeServices command:
btmcli mergeServices -f CreditService -X 1.5 -T 1.6
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the moveEndpoints command to move one or more endpoints from the source version to the target version of the specified service.
You can only move the entire set of endpoints defined for a service in a given WSDL as a unit, regardless of how you identify the endpoints.
You can preview the results of this command before committing to the changes it defines. After previewing, you must run the command again without the -P option to actually make the changes.
The moveEndpoints command does not move any measurements. The measurements for the endpoint remain associated with the endpoint and nothing happens to these when the endpoint is moved to a new service. The measurements for the old service version continue to include data previously aggregated from the moved endpoint. The historical measurements for the target service version are unchanged; new measurements for the endpoint are included in the target version of the service.
You can use this command to split a service in two by specifying the previously undefined version with the -T flag and using the -force flag.
Use the mergeServices command to merge all endpoints from one service version to another.
See Section 12.7, "Resolving Discovery Issues," for a discussion of the use of this command in resolving discovery issues.
btmcli moveEndpoints -n friendlyName | -qname qname -w wsdlUrl | -e endpointUrl
-V version -T targetVersion [-P]
-s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The friendly name of the service whose endpoints are moved.
If two versions do not have the same friendly name, you must use the qname flag to specify the service name. |
| -qname | -- | The qualified name of the service whose endpoints are moved.
The qualified name has the form WSDLtargetNamespace:serviceName. For example: http://amberpoint.com/orderService:CreditServiceSOAP. |
| -w | -wsdlURL | The URL of the WSDL file that defines the service whose endpoints are moved. |
| -e | -endpointUrl | The URL of an endpoint in the source version of the service.
The endpoint URL might identify multiple endpoints if the WSDL defines more than one endpoint at the same URL with different bindings. This is a common case for WSDLs that define more than one endpoint for a service. |
| -V | -version | The version of the service that will be merged into the specified target.
Use the "-" string to represent the default, unnamed version. |
| -T | -targetVersion | The service version in which to merge the source version (-V). After the merge, this version will contain the endpoints from both versions. |
| -P | -preview | Specify this flag to preview the results of the move without actually moving endpoints. |
| -f | -force | Create a new service version if the specified target version does not exist. You can assign this service a name different from that of the source version using the -newServiceName flag. |
| -newServiceName | If you use the -f option, you can use the -newServiceName flag to specify a friendly name for the target version that is to be created. If a target version already exists, this flag is ignored. | |
| -s | -sphereUrl | The URL of the sphere. http://hostname:port/btmcentral/sphere/
This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the moveEndpoints command:
btmcli moveEndpoints -n catalogService
-e http://test.myhost.com:7412/catalogMgmt/svcs/CatalogSvc
-V 1.5 -T 1.6
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the moveMeasurements command to 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.
Caution: Use this command with care. The system does not check to see that the services or endpoints are actually different iterations of the same object. Once merged, the measurements for the two objects cannot be separated.
When you deploy a new version of a service known to the sphere, and the modified WSDL is registered or discovered, the qualified name of the service defined in the WSDL is expected to match the name of the service found in the WSDL the last time it was read. If there is no match and the service name change option (in the service versioning policy) has a value of "replace the previous endpoints (losing all measurements)," Business Transaction Management deletes the endpoints that were previously read from the WSDL and creates new endpoints belonging to the service currently defined in the WSDL.
If only the namespace or service name defined in the WSDL has changed, the new endpoints might look the same as the old ones (same URL and binding), but they will have a different unique ID. Business Transaction Management depends on this ID to associate measurements with their respective objects; if the ID changes, it leaves measurements made for the old endpoints orphaned and inaccessible. If the service and endpoints defined in the updated WSDL are logically the same, you should use the moveMeasurements command to re-associate the measurements with the new incarnation of the service or endpoint.
Since the old endpoint and service have already been deleted, the old object to move measurements from must be identified by its unique ID. You can determine what the ID of a deleted service is by checking the sphere system log, as follows:
Select Administration > System Services in the navigator.
Select AP_Sphere_Service in the summary pane.
Select Open System Service Log for AP_Sphere_Service from the Admin menu.
The Log Viewer is displayed: look for the deleted service, and note its Exchange ID value.
Because no metadata about the deleted object is known to the sphere, this command is limited in the validation it can do. The command will refuse to do anything if the target cannot be found or is not specified uniquely. It will also refuse to move any measurements if the ID specified refers to an extant object that has not been deleted from the sphere.
See Section 12.7, "Resolving Discovery Issues," for a discussion of the use of this command in resolving discovery issues.
btmcli moveMeasurements -id id -n friendlyName | -qname qname [-V version] [-e endpointUrl] [-bn bindingName] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -id | -- | The UUID of the deleted endpoint or service for which to move measurements.
If the system deletes a service or endpoint because a WSDL has changed, it will send a system alert containing the UUID(s). Otherwise, you will need to check the service log for the sphere service (as described above) to get the id. |
| -n | -name | The friendly name of the target service where to move measurements. |
| -qName | The qualified name of the target service where to move measurements. | |
| -V | -version | The version of the target service where to move measurements. Only required if there are multiple versions of the service. |
| -e | -endpointUrl | The URL of the target endpoint to move measurements to. |
| -bn | -bindingName | The binding name of the target endpoint. (Only needed if the endpoint URL is not unique.) |
| -s | -sphereUrl | The URL of the sphere. http://hostname:port/btmcentral/sphere/
This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following examples show the use of the moveMeasurements command:
btmcli moveMeasurements -id 00EB2838-7E62-11DF-ABB5-27339B5EB390
-n MyCreditService
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
btmcli moveMeasurements -id CAEAF3FF-C5A7-11DF-80D5-2DF5BB94EBDE
-e http://text12.myhost.com:7012/bookmart/ofder/OrderService
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the putSetupData command to read the setup file from standard input or a supplied input file and to save it as the setup data for the specified system service.
See Section 12.4, "Backing up and Restoring Business Transaction Management," for a discussion of the use of this command in backing up the system.
btmcli putSetupData -e endpointUrl [-i inputFile] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -e | -endpointUrl | The URL of the system service. |
| -i | -inputFile | The name of the file from which to get input. |
| -s | -sphereUrl | The URL of the sphere where the service whose data you want to read is installed.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following examples show files written as the setup file for another service at the specified endpoint.
cat myFile | btmcli putSetupData -e myServiceEndpoint btmcli putSetupData -e myServiceEndpoint -i myInputFile
Use the registerDevice command to register a management device with the sphere. Although Business Transaction Management is able to infer the existence of load balancing devices by analyzing message traffic, explicitly registering a device enables the display of its friendly name and of other information, and provides access to the device's administrative interface if any.
Currently, hardware and software load balancers are the only supported device type for this command, and the F5 BigIP is the only fully-supported load-balancer.
In most cases, Business Transaction Management automatically detects and models routing entry points by observing message traffic and reading destination information from the message header. However, if the observed messages do not carry information about their original recipient (the load balancer) in the HTTP Host headers, you will need to manually assign a routing entry point to the load balancer. You will also need to add target entry points to indicate where the messages are being routed. You need to use the Business Transaction Management management console to do this. See Section 12.6, "Setting up Load Balancers," (setting up a load balancer) for a full discussion.
If you register multiple devices, you can use the setDefaultLoadBalancer command to set the default device. (Any newly discovered routing entry points will be modeled as part of the default device unless they belong to an F5 load balancer.)
To unregister a device, you must use the management console.
btmcli registerDevice -baseAddress baseAddress -fn friendlyName -vendor vendor [-administratorUI administratorUI] [-phaseInLifecycle DEBRECATED | deprecated | DEVELOPMENT | development |PRODUCTION | production | STAGING | staging |TEST | test] -deviceLogin login:password -s sphereUrl -l login:password
| Name | Long Name | Description |
|---|---|---|
| -- | -baseAddress | The base address of the URL of your load balancer; for example https://myf5:443/. |
| -fn | -friendlyName | The friendly name for your load balancer. This name is displayed in the Business Transaction Management Management Console. |
| -- | -vendor | If you are registering an F5 BigIP device, specify F5 (case insensitive). When set to this value, the vendor flag is functional.
For other types of load balancers, this flag is required, but it is purely descriptive. You can specify any value (except F5). The specified value is displayed in the Management Console. |
| -- | -administratorUI | For devices other than F5, the URL of your load balancer's HTML administrative console. The management console uses this URL to display a link to your load balancer's console.
This flag is not required for F5 devices because the URL is automatically obtained. |
| -- | -phaseInLifecycle | Specifies the lifecycle phase of the device container and all of the endpoints that are created within it. Valid values are deprecated, development, production, staging, and test. These are case insensitive. |
| -- | -deviceLogin | This flag is required for F5 devices and ignored for other types of load balancers.
The login credentials for the F5 load balancer in the format login:password. A user role of Guest provides sufficient privileges. If this is a limited-privilege account, Business Transaction Management will discover the objects and policies managed by the device, but you might not be able to modify them using Business Transaction Management. You can encrypt passwords using the encryptPassword CLI command, for example: btmcli encryptPassword -password "myPassword" |
| -s | -sphereUrl | Required unless you have set the AP_SPHERE_URL environment variable for your sphere.
Specify the URL of the sphere with which you want to register the device; for example: http://mySphereHost:8080/btmcentral/sphere/ Replace the host name and port number with appropriate values. This URL always ends with btmcentral/sphere/. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows how you use the registerDevice command to register an F5 load balancer.
btmcli registerDevice -baseAddress https://myF5:443
-fn MyF5LoadBalancer
-vendor F5
-phaseInLifecycle development
-deviceLogin my_F5_username:my_F5_password
-s http://mySphereHost:1771/btmcentral/sphere/
-l admin:abracadabra
Use the registerExternalContainer command to 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. In the console, such endpoints show up under the Unassigned Endpoints node.
Note that there is no command that allows you to move endpoints between containers individually; you have to use this command to move all endpoints starting with the given base address.
By default, manually registered endpoints are allocated to the System container. The registerExternalContainer command allows you to create an external container for endpoints that you want to treat and examine as a group. For example, this container might allow you to model the fact that two or more base addresses for manually registered endpoints are located in the same application server.
You cannot use base addresses from a physical container or a device, but you can use base addresses from another external container if you specify the -f flag. That is, you cannot group endpoints that have been discovered into an external container.
The optional flags for this command allow you to specify information that is then displayed in the container's profile information. To update this information, execute this command again with different option values.
When updating an existing container, if the first entry in the list of base addresses changes, the container's primary base address also changes. If you omit base addresses that previously belonged to the container, they are excluded from the container and returned to the System container.
You can run this command before or after services with endpoints in this container have been registered.
btmcli registerExternalContainer -baseAddress baseAddress1 [[baseAddress2]...] [-fn friendlyName] [-vendor vendor] [-containerInfo containerInfo] [-ofName osName] [-osVersion osVersion] [-administratorUI administratorUI] [-phaseInLifecycle DEBRECATED | deprecated | DEVELOPMENT | development |PRODUCTION | production | STAGING | staging |TEST | test] [-caseInsensitive] [-f] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -- | -baseAddress | Known base addresses for endpoints that you want to associate with the container. If you specify more than one, the first one is considered the primary base address. |
| -fn | -friendlyName | The friendly name for the new container. By default, this is the host:port of the primary base address. |
| -- | -vendor | Vendor of the application server software for the container; for example, IBM, Oracle, Microsoft. |
| -- | -containerInfo | The name and version of the application server software for the container in the format name/version. For example, WebLogic Server/10.3. |
| -- | -osName | The name of the operating system the container is running in. For example, Windows or Linux. |
| -- | -osVersion | The version of the operating system the container is running in. For example: 2003, 4.3. |
| -- | -administratorUI | A URL that can be used to access the administrative UI of the container. |
| -- | -phaseInLifecycle | Specifies the lifecycle phase of the container. |
| -- | -caseInsensitive | If set, URLs in this container are compared without attention to case. |
| -f | -force | Specifies that you want to re-associate a base address that currently belongs to a different external container. |
| -s | -sphereUrl | The URL of the sphere with which you want to register the container.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example registers an external container that will contain the endpoints with the specified base addresses.
btmcli registerExternalContainer
-baseAddress http://my_host:1234/ http://my_host/4567/
-s http://my_host:1234/btmcentral/sphere/
-l admin:abracadabra
Use the registerMonitor command to register a monitor agent with the sphere.
Following installation and configuration of Business Transaction Management central services, you can deploy one or more monitor nodes to additional application servers for processing observed messages. You need to run the reigsterMonitor command for each monitor you want to add.
If the nodes hosting Business Transaction Management monitors use aliases, you can run the addNodeAlias command to register the aliases with the sphere.
btmcli registerMonitor -e endpointUrl [-fn friendlyName]
-s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -e | -endpointUrl | Specifies the URL of the monitor to register with the sphere. For example,
http://localhost:8080/btmmonitor/agent/agent Replace the host name and port number with appropriate values. This URL always ends with btmmonitor/agent/agent. |
| -fn | -friendlyName | The friendly name of the endpoint for the monitor agent you want to register. |
| -s | -sphereUrl | Required. The URL of the sphere with which you want to register the container.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
btmcli registerMonitor -e http://localhost:8080/btmmonitor/agent/agent
-s sphereUrl http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the removeBaseAddressAlias command to 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.
The removeBaseAddressAlias command allows you to remove incorrect or outdated aliases from the system. Although it does not undo the removal of duplicate artifacts caused by the complementary addBaseAddressAlias command, any new discoveries for the base address and the ex-alias will again be treated as separate entities.
See Section 12.7, "Resolving Discovery Issues," for a discussion of the use of this command in resolving discovery issues.
btmcli removeBaseAddressAlias -baseAddress address -alias address
-s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -- | -baseAddress | The base address of an existing entry point in the sphere. Use the format scheme://host:port/ |
| -alias | -- | The base address to remove as an alias for the above entry point. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the removeBaseAddressAlias command.
btmcli -removeBaseAddressAlias http://jbujes:8080 -alias http://1.2.3.4:8080
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the removeDuplicateEndpoint command to 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.
If duplicates differ only in their base address, it is assumed that other endpoints found under both base addresses are also duplicates. In addition, the service descriptors (WSDLs) for the duplicate endpoints are also deleted from the model. WSDLs and endpoints under the duplicate entry point that are not actually duplicates are not removed; they are moved under the remaining entry point.
If the specified endpoint URL refers to a dependency-discovered endpoint and the duplicate URL refers to a discovered or manually-registered endpoint, the command is reversed: the duplicate endpoint is preserved and the base address of the endpoint URL is treated as an alias.
You can preview the results of this command before committing to the changes it defines. After previewing, you must run the command again without the -P option to actually make the changes.
See Section 12.7, "Resolving Discovery Issues," for a discussion of the use of this command in resolving discovery issues.
btmcli removeDuplicateEndpoint -e endpointUrl -d duplicateUrl [-P] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -e | -endpointUrl | The URL of the endpoint to preserve. |
| -d | -duplicateUrl | The URL of the endpoint to remove as a duplicate. |
| -P | -preview | Preview the results of the move without actually moving endpoints. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
Alternate Means of Removing Duplicates
In the following situations, the removeDuplicateEndpoint command will refuse to make the specified changes to avoid compromising the integrity of the model or destroying information that is not actually duplicated.
The endpoints belong to different services or different versions of the same service.
The endpoints implement different interfaces.
The endpoints live in different deployments.
The WSDL for the duplicate endpoint refers to services or endpoints that are not referenced by the WSDL for the remaining endpoint; that is, the WSDLs cannot be considered duplicates.
In these cases, you might need to do the following:
Use the unregister command to unregister the service endpoints that cannot be removed with the removeDuplicateEndpoint command.
Use the addNodeAlias or addBaseAddressAlias commands to add aliases that help the system recognize endpoint duplication.
The following example shows the removeDuplicateEndpoint command:
btmcli removeDuplicateEndpoint
-e http://jbujes.edge.com:7001/bookmart/credit/CreditService
-d http://jbujes.delphi.com:7001/bookmart/credit/CreditService -P
-s http://localhost:8080/btmcentral/sphere/
-l admin:password
Use the removeNode command to delete information about the specified node from the sphere database. Removing a node deletes all information related to that node including its aliases.
Removing a node is not something you would normally need to do unless aliases for different machines have gotten so mixed up that you face the choice of pruning nodes or reinstalling the system. Under most circumstances (bad hosts file corrected, DNS alias changed to point to a different machine), removing an alias from one node and adding it back to a different node should be all that you need to do.
btmcli removeNode -n nodeName -alias aliasName
-s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The canonical name of the network node. Typically a fully-qualified domain name. For example, jbujes-myPC.edgility.com |
| -f | -force | Forces the node to be removed even if it is still referenced by containers or entry points.
If you assign this node's aliases to another network node before you remove this node, you can enable a container to associate itself with a different node. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the removeNode command.
btmcli removeNode -n jbujes.edge.com
-s http://localhost:8080/btmcentral/sphere/
-l username:password
Use the removeNodeAlias command to delete alias information from the sphere database.
See Section 12.7, "Resolving Discovery Issues," for a discussion of the use of this command in resolving discovery issues.
btmcli removeNodeAlias -n nodeName -alias aliasName -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The canonical name of the network node. Typically a fully-qualified domain name. For example, jbujes-myPC.edgility.com |
| -alias | -alias | An alias for the network node. This can be a domain name or a static IP address. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the removeNodeAlias command.
btmcli removeNodeAlias -n jbujes.edge.com -alias Athena
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the removePathAlias command to 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.
See also removeNodeAlias for host name aliases and removeBaseAddressAlias for other aliases in the authority part of the WSDL's URL.
The removePathAlias command allows you to remove outdated aliases from the system. For instance, if a service descriptor has an alias added due to an HTTP redirect that is later disabled (WSDL URL A redirected to URL B, but now the two URLs represent different WSDLs), this command removes the alias so that WSDL A can be registered independently.
See Section 12.7, "Resolving Discovery Issues," for a discussion of the use of this command in resolving discovery issues.
ap removePathAlias -w wsdlUrl| -e endpointUrl -alias pathAlias -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -w | -wsdlUrl | The full URL or the WSDL (service descriptor) for which you want to remove an alias. |
| -e | -endpointUrl | The full URL of the endpoint(s) for which to remove the alias. If multiple endpoints are matched, the alias will be removed from all of them. |
| -alias | -- | The alternate path to remove from the service descriptor or endpoint. This should be just the path portion of the URL, starting with "/". |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the removePathAlias command using an encrypted password.
btmcli removePathAlias -e http://jbujes:7001/credit/CreditService
-alias /bookmart/amex/CreditSrevice
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the removePolicy command to completely remove an applied policy from the Business Transaction Management system.
btmcli removePolicy -name PlcyName [-type PlcyType] [-subType PlcySubType] [-version PlcyVersion] [-wait true|false] [-f] -s sphereUrl -l username:password
To determine the type and subtype of a policy, select Policies in the Navigator. The type and subtype for each policy is displayed in the main pane.
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The name of the policy you want to remove. If this name is unique, you do not need to supply additional type or version information. |
| -t | -type | The policy type for the policy you want to remove. Use this flag if the policy name is not unique. |
| -subType | -- | The policy subtype for the policy you want to remove.
If the name and type combination is not unique, specify a policy subtype. |
| -V | -version | The version associated with the policy you want to remove.
If the name, type, and subtype triple is not unique, specify the version number. Version numbers are automatically appended to policy names to create unique policies. |
| -wait | -- | TRUE: Wait for the policy to be removed before executing another script.
The default value is FALSE. |
| -f | -force | Remove the policy even if it is marked internally "do not remove." |
| -s | -sphereUrl | The URL of the sphere where the policy is applied.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example removes the policy myLoggingPolicy from the sphere, and waits until the policy is removed before executing any other command.
btmcli removePolicy -name myLoggingPolicy -wait true
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
The removePolicyTemplate command removes the specified policy template from the system.
btmcli removePolicy -name PolTemplName [-type Type] [-subType SubType] [-version PolicyVersion] [-f] -s sphereUrl -l username:password
To determine the type and subtype of a policy template, select Policy Templates in the Navigator. The type and subtype for each policy is displayed in the main pane.
| Name | Long Name | Description |
|---|---|---|
| -name | -- | The name of the policy template you want to remove. If this name is unique, you do not need to supply additional type or version information. |
| -type | -- | The policy type for the policy template you want to remove. Use this flag if the policy name is not unique. |
| -subType | -- | The policy subtype for the policy template you want to remove.
If the name and type combination is not unique, specify a policy subtype. |
| -version | -- | The version associated with the policy you want to remove.
If the name, type, and subtype triple is not unique, specify the version number. Version numbers are automatically appended to policy names to create unique policies. |
| -f | -force | Remove the policy template even if it is marked internally "do not remove." |
| -s | -sphereUrl | The URL of the sphere where the policy is applied.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example removes the policy template myPolicyTemplate from the sphere.
btmcli removePolicyTemplate -name myPolicyTemplate
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the renameEndpint command to change the specified endpoint's friendly name in the sphere.
When multiple endpoints at the same URL are given the same name in their respective WSDL definitions, giving them unique friendly names can make it easier to distinguish between them in future commands and in command output. You must provide the endpoint URL and a new friendly name. All other parameters are optional and are included only to help you distinguish the desired endpoint from others with the same URL.
See Section 12.7, "Resolving Discovery Issues," for a discussion of the use of this command in resolving discovery issues.
btmcli renameEndpoint -e endpointUrl -fn friendlyName [-bn bindingName] [-w wsdlUrl] [-n name] [-service serviceName] [-qname qname] [-V version] [-interfaceQName interfaceQName] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -e | -- | The endpoint URL of a web service. |
| -bn | -bindingName | The binding for the endpoint. Used to disambiguate endpoint URLs with multiple bindings. For example: SOAP and HTTP |
| -w | -wsdlUrl | The URL of the WSDL file. |
| -n | -name | The existing friendly name of the endpoint to be renamed. |
| -service | -- | The friendly name of the service to which the renamed endpoint belongs. |
| -qname | -- | The qualified name of the service to which the renamed endpoint belongs. |
| -V | -version | The version of the service to which the renamed endpoint belongs. Use with the -service or -qname flags if needed.
Use the "-" string to represent the default, unnamed version. |
| -- | -interfaceQName | The qualified name of the interface the renamed endpoint implements. |
| -fn | -friendlyName | The new friendly name for the endpoint to be renamed. |
| -s | -sphereUrl | The URL of the sphere. http://hostname:port/btmcentral/sphere/
This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the renameEndpoint command used to rename CreditService to MyCreditService.
btmcli renameEndpoint -e http://jbujes:7001/bookmart/credit/CreditService
-fn MyCreditService
-s http://localhost:8080/btmcentral/sphere
-l admin:abracadabra
Use the resetSphereUrl command to make sure that 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.
btmcli resetSphereUrl -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/apcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the resetSphereUrl command.
btmcli resetSphereUrl -s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
The retrieveObjectData command retrieves profile and measurement data for one or more objects. You can use this command's output file in the following ways:
Input to a reporting tool.
Business Transaction Management provides Oracle BI Publisher templates that you can use with the command's output file to produce formatted reports. See Chapter 9, "Creating Reports," for more information on using these templates.
Input to the setBaseLines command.
In this case, you set performance baseline values for a set of objects by using the output file of retrieveObjectData as an input file to setBaselines. Setting baselines enables you to then create a baseline SLA policy. (Do not set the retrieveObjectData command's attribute if you are using the output file to set baselines.)
Command syntax
btmcli retrieveObjectdata -t type1 [[type2] ...] [-query filterQuery] [-attributeNames attrName1 [attrName2] ... instrName1 [instrName2] ...] [-segments segment1 [segment2] ...] [-inTheLast inTheLast] | [-startTime startTime] [-endTime endTime] [-intervalSize intervalSize] [-format XML|CSV|SQL] [-o outputFile] [-metadata drop|create|none] [-tableName tableName] -s sphereUrl -l username:password
You can use the listInstruments command to get the information about attributes, segments, and instruments that you must pass as arguments to the retrieveObjectData command. If you specify a list of attributes and a list of segments, the command parser applies each segment to any instrument in the attribute list that has that segment.
If no time values are specified, the last hour's data is retrieved in a single segment.
| Name | Long Name | Description |
|---|---|---|
| -t | -type | Specifies the object tree whose data is to be retrieved.
At a minimum a root object type must be given that determines (along with the query) which objects will be retrieved. In addition to this, you can specify any number of 'child' types. These trees mirror those found in the custom data explorer. An example type tree is 'service endpoint operation' or 'observer probe endpoint'. |
| -query | -filterQuery | Limits the objects to be retrieved to the set defined by the query filter.
The query must apply to the root object type of the tree. Only those objects that match the given query will be returned in the result set, along with the associated objects in the sub-tree. Use the Filter tool to construct AQL queries, and then copy and paste these into the command line. |
| -- | -attributeNames | Use this argument to specify which attribute and instrument values to retrieve for each object, for example:
-attributeNames friendlyName averageResponseTime In this example, friendlyName is an attribute and averageResponseTime is an instrument. You can specify multiple attribute names (separated by spaces) followed by multiple instrument names (separated by spaces). Attribute names can refer to any attribute that is available in the column chooser. Attributes can be qualified by an object type followed by two colons ('::'), for example: Endpoint::friendlyName If you specify a qualified attribute name, attribute values are retrieved for only the specified object type (in the example, that would be the friendly names of only endpoints). If you specify an unqualified attribute name, attribute values are retrieved for all object types listed in the type argument that have that attribute (for example, endpoints, services, and operations). See Section 10.1.6, "Attribute Names," for a complete list of commonly used attribute names and object types. For a complete list of instrument names, run the |
| -segments | -- | Specifies the segments to use when retrieving the data for any specified measurement attributes (instruments). This provides a breakdown of the data for each specific value of the named segment that was recorded during the specified time-frame. |
| -inTheLast | -- | Specifies a time range extending from the current time back into the past by the indicated amount.
The value is given as a number followed by a unit (s, S = seconds; m, M = minutes; h, H = hours; d, D = days) e.g. "1H" for "1 Hour". |
| -startTime | -- | Specifies the start of a time range over which to produce values for any specified measurement attributes (instruments). If 'endTime' is not specified, the range ends at the current time.
The current default date format is used, e.g. "2010-08-03 15:00:00". |
| -endTime | -- | Specifies the end of a time range over which to get values for any specified measurement attributes (instruments).
The current default date format is used, e.g. "2010-08-03 18:00:00". |
| -- | -intervalSize | Indicates the size of the intervals into which the specified time range is to be divided.
The interval size is given as a number followed by a unit (s, S = seconds; m, M = minutes; h, H = hours; d, D = days) e.g. "1H" for "1 Hour". The interval size must be less than or equal to the length of the specified time range. If this optional argument is not specified the entire time range will be used and only a single interval is returned. Note: Do not set this attribute if you are using the output file as input to the |
| -format | -- | Specifies the format of the output file. Legal values are XML, CSV, and SQL. XML is the default format. |
| -o | -outputFile | Name of the output file. |
| -metadata | -- | Specifies whether SQL metadata commands are created.
Valid values are "drop" to drop and create the table, and "create" to only create the table. |
| -tablename | -- | Specifies the SQL table name used for SQL output; if no name is specified then a name is generated. |
| -s | -sphereUrl | The URL of the sphere. For example, http://hostname:port/btmcentral/sphere/
This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
Example 1: Retrieving data for containers.
btmcli retrieveObjectData
-t container
-s http://myHost:7003/btmcentral/sphere/
-l my_sphere_username:my_sphere_password
- my_containers_output.xml
Example 2: Retrieving the average response time for each service for purposes of reporting (note that -intervalSize is specified).
btmcli retrieveObjectData
-t service
-s http://my_host:7003/btmcentral/sphere/
-l my_sphere_username:my_sphere_password
-attributeNames firendlyName averageResponseTime
-inTheLast 24h
-intervalSize 1h
-format xml
-o my_avg_response_time_output_for_reporting.xml
Example 3: Retrieving the average response time for each service, endpoint, and operation for purposes of setting baselines (note that -intervalSize is not specified).
btmcli retrieveObjectdata
-t service endpoint operation
-s http://my_host:7003/btmcentral/sphere/
-l my_sphere_username:my_sphere_password
-attributeNames friendlyName averageResponseTime
-inTheLast 24h
-o my_avg_response_time_output_for_baselines.xml
Use the sendEventNotification command to create and send an event notification using the Notifier Service. How the notification is handled is determined by the currently active subscriptions.
The system automatically generates alerts when one of the following happens:
An SLA enforcement policy issues a failure, warning, or compliance alert
A condition definition causes the Transaction Monitoring Service to issue a condition alert.
A system service throws an exception, causing the system to issue a system alert.
In addition to these cases, an administrator might also want to issue an alert to notify users that the system needs to come down for maintenance or upgrade, or to let users know that some administrative action will regenerate the data used to create reports. The sendEventNotification command is provided to enable this kind of notification. (It would also be possible to send an event notification using the sendToNotifier command, but it would be a lot more work.)
btmcli sendEventNotification -source source -n name -topic topic [-subtopic subtopic] -severity SEVERE | WARNING | INFO | CONFIG | FAILURE | SUCCESS -message message [-attributes name1:value1 [[name2:value2] ...]] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -source | -- | Indicates where the notification was generated. Possible sources include ASLM, ExM, and System. You can specify an arbitrary value. |
| -n | -name | The name associated with the event notification. This should provide information as to what the event is about. |
| -topic | -- | The event notification's topic. Used to help categorize similar event notifications. |
| -subtopic | -- | The event notification's subtopic. Used to help categorize event notifications. |
| -- | -severity | Indicates the importance of the situation that caused the notification. |
| -message | -- | A textual description of what the event notification means and whether any user action is required. |
| -- | -attributes | A list of name:value pairs that will be attached to the event notification and made available to anyone who receives the notification. These attributes typically reference objects related to the notification. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the sendEventNotification command used to notify current subscribers that the system is about to be backed up.
btmcli sendEventNotification -source System -n BackupWarning
-topic SysNotifications -severity WARNING
-message "System backup in 10 minutes. Please save your work."
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
You can use the sendToNotifier command to manage email and web service subscriptions.
The sendToNotifier command sends a command (specified in an XML input file) to the Notifier Service for processing. You can create an email subscription, list existing subscriptions, delete subscriptions, and so forth. The command returns the response document returned by the Notifier Service. To issue additional commands, you must call sendToNotifier again, specifying an input file that contains a different command.
Command syntax for sendToNotifier is fairly simple, but creating the input command document can be complicated.
Business Transaction Management currently supports email and web service subscriptions only through the command line interface.
The command document, described at the end of this section, can contain an xml message (command) that accomplishes one of the following tasks:
Create an email subscription
Create a subscription to call a notification operation on a web service
List existing subscriptions
Delete a subscription from the notifier
btmcli sendToNotifier -i inputFile [-o outputFile] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -i | -inputFile | An XML file containing the command to send to the Notifier Service. Each file can contain one command. |
| -o | -outputFile | A file to hold the response from the Notifier Service. If none is specified, the response is sent to stdout. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The use of sendToNotifier is one step in setting up email notification. The overall procedure also includes the following steps:
Select System Services from the Navigator and select AP_Notifier_Service from the services listed in the summary area.
Edit its setup data (from the Admin menu) to specify the mail host and the email sender to be used.
Use the sendToNotifier command to register a subscription to SLA alerts, condition alerts, and so on. (The input command document will contain a command that specifies which alerts you are interested in.) For example, the following document registers a subscription for condition alerts:
<ap:registerSubscription
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ap:subscription name="All Exception Alerts" enabled="true" userID="testID">
<ap:deliveryMechanism>
<ap:sendEmail format="long" style="html">
<ap:from>BTM.TEST@test.com</ap:from>
<ap:recipient type="TO">your.name@yourdomain.com</ap:recipient>
</ap:sendEmail>
</ap:deliveryMechanism>
<ap:notificationFilters>
<ap:source>
<ap:value>ExM</ap:value>
<ap:operation>in</ap:operation>
</ap:source>
</ap:notificationFilters>
</ap:subscription>
</ap:registerSubscription>
The input command document is described in Section 10.47.3, "The Notifier Command Document."
Define SLA or condition alerts for the objects of interest.
You can also use sendToNotifier to list subscriptions and delete subscriptions. Here are sample command documents that illustrate how you would do this.
To list subscriptions
<ap:getSubscription xmlns:ap="http://namespace.amberpoint.com/amf"/>
To cancel subscriptions
<ap:cancelSubscription xmlns:ap="http://namespace.amberpoint.com/amf"> <ap:subscription name="All Exception Alerts" userID="testID"/> <ap:subscription name="All SLA Alerts" userID="testID"/> <ap:subscription name="All System Alerts" userID="testID"/> </ap:cancelSubscription>
Examples
The following example shows the sendToNotifier command.
btmcli sendToNotifier -i MyNotifierCommand -o MyNotifierReponse
-s http://localhost:8080/btmcentral/sphere -l admin:abracadabra
A Notifier Service command (xml message) can be included in a command document that is input to the sendToNotifier command. Notifier service commands are described in the following subsections; they allow you to do the following:
Create an email subscription
Create a web service subscription
List subscriptions
Delete a subscription
Get notification interest
Get a template
You may include only one command per document. To execute several commands, you must create a document for each command and invoke the sendToNotifier command for each document.
The following subsections describe the commands you can include in a Notifier Document.
This command supports the following variations:
Create a subscription for all alerts of a particular type (e.g. system alert, SLA alert, condition alert)
Create a subscription for all alerts on a particular object (e.g. transaction, service, endpoint, operation, consumer, system service)
Create a subscription for all alerts of a particular severity (e.g. failures and warnings, but not compliance or info alerts)
Create a subscription for all alerts generated by a particular policy (e.g. all alerts generated by the Baseline SLA Policy)
Create a subscription for all alerts generated by a particular condition (e.g. all condition alerts for the FaultMonitoring condition)
In addition to the sample commands below, you also need to be familiar with the metadata used to specify alert types. This is described in the next subsection.
<ap:registerSubscription xmlns:ap="http://namespace.amberpoint.com/amf"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/1999/XMLSchema"
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ap:subscription name="All SLA Alerts" enabled="true" userID="testID">
<ap:deliveryMechanism>
<ap:sendEmail format="short" style="text">
<ap:from>BTM.TEST@test.com</ap:from>
<ap:recipient type="TO">your.email@test.com</ap:recipient>
</ap:sendEmail>
</ap:deliveryMechanism>
<ap:notificationFilters>
<ap:source>
<ap:value>ASLM</ap:value>
<ap:operation>in</ap:operation>
</ap:source>
</ap:notificationFilters>
</ap:subscription>
</ap:registerSubscription>
Here is a more detailed example with comments:
<ap:registerSubscription xmlns:ap="http://namespace.amberpoint.com/amf"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/1999/XMLSchema"
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ap:subscription name="Warning and Failure SLA Alerts" enabled="true"
userID="testID">
<ap:deliveryMechanism>
<ap:sendEmail format="long" style="html">
<ap:from>BTM.TEST@test.com</ap:from>
<ap:recipient type="TO">your.name@test.com</ap:recipient>
</ap:sendEmail>
</ap:deliveryMechanism>
<ap:notificationFilters>
<ap:source>
<ap:value>ASLM</ap:value><!-- subcribe to SLA alerts -->
<ap:operation>in</ap:operation>
</ap:source>
<ap:severity>
<ap:value>WARNING</ap:value> <!-- subcribe to WARNING and FAILURE alerts -->
<ap:value>FAILURE</ap:value>
<ap:operation>in</ap:operation>
</ap:severity>
</ap:notificationFilters>
</ap:subscription>
<ap:subscription name="Exception Alert transaction OrderService_submit"
enabled="true" userID="testID">
<ap:deliveryMechanism>
<ap:sendEmail format="short" style="text">
<ap:from>BTM.TEST@test.com</ap:from>
<ap:recipient type="TO">your.name@test.com</ap:recipient>
</ap:sendEmail>
</ap:deliveryMechanism>
<ap:notificationFilters>
<ap:event>
<ap:value>Exception Detected</ap:value> <!-- subscribe to Exception alert
event-->
<ap:operation>in</ap:operation>
</ap:event>
<ap:info>
<ap:name>correlationName</ap:name> <!-- subcribe to tx by friendly name-->
<ap:value>OrderService_submit</ap:value>
<ap:operation>in</ap:operation>
</ap:info>
</ap:notificationFilters>
</ap:subscription>
</ap:registerSubscription>
Create a Web Service Description
This command supports the following variations:
Create a subscription for all alerts of a particular type (e.g. system alert, SLA alert, condition alert)
Create a subscription for all alerts on a particular object (e.g. transaction, service, endpoint, operation, consumer, system service)
Create a subscription for all alerts of a particular severity (e.g. failures and warnings, but not compliance or info alerts)
Create a subscription for all alerts generated by a particular policy (e.g. all alerts generated by the Baseline SLA Policy)
Create a subscription for all alerts generated by a particular condition (e.g. all condition alerts for the FaultMonitoring condition)
<ap:registerSubscription xmlns:ap="http://namespace.amberpoint.com/amf"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/1999/XMLSchema"
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ap:subscription name="Dispatch" enabled="true" userID="ABC">
<ap:deliveryMechanism>
<ap:callWebService>
<ap:httpEndPoint>
<ap:uri>http://10.148.118.72:8080/eProxy/svc/NotifPort_Proxy</ap:uri>
<!-- this is my test webService, replace with your own.-->
<ap:soapAction>ReplaceWithRealSoapActionForDotNetService</ap:soapAction>
</ap:httpEndPoint>
</ap:callWebService>
</ap:deliveryMechanism>
<ap:notificationFilters>
<ap:source>
<ap:value>ASLM</ap:value>
<ap:value>ExM</ap:value>
<ap:value>System</ap:value>
<ap:operation>in</ap:operation>
</ap:source>
</ap:notificationFilters>
</ap:subscription>
</ap:registerSubscription>
This command supports the following variations:
List all email subscriptions
List all web service subscriptions
List all subscriptions for a particular email address
List all web service subscriptions for a particular web service
List all subscriptions for a particular object (transaction, service, endpoint, operation, system service, consumer)
Here are some examples for these actions:
Get all subscriptions
<ap:getSubscription xmlns:ap="http://namespace.amberpoint.com/amf"/>
Get subscriptions by subscription name
<ap:getSubscription xmlns:ap="http://namespace.amberpoint.com/amf">
<ap:subscription name="Dispatch"/>
</ap:getSubscription>
Get subscriptions by user name
<ap:getSubscription xmlns:ap="http://namespace.amberpoint.com/amf">
<ap:subscription userID="mary"/>
</ap:getSubscription>
This command supports the following variations:
Delete all subscriptions for a particular email address
Delete all web service subscriptions for a particular web service
Delete all subscriptions on a particular object (e.g. transaction, service, endpoint, operation, system service, consumer)
For example,
<ap:cancelSubscription xmlns:ap="http://namespace.amberpoint.com/amf">
<ap:subscription name="Dispatch" userID="mary"/> </ap:cancelSubscription>
This command returns available formats such as "long HTML", "short text." The following is sample output for the command:
<ap:getFormatInformationResponse xmlns:ap="http://namespace.amberpoint.com/amf" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <ap:for value="Email" xmlns:ap= "http://namespace.amberpoint.com/amf"> <ap:format value="long"xmlns:ap="http://namespace.amberpoint.com/amf"/> <ap:format value="short" xmlns:ap="http://namespace.amberpoint.com/amf"/> <ap:style value="html" xmlns:ap="http://namespace.amberpoint.com/amf"/> <ap:style value="text" xmlns:ap="http://namespace.amberpoint.com/amf"/> </ap:for> </ap:getFormatInformationResponse
Use a command like the following:
<ap:getNotificationInterest xmlns:ap="http://namespace.amberpoint.com/amf"/>
Use a command like the following:
<ap:getTemplate/>
You will need to be familiar with metadata for SLA, Exception, and system alerts. You use this information to properly format a subscription for a particular type of information. Metadata information is shown in the following tables.
The following table specifies metadata for SLA alerts.
| Metadata | Available values | Sample subscription |
|---|---|---|
| (header) source | ASLM |
<ap:notificationFilters> <ap:source> <ap:value>ASLM</ap:value> <ap:operation>in</ap:operation> </ap:source> </ap:notificationFilters> |
| (header) event | enforcement_condition |
<ap:notificationFilters>
<ap:event>
<ap:value>enforcement_condition</ap:value>
<ap:operation>in</ap:operation>
</ap:event>
</ap:notificationFilters>
|
| (header) severity | WARNING
FAILURE SUCCESS INFO |
<ap:notificationFilters>
<ap:severity>
<ap:value>WARNING,FAILURE</ap:value>
<ap:operation>in</ap:operation>
</ap:severity>
</ap:notificationFilters>
|
| (header) templateSet | ASLM-Template |
<ap:notificationFilters>
<ap:templateSet>
<ap:value>ASLM-Template</ap:value>
<ap:operation>in</ap:operation>
</ap:templateSet>
</ap:notificationFilters>
|
| (info) com.amberpoint.notification.enforcementValue | (value of SLA enforcement that triggered the alert) |
<ap:notificationFilters>
<ap:info>
<ap:name>com.amberpoint.notification.
instrumentName</ap:name>
<ap:value>85</ap:value>
<ap:operation>in</ap:operation>
</ap:info>
<ap:notificationFilters>
|
| (info) com.amberpoint.notification.instrument
Name |
(qualified name of instrument) | See Note below table. |
| (info) com.amberpoint.notification.objectType | Service, Endpoint, Transaction |
<ap:notificationFilters>
<ap:info>
<ap:name>com.amberpoint.notification.
objectType</ap:name>
<ap:value>Service</ap:value>
<ap:operation>in</ap:operation>
</ap:info>
<ap:notificationFilters>
|
| (info) com.amberpoint.notification.objectId | (UUID of the object that SLA policy is applied on) |
<ap:notificationFilters>
<ap:info>
<ap:name>com.amberpoint.notification.
objectId</ap:name>
<ap:value>uuid:DA936829-98FF-11DF-828B-
A3EAF532919E</ap:value>
<ap:operation>in</ap:operation>
</ap:info>
<ap:notificationFilters>
|
| (info) com.amberpoint.notification.policyId | (UUID of the SLA policy) |
<ap:notificationFilters>
<ap:info>
<ap:name>com.amberpoint.notification.
policyId</ap:name>
<ap:value>uuid:896FCF93-9900-11DF-8753-
57E6CFA43E9B</ap:value>
<ap:operation>in</ap:operation>
</ap:info>
<ap:notificationFilters>
|
| (info) com.amberpoint.notification.senderId | (UUID of the AP_Enforcer_Service) |
<ap:notificationFilters>
<ap:info>
<ap:name>com.amberpoint.notification.
senderId</ap:name>
<ap:value>uuid:896FCF93-9900-11DF-8753-
57E6CFA43E9B</ap:value>
<ap:operation>in</ap:operation>
</ap:info>
<ap:notificationFilters>
|
| (info) com.amberpoint.notification.senderUrl | (Location of AP_Enforcer_Service) |
<ap:notificationFilters>
<ap:info>
<ap:name>com.amberpoint.notification.
senderUrl</ap:name>
<ap:value>http://localhost:8080/
btmperformance/endorcer</ap:value>
<ap:operation>in</ap:operation>
</ap:info>
<ap:notificationFilters>
|
| (info) com.amberpoint.notification.transaction
Id |
UUID of transaction (only if the SLA is applied on a Transaction) |
<ap:notificationFilters>
<ap:info>
<ap:name>com.amberpoint.notification.
transactionId</ap:name>
<ap:value>uuid:896FCF93-9900-11DF-8753
-57E6CFA43E9B</ap:value>
<ap:operation>in</ap:operation>
</ap:info>
<ap:notificationFilters>
|
| (info) endpointId | (UUID of AP_Enforcer_Service system endpoint) |
<ap:notificationFilters>
<ap:info>
<ap:name>com.amberpoint.notification.
endpointId</ap:name>
<ap:value>uuid:896FCF93-9900-11DF-8753-
57E6CFA43E9B</ap:value>
<ap:operation>in</ap:operation>
</ap:info>
<ap:notificationFilters>
|
| (info) serviceID | (UUID of AP_Enforcer_Service) |
<ap:notificationFilters>
<ap:info>
<ap:name>com.amberpoint.notification.
serviceId</ap:name>
<ap:value>uuid:896FCF93-9900-11DF-8753-
57E6CFA43E9B</ap:value>
<ap:operation>in</ap:operation>
</ap:info>
<ap:notificationFilters>
|
Sample subscription for (info) com.amberpoint.notification.instrumentName is as follows:
<ap:notificationFilters>
<ap:info>
<ap:name>com.amberpoint.notification.instrumentName</ap:name>
<ap:value>http://schemas.amberpoint.com/instruments/transactions/
types:startedTransactionCount</ap:value>
<ap:operation>in</ap:operation>
</ap:info>
<ap:notificationFilters>
The following table specifies metadata for condition alerts.
| Metadata | Available Values | Sample Subscription |
|---|---|---|
| (header) source | ExM |
<ap:notificationFilters>
<ap:source>
<ap:value>ExM</ap:value>
<ap:operation>in</ap:operation>
</ap:source>
</ap:notificationFilters>
|
| (header) event | Exception Detected |
<ap:notificationFilters>
<ap:event>
<ap:value>Exception Detected</ap:value>
<ap:operation>in</ap:operation>
</ap:event>
</ap:notificationFilters>
|
| (header) severity | FAILURE,
WARNING, INFO |
<ap:notificationFilters>
<ap:severity>
<ap:value>WARNING</ap:value>
<ap:operation>in</ap:operation>
</ap:severity>
</ap:notificationFilters>
|
| (header) templateSet | Exm-Template |
<ap:notificationFilters>
<ap:templateSet>
<ap:value>Exm-Template</ap:value>
<ap:operation>in</ap:operation>
</ap:templateSet>
</ap:notificationFilters>
|
| (info) com.amberpoint.notification.objectType | Transaction |
<ap:notificationFilters> <ap:info> <ap:name>com.amberpoint.notification.objectType</ap:name> <ap:value>Transaction</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters> |
| (info) com.amberpoint.notification.objectId | (UUID of Transaction) |
<ap:notificationFilters>
<ap:info>
<ap:name>com.amberpoint.notification.objectId</ap:name>
<ap:value>uuid:896FCF93-9900-11DF-8753-57E6CFA43E9B
</ap:value>
<ap:operation>in</ap:operation>
</ap:info>
<ap:notificationFilters>
|
| (info) com.amberpoint.notification.transactionId | (UUID of Transaction) |
<ap:notificationFilters>
<ap:info>
<ap:name>com.amberpoint.notification.transactionId</ap:name>
<ap:value>uuid:896FCF93-9900-11DF-8753-57E6CFA43E9B
</ap:value>
<ap:operation>in</ap:operation>
</ap:info>
<ap:notificationFilters>
|
| (info) correlationName | (Friendly name of function) |
<ap:notificationFilters> <ap:info> <ap:name>correlationName</ap:name> <ap:value>testTransaction1</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters> |
| (info) detectionTime | (Human readable time stamp. E.g. Thu Jul 22 12:25:49 PDT 2010) |
<ap:notificationFilters> <ap:info> <ap:name>detectionTime</ap:name> <ap:value>Thu Jul 22 12:25:49 PDT 2010</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters> |
| (info) exceptionPriority | failure, warning, informational |
<ap:notificationFilters> <ap:info> <ap:name>exceptionPriority</ap:name> <ap:value>warning</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters> |
| (info) exceptionTemplate | (friendly name of condition) |
<ap:notificationFilters>
<ap:info>
<ap:name>exceptionTemplate</ap:name>
<ap:value>condition2</ap:value>
<ap:operation>in</ap:operation>
</ap:info>
<ap:notificationFilters>
|
| (info) exceptionType | (name of transaction + name of condition Or name of service + name of condition) |
<ap:notificationFilters> <ap:info> <ap:name>exceptionType</ap:name> <ap:value>testTransaction1+condition2</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters> |
| (info) exceptionsURL | (URL that links back to the exception instance UI page) |
<ap:notificationFilters> <ap:info> <ap:name>exceptionsURL</ap:name> <ap:value>http://localhost:8080/btmui</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters> |
| (info) instanceID | (UUID of exception instance) |
<ap:notificationFilters>
<ap:info>
<ap:name>instanceId</ap:name>
<ap:value>uuid:896FCF93-9900-11DF-8753-57E6CFA43E9B
</ap:value>
<ap:operation>in</ap:operation>
</ap:info>
<ap:notificationFilters>
|
The following table specifies metadata for system alerts.
| Metadata | Possible Values | Sample Subscription |
|---|---|---|
| (header) source | System |
<ap:notificationFilters>
<ap:source>
<ap:value>System</ap:value>
<ap:operation>in</ap:operation>
</ap:source>
</ap:notificationFilters>
|
| (header) event | business_object_creation |
<ap:notificationFilters>
<ap:event>
<ap:value>business_object_creation</ap:value>
<ap:operation>in</ap:operation>
</ap:event>
</ap:notificationFilters>
|
| (header) severity | INFO |
<ap:notificationFilters>
<ap:severity>
<ap:value>INFO</ap:value>
<ap:operation>in</ap:operation>
</ap:severity>
</ap:notificationFilters>
|
| (header) templateSet | System-Template |
<ap:notificationFilters>
<ap:templateSet>
<ap:value>System-Template</ap:value>
<ap:operation>in</ap:operation>
</ap:templateSet>
</ap:notificationFilters>
|
| (info) com.amberpoint.notification.senderId | (UUID of service that sends out this alert.) |
<ap:notificationFilters> <ap:info> <ap:name>com.amberpoint.notification.senderId</ap:name> <ap:value>uuid:896FCF93-9900-11DF-8753-57E6CFA43E9B</ap:value> <ap:operation>in</ap:operation> </ap:info> <ap:notificationFilters> |
| (info) com.amberpoint.notification.senderUrl | (Location of service that sends out this alert.) |
<ap:notificationFilters>
<ap:info>
<ap:name>com.amberpoint.notification.senderUrl</ap:name>
<ap:value>http://localhost:8080/btmperformance/endorcer
</ap:value>
<ap:operation>in</ap:operation>
</ap:info>
<ap:notificationFilters>
|
The setBaselines command sets baselines for the specified objects. Setting baselines enables you to then create a baseline SLA policy.
You can use the retrieveObjectData command to retrieve and output historical performance data to a file; then you can use that file as input to the setBaselines command. If you create the input file by hand, use the same format as the output of the retrieveObjectData command.
You can also use this command to delete existing baselines for the specified object or for all managed objects.
btmcli setBaselines -i inputFile [-delete] [-all] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -i | -- | An XML document that indicates the baseline values for services, service operations, endpoints, endpoint operations, and transactions. Baseline values can be used for baseline service level agreements (SLAs based on historically-derived performance thresholds). |
| -delete | -- | Delete any existing baselines for the referenced managed objects before setting new baselines. |
| -all | -- | When combined with the -delete option, deletes all existing baselines for all managed objects. In this case, an input file is not required. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the setBaselines command.
btmcli setBaselines -i MyBookmartBaselines -delete
-s http://mySphereHost:1771/btmcentral/sphere/
-l my_btm_admin_username:my_btmadmin_password
Use the setDefaultLoadBalancer command to 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.
See Section 12.6, "Setting up Load Balancers," for a complete discussion of load balancers and how the default is set.
btmcli setDefaultLoadBalancer -baseAddress baseAddress | -fn friendlyName -s sphereURL -l username:password
| Name | Long Name | Description |
|---|---|---|
| -- | -baseAddress | The base address of the URL for the load balancer. For example, https://myf5:443/ |
| -fn | -friendlyName | The friendly name of the load-balancer in the sphere. This name is displayed in the summary pane when you select Devices from the navigator. It is the name you assigned when you registered the load balancer. |
| -s | -sphereUrl | Required. The URL of the sphere with which you want to register the container.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example specifies the default routing device:
btmcli setDefaultLoadBalancer -baseAddress https://myF5:443/
-s http://localhost:8080/btmcentral/sphere -l admin:abracadabra
Use the showService command to 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).
The non-verbose output includes: the version number, the qualified name of the service, its friendly name, its binding, who it is managed by and its full URL.
btmcli showService -n friendlyName | -qname qname| -e endpointUrl | -wwsdlUrl [-V version] [-v] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The friendly name of the service for which information is sought. You can qualify the name using the-versionflag. Otherwise, information about all the services with the friendly name is displayed. |
| -qname | -- | The qualified name of the service for which information is sought. The qualified name has the form WSDLtargetNamespace:serviceName. For example: http://amberpoint.com/orderService:CreditServiceSOAP. |
| -e | -endpointUrl | The URL of any endpoint of the service. If multiple services define endpoints at this location, information about all these services is displayed. |
| -w | -wsdlUrl | The URL of the WSDL file that defines one or more of the service endpoints. |
| -V | -version | The version of the service for which information is displayed.
Use the "-" string to represent the default, unnamed version. |
| -v | -verbose | Display additional information for each endpoint. |
| -s | -sphereUrl | The URL of the sphere. http://hostname:port/btmcentral/sphere/
This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following shows the output to some sample commands.
btmcli showService -n OrderService
OrderService (Version -)
QName: http://amberpoint.com/orderService:OrderService
Name: OrderServiceSOAP Binding: SOAP/HTTP Managed by: Monitored by Observer
http://islam.us.test.com:7412/bookmart/order/OrderSerrvice
btmcli showService -qname http://schemas.amberpoint.com/sphere:SphereService
AP_Sphere_Service (Version 7.0.0.0-ExM-Hegemony)
QName: http://schemas.amberpoint.com/sphere:SphereService
Name: AP_Sphere_Service_SOAP Binding: SOAP/HTTP
Managed by: AmberPoint AP_Core_Service
http://islam.us.test.com:8080/btmcentral/sphere/
The following example uses the showService command to display information for the service defined by the specified wsdl:
btmcli showService -w http://jbujes-desk.edgility.com:7001/bookmart/credit/CreditService?wsdl -s http://localhost:8080/btmcentral/sphere -l admin:abracadabra
Use the unmonitorEndpoint command to 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.
Use the monitorEndpoint command to re-enable monitoring.
btmcli unmonitorEndpoint -n name | -e endpointUrl1 [[endpointUrl2] ...]
-s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The friendly name of the endpoint to stop monitoring. |
| -e | -endpointUrl | A list of endpoint URLs for the endpoints you want to stop monitoring.
If this is a web service, you can supply the actual URL to reach the endpoint. If this is another type of component, look in the Profile tab in the management console to determine the endpoint's URL. |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example shows the unmonitorEndpoint command used to stop monitoring MyEndpoint.
btmcli unmonitorEndpoint -n MyEndpoint
-s http://localhost:8080/btmcentral/sphere/
-l Admin:abracadabra
Use the unregister command to unregister the service, WSDL, or endpoint from the sphere.
For each service unregistered using the -w or -n options, the command outputs information about the item unregistered in the following format:
WSDL_URL:serviceFriendlyName
For each endpoint unregistered using the -e and -interfaceQName options, the command outputs information about the item unregistered in the following format:
endpointUrl:endpointBinding
This command produces no output if the items to be removed are not registered with the sphere.
To unregister a specific endpoint, specify the service the endpoint belongs to using -n or -qname flags, and the endpoint to be removed using the endpointUrl and -interfaceQName flags. This option is generally useful if a dependency-discovered endpoint was created incorrectly. If you do not specify the -interfaceQName flag, only dependency-discovered endpoints are removed.
When unregistering replicated services composed of endpoints from one WSDL file, specifying the service name or the WSDL URL, results in the same behavior. Unregistering replicated services composed of endpoints from multiple WSDL files, results in different behaviors, depending on how the service is identified:
If a service is identified by its friendly or qualified name, the entire service is unregistered.
If a WSDL is identified by the -wsdlUrl flag, only the endpoints from that WSDL are unregistered. Endpoints discovered from other WSDLs are not affected.
Once you unregister a service or endpoint, you will no longer be able to access its history. If you think you might want to re-register the service or endpoint and access its history, you will need to save its UUID (shown in the Profile tab).
btmcli unregister -n serviceName | -qname qualifiedName | -w wsdlUrl1 [[wsdlUrl2...] [-V version] [-e endpointUrl] [-interfaceQName interfaceQName] [-f] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -n | -name | The friendly name of a service to remove from the sphere.
If the name is not unique, it must be qualified using the -V (version) flag. |
| -qname | -- | The qualified name (WSDL targetNamespace plus service name) of the service to remove from the sphere.
This option is useful when multiple services with different qualified names have been assigned the same friendly name in the sphere. If the name is not unique, it must be qualified using the -V (version) flag. |
| -w | -wsdlUrl | The URL for the WDSL file whose service(s) you want to unregister.
You must specify the -w or -n flag, but not both, with this command. |
| -V | -version | The version of a service to remove. Must be used in conjunction with the-qname or -name options.
Use the "-" string to represent the default, unnamed version. |
| -e | -- | The URL of a specific endpoint; in this case the corresponding WSDL is not unregistered. |
| -interfaceQName | The qualified name of the interface for a specific endpoint to unregister. | |
| -f | -force | Unregister a service even if some of its endpoints are monitored. They will be unmonitored prior to removing the service. |
| -s | -sphereUrl | The URL of the sphere where the WSDL is installed.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example unregisters the service in the specified wsdl.
btmcli unregister -w http://myProductionBox:28006/OrderService.wsdl
-s http://mydomain.com/btmcentral/sphere/ -l Admin:abracadabra
Use the unregisterContainer command to unregister a container previously registered with Business Transaction Management. Use this command after the container has been taken offline permanently. It is faster to use this command to unregister the container than to unregister each endpoint in it.
Physical containers must be offline long enough for the system to mark them down before you can unregister them.
This command also unregisters all the system services, service descriptors, and endpoints in the container. Any monitored endpoints in the container are no longer monitored, and measurements for these endpoints are deleted.
btmcli unregisterContainer -baseAddress baseAddress | -fn friendlyName -s sphereURL -l username:password
| Name | Long Name | Description |
|---|---|---|
| -i | -baseAddress | The base address of an existing entry point in the sphere.
Base address format: scheme://host:port/ |
| -fn | -friendlyName | Friendly name of the container to unregister. If the friendly name is not unique, you must use the baseAddress option instead. |
| -s | -sphereUrl | Required. The URL of the sphere residing in the container you want to unregister.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following command unregisters the container with the friendly name MyApps.
btmcli
btmcli unregisterContainer -fn MyApps
-s http://localhost:8080/btmcentral/sphere/
-l admin:abracadabra
Use the unregisterMonitor command to unregister the specified monitor 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.
Unregistering a monitor agent has the following consequences:
Any monitored endpoints associated with the monitor will be unmonitored.
Measurements for unmonitored endpoints will be lost; use this command only when the monitor has been taken offline permanently.
btmcli unregisterMonitor -baseAddress address | -fn friendlyName - s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -- | -baseAddress | The base address of the monitor in the sphere. For example,
http://localhost:8080/btmmonitor/agent/agent |
| -fn | -friendlyName | The friendly name of the monitor agent to unregister.
If the friendly name is not unique, you must use the -baseAddress option instead. |
| -s | -sphereUrl | The URL of the sphere where the WSDL is installed.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
The following example unregisters the monitor with the specified base address.
btmcli unregisterMonitor -base address
http://localhost:8080/btmmonitor/agent/agent
-s http://mydomain.com/btmcentral/sphere/ -l admin:abracadabra
Use the updateProfileData command to 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.
This command is useful in two distinct cases:
You want to update a collection of objects with a common set of attribute values. For example, you want to set the application group for a set of services to the same value.
You want to set the attribute values for a collection of objects to different values. For example, you want to import data obtained from an external data source.
See the discussion below for additional information.
btmcli updateProfileData -t type [-query filterQuery] [-val name1:val1 [[name2:val2]...]]] | [-profileData profileData] -s sphereUrl -l username:password
| Name | Long Name | Description |
|---|---|---|
| -t | -type | The type of objects to update. |
| -query | -filterQuery | Selects the set of objects that match the query.
Use the Filter tool to construct AQL queries, and then copy and paste these into the command line. |
| -val | -attributeValues | A list of name:value pairs used to update the selected objects. Each entry in the list specifies the name of an attribute and its value.
If you provide this argument, you must also provide the -query argument. Look at section "Attribute Names" for a complete list of commonly used attribute names and object types. |
| -- | -profileData | Specifies the name of a file containing the profile data to update. This file can have one of two formats, depending on the flags specified.
If you provide the -query argument, the file should be a Java properties file where each entry is an attribute name and its associated value. If there is no -query argument, this file should be a text-delimited file in csv form where the first row specifies the attributes to update, and subsequent rows provide values for a series of object instances. In order to identify the objects to be updated, the key attributes must be included (either the object id or the attributes that make up the type's natural key). |
| -s | -sphereUrl | The URL of the sphere.
http://hostname:port/btmcentral/sphere/ This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere. |
| -l | -userLogin | The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.
See Section 10.1.3, "Security Options in Accessing CLI Commands" for information on furnishing login credentials. You can encrypt passwords using the |
Discussion
This command has essentially three forms of use:
In order to update one or more attributes to the same values for a set of objects use the following form:
updateProfileData -t myType -query myQuery -val attr1=valueattr2=value ...
or the form
updateProfileData -t myType -query myQuery -profileData javaPropFile
In order to perform a bulk update of a set of objects where the attribute values for each object are different (such as when updating from an external database), use the form:
updateProfileData -t myType -profileData CSVFile_with_1_row_per_Object_to_update
The following example shows the updateProfile command.
btmcli updateProfileData -t endpoint -profileData MyJavaPropertyFile
-s http://localhost:8080/btmcentral/sphere/ -l Admin:abracadabra