Authors (alphabetically): 
Daniel Berglie (Celeste Digital)
Ivo Šalković (IBM)
Martin Štepanek (IBM)
Johan Thole (IBM)

Reviewer:
Kim Clark (IBM)

Table of Contents

Abstract
Designing an integration flow in ACE Designer

• Configuring connectors and using them in Designer flows

Deploying an App Connect Designer flow - the standard way

• Creating configurations for the runtime
  • Creating an Accounts configuration
  • Creating a BarAuth configuration
• Creating an integration runtime

Deploying an App Connect Designer flow - the automated way

• Generating an App Connect aaS Access Token
• Creating configurations for the runtime
• Creating the integration runtime

Conclusion
References
APPENDIX A: Creating an access token for your GitHub repository
APPENDIX B: How to authenticate and connect to the IBM App Connect Enterprise as a Service API

• Getting the credentials
• Using these credentials to get an access token
• Using the access token in API calls

Abstract

App Connect is IBM’s integration solution used to integrate different applications and systems, supported by numerous (200+) prebuilt connectors and best practice integration templates.
App Connect provides two different user interfaces for building integrations. The “Toolkit” interface has been used by deep integration specialists for decades to create advanced integrations, and there is already material on how to automate the deployment of integrations created in this way. The other user interface is known as “Designer”, and it is specifically designed to make it possible for non-specialists to build and deploy integration solutions with App Connect. However, since this interface is targeted at the less specialist user, there is less documentation on how to incorporate Designer built flows into automation pipelines. With automation and gitops being the standard in today’s IT development and operations, we also wanted to explore the options for using App Connect’s Designer user interface with automation and gitops in mind.

In the following article, we will first show what it means to design and deploy App Connect Designer integration flows manually. After that, we will show how it could be integrated with git and scripting, so that we could version our code and configurations and automatically deploy them.

We are also providing code examples, so that our readers can test this approach and reuse it.

Designing an integration flow in ACE Designer

Before we start, we must clarify two perspectives available in the App Connect Designer tool:

• There is the App Connect Designer interface, which you use to develop and test your designer flows. 
• There is the App Connect Dashboard, which you use to deploy and manage your integration runtimes.

Both are accessible from the Web interface:

Figure 1: App Connect Designer and Dashboard perspectives

Configuring connectors and using them in Designer flows

This document assumes that the reader knows how to create Designer flows in the App Connect Designer interface, so the required steps will only be covered at high level. We will use the example of a flow built to integrate with Cloudant which will enable us to discuss how to handle credentials in your deployment. You could of course use any flow you like to follow the example and the concepts would be the same.

To connect to an external service, we must first configure the connector in the Catalog. In this example, IBM Cloudant is used (please note: Cloudant is a premium connector):

Figure 2: Configuring IBM Cloudant connector

To connect to the service, we need to know its credential information. In the case of IBM Cloudant:

Figure 3: Cloudant connection information

Once the connector is configured, we can use it within the Designer, for our integration flows, which we will create.

Next, we need to configure an App Connect Designer flow to use this connection in the runtime deployment.

As an example, a screenshot is provided of a simple Designer flow that uses the IBM Cloudant connector. Creating and testing of the flows is outside the scope of this document.

Figure 4: Example Cloudant service API

Figure 5: Example App Connect Designer flow, which uses Cloudant service

Once developing and testing of the flow in the Designer has finished, we can export the developed artifacts. In the App Connect Designer, we need to select our flow and click “Export”:

Figure 6: Exporting developed artifacts from the App Connect Designer

There are three export options:

• Exporting the source as a YAML file.
• Export the artifacts as a BAR file for deployment in an App Connect runtime.
• Export an archive containing the BAR file and the OpenAPI document (for flows exposing an API).

Since our goal in the next step is to deploy the flow, we must select “Runtime flow asset (BAR)” and click the “Export” button.

Figure 7: Selecting which artifacts to export

In this document, we will assume that the BAR file has been exported and stored in a private GitHub repository, and this step will not be described.

Up to this point, there is no difference in approach – both with standard deployment and automated deployment, we must first create an integration flow.
Now, we will explore two different approaches – first, the standard way of deployment using the App Connect Dashboard, and second, an automated way of deployment, using API and scripting.

Deploying an App Connect Designer flow – the standard way

Creating configurations for the runtime

To specify the connection details, credentials and other configurations for our flow, we must create appropriate configuration assets in the App Connect dashboard. These configurations are then referenced and used when we create an integration runtime. Configurations also allow us to separate the configuration, which depends on the environment, from the source code. In this way, we can easily prepare different configurations, and reference an appropriate one, depending on the environment to which we are deploying our runtime.

