Cloud Pak for Integration

Creating a scenario

Use case 1

Order processing

Integration capabilities for the scenario - APIC + ACE + MQ + Event Streams

High level overview

Scenario: The company ABC exposes its order processing service as an API. The API is implemented as ACE flow which posts the request to two different systems via MQ queue and ES topic.

Download artefacts to the developer’s machine

  • You can download the artefacts from here: Artefacts
  • Download all files including generateSecret subdirectory

Prepare Event Streams

  • ICP: Workload > Helm Releases
  • Find es helm release usecase1
  • Upgrade / Reuse values usecase1
  • Disable message indexing usecase1
  • Click Upgrade

Create Event Streams topic

  • Open Platform Navigator:
  • You can click Skip welcome usecase1
  • Click on Event Streams instance usecase1
  • In case of “es did not load correctly error”, click on the provided “Open es” link usecase1
  • ES dashboard opens, click Topics tab usecase1
  • Click on Create topic usecase1
  • Enter NewOrder for topic name and click Next usecase1
  • Leave Partitions as 1, click Next usecase1
  • Specify A Week for message retention, click Next usecase1
  • Leave defaults for Replicas setting, click Create Topic usecase1
  • The confirmation message appears usecase1

Extract the Event Streams connection information

  • Select Connect to this cluster usecase1
  • Make note of the Bootstrap server address: usecase1
  • Download the PEM Certificate usecase1

  • Create API Key using the section on the right
  • Enter OrdersFlow for the Application name usecase1
  • Specify Produce, consume and create topics usecase1
  • Select all topics usecase1
  • Select all consumer groups usecase1
  • Click Generate API key… usecase1
  • and download the JSON file usecase1

