BluemixUtility scripts

The script library provides BluemixUtility scripts that enable you to configure IBM Cloud® services. You can run a script individually or combine many procedures to create custom automation scripts for your environment.

Deprecated feature: [9.0.5.5 or later]BluemixUtility scripts for configuring IBM Cloud services are deprecated. To configure access to IBM Cloud services, such as Cloudant®, dashDB®, or Watson™ Services, see the documentation for the cloud service that you want to configure.

The BluemixUtility scripts are located in the app_server_root/scriptLibraries/bluemixutility directory.

Avoid trouble: Do not edit the scripts in the script library. To write custom script library procedures, use the scripts in the app_server_root/scriptLibraries directory as Jython syntax samples. Save the custom scripts to a new subdirectory to avoid overwriting the library.
Use the following scripts to configure services in your environment:

bind

The script binds an IBM Cloud service configuration to a product server . The configuration for a service might provide default values for an option, such as the jndiName of a dataSource element. In some cases, the default values do not match what the application expects. Use the variables option to override a default value with the value that your application expects.

Table 1. bind argument descriptions . Run the bind script with the scope and serviceName required arguments and any optional arguments.
Argument Required or Optional Description
scope Required Specifies a server scope to bind to an IBM Cloud service configuration.
serviceName Required Specifies the name of the imported service configuration.
variables Optional Specifies a map of variable names to override variables in the imported service configuration. You can get a variable name from the showImport script.
acceptLicense Optional Automatically indicates acceptance of license terms and conditions.

Syntax

Bind a service to server scope.

BluemixUtility.bind("acceptLicense=true", "scope=Node=node_name:Server=server_name", "serviceName=service_name", "variables=[v1Name=v1Value, v2Name=v2Value, …]")

Example usage

Bind a service to a server scope with no variables.

BluemixUtility.bind("acceptLicense=true", "scope=Node=myNode:Server=myServer", "serviceName=myDiscoveryService")

BMUX0206I: Bind successfully on service myDiscoveryService.
Bind a service to a server scope with one variable. (Get the variable name from the showImport script.)

BluemixUtility.bind("acceptLicense=true", "scope=Node=myNode:Server=myServer", "serviceName=dashDB1", "variables=[jndiName=dashDB1]")

BMUX0206I: Bind successfully on service dashDB1.
Bind a service to a server scope with multiple variables. (Get the variable names from the showImport script.)
BluemixUtility.bind("acceptLicense=true", "scope=Node=myNode:Server=myServer", "serviceName=dashDB1", "variables=[proxyUser=user1, proxyHost=myHost.com.ibm, proxyPort=3199, proxyPassword=abcd]")

BMUX0206I: Bind successfully on service dashDB1.

configureProxy

The script configures a proxy server to connect to a service.

Table 2. configureProxy argument descriptions . Run the configureProxy script with the proxyHost and proxyPort required arguments and any optional arguments.
Argument Required or Optional Description
proxyHost Required Specifies the host name of a proxy server.
proxyPort Required Specifies the port of a proxy server.
proxyUser Optional Specifies the user name to log in to a proxy server.
proxyUserPassword Optional Specifies the password to log in to a proxy server.

Syntax


BluemixUtility BluemixUtility.configureProxy("proxyHost=host_name", "proxyPort=port_number", "proxyUser=user_name", "proxyUserPassword=user_password")

Example usage


BluemixUtility BluemixUtility.configureProxy("proxyHost=host1.ibm.com", "proxyPort=3128", "proxyUser=user1", "proxyUserPassword=password")

BMUX0200I: Configure proxy server successfully.

createService

The script creates a service instance from the catalog.

Table 3. createService argument descriptions . Run the createService script with the serviceType, servicePlan, and serviceName required arguments and any optional arguments.
Argument Required or Optional Description
serviceType Required Specifies the type of service to create.
servicePlan Required Specifies the plan of the service to create.
serviceName Required Specifies the name of the service to create. You can specify a unique serviceName for your service instance.
credentialName Optional Specifies the name of the service credential. The default value is credential-1.

Syntax


service = BluemixUtility.createService("serviceType=service_type", "servicePlan=service_plan", "serviceName=service_name", "credentialName=credential-1")

Example usage

Create a dashDB service.

