CP4I Modernization Practicum Workshop Singapore

IBM Cloud Pak for Integration - Configuration

4.1. High Level Architecture

4.2. Prepare Client Tools

4.3. Messaging Queue (MQ)

4.4. Integration - ACE to MQ

4.5. Integration Dashboard - Deploy a local integration server

4.6. API Connect (APIC)

——————————————————————

High Level Architecture

Below is the high level architecture that we plan to implement as part of this scenario.

Prepare Client Tools

Make sure that you setup/prepare the below pre-req before proceeding.

IBM App Connect Enterprise (ACE) Toolkit Setup

Refer to the instruction here

Openshift Command Line Interface (CLI) Setup

Refer to the instruction here

Mailtrap SMTP Setup

Refer to the instruction here

Messaging Queue (MQ)

Check & Create Queue Manager

Go to IBM Cloud Pak home. Check the IBM Cloud PAK URL from Openshift Route cp4d or as per given by the instructor.

Login to IBM Cloud Pak using the IBM provided credentials (admin only).

Use IBM provided Authentication (admin only) and log in with admin and its password.

Go to IBM Cloud Pak Home. You can verify the currently added/configure instances from Menu -> Integration Instances.

The below instances should already be pre-created for you.

Click on Messaging as highlighted in the screen below. (Menu -> Run -> Messaging)

This will redirect to a Messaging screen as below. If there MQ Console does not appear,Click on Create an instance to create a new queue manager instance. If MQ Queue Manager appear, then you can skip creating queue manager.

Alternatively Queue Manager can be created from Menu -> Administration -> Integration Instances -> Create An Instance+. Select Messaging Option and proceed as below.

Select Quick start option from this screen, and click on Next.

Modify the details for your queue manager as below:

Lastly click on Create from the top right corner and queue manager will be created. You will be redirected to a new page, showing the details of your newly created Queue manager.

The Queue Manager Name is always QUICKSTART unless the name was changed from the advanced properties in the final Creation Screen. Need to toggle the Advanced option to see the advance details.

Click on queue manager name –> It should open up MQ Console

Click on manage –> quickstart to open queue manager

Create Queue

Click on Create icon to create the queue.

Select a Local Queue.

Provide the details of the queue and click create.

Queue will be created shortly.

Configure Default Channel Security**

There are different layers of authorization and authentication configured on the Channel access. To simplify the exercise, we will proceed to disable to Channel security authentication and authorization using the script mq_ace_lab.mqsc . Below steps will assist to disable.

Copy Login Commands to login to oc client.

Login to Openshift cluster using oc client.

oc login --token=sha256\~xxxxxx-xxxxxx-g --server=https://servername:30273

run below command to see all your projects.

oc projects

Run below command to switch to your project.

oc project cp4i

Run below command to see the pod name of the mq queue manager.

oc get pods \| grep -i mq

Note the MQ Queue Manager POD Name. eg. ** quickstart-cp4i-ibm-mq-0 **

Change Directory to the location of your mqsc file. Use the following command to upload mqsc file to the MQ pod. QUICKSTART is queue manager name.

oc exec -it quickstart-cp4i-queue-ibm-mq-0(this is your pod’s name) runmqsc QUICKSTART(QMGR-Name) < mq_ace_lab.mqsc

This script performs:

The above command should succeed with below lines in the end.

94 MQSC commands read.

No commands have a syntax error.

All valid MQSC commands were processed. </i> </u>

Note the default channels details. Go to the Applications Tab for the Queue Manager that you created.

Click on App Channels link in the left pane. Click on the Filter and Select Show System Channels.

You should be able to see the System Channels. Note the default channel to be used for MQ Communication.

Integration - ACE to MQ

Integration has the following components:

Prepare - Asset into IBM ACE Toolkit

Open IBM ACE Toolkit under a workspace and create a REST API project.

Give it a name and select the specification as Swagger 2.0 Click Finish.

Open the REST API Description. In the right Pane, Under Resources, Click on + icon to create a resource.

Enter the resource path and select the operation as post. Click Apply.

A New resource will be created.

Click on the subflow icon or this new resource.