In this example, we decided to define two "Configurations":

• One of type “Accounts”, which will define connection and authentication details for the Cloudant database.
• One of type “BarAuth”, which will be used to define the credentials required to download the BAR file from a secured repository (in our case, GitHub).

Creating an Accounts configuration

The screenshot below shows how to add the IBM Cloudant account to a configuration. It’s very important to use the same account name as specified when creating your Designer flows.

Figure 8: Creating an "Accounts" configuration

Creating a BarAuth configuration

When creating a runtime, you need at least to specify a BAR file and a configuration. The BAR file can be uploaded manually, or the dashboard can retrieve it using a BAR file URL. In the second case, you also need to create a BarAuth configuration (if your repository requires authentication).

Here is an example of a BarAuth configuration, for connecting to GitHub using the git username and a generated access token:

Figure 9: Creating a "BarAuth" configuration

Creating an integration runtime

To create an integration runtime manually, you need to supply the following information:

• The BAR file location.
• The Accounts configuration (containing the accounts needed by the connectors).
• The BarAuth configuration (containing the credentials for retrieving the BAR file).

For the runtime creation, we use the following parameters:

To create an integration runtime manually, we follow these steps:

Figure 10: Manual deployment - creating the runtime

1. Click Deploy integrations
   Here you can specify the resources you want to deploy (you can change this later):
   
   
   

   Figure 11: Manual deployment - selecting runtime size

   
   In this case, we will deploy a small integration server.

2. Select the configurations that the integration server needs and which we have created previously:
   
   
   

   Figure 12: Manual deployment - selecting the configurations to use in deployment

   In this case, we select the Accounts configuration (containing the connector authentication details) and the BarAuth configuration (containing the credentials for pulling the BAR file).

3. Specify the BAR file location, and other properties (like the number of replicas).
   
   
   

   Figure 13: Manual deployment - specifying the BAR URL
   
   

4. Click the “Create” button to create the runtime. It will take some time before the runtime is deployed. The dashboard is not automatically updated, so you will have to refresh the browser page to see the latest status. After the server with the flow has been deployed, you will see that it is in the “Ready” status.
   
                                                      Runtimes
   
   

   Figure 14: Waiting for the deployment process to finish and server to become "Ready"

Deploying an App Connect Designer flow – the automated way

In the previous steps, we have created the Accounts configuration for IBM Cloudant and the BarAuth configuration to connect to GitHub manually in the App Connect Dashboard UI. Now, we will do the same using the IBM App Connect Enterprise as a Service REST API. The description and the OpenAPI document can be found in the documentation:
https://www.ibm.com/docs/en/app-connect/saas?topic=overview-openapi-document

Generating an App Connect aaS Access Token

Before we can use the App Connect aaS API, we must generate an Access Token, which we have to use with each API call, to authenticate. The process of obtaining and using an Access Token is described in APPENDIX B: How to authenticate and connect to the IBM App Connect Enterprise as a Service API. Please follow those instructions before proceeding.

Creating configurations for the runtime

We will be using the PUT operation for the configuration objects:
/api/v1/configurations/{configuration}

This operation allows us to replace or create a configuration object with a specific name.

First, we will create the Account configuration for IBM Cloudant. We need to specify a configuration object with all the information we previously used in the App Connect Dashboard UI.

For reference, see the details in the documentation:

https://www.ibm.com/docs/en/app-connect/containers_cd?topic=types-accounts-type#certc_configaccounts__localconn_about

In our case, the object for the IBM Cloudant Account configuration will look something like this:

accounts:
  cloudantdb:
    - name: Account 1
      credentials:
        username: 8461a90…078aca2-bluemix
        password: 2692f9a…97fb462643565b8dfd6
        apiKey: JkPQ8xnH…xxG1MX5lQjpfiEmLIwIS8v5D9OHgA67gXu
      endpoint:
        url: >-
          1261a990-0234-423d-a81b-abd2f078bcf2-bluemix.cloudantnosqldb.appdomain.cloud

Use the same values you used for the IBM Cloudant account when developing the flow in App Connect Designer.

Next, to use this object in the API call, we must Base64-encode. Find more information in the documentation here:
https://www.ibm.com/docs/en/app-connect/containers_cd?topic=resources-configuration-reference#install__install_cli__title__1

We will use this Base64 encoded value as a "data" element in the body of the API call. The result should look something like this:

{
  "metadata": {
    "name": "ibm-t3-accounts"
  },
  "spec": {
    "type": "accounts",
    "data": "encoded_data”
    "description": "Configuration to connect to IBM Cloudant"
  }
}

Save this as a JSON file. We will reference it in the API call. The cURL command for calling the API will look like this:

curl --request PUT \
  --url https://yourAceUrlHere/api/v1/configurations/ibm-t3-accounts \
  --header "Authorization: Bearer YourBearerTokenHere" \
  --header 'X-IBM-Client-Id: YourClientIdHere \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '@YourJsonFileHere.json'

Note: Beware that there's a path parameter that defines the name of the configuration object in the URL. It is the same name that we use in the metadata.name value in the JSON file. If a configuration object with this name already exists, this API call will replace it.

Similarly, we need to create the BarAuth configuration to connect to GitHub, where our BAR file is stored. Use the BarAuth you used for the first part of this guide. It will look something like this:

{“authType”:“BASIC_AUTH”,“credentials”:{“username”:“my_testuser”,“password”:“ghp_FkNAEHDht0Up2A81OJ3RGGPmMwuyYy1IYnCh”}}

Again, Base64-encode it. Create a new JSON file and use this encoded value as a "data" element. The result should look something like this:

{
  "metadata": {
    "name": "ibm-t3-github-barauth"
  },
  "spec": {
    "type": "barauth",
    "data": "encoded_data",
    "description": "Barauth configuration for basic authentication to retrieve BAR from GitHub"
  }
}

Use this file in the API call to create the configuration:

curl --request PUT \
  --url https://yourAceUrlHere/api/v1/configurations/ibm-t3-github-barauth \
  --header "Authorization: Bearer YourBearerTokenHere" \
  --header 'X-IBM-Client-Id: YourClientIdHere \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '@YourJsonFileHere.json'

Note: Beware that there's a path parameter that defines the name of the configuration object. It is the same name that we use in the metadata.name value in the JSON file. If a configuration object with this name already exists, this API call will replace it.

Now we have everything ready to create the Integration Runtime to run our integration flow.

Creating the Integration Runtime

Similarly to the configuration object, we will be using the PUT operation for the Integration Runtime object:

/api/v1/integration-runtimes/{integration-runtime}

This operation allows us to replace the integration runtime with the specified name if it exists or create an integration runtime with the specified name if it doesn't exist.

First, create a JSON file to specify details about the Integration Runtime we're about to create. It will look something like this:

{
  "metadata": {
    "name": "ibm-t3-integration-server"
  },
  "spec": {
    "barURL": [
      "https://raw.githubusercontent.com/...JTH-Customer-API.bar?token=GHSAT0AAWBCRO6PW4TJZFV972UR12ZRKEXUQ"
    ],
    "configurations": [
      "ibm-t3-accounts",
      "ibm-t3-github-barauth"
    ],
    "forceFlowBasicAuth": {
      "enabled": false
    },
    "replicas": 1,
    "template": {
      "spec": {
        "containers": [
          {
            "name": "runtime",
            "resources": {
              "limits": {
                "cpu": "1000m",
                "memory": "2048Mi"
              }
            }
          }
        ]
      }
    }
  }
}

Change the following parameters with your values:

metadata.name – choose a name for your Integration Runtime. We will use the same name in the API call later.

spec.barURL: RAW link to the BAR file in your GitHub repository.

spec.configuration: link the configurations you created in the previous step.

You can optionally change other values as well. For a complete list of possible parameters, check the OpenAPI document in the documentation from the link above.

curl --request PUT \
  --url https://YourAceUrlHere/api/v1/integration-runtimes/ibm-t3-integration-server \
  --header "Authorization: Bearer YourBearerTokenHere" \
  --header 'X-IBM-Client-Id: YourClientIdHere \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '@YourJsonFileHere.json'

Note: Beware that there's a path parameter that defines the name of the Integration Runtime. It is the same name that we use in the metadata.name value in the JSON file. If an Integration Runtime with this name already exists, this API call will replace it. You can use this call to subsequently change the configuration of the Integration Runtime - for example, to add more replicas, more computation power, etc.

That's it, your Integration Server should be up and running – check your App Connect Dashboard UI and wait for it to come online.

Since we want to automate as much as possible, we have created a script which implements all the steps described above in one connected unit. The only thing needed is to enter your parameters and to run it.

The script and other template files (configurations, server runtime, sample BAR file) can be found here:

https://github.com/isalkovic/App Connect_Designer_PoC

Conclusion