service = BluemixUtility.createService("credentialName=credential-1", "serviceType=dashDB", "servicePlan=Entry", "serviceName=dashDB1")

BMUX0203I: Service dashDB2 successfully created.
com.ibm.ws.bluemix.utility.cloudfoundry.CloudFoundryServiceInstance@54fc8cc1
Create a Watson discovery service.

service = BluemixUtility.createService("serviceType=discovery", "servicePlan=free", "serviceName=myDiscoveryService")

BMUX0203I: Service myDiscoveryService successfully created.
com.ibm.ws.bluemix.utility.cloudfoundry.CloudFoundryServiceInstance@58cf9cd1
View the created service details with createServiceToString.

BluemixUtility.createServiceToString(service)

Name: dashDB1
Type: dashDB
Plan: Entry
Description: A flexible and powerful data warehouse for enterprise-level analytics.
Documentation: https://console.ng.bluemix.net/docs/services/dashDB/dashDB.html
Service keys:
        credential-1
View the created service details with print.

print service2

BMUX0203I: Service myDiscoveryService successfully created.
Name: myDiscoveryService
Type: discovery
Plan: free
Description: Add a cognitive search and content analytics engine to applications. 
Documentation: https://www.ibm.com/watson/developercloud/discovery.html 
Service keys:
Parse the returned CloudFoundryService object.

service = BluemixUtility.createService("credentialName=credential-1", "serviceType=dashDB", "servicePlan=Entry", "serviceName=dashDB1")
name = service.getName()
type = service.getService().getLabel()
plan = service.getPlan().getName()
desc = service.getService().getDescription()
docUrl = service.getService().getDocumentationUrl()
keys = service.getServiceKeys()
for k in keys:
     key = k.getName()

deleteService

The script deletes a service instance.

Table 4. deleteService argument descriptions . Run the deleteService script with the serviceName required argument.
Argument Required or Optional Description
serviceName Required Specifies the name of the service to delete.

Syntax


BluemixUtility.deleteService("serviceName=service_name")

Example usage


BluemixUtility.deleteService("serviceName=dashDB1")

BMUX0208I: Service key credential-1 successfully deleted.
BMUX0209I: Service dashDB1 successfully deleted.

getSSOURL

The script obtains the SSO passcode URL string from the service. You can get the one-time passcode for a user from a web browser open on this URL and provide the passcode in the login script.

Table 5. getSSOURL argument descriptions . Run the getSSOURL script with the api required argument.
Argument Required or Optional Description
api Required Specifies the API endpoint.

Syntax


URL = BluemixUtility.getSSOURL("api=API_endpoint")

Example usage


BluemixUtility.getSSOURL("api=https://api.ng.bluemix.net")

Output: 'https://login.ng.bluemix.net/UAALoginServerWAR/passcode'

help

The script displays the general help for BluemixUtility or the help for a specific BluemixUtility script.

Syntax

Display the general help for BluemixUtility.


print BluemixUtility.help()

Display the help for a BluemixUtility script.


print BluemixUtility.help(action)

Example usage

Display the general help for BluemixUtility.

print BluemixUtility.help()

BMUX2001I: The BluemixUtility script provides the script utilities to configure your WebSphere Application Server to use Bluemix cloud services.
Usage: BluemixUtility.action(arguments)
Actions:
        login
                Log in to IBM Bluemix.
        marketplace
                List all IBM Bluemix services that can be configured using this utility.
        createService
                Create a service instance from the IBM Bluemix catalog.
        listServices
                List all service instances.
        showService
                Show information about an IBM Bluemix service instance.
        importService
                Import a configuration for an IBM Bluemix service.
        showInstructions
                Show the instructions for a service.
        listImports
                List all imported service configuration that can be bound to a WebSphere Application Server.
        showImport
                Show information about an imported service configuration.
        bind
                Bind an IBM Bluemix service configuration to a WebSphere Application Server.
        unbind
                Unbind an IBM Bluemix service configuration from a WebSphere Application Server.
        deleteService
                Delete a service instance.
        switchService
                Switch to a different IBM Bluemix organization or space.
        info
                View IBM Bluemix connection information.
        logout
                Log out of IBM Bluemix.
        getSSOURL
                Get the login SSO URL from Bluemix.
        showLicenses
                Show the licenses for a service.
        configureProxy
                Configure a proxy server
        Help
                Print the help information for the specified action.