New subflow editor will open. Drag the IBM MQ -> MQ Output Connector from the transformation section in the left toolbox.

Connect the Boxes together.

Find the MQ Queue Manager Service IP address from the “openshift console” or oc client (oc get svc | grep -i mq).

Click on the MQ Output and configure the MQ Details. Enter the Queue Name.

Enter the MQ Queue Name in the Basic Tab. Then in the MQ Connection tab, Enter the MQ Connection Details like Queue Manager Name, Queue Manager Host Name (Service IP), Listener Port no (1414 Default), Connection Channel Name (default – SYSTEM.DEF.SVRCONN).

If you have a policy for MQ EndPoint,then you can configure the policy name in the policy tab here in the format {MQPolicyProjectName}:PolicyName, so that it can be used as a configuration for the integration server. In this case, above details on MQ Connection tab are not required. The Policy Project Creation Reference is here.

Build – BAR File

Add a new BAR file in the project to package and export the configuration.

Enter the bar file details and click Finish.

Include the newly created project. Add the Build options and Click Save.

Rebuild BAR and save file one more time.

Check the properties of the generated bar file.

Copy the bar file path or open it in finder window.

Integration Dashboard - Deploy an integration server

Proceed to create a Integration Server in CP4I Console. Click on Deploy Integrations.

Click Deploy a Server and Chose a Quick Start Plan. Click Next.

Drag and Drop the newly generated bar file here. Click Next.

Skip any Configuration to be applied this integration if you have not created a Policy Project. Just Click Next.

If you have a MQ Policy Project, then you can create configuration for it, select it and Click Next. Click here for more details.

Enter the Integration Server Name starting with your Name to make it unique, Select License. Click Create.

The Integration Server will be created and ready shortly. You may refresh the page to check on the readiness status update.

Click on the Server once its ready.

Click on the API.

Click on the post/AccountEnquiry.

Click on Try It Tab to test the Rest Interface.

Click on Generate to generate a random test message. Click Send.

The response should come successfully.

This completes the creation and testing of local integration server.

API Connect (APIC)

Navigate to Administration -> Integration Instances.

If there is no existing instance of API Management, Create an instance of the API Connect (API Management) as per following procedure.

If there is already an instance, then you should be able to see instances for API Management, API Management Administration, API-managed enterprise gateway. In this case, just click on the instance name for API Management Administration and continue to create organiation as per next section of Cloud Manager (API Management Administration).

Chose the basic one node plan. Click Next.

Enter the API instance Name and accept the license. Enter the license ID.

The matching Storage Class will be automatically selected. Click Finish.

The following API Connect Instances will be created in about 45 minutes.

Cloud Manager (API Management Administration)

Create Organization

Click on the API Management Administration Link to open Cloud Manager Console.

Click Manage Organization.

Click on Add to create an API organization which is like a logical separation of multiple API users.

Enter the Organization Name.

Change the User Registry to Common Services User Registry. Enter the existing user name as admin. Click Create.

Configure SMTP for notifications

Click on Resource’s link in the left pane. Click on Notification Link in the left pane.

Click on Create button to create a new SMTP Server.

Add a new smtp server for email notifications. You can add any smtp provider eg. Sendgrid or mailtrap or any other.

Click test email to test the connection. Enter the recipient email id and click Send Test Email.

The email should be sent successfully. You can verify this only through the mailtrap inbox. It will not land in the actual reciever inbox.

Click Save to save the config.

Also update the same email smtp settings for the Dummy mail server as well.

Configure admin email id

In the Cloud Manager, Under Manage Organization, Go to Logged in User (admin) Settings and click My Account.

Update the email id for the current account. Very Important. Otherwise later you will not be able to create a portal service under a catalog.

API Manager (API Management)

Click on the API Management Link to open API Management Console. If you see below picture then your Organization is not set correctly.

After setting the organization correctly, the API Manager should look like this.

Develop API

Click on Develop APIs and products. Create a new API. This will encapsulate the API created on the ACE.

Chose the default option “From Target Service”. Click Next.

Provide the details for Target service.

Note the Target Service URL from Integration Dashboard that we created earlier.

example, http://hostname/MyEquiry/v1/AccountEnquiry

