Skip to main contentIBM Cloud Pak Playbook

Creating a scenario

Use case 1

Order processing

Integration capabilities for the scenario - APIC + ACE + MQ + and Platform Tracing

High level overview

Scenario: The company ABC exposes its invoice processing service as an API. Invoices are posted into the API in JSON format and consumed by an integration flow that puts it to queue so it can be processed by the back office financial systems.

Download artefacts to the developer’s machine

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

Prepare MQ

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: https://icp-proxy.icp4i-6550a99fb8cff23207ccecc2183787a9-0001.us-east.containers.appdomain.cloud/integration
  • 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 processing
  • Add Channels widget usecase1
  • Select the SYSTEM.DEF.SVRCONN channel and click Properties
  • On the MCA tab, for MCA User ID specify mqmusecase1
  • Click Add widget again and select Authentication Information widget usecase1
  • Click on the cogwheel to configure the widget usecase1
  • … and select System objects: Showusecase1
  • 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 <service_name>.svc.cluster.local for the host name and target listener port (not mapped one): usecase1

Deploy ACE Flow

  • Download

  • 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: **qm-test4-ibm-mq.mq.svc.cluster.local**
    - Listener port number: **1414**
    - Channel name: **ACE.TO.MQ**
    usecase1
  • Select Kafka producer node.

  • Enter NewOrder for the topic name and previously noted bootstrap server address, in our case it is icp-proxy.icp4i-6550a99fb8cff23207ccecc2183787a9-0001.us-east.containers.appdomain.cloud:32490 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

  • 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: icp-proxy.icp4i-6550a99fb8cff23207ccecc2183787a9-0001.us-east.containers.appdomain.cloud 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",
  • 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 http://orders.icp-proxy.icp4i-6550a99fb8cff23207ccecc2183787a9-0001.us-east.containers.appdomain.cloud:30753/orders/v1/create -d @order.json
  • The response similar to the following should be returned:

    {"accountid":"A-10000","orderid":"1632603"}
  • 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