Options:
        Use help(action) for detailed information of each action.
Display the help for the BluemixUtility.login script.

print BluemixUtility.help("login")

BUMX2002I: login
        Required Arguments: user, password, api
        Optional Arguments: org, space, passcode
        Description: Log in to Bluemix. If passcode is specified, user and password are not required.
        Usage: BluemixUtility.login("api=https://api.ng.bluemix.net", "user=user1", "password=pwd", "org=org", "space=dev")
        Return: None
Display the help for the BluemixUtility.marketplace script.

print BluemixUtility.help("marketplace")

BUMX2003I: marketplace
        Arguments: None
        Optional Arguments: serviceTypes (separate types by space)
        Description: List all Bluemix services that can be configured by using the Bluemix utility.
        Usage: BluemixUtility.marketplace("serviceTypes=type1 type2 type3")
        Return: List of Bluemix CloudFoundryService objects.
        Note: Use marketplaceToString(services) to view all Bluemix services returned from the marketplace action

importService

The script imports a configuration for a service. The imported service script and the shared libraries are stored in the configuration tree in the /config/cells/cellName/bluemixservices/serviceName directory or in the wstemp tree in the /wstemp/session/workspace/cells/cellName/bluemixservices/serviceName directory.

Table 6. importService argument descriptions . Run the importService script with the serviceName required argument and any optional arguments.
Argument Required or Optional Description
serviceName Required Specifies the name of the service to import.
acceptLicense Optional Specifies whether to automatically accept the license. Use true to accept the license and false to not accept it.
credentialName Optional Specifies the name of the service credential.
encodeAlgorithm Optional Specifies how to encode sensitive information in the imported service. The default encoding algorithm is xor.
encodeKey Optional Specifies the key to use when encoding with AES encryption.
parameters Optional Specifies other parameters to help generate and import a service configuration. For multiple parameters, separate them with a comma.

Syntax


BluemixUtility.importService("acceptLicense=true", "serviceName=service_name", "credentialName=credential_name", "encodeAlgorithm=algorithm", "encodeKey=key", "parameters=[p1Name=p1Value, p2Name=p2Value, …]")

Example usage

Specify values for all required and optional arguments of importService.

BluemixUtility.importService("acceptLicense=true", "serviceName=dashDB1", "credentialName=credential-1", "encodeAlgorithm=xor", "parameters=[jndiName=test, jdbcProvider=jdbc1]")

BMUX0205I: Configuration for the dashDB1 service was successfully imported.
Specify values for the serviceName required argument and one optional argument of importService.

BluemixUtility.importService("acceptLicense=true", "serviceName=myDiscoveryService")

BBMUX0205I: Configuration for the myDiscoveryService service was successfully imported.

info

The script views the connection information.

Syntax


BluemixUtility.info()

Example usage

Get the connection information.

info = BluemixUtility.info()

Output: a TargetInfo object
View the connection information. 

BluemixUtility.infoToString(info)

API endpoint: https://api.ng.bluemix.net
Organization: user1@us.ibm.com
Space: dev
The example uses infoToString. You can use the print command instead.
print info
Parse the TargetInfo object.

info = BluemixUtility.info()
api = info.getAPI()
org = info.getOrganizationName()
space = info.getSpaceName()

listImports

The script lists all imported service configurations that can bind to a product server.

Table 7. listImports argument descriptions . Run the listImports script, which has the scope optional argument.
Argument Required or Optional Description
scope Optional Specifies the server scope to which the services are bound.

Syntax

List all imported service configurations for a server.

services = BluemixUtility.listImports("scope=Node=node_name:Server=server_name")

Example usage

List all imported services.

BluemixUtility.listImports()

[dashDB1, dashDB2, myDiscoveryService]
List all imported services under a server scope.

BluemixUtility.listImports("scope=Node=myNode:Server=myServer")

[dashDB1, myDiscoveryService]
View the list of imported services under a specific scope.

services = BluemixUtility.listImports("scope=Node=myNode:Server=myserver")
BluemixUtility.listImportsToString(services)

BMUX0210I: The following IBM Bluemix service configurations have been imported:
dashDB1, myDiscoveryService
Parse the returned list of imported service names.