Enter the title of the API. This will also create an endpoint / base path using which the API can be called and it will just redirect the request to Target Service URL.

Click Next.

Click Edit API.

Configure API

After Clicking Edit API, API Design Screen will open.

As we are exposing only post service in the backend we can delete the other operations from here.

Click Save.

Under Security Schema Click Add to add another security schema.

Select apiKey as the security definition key.

Enter the details as below.

Client Secret is added as security schema. Click Save.

Go to General -> Security . Edit the security schema name.

Select both parameter and Click Submit.

Click Save.

Now make this API online so that it will be published in a development sandbox.

Develop Product

Go to API Manager Home again and click on “Develop API and Products”.

Now we need to package this API into a product. One product can have multiple APIs.

Click Add -> Product.

Click Next.

Give a product Name. Click Next.

Select an API to be added into this product. Click Next.

Review the plan details. You can more plans by clicking on Add Button. Can define the new plan name and rate limit (eg. API Calls Frequency). You can add arbitary plans and API Calls Frequency.

Click Next After adding the required plans.

Click Next with default options.

Click Done. We will publish it separately later after creating catalog.

New product is added with the new API.

Go to API Manager “Manage Settings” to update the email Notification settings.

Go to “Notifications”. Click Edit.

Configure the sender name and email address.

Create Catalog

Now we can create a catalog. One catalog can contain one developer portal where this product can be published. We can have a internal and external catalog where internal catalog is for internal organization and external is for external users.

Go to manage catalogs under API Manager.

Create new Catalog.

Enter a name and Click Create

Open the new Catalog and navigate to Catalog settings.

Create a developer portal here. Click Create. If the email if is not updated for the logged in user account, then there will be an error mentioning so. Update the admin user email id from Cloud Manager -> My Account as explained earlier. Also make sure smtp settings are correct under Cloud Manager notification settings.

Select the portal service as “portal-service” and Click Create.

It will take a few minutes for the portal service to be ready. You will receive an email once its ready to set the password for the portal admin account.

Note down the Portal API URL from Catalog Settings -> Portal . eg.

https://hostname/api-organization/practicum-catalog

(optional) Once you receive the email to set the password click on that link and set the password for the admin account for API Manager.

Publish Product

In the original API Manager Window, Now lets publish the product to the new catalog from API Manager first. So it can be visible in this catalog.

Go to API Manager Home and click Develop APIs and Products. Go to Products Tab. Select the product settings and click Publish.

Select the new catalog.Click Next.

You can set the catalog visibility to Authenticated users. Click Publish.

It will be published shortly.

API Connect Developer Portal

Open the Portal API URL as noted above in the browser.

Note: Use Mozilla Browser only for this as there will be issues with chrome browser with default self-signed certificate settings and chrome will prevent the connection.

Click on Create Account to create a new account.

You will receive email with activation instructions.

The account will be activated and you will be able to login with the newid. Sign in with the new id and password.

Click on Create a new App.

Enter an application Name and click Save.

Once application created successfully, note down the Key and Secret for this application. You can not see the Key and Secret for this application after this page. Each application will interact with API Manager/ACE using this client secret. Click OK.

You can optionally click on verify link to verify your secret against this application’s key.

Click on Why not browse the available APIs to subscribe to API Product for this App.

Click on the published API product.

Just click on the Select button for one of the plan exposed by the product.

Select the application to be subscribed.

To confirm subscription, click Next.

Click Done.

Click on POST / option under overview, in the left pane.

Click on Try It tab to test this API product.

Enter the API Secret for authentication and click Send.

If you receive an error like below, then it could be because you are using any other browser than Firefox. Or the Certificate is not trusted.

Open this URL in the error below in the browser. eg.

https://hostname/api-organization/practicum-catalog/my-account-api/

Accept the certificate. Ignore the error.

Now You can try to send the API call one more time, you should be able to see the response successfully.

Check in the IBM MQ if this message has been stored in Queue Successfully.

Go to Integration Instances -> Messaging instance Name -> Manage -> Queue name

Go to Configuration Index

Go back to -> Table of Contents

Go to next topic -> Conclusion