App Connect Designer is a powerful and easy to use tool, where integrations are designed and deployed in a simple way. Because it is trying to simplify things so much, it is lacking in capabilities like versioning, automation and management, which may be important for some users. Some of these deficiencies can be made up for by using external tooling like:

• Git – for code versioning and deployment artifacts repository.
• Shell scripting – to automate and connect repetitive manual tasks and eliminate mistakes.
• Automation platforms like Tekton or Jenkins – to run build and deploy scripts in a consistent way, with auditable history and repeatability.

References

App Connect aaS OpenAPI: 
https://www.ibm.com/docs/en/app-connect/saas?topic=overview-openapi-document

GitHub repo with example code used for this article:
https://github.com/isalkovic/ACE_Designer_PoC

APPENDIX A: Creating an access token for your GitHub repository

In order to access the BAR file, which was stored in a private GitHub repository, we need to enable access to the repository by creating an access token. We can follow the next steps to generate the token. 

In the GitHub repository UI, navigate to “Settings”, and choose “Developer settings”.
In the “Developer Settings”, select “Personal Access tokens - Tokens (classic)”:

Figure 15: Generating new access token on GitHub

Click “Generate new token” and fill out the details (like the OAuth scopes), with at least Read permissions to the repository files.

Figure 16: Generating new access token on GitHub - continued

Copy the generated access token and store it securely, as you cannot retrieve it anymore later.

For the rest of the manual deployment chapter, we must switch to the App Connect dashboard perspective.
 

APPENDIX B: How to authenticate and connect to the IBM App Connect Enterprise as a Service API

The first step to connect to the API is to generate an access token. For this we will need to supply a client Id, a client Secret, and an API key.

Documentation: https://www.ibm.com/docs/en/app-connect/saas?topic=overview-accessing-api#apikey__title__1

Getting the credentials

Let’s start with the id and secret: in the IBM App Connect Designer, navigate to the settings tab (1), Public API credentials (2), and click Generate (3).

Give your credentials a good name for reference, then continue. Once generated, make sure to store these credentials in a safe place, as they will only be displayed once.

For the API key: in the IBM App Connect Designer, navigate to your profile picture at the top right and go to “Service IDs and API keys”.

Click on Generate Key, give it a name for your own reference and hit generate.

The key will only be visible for a limited time and cannot be viewed again after the window is closed. Make sure to store the key in a safe space.

Using these credentials to get an access token

We will now construct a cURL request that we can paste into a Mac Terminal or for example a Windows Git Bash Terminal. We can also translate this command to Postman for a more graphical interface. We will need the same information regardless of how you send the request.

curl --request POST \
  --url
https://api.region.appconnect.automation.ibm.com/api/v1/tokens \
  --header 'X-IBM-Client-Id: clientId' \
  --header 'X-IBM-Client-Secret: clientSecret' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-ibm-instance-id: appConnectInstanceId' \
  --data '{
  "apiKey": "myapikey"
}'

The bolded words will need to be filled in.

Region can be found in the URL of your App Designer or in the documentation:

https://www.ibm.com/docs/en/app-connect/saas?topic=information-api-overview#aas_api__endpoints__title__1

clientId and clientSecret come from the clientId and clientSecret we generated previously.

The appConnectInstanceId can also be found in the URL, it is the first 9 characters:

Myapikey is the API key we generated in the previous step.

The end result will look something like this:

curl --request POST \
--url https: //api.p-fra-c1.appconnect.automation.ibm.com/api/v1/tokens \
--header 'X-IBM-Client-Id: 1451fffs2348294dd' \
--header 'X-IBM-Client-Secret: ee5555hhh23423423fff' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-ibm-instance-id: vnna766ye' \
--data '{
"apiKey": "P42BS74ycKdjgbXww7A2WgYq-SGhw9pX9knxR9rDRmXzusd4fxm4vq_JJZyz_HJW3xQX8aOpznACq7GU33M7eeRdVO"
}'

In Postman, the request headers would look like this:

And the Postman body (green) should look like:

Using the Access token in API calls

To use any of the calls from the API -  https://www.ibm.com/docs/en/app-connect/saas?topic=overview-openapi-document

In Postman, on the API call you want to invoke:

In Authorization (1), select bearer token (2) and paste in your access key (3).

In the header, you will also need to add your client id (2) and your instance id (3, the 9 characters at the start of your designer URL from the credentials step).

x-ibm-client-id
x-ibm-instance-id

You will need to do these steps for all API calls.
You are now equipped with all you need to use the IBM App Connect API.