services = BluemixUtility.listImports()
for s in services:
      print s

listServices

The script lists all the available service instances.

Syntax


services = BluemixUtility.listServices()

Example usage

List all the available service instances.

services = BluemixUtility.listServices()

Output: list of CloudFoundryServiceInstance objects
View the list of all available service instances.

BluemixUtility.listServicesToString(services)

               Name        Type    Plan
            dashDB1      dashDB   Entry
            dashDB2      dashDB   Entry
            dashDB3      dashDB   Entry
 myDiscoveryService   discovery    free
Parse the returned CloudFoundryService objects.

services = BluemixUtility.listServices()
for s in services:
      name = s.getName()
      type = s.getService().getLabel()
      plan = s.getPlan().getName()

login

The script logs in to IBM Cloud.

Table 8. login argument descriptions . Run the login script with the required and optional arguments.
Argument Required or Optional Description
api Required Specifies the API endpoint.
user Required (optional when you log in with the SSO passcode) Specifies the user name of the IBM Cloud account.
password Required (optional when you log in with the SSO passcode) Specifies the password of the IBM Cloud account.
passcode Optional Specifies the one-time passcode value. The user and password arguments are not required when you specify the passcode value. To get the passcode value, open a web browser on the URL returned by the getSSOURL script.
org Optional Specifies the organization name.
space Optional Specifies the space name.

Syntax


BluemixUtility.login("user=user_name", "password=password", "api=API_endpoint", "org=organization_name", "space=space_name", "passcode=passcode_value")

Example usage

Log in with a user and password.

BluemixUtility.login("user=user1@us.ibm.com", "password=password", "api=https://api.ng.bluemix.net", "org=user1@us.ibm.com", "space=dev")

BMUX0201I: Authentication successful.
Log in with a one-time passcode value. Get the one-time passcode value from a web browser opened on the URL returned by getSSOURL. The user and password are not required when you log in to IBM Cloud with the passcode value.

BluemixUtility.login("api=https://api.ng.bluemix.net", "org=user1@us.ibm.com", "space=dev", "passcode=1234abcd")

BMUX0201I: Authentication successful.

logout

The script logs out of IBM Cloud.

Syntax


BluemixUtility.logout()

Example usage


BluemixUtility.logout()

BMUX0202I: Logout successfully.

marketplace

The script lists all the IBM Cloud services that you can configure with BluemixUtility.

Table 9. marketplace argument descriptions . Run the marketplace script, which has the serviceTypes optional argument.
Argument Required or Optional Description
serviceTypes Optional Specifies one or more service types. For multiple service types, separate them with a space.

Syntax

List all configurable services.

services = BluemixUtility.marketplace()
List services for specific service types.

services = BluemixUtility.marketplace("serviceTypes=type1 type2 type3 …")

Example usage

List all configurable services.

services = BluemixUtility.marketplace()

Output: list of CloudFoundryService objects
List services for specific service types.

services = BluemixUtility.marketplace("serviceTypes=dashDB")

Output: list of CloudFoundryService instances
View all available services that can be configured in a string.

BluemixUtility.marketplaceToString(services)

Service: dashDB
Description: A flexible and powerful data warehouse for enterprise-level analytics.
Documentation: https://console.ng.bluemix.net/docs/services/dashDB/dashDB.html
Plans: Enterprise, EnterpriseMPP32.244.1400forAWS, Entry, EnterpriseTransactional12.128.1400, EnterpriseTransactional2.8.500, 
EnterpriseTransactional2.8.500.PPU, EnterpriseTransactionalHA12.128.1400, SMP Small, SMP Large, EnterpriseTransactionalHA2.8.500, 
EnterpriseTransactionalHA2.8.500.PPU, SMP Medium, Enterprise256.4, Enterprise256.12, EnterpriseMPP.4, MPP Small

Service: text_to_speech
Description: Synthesizes natural-sounding speech from text.
Documentation: https://www.ibm.com/watson/developercloud/text-to-speech.html
Plans: standard, premium

Service: speech_to_text
Description: Low-latency, streaming transcription
Documentation: https://www.ibm.com/watson/developercloud/speech-to-text.html
Plans: standard, premium

