The industry is rapidly embracing cloud technology to drive internal efficiencies and launch new cloud services. In that context, the capability to integrate, aggregate, and deliver a broad variety of differentiated cloud services faster and more efficiently is essential to cloud service providers. Brokerage services platforms play an important role here as well. They provide a pre-built environment for exposing and reselling cloud services. Onboarding new services providers within this brokerage services platform mean managing user provisioning, service versions, service activation, service deletion, and so on.
For quicker services activation and better market reactivity, you can use IBM WebSphere Cast Iron to connect the brokerage services platforms to the cloud services providers. This simplifies and shortens time-to-market of new cloud services in the brokerage platforms.
Figure 1 outlines the key components of such brokerage platforms. On top, end users are requesting cloud services using a storefront. This storefront is typically based on standard commerce platforms, provides good shopping and cloud technology agnostic experience, and sells IaaS, PaaS, or SaaS based services.
On the bottom, different cloud service providers are used to deliver a broad variety of differentiated cloud services. In the middle, WebSphere Cast Iron provides the integration layer, typically leveraging the APIs that are externalized by the different cloud service providers, and providing a secure connection between the brokerage service provider's data center and cloud services.
Figure 1. Cast Iron as a hybrid cloud integration platform
There are two main groups as brokerage service providers:
- Global cloud service providers, such as IBM SmartCloud, Microsoft® Azure, Amazon® Web Services, Google® App Engine, Orange Business Services, and so on.
- Potential country-specific brokerage service providers, such as Value Added Distributors (VADs), Value Added Resellers (VARs), Independent Software Vendors (ISVs), System Integrators (SIs), and Managed Service Providers (MSPs).
As for cloud service providers, IBM SmartCloud Enterprise (hereafter called SmartCloud), part of the IBM SmartCloud offering, delivers a secure and scalable hosted IT infrastructure with on-demand access to virtual server and storage resources.
This article provides the steps to perform a SmartCloud instance provisioning request from Cast Iron using the SmartCloud REST API without writing any code. This is based on Cast Iron Studio V18.104.22.168 and SmartCloud REST API reference release 2.0. This article does not provide an IBM SmartCloud Enterprise account, you need to have your own account.
WebSphere Cast Iron with SmartCloud Enterprise integration scenario
The IBM WebSphere Cast Iron solution is a single, complete, and robust platform that is designed from the ground up to meet the specific needs of connecting all your cloud applications, all your on-premise applications, and any hybrid combination of the two sets of applications.
WebSphere Cast Iron Cloud integration simplifies data migration and application integration by providing everything that is needed to complete such projects using a "configuration, not coding" approach that does not require expert programmers or middleware specialization. Companies choose WebSphere Cast Iron Cloud integration to integrate their applications in days and for up to 80 percent less than the cost of other traditional alternatives.
On the other hand, the IBM Cloud (also known as IBM SmartCloud Enterprise) is an IBM hosted IaaS offering designed to support corporate enterprises and provides a public, shared, virtualized, and user-managed environment that may be accessed via the Internet and at a low pay-per-use basis.
SmartCloud has several APIs (a Java™ API, a Command Line Interface API), including a REST API. This REST API is the most suitable for Cast Iron to integrate, and this article describes how to use it within Cast Iron (see Figure 2).
Cast Iron performs the instance creation request to SmartCloud and answers back with a custom response message, containing the request ID of the instance creation request.
Figure 2. Cast Iron integration scenario with SmartCloud
First, let's take a look at the SmartCloud REST API.
Using the SmartCloud REST API
In order to interact with SmartCloud, some basic understanding of its REST API is needed. This section gives a short description of the general mechanisms.
The SmartCloud REST API manages SmartCloud instances from third party
applications. All resource can be accessed by unique URIs built from the
base URL using the standard set of HTTP methods. The base URL is:
This URL will be referred in the rest of the article as
For instance, to access the list of data center locations, use the
following resource URI:
Requests and responses format
The REST API service for SmartCloud is a secured web resource that uses basic authentication. All requests to the API are required to pass SSL to ensure transport level encryption.
Creating a SmartCloud instance using its REST API
By reading the REST API documentation (see Figure 3), we understand that
the following resource URI is called to request an instance creation:
Figure 3. Information about creating a SmartCloud instance using the REST API
The mandatory parameters are:
- Name of the instance
- Image identifier from which to create the instance
- Type of the instance
- Data center location identifier
- Instance username
- Instance password
Other parameters are available, such as a reserved IP address, a volume ID of the persistent storage disk to be associated with the instance, and so on. In this article, we will explain the creation of a SmartCloud instance using the above mentioned mandatory parameters only.
The parameters are sent to Cast Iron as part of the input request. We have chosen to include these parameters into the URL to be sent to Cast Iron. Another choice is to send an XML document over HTTP, containing all the parameters. Cast Iron would then receive an HTTP request such as:
This article is based on the hypothesis that all the values for theses parameters are known beforehand by the brokerage platform making the call to Cast Iron. Therefore, Cast Iron receives the HTTP request, extracts the parameters, and directly makes the instance request provisioning.
Note: The request received by Cast Iron would normally be secured, for instance, by using SSL over HTTP. This article does not describe this feature.
Using WebSphere Cast Iron to create a SmartCloud instance
This scenario consists in sending a provisioning request for a Windows® Server 2008 image. Using the Cast Iron "configuration, not coding" approach, you can perform this easily, without writing any code.
Cast Iron receives an HTTP request such as:
As explained earlier, all the parameter values are known by the application that is sending the request to Cast Iron. This is why the above parameters are already populated with the appropriate value.
The main steps for doing this are:
- Extract the HTTP request parameters value.
- Post an HTTP request to SmartCloud for instance provisioning.
- Process the SmartCloud response and send a custom response message.
Extracting the parameters value
- Open Cast Iron Studio and create a new project.
- Import the REST API XSD schema provided by your SmartCloud
environment. From the Project tab, right-click on
XML Schemas and select the appropriate XSD
schema. For reference, see IBM SmartCloud Enterprise REST API Reference Release
Note: This schema needs to import the attachment profile WS-ISwA.xsd schema. This schema is used to manage attachments. In our scenario, we will not be sending a request with an attachment. Therefore, you may either choose to also import this schema, or modify the REST API schema to first delete this reference, and delete the element type (
type="ref:swaRef") using it.
- Create two endpoints, one for receiving the input request and another one for SmartCloud.
- From the Project tab, right-click on
Endpoint and select HTTP. Leave
all the default parameters (select Integration Appliance
Receives Request). Rename the endpoint as
- Create another HTTP Endpoint for SmartCloud.
- This time, select Remote Server and provide the Host
Name information for SmartCloud, such as
22.214.171.124. Or, you may want to use a configuration property for this value, as shown in Figure 4, with the property
SCEHost_IP. Finally, fill in
443as the port number.
- In the login Section, choose the BasicAuthentication mechanism and provide your username and password for your SmartCloud account. Again, you may want to use configuration properties as shown in Figure 4.
- In the Security section, select HTTPS. Rename it as
Figure 4. SmartCloud Endpoint configuration
- Click the Test Connection button at the bottom of
this HTTP Endpoint configuration pane (see Figure 4) to test your
connection to your SmartCloud environment. You get the following
message as shown in Figure 5.
Figure 5. SmartCloud endpoint testing result
You are now ready to build the orchestration.
- Create a new orchestration and rename it
- Drag and drop the HTTPReceiveRequest Endpoint to the
orchestration, and select the Receive Request activity as
shown in Figure 6.
Figure 6. Adding an HTTP Receive Request activity
- In the Configure checklist, fill in
/createSCEInstanceas the URL and check the Requires a Reply option as shown in Figure 7.
Figure 7. Configure the HTTP Receive Request activity
- In the Map Outputs checklist, you will create
variables for getting the parameters value carried in the URI. Click
the Select Outputs button and create
the following string variables:
- Create a String variable and name it
- Create a String variable and name it
- Create a String variable and name it
- Create a String variable and name it
- Create a String variable and name it
- Create a String variable and name it
You get similar results as shown in Figure 8.
Figure 8. Variables creation
- Create a String variable and name it
- Using the Functions tab, build a custom mapping to extract the value for each parameter.
- Drag and drop the Substring After Function. Link it
to the URI (as input) and configure the matchString with the value
instanceName=, as shown in Figure 9.
Figure 9. Substring After Function configuration
- Drag and drop the SubString Before function, map it
to the previous function (as input), and configure the matchString
with the value "&", as shown in Figure 10. This way, you get the
value of each parameter.
Figure 10. Substring Before Function configuration
- Map this second function with the instanceName
parameter created earlier, as shown in Figure 11.
Figure 11. Custom mapping for getting the instanceName variable value
- Right-click on the mapping and select Apply function Graph to have Cast Iron validate the mapping.
- Repeat Steps a through d for each parameter. You get results similar
to those shown in Figure 12.
Figure 12. Custom mapping for extracting all the input parameters value
Creating the POST HTTP request activity to SmartCloud
Before creating the actual HTTP POST Activity, you will configure two activities. The first activity is building the SmartCloud URI instance creation (the Map Variables Activity). The second activity is for trapping any error occurring when sending the request to SmartCloud (the Try… activity).
The Map Variables activity consists in concatenating the
base_url with the mandatory parameters along
with their value. For example:
You will also use this activity to populate two other variables:
SCEbaseUrl variable for storing the SmartCloud
- The OutputMessage variable for building the custom response message.
- Drag and drop the Map Variables Activity after the HTTP Receive Activity.
- Use the Select Inputs button to select all six
variables (instanceName, imageId, locationId,
instanceUsername, instancePassword, instanceType) that
were created earlier (see Figure 13).
Figure 13. Adding the variables for building the request
- Create a new String variable using the Select
Outputs button and name it
uriSceParam, as shown in Figure 14.
Figure 14. Selecting the variable in the Map Variables output section
- Drag and drop the Concatenate Function and configure
it to concatenate each variable in order to build a string
corresponding to the expected SmartCloud instance creation URI (see
Figure 15. Concatenate Function configuration
Any typo in the parameter name (for instance, "Name" instead of "name") would fail the request to SmartCloud. You might want a take a close look at the parameter's name and case, as described in the product documentation.
You see the following mapping as shown in Figure 16.
Figure 16. Custom mapping for building the SmartCloud parameters call
- Click the Select Outputs button, create a new string
variable, and name it
SCEbaseUrl. As shown in Figure 17, assign it the SmartCloud base URL value (for which you can create a configuration property).
Figure 17. SmartCloud base URL variable configuration
- Finally, click the Select Outputs button, create a
new string variable, and name it
OutputMessage. Since this variable will be instantiated later in the orchestration in the Try… activity, it needs to be instantiated out of this activity. This is why you assign it a default value as shown in Figure 18 (a dummy text message, for instance "default output message").
Figure 18. Dummy default value for OutputMessage variable
- Drag and drop the Try… activity
after the Map Variables Activity as shown in Figure 19.
Figure 19. Try… activity creation
- Drag and drop the SCE endpoint within the Try… branch
and select the Post Request activity as shown in
Figure 20. POST Request Activity creation
- In the Map Inputs Checklist:
- In the From Orchestration section (left part of the mapping), select the uriSceParam and SCEbaseUrl variables created earlier.
- In the To Activity section (right part of the
mapping, just below the body variable), right-click and select
Show Optional Parameters as shown in Figure
21. This way, you can access the HTTP
Figure 21. Displaying the HTTP parameters
- Then, fill in the following values for the HTTP headers as shown in
- Uri: Drag and drop the Concatenate Function and configure it to concatenate the SCEbaseUrl, the string /instances?, and the variable uriSceParam.
- Method: Set POST as the default value for the method HTTP header.
- Body: Type the space character. Cast Iron does not allow an empty body, so you just post a body containing a space character.
Figure 22. HTTP Parameters configuration
- In the Map Outputs Checklist, use the
Copy button to copy the body and rename the
created variable to
InstanceCreationResult, as shown in Figure 23.
Figure 23. Map output configuration of the POST Request Activity
- In order to send a custom message upon instance creation error, you
will instantiate a variable with this error message. Drag and drop the
Map Variables Activity in the
CatchAll branch as shown in Figure 24.
Figure 24. Map variables activity in the CatchAll branch
- Click the Select Inputs button and choose the faultInfo XML variable.
- Click Select Outputs button and choose the OutputMessage variable.
- Use the Concatenate
Function to concatenate an error message with the
actual message element of the faultInfo variable to the OutputMessage
variable as shown in Figure 25.
Figure 25. Concatenate Function configuration
Parsing the SmartCloud response
In order to complete the orchestration, you now need to parse the SmartCloud instance creation response and reply to the original caller with the instance request information (request identifier, date, and so on).
Looking at the SmartCloud XSD, notice that the create instance response
CreateInstanceResponse) contains a
Instance (see Figure
26). This is for the case where several
instance creations are submitted in one request.
Figure 26. SmartCloud XSD extract
However, the scenario described in this article is based on a single
instance creation request, so there will always be only a single
occurrence of the
Instance element. You will
then filter the parsing activity result to keep only the first
- Drag and drop the Read XML activity after the
Post Request activity (see Figure 27).
Figure 27. Read the XML activity creation
- In the Configure checklist, click the
Browse button and create a variable based
on the CreateInstanceResponse element from
the SmartCloud XSD schema (see Figure 28).
Figure 28. Read the XML activity configuration
- In the Map Inputs checklist, use the
Select Inputs button to select the
InstanceCreationResult variable and map
it to the XmlText one, as shown in Figure
Figure 29. Map inputs mapping of the Read XML activity
- In the Map Outputs checklist, use the
Copy button to copy the OutputXML
variable and rename the variable to
ParsedCreateInstanceResponse, as shown in Figure 30.
Figure 30. Map outputs mapping of the Read XML activity
- In order to select the first occurrence of the Instance
element, right-click on Instance, and select
the Filter Recurring Nodes menu, as shown in
Figure 31. Filter Recurring Node configuration
- Fill in
1in the XPATH expression and click OK as shown in Figure 32.
Figure 32. Filter Recurring Node XPATH Predicate
- Drag and drop the For Each activity after the
Read XML one as shown in Figure 33.
Figure 33. For Each activity creation
- Configure the For Each activity for looping
through the result of the Read XML activity as shown in Figure
- For the Variable Name, select ParsedCreateInstanceResponse.
- For the Element Name, select the Instance recurring element.
- For the last Variable Name, type
Figure 34. For each Activity configuration
- Drag and drop the Map Variables activity in the For Each branch.
- Click the Select Inputs button to select the createinstanceResponseLoop variable.
- Click the Select Outputs button to select the OutputMessage variable.
- Drag and drop the Concatenate function and
build a custom mapping, displaying a text message containing
the instance creation information. Figure 35 shows an example
of such a custom message to be sent back.
Figure 35. Custom message configuration
- Drag and drop the Send Response Activity
after the Try… activity, as shown in Figure 36.
Figure 36. Send Response activity creation
- The Configure section is already configured,
since there is only one HTTP Receive Request activity
requesting a reply in this orchestration (Cast Iron Studio
automatically filled this in). Then, go in the Map
Inputs checklist, click the Select
Inputs button to select the
OutputMessage variable, and map it to
body on the right (see Figure 37).
Figure 37. Send Response Activity configuration
The orchestration configuration is now complete. In order to get a clearer understanding of which activity is performing what action, you may customize the name of each activity. You can then get an orchestration that looks similar to Figure 38.
Figure 38. Completed orchestration configuration
You are now ready to test your orchestration. You will test locally within Studio, and then deploy and run it on a Cast Iron Server.
Testing the orchestration locally within Studio
- Using the Verify tab, you will start the
orchestration. You may use the HTTP Post Utility from
Studio to send the HTTP request to the orchestration. The request to
be sent is shown below. You may want to change the value of the parameters,
adjusting to your own needs.
http://<yourComputerName>/createSCEInstance?instanceName=CastIronInstance&imageId= 20012054&instanceType=BRZ64.2/4096/60*500*350&locationId=61&instanceUsername= vmAdmin01&instancePassword=CIS01Demo&
- From this Verify tab, you can then drill down into each activity input
and output. For instance, let's imagine that an error happens in the
SmartCloud authentication. Since you have trapped the POST SCE Request
into a Try… activity, the orchestration does not fail and returns the
custom error message that you have defined. You get the following run as
shown in Figure 39.
Figure 39. Simulating an error in the orchestration
- Let's run another orchestration and see how it goes when no error
happens (see Figure 40).
Figure 40. Running the orchestration without any error
- Notice that the request identifier of your instance is sent back (such as 246926).
You may now want to login to your SmartCloud account and check the
status of your instance, as shown in Figure 41.
Figure 41. Checking your instance creation request in SmartCloud
The status of the instance is first "Requesting". It changes to "Provisioning" as shown in Figure 42, and finally "Active" after it starts as shown in Figure 43.
Figure 42. Status changed from Requesting to Provisioning
Figure 43. Status changed from Provisioning to Active
If you want to go further
If you want to go further with the Cast Iron SmartCloud integration, you can configure other orchestrations as follows:
- An orchestration for getting the status of an instance
- An orchestration for deleting an instance
The SmartCloud REST API explains how to perform these:
- For getting the status of an instance, call the following resource URI
as shown in Figure 44:
Figure 44. Getting the status of an instance
- For deleting an instance, call the following resource URI as shown in
Figure 45. Deleting an instance
See the complete project that is provided in the Download section of this article.
Deploying to the Cast Iron Server
- From Cast Iron Studio, select the menu File > Publish
Project and fill in the host name, user name, and password of
your Cast Iron Server, as shown in Figure 46. Keep in mind that the
host name should be the admin IP address.
Figure 46. Deploying on a Cast Iron Server
- Now you may log in to your Cast Iron Server Web Management Console. You
see that your project is ready to be started, as shown in Figure 47.
Figure 47. Project deployed on a Cast Iron Server
- Before starting your project, you might want to take a look at the
configuration properties and adjust the values to your own environment, as
shown in Figure 48.
Figure 48. Adjusting the configuration properties
- Now you can start your project and test it again. You can also use the HTTP POST Utility provided with your Cast Iron Studio installation to post HTTP requests to your deployed orchestrations.
WebSphere Cast Iron provides a hybrid cloud integration platform, allowing integration of public cloud applications and private on-premises applications. With the "configuration, not coding" approach of WebSphere Cast Iron, this article showed how you can quickly and easily integrate with cloud providers such as IBM SmartCloud Enterprise. Cast Iron offers the ability to customize a cloud service request, get the status of an instance provisioning, delete an instance, and so on. Cast Iron simplifies and shortens time-to-market of new cloud services in brokerage platforms.
However, Cast Iron also extends some of the IBM Tivoli® components to help clients monitor and secure the management of resources on both public and private clouds. Tivoli hybrid cloud capabilities are now offered as an extension of Tivoli Service Automation Manager, IBM Service Delivery Manager, and IBM Tivoli Monitoring, running on WebSphere Cast Iron Hypervisor Edition.
|Code sample file||SmartCloudIntegration.zip||56KB|
- IBM WebSphere Cast Iron
- WebSphere Cast Iron Cloud Integration product page
- Announcement: IBM WebSphere Cast Iron Live V6.2 provides externalization of services through web APIs and rapid integration for hybrid environments
- Cast Iron community forum
- IBM WebSphere Cast Iron Version 6.1 Information Center
- IBM Redbook: Connect cloud and on-premise applications using IBM WebSphere Cast Iron Integration
- IBM Redbook: Getting started with IBM WebSphere Cast Iron Cloud Integration
- Integrating cloud applications with WebSphere Cast Iron Cloud Integration
- IBM Hybrid Cloud solution
- IBM SmartCloud Enterprise