Deploying and testing an enterprise integration solution in App Connect on IBM Cloud

• An App Connect service on IBM Cloud with enterprise integration capabilities; for example, as now provided in the free Lite plan. (For more details, see http://ibm.biz/acocstart4free.)
• A valid BAR file that you’ve created in the IBM App Connect Enterprise Toolkit. For this example, we are using the Transformation_Map application built and tested in Get started with IBM App Connect Enterprise. That created the BAR file: C:\workspace\Transformation_Map\Transformation_Map.bar where C:\workspace is the location of your Toolkit Eclipse workspace directory on the filesystem (in this case on Windows). Tip: If you have not created the BAR file using your App Connect Enterprise Toolkit, you can download the project interchange ZIP file from https://github.com/ot4i, and extract the BAR file from that archive. For more about the App Connect Enterprise tutorials on Github, see Tutorials for App Connect Enterprise.

(Click image to view full size)

• Your preference for the VPC ( Virtual Processor Core) capacity of the integration server to be created to run the BAR file's integration solution.

  You can change the following VPC configuration options for the integration server that will be created for a BAR file either when you deploy the BAR file or later by editing the integration server.

  • Size of the container: A BAR file is run by a single integration server created with a specific capacity (container size). When deploying a BAR file, you can choose small container sizes so that the total capacity bought can be spread between many smaller BAR files. This lets you run many more separate BAR files, which allows for finer-grained control of updating, starting, and stopping integration servers (and the integration solutions they run) independently.
  • Number of replicas: In addition to allowing different sized integration servers, you can also define the number of replicas of an integration server required to allow for better availability of the integration solutions. All replicas for an integration server share the same HTTP hostname, and HTTP traffic is spread between the integration servers. If one server happens to crash or get restarted for any reason then the other servers continue unaffected. When a system update happens to App Connect, only one of the replicas is restarted at a time so the others can continue to handle requests. Note: When running with multiple replicas, some functions will not work as you might first expect, due to the fact that completely separate integration servers will be created. For example, collecting service trace or trying to use the graphical debugger from an on-premises App Connect Toolkit will only work correctly when running with a single replica. When using event-driven nodes, like aggregation or collector, then the state store will not be shared between replicas and this should be taken into account when deciding to use additional replicas.
  

  (Click image to view full size)

1. Launch App Connect on IBM Cloud.
2. Click New > Import a BAR file.
   

   (Click image to view full size)

3. Either click the Import a BAR file dialog box to select the BAR file from your file system, or drag the BAR file from your file system to the dialog box.
4. For this example, leave the VPC (Virtual Processor Core) configuration options (for example, Number of replicas) to default for the integration server that will be created for the BAR file.
5. Click Import BAR. An integration server is created, and a tile is added to the dashboard to represent it. Initially, you'll see the status as ‘Preparing’, which means that the contents of the BAR file are being unpacked onto the integration server. When preparation has finished, the status will show as ‘Stopped’, indicating that the integration server is ready to be configured and started. Tip: If you see a message saying that preparation failed, click Try again in the message to start preparation again.
   

   (Click image to view full size)

6. Examine the default configuration of the integration server, and optionally change values:
   • Open the integration server, by clicking the tile.
   • The BAR file name is used as the default name for the integration server. You can change this name, by clicking the default name and then typing a new name.
   • You can add or edit a description for your integration solution (up to 128 characters).
   • You can change the VPC configuration values for 'Number of replicas' and 'Size of the container'.
   • Examine the configuration of HTTPS basic authentication, which is turned on by default. You can change the password and basic authentication header (by clicking Regenerate credentials) or turn of basic authentication.
   • In the bottom section, you can see the name of the message flow invoked for the integration solution, and the HTTP input URL that can be used to invoke the integration.
7. Copy the configuration details that you’ll use to test the integration solution (Transformation_Map):
   • From the bottom section (Transformation_Map), copy the HTTP Input value
   • From the Basic authentication credentials, copy the User name (iib) and password (or the HTTPS basic authentication header if you want to use that instead).
8. When you've finished examining the configuration, return to the dashboard then start the integration server by opening the tile menu (⋮) and then clicking Start.
9. Test the integration solution by sending it data using an HTTP client such as cURL. The steps are the same as in Get started with IBM App Connect Enterprise, but in this example the host is an IBM Cloud hostname and by default uses basic authentication, and the data submitted is raw XML from the Transformation_Map\input.xml file. For example, on a Windows computer where you downloaded the project interchange ZIP file or used the App Connect Enterprise Toolkit to explore the sample integration solution, complete the following steps:
   1. In a command window, change directory to your local workspace; for example, cd C:\workspace where C:\workspace is either the location where you extracted files from the project interchange ZIP file or the location of your Toolkit Eclipse workspace directory on the filesystem, which contains the Transformation_Map files including the input XML file C:\workspace\Transformation_Map\input.xml.
   2. Copy the contents of the input XML file C:\workspace\Transformation_Map\input.xml.
   3. Submit the cURL command to post the data copied from the input XML file:

      curl -X POST http_input -u 'username:password' -d '<?xml version="1.0" encoding="UTF-8"?>
      <SaleEnvelope>
      ...
                      <CompletionTime>12.00.00</CompletionTime>
              </Trailer>
      </SaleEnvelope>'
      

      (Enter) For example:

      curl -X POST
      https://ihavef0l.ace.ibm.com/Transformation_Map -u 'iib:o1B=c4ef'
      -d '<?xml version="1.0" encoding="UTF-8"?>...'

   The transformed response message should look like this: In a command window:

   <SaleEnvelopeA><SaleListA><Statement Style="Full" Type="Monthly"><Customer><Initials>KA</Initials><Name>Braithwaite</Name><Balance>00.50</Balance></Customer><Purchases><Article><Desc>Twister</Desc><Cost>0.48</Cost><Qty>01</Qty></Article><Article><Desc>The Times Newspaper</Desc><Cost>0.32</Cost><Qty>01</Qty></Article></Purchases><Amount Currency="Sterling">0.8</Amount></Statement><Statement Style="Full" Type="Monthly"><Customer><Initials>TJ</Initials><Name>Dunnwin</Name><Balance>81.84</Balance></Customer><Purchases><Article><Desc>The Origin of Species</Desc><Cost>35.74</Cost><Qty>02</Qty></Article><Article><Desc>Microscope</Desc><Cost>57.92</Cost><Qty>01</Qty></Article></Purchases><Amount Currency="Euros">129.41</Amount></Statement></SaleListA></SaleEnvelopeA>
   

   Or formatted, as in a result from Postman:

   <SaleEnvelopeA>
       <SaleListA>
           <Statement Style="Full" Type="Monthly">
               <Customer>
                   <Initials>KA</Initials>
                   <Name>Braithwaite</Name>
                   <Balance>00.50</Balance>
               </Customer>
               <Purchases>
                   <Article>
                       <Desc>Twister</Desc>
                       <Cost>0.48</Cost>
                       <Qty>01</Qty>
                   </Article>
                   <Article>
                       <Desc>The Times Newspaper</Desc>
                       <Cost>0.32</Cost>
                       <Qty>01</Qty>
                   </Article>
               </Purchases>
               <Amount Currency="Sterling">0.8</Amount>
           </Statement>
           <Statement Style="Full" Type="Monthly">
               <Customer>
                   <Initials>TJ</Initials>
                   <Name>Dunnwin</Name>
                   <Balance>81.84</Balance>
               </Customer>
               <Purchases>
                   <Article>
                       <Desc>The Origin of Species</Desc>
                       <Cost>35.74</Cost>
                       <Qty>02</Qty>
                   </Article>
                   <Article>
                       <Desc>Microscope</Desc>
                       <Cost>57.92</Cost>
                       <Qty>01</Qty>
                   </Article>
               </Purchases>
               <Amount Currency="Euros">129.41</Amount>
           </Statement>
       </SaleListA>
   </SaleEnvelopeA>
   

   Result: You have deployed, run, and and tested an enterprise integration solution in IBM App Connect on IBM Cloud.

10. To view and manage event messages that are logged for all your integration servers and other flows in App Connect, click the Logs icon on the Dashboard.

    

    (Click image to view full size)

    To view and manage event messages for a specific integration server within the log viewer, click the integration server's tile and then click View logs.

    Optionally, to download the log file click the Download icon .

11. Optionally, you can stop the integration server by opening the tile menu (⋮) and then clicking Stop.

This tutorial has demonstrated a subset of the capabilities for deploying and running enterprise integration solutions in App Connect on IBM Cloud.

If you want to explore more of the capabilities of App Connect Enterprise on IBM Cloud, see more tutorials.