Service: tone_analyzer
Description: Tone Analyzer uses linguistic analysis to detect three types of tones from communications: emotion, social, and language.  
This insight can then be used to drive high impact communications.
Documentation: http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/tone-analyzer.html
Plans: premium, standard

Service: personality_insights
Description: The Watson Personality Insights derives insights from transactional and social media data to identify psychological traits
Documentation: https://www.ibm.com/watson/developercloud/personality-insights.html
Plans: tiered, premium

Service: natural_language_classifier
Description: Natural Language Classifier performs natural language classification on question texts. 
A user would be able to train their data and the predict the appropriate class for a input question.
Documentation: https://www.ibm.com/watson/developercloud/nl-classifier.html
Plans: standard

Service: document_conversion
Description: Converts a  HTML, PDF, or Microsoft Word document into a normalized HTML, plain text, or a set of JSON-formatted Answer units.
Documentation: https://www.ibm.com/watson/developercloud/document-conversion.html
Plans: standard, premium

Service: retrieve_and_rank
Description: Add machine learning enhanced search capabilities to your application
Documentation: https://www.ibm.com/watson/developercloud/retrieve-rank.html
Plans: standard

Service: discovery
Description: Add a cognitive search and content analytics engine to applications.
Documentation: https://www.ibm.com/watson/developercloud/discovery.html
Plans: free, standard

Service: watson_vision_combined
Description: Find meaning in visual content! Analyze images for scenes, objects, faces, and other content. 
Choose a default model off the shelf, or create your own custom classifier. Find similar images within a collection. 
Develop smart applications that analyze the visual content of images or video frames to understand what is happening in a scene.
Documentation: https://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/visual-recognition.html
Plans: free, standard

Service: language_translator
Description: Translate text from one language to another for specific domains.
Documentation: https://www.ibm.com/watson/developercloud/language-translator.html
Plans: premium, advanced, standard
Parse the returned CloudFoundryService objects.

services = BluemixUtility.marketplace()
for s in services:
      name = s.getLabel()
      desc = s.getDescription()
      docUrl = s.getDocumentationUrl()
      plans = s.getServicePlans()
      for plan in plans:
            pName = plan.getName()

showImport

The script shows information about an imported IBM Cloud service configuration such as configuration location, configuration variables, and bound servers. You can specify the variables that are returned from showImport during a bind operation to configure or override the resources or properties in the server scoped configuration.

Table 10. showImport argument descriptions . Run the showImport script with the serviceName required argument.
Argument Required or Optional Description
serviceName Required Specifies the name of the imported service.

Syntax


importInfo = BluemixUtility.showImport("serviceName=service_name")

Output: an ImportServiceDetails object

Example usage

Get information about an imported service. The example gets information about the dashDB1 and myDiscoveryService imported services.

importInfo = BluemixUtility.showImport("serviceName=dashDB1")

importInfo2 = BluemixUtility.showImport("serviceName=myDiscoveryService")
View the returned information about an imported service with showImportToString.

BluemixUtility.showImportToString(importInfo)

Configuration location: cells/myCell/bluemixservices/dashDB1
Configurable variables:
  Name: jndiName
  Value: jdbc/dashDB1
Bound servers:
  myNode/server1
  myNode/server2
View the returned information about an imported service with print.

print importInfo2

Configuration location: cells/timmie1Cell05/bluemixservices/myDiscoveryService
Configurable variables: No configurable variable
Bound servers: No server/cluster bound
Parse the returned ImportServiceDetails object.

importInfo = BluemixUtility.showImport("serviceName=dashDB1")
configLoc = importInfo.getConfigLocation()
configVariables = importInfo.getVariables()
for var in configVariables:
      vName = var.getKey()
      vValue = var.getValue()
boundServers = importInfo.getBoundServers()
for server in boundServers:
      print server

showInstructions

The script shows the instruction of a service.

Table 11. showInstructions argument descriptions . Run the showInstructions script with the serviceName required argument.
Argument Required or Optional Description
serviceName Required Specifies the name of the service.

Syntax


instructions = BluemixUtility.showInstructions("serviceName=service_name")

Example usage


BluemixUtility.showInstructions("serviceName=dashDB1")

Output: an instruction string

showLicenses

The script shows all software licenses that you must accept to use a service.

