Use the register command to register the services (found within the specified WSDL file) with the sphere and write the location URLs of the WSDL's service endpoints to standard output. This command produces the same output if the WSDL is already registered with the sphere. You might need to explicitly register a service in those cases where Business Transaction Management cannot discover SOA-type components directly. For example, a service in a container that cannot be observed or in a container where no observer has been installed.

The register command determines whether the specified WSDL has already been processed. If it has, and the -f (force) flag is not used, the system does not register the WSDL again.

It is possible that Business Transaction Management does not correctly evaluate whether WSDLs are the same, and objects in the sphere might not correspond exactly to those in the WSDL. In this case, you can use the -f flag to reprocess the WSDL. For example, if you want to manually merge services with interfaces that aren't exact matches, you might then also want to reprocess the WSDL.

You can use this command to register more than one service and to match these with friendly names and version information. (This reflects the capabilities offered by the GUI.)

You can also specify a version for each service you register. Business Transaction Management does not enforce any specific versioning notation. For a service with existing replicates, there are two possibilities:

  • If another service with the same qualified name and the given version already exists, merge the specified WSDL's endpoints into that version of the service.

  • If no such version exists, but this WSDL has been processed before, update its service version to the new version.

By default, registered services are placed in the System container (in the Console this is shown in the Unassigned endpoints node). If you prefer to group services together in their own container, you can use the registerExternalContainer command to register a container and associate that container with the base address of the endpoints of the manually registered services.

Command Syntax

btmcli register -w wsdlUrl1 [[wsdlUrl2]...] [-L username:password]
                [-service svc1 [[svc2]...]]] [-fn fName1 [[fName2]...]]]
                [-V version1 [[version2]...]]] -f
                -s sphereUrl -l username:passwword
Name Long Name Description
-w -wsdlUrl The URL for the WDSL file whose service(s) you want to register.
-L -wsdlLogin The user credentials required to access a secure WSDL file.

You can encrypt passwords for use with this command using the encryptPassword command.

-service -- Register only the service(s) with matching name attributes in the WSDL. Other services defined in the WSDL are not registered.
-fn -friendlyName Registers a friendly name for the service defined in the WSDL. If the WSDL defines more than one service, you must specify the services you want to register using the -service flag. The friendly names you then define with the -fn flag are mapped to registered services based on their position in their respective list.
-V -version The version of the newly-registered service. Use the "-" string to represent the default, unnamed version.

If a service with the same qualified name and version already exists, the endpoint(s) read from this WSDL are merged into the existing service.

If multiple services are specified using the -service flag, you can specify a single version to use for all services, or a different version for each. Versions are mapped to services based on their position in their respective list.

-f -force Force the WSDL to be reprocessed even if it has not changed since it was last read.
-s -sphereUrl The URL of the sphere where the WSDL is installed.


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 Security Options in Accessing CLI Commands for information on furnishing login credentials.

You can encrypt passwords using the encryptPassword command.


The following example registers the service in the specified wsdl using the "friendly name" AmazonSearch.

btmcli register -w
                -n AmazonSearch -s http://localhost:8080/btmcentral/sphere/
                -l admin:abracadabra