Generate a Secret object for connecting from ACE helm release to the Event Streams instance

  • Navigate to the directory with downloaded artefacts - subdirectory generateSecret
  • Copy API Key from previously downloaded es-api-key.json to setdbparms.txt (Note: copy only key, not the quotes arround it) API key
  • Override the text ** in **setdbparms.txt** file. ![API key](
  • The result should look similar to the following: API key
  • Extract the certificate from the previously downloaded es-cert.pem file:
      openssl x509 -in es-cert.pem -text
  • Copy the certificate, including the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- and paste it to both files: truststore-Cert-mykey.crt and keystore-mykey.crt: Certificate
  • Navigate to the OpenShift console and select Copy Login Command CLI login
  • Open terminal window and paste the command
  • Navigate to the generateSecret directory and run
      ./ my-secret release1
  • The result should be similar to the following:
      Creating configuration secret
      kubectl create secret generic my-secret --from-file=adminPassword=./adminPassword.txt --from-file=appPassword=./appPassword.txt --from-file=truststorePassword=./truststorePassword.txt --from-file=truststoreCert-=./truststore-Cert-mykey.crt --from-file=serverconf=./serverconf.yaml  --from-file=setdbparms=./setdbparms.txt
      secret/my-secret created
      Creating users secret
      kubectl create secret generic release1-ibm-ace --from-file=adminusers=./adminusers.txt
      secret/release1-ibm-ace created  

Configuring MQ artefacts post-deployment

Note: The post-deployment configuring of MQ artefacts described here can be used for demo and test environments. For the production we recommend to create a configuration secret to define the MQ configuration as a part of the Helm release or to enable the persistence for the MQ so that the configuration is preserved in case that MQ pods are recreated.

  • Open Platform Navigator:
  • Select mq usecase1
  • In case of error message that the instance did not load correctly, select provided link usecase1
  • The MQ Console will open usecase1
  • Select queue manager and the select properties: usecase1
  • On the Communication tab, find the CHLAUTH Records property and make it Disabled usecase1
  • Click Save and Close
  • Click on Add widget button on top-right… usecase1
  • …and add Queues widget usecase1
  • Click on Create usecase1
  • Select Local queue type usecase1
  • and give it a name NEWORDER.MQ usecase1
  • Add Channels widget usecase1
  • Click on Create to create a new channel usecase1
  • … call it ACE.TO.MQ, select Server-connection channel type usecase1
  • Select the channel and click Properties usecase1
  • On the MCA tab, for MCA User ID specify mqm usecase1
  • Click Add widget again and select Authentication Information widget usecase1
  • Click on the cogwheel to configure the widget usecase1
  • … and select System objects: Show usecase1
  • Select SYSTEM.DEFAULT.AUTHINFO.IDPWOS and then click Properties usecase1
  • On the User ID + password tab, for both Local connections and for Client connections specify None usecase1
  • Select Save and Close
  • Select queue manager again and click on “three dots” icon, the select “Refresh security” usecase1
  • Click on Connection authentication usecase1

Confirm MQ Listener port

  • Still in MQ Console, add Listeners widget usecase1
  • Configure widget to see system objects usecase1
  • Select System objects: Show usecase1
  • Check the value of SYSTEM.LISTENER.TCP.1 (default is 1414) usecase1
  • Navigate to OpenShift console, select mq project and the select Application > Services usecase1
  • Select the service whose name starts with the queue manager name and has extension ‘-ibm-mq’ usecase1
  • Check the NodePort that the listener port is mapped to (in this case it is 32251): usecase1

  • We can access the listener from the outside of the cluster using the cluster proxy host name and this port.
  • However, if we are accessing the mq inside the cluster, we can use .svc.cluster.local for the host name and target listener port (not mapped one): ![usecase1](

Modify ACE flow

  • Start the ACE Toolkit and import project interchange file available under the previously downloaded artefacts
  • Navigate to orders project Resources/Subflows and open New_Order.subflow usecase1
  • Add Http Header, MQ Output and Kafka Producer node and connect them as shown on the picture below: usecase1

  • Select Http Header node and configure it to delete header usecase1

  • Select MQ Output node, for Queue Name specify NEWORDER.MQ usecase1
  • In the MQ Connect tab define
    • Connection: MQ client connection properties
    • Destination queue manager name: qmtest4
    • Queue manager host name:
    • Listener port number: 1414
    • Channel name: ACE.TO.MQ


  • Select Kafka producer node.
  • Enter NewOrder for the topic name and previously noted bootstrap server address, in our case it is usecase1
  • Under Security tab select SASL_SSL for the Security protocol and TLSv1.2 for SSL protocol. usecase1

  • Save the work.
  • Create BAR file. Name it orders
  • Add orders REST API, optionally select Compile and in-line resources and click on Build and Save usecase1

Deploy the BAR file

  • Open Platform Navigator:
  • Click on ACE instance usecase1
  • On the ACE dashboard navigate to the Servers tab and click Add server usecase1
  • Select BAR file.. usecase1
  • … and click Continue usecase1
  • Copy the Content URL to the clipboard and click Configure release usecase1

  • Helm chart opens. Click Configure. usecase1
  • Enter orders for Helm release name, select ace namespace, local-cluster and accept license agreement: usecase1
  • Scroll down and select All parameters usecase1
  • Paste previously copied Content Server URL. usecase1
  • Scroll down and for Image pull secret enter deployer-dockercfg-wmwxh (this secret is created during the pak installation, use OpenShift web console or oc get secrets -n ace command to obtain the exact name) usecase1
  • Scroll down and enter your proxy node doman name for the Node port IP. For example: usecase1
  • Enter keystore and truststore aliases and secret name as defined previously in the step for generating secrets for accessing Event Streams. In our case, the keystore alias is mykey, the truststore alias is Cert-mykey and secret name is my-secret usecase1
  • Scroll down once more and disable persistence usecase1
  • Click on the Install button.

  • The installation can take several minutes.
  • Navigate back to ACE dashboard, click on Done and wait until the server is ready. usecase1

  • You can also navigate to the OpenShift console and select ace project, Applications > Pods to see the pods. usecase1

  • Or check the pods using CLI usecase1

  • As the result you will see the running server in the Dashoard: usecase1

Test the deployed ACE APIs

  • Open the Cloud Pak Navigator and select the App Connect instance Navigator

  • Click on ordersapi server that we have just deployed Server

  • The list of artefacts deployed on server appears. In our case we have only the API called orders. Click on it: API

  • The page that appears shows the REST API base URL, link to the OpenAPI document (swagger) file, and list of operations. In our case there is only one POST operation and the route of that operation is /create: Operations

  • Prepare a JSON file with the following content. Name it, for example order.json:
    "accountid": "A-10000",
    "order": {
      "orderDate": "2004-01-19T04:25:25.938Z",
      "contractId": "00000100",
      "orderDetails": [
          "lineItemNumber": 1,
          "productId": "AJ1-05",
          "quantity": "20"
  • Navigate to the terminal window and run (note that URL is built from REST API base URL and operation path /orders):
      curl -k -X POST -d @order.json
  • The response similar to the following should be returned:
  • Open the Platform Navigator and select MQ instance Check MQ

  • Select queue widget, refresh if necessary, the queue depth should be increased Check MQ

  • Select Browse messages to see the content Check MQ

  • Using the Platform Navigator, select the Event Streams instance Check ES

  • Select Topics Check ES

  • Select topic Check ES

  • then check the messages Check ES

Expose the API using API Connect

  • Open once again the ACE dashboard Navigator

  • Click on our ordersapi server Server

  • And finally select our API: API

  • As already mentioned there will be a link to the OpenAPI (swagger) document on the right side of the page: OpenAPI

  • Click on it to open the document in browser Document

  • Using the browser, save the document to some directory on your local disk. The default name of the file is swagger.json

  • Go back to the Platform Navigator and select the API Connect instance API Connect

  • Login to the API Manager API Manager

  • Click on Develop APIs and Products APIs

  • Add new API: API

  • Select to create API From existing OpenAPI service and click Next API

  • Select previously downloaded swagger.json and click Next JSON

  • Keep default values on the next page and click Next Create API

  • Select Activate API and click Next Activate API

  • Wait until API is prepared and click Edit API Edit API

  • Select Assemble: Assemble

  • Run API test Test

  • Select post/create operation: Operation

  • Copy/paste the same JSON structure that you prepared in the Test the deployed ACE APIs step: JSON

  • Click on Invoke Invoke

  • In case of CORS error click on the provided link: CORS

  • Confirm to open the page, navigate back to the test tool and click Invoke again Invoke

  • You should receive HTTP 201 status code Response