Table 12. showLicenses argument descriptions . Run the showLicenses script with the serviceName required argument.
Argument Required or Optional Description
serviceName Required Specifies the name of the service.

Syntax


licenses = BluemixUtility.showLicenses("serviceName=service_name")

Example usage

Get information about licenses needed for a service.

licenses = BluemixUtility.showLicenses("serviceName=dashDB1")

licenses2 = BluemixUtility.showLicenses("serviceName=myDiscoveryService")

Output: set of License objects
View all licenses for license, a dashDB service.

BluemixUtility.showLicensesToString(licenses)

License type: IBM IPLA
License link: https://oneconnect.mybluemix.net/ds/drivers/license/jcc4jar/live
Libraries:
        https://oneconnect.mybluemix.net/ds/drivers/download/jcc4jar/jvm/live
View all licenses for license2, a discovery service.

BluemixUtility.showLicensesToString(licenses2)

License type: Apache
License link: https://www.apache.org/licenses/LICENSE-2.0.txt
Libraries:
        https://repo1.maven.org/maven2/com/ibm/watson/developer_cloud/java-sdk/3.7.2/java-sdk-3.7.2-jar-with-dependencies.jar
Parse the returned License objects.

licenses = BluemixUtility.showLicenses("serviceName=dashDB1")
for license in licenses:
     name = license.getName()
     url = license.getUrl()
     libraries = license.getLibraries()
     for lib in libraries:
           print lib

showService

The script shows information about a service instance.

Table 13. showService argument descriptions . Run the showService script, which has the serviceName required argument and an optional argument.
Argument Required or Optional Description
serviceName Required Specifies the name of the service to show.
showCredentials Optional Specifies whether to show the service credentials. Use true to show credentials and false to not show them.

Syntax


service = BluemixUtility.showService("showCredentials=true", "serviceName=service_name")

Example usage

Get information about a service instance.

service = BluemixUtility.showService("showCredentials=true", "serviceName=dashDB1")

service2 = BluemixUtility.showService("showCredentials=true", "serviceName=myDiscoveryService")

Output: a CloudFoundryServiceInstance object
View the service information with showServiceToString.

BluemixUtility.showServiceToString(service)

Name: dashDB1
Type: dashDB
Plan: Entry
Description: A flexible and powerful data warehouse for enterprise-level analytics.
Documentation: https://console.ng.bluemix.net/docs/services/dashDB/dashDB.html
Service keys:
        credential-1
View the service information with print.

print service2

Name: myDiscoveryService
Type: discovery
Plan: free
Description: Add a cognitive search and content analytics engine to applications.
Documentation: https://www.ibm.com/watson/developercloud/discovery.html
Service keys:
        credential-1
        password: password_value
        url: https://gateway.watsonplatform.net/discovery/api
        username: user_name_value
Parse the returned CloudFoundryService object.

service = BluemixUtility.showService("showCredentials=true", "serviceName=dashDB1")	
name = service.getName()
type = service.getService().getLabel()
plan = service.getPlan().getName()
desc = service.getService().getDescription()
doc = service.getService().getDocumentationUrl()
keys = service.getServiceKeys()
for k in keys:
     key = k.getName()

switchService

The script switches to a different organization or space.

Table 14. switchService argument descriptions . Run the switchService script with no arguments or with any optional arguments.
Argument Required or Optional Description
org Optional Specifies the organization name to switch.
space Optional Specifies the space name to switch.

Syntax


BluemixUtility.switchService("org=organization_name", "space=space_name")

Example usage


BluemixUtility.switchService("org=user1@us.ibm.com", "space=dev")

unbind

The script unbinds a service configuration from a product server.

Table 15. unbind argument descriptions . Run the unbind script with the scope and serviceName required arguments.
Argument Required or Optional Description
scope Required Specifies a server scope to unbind from a service configuration.
serviceName Required Specifies the name of the service configuration to unbind.

Syntax

Unbind a service from server scope.

BluemixUtility.unbind("scope=Node=node_name:Server=server_name", "serviceName=service_name")

Example usage

Unbind a service from server scope.

BluemixUtility.unbind("scope=Node=myNode:Server=myServer", "serviceName=dashDB1")

BMUX0207I: Unbind successfully on service dashDB1.