Tutorials for IBM App Connect

Learn how to create a custom application from an Integration Bus application definition file so that every time a message flow processes a message, details of that message are sent in an email from your Gmail account.

The tutorial uses a pre-built sample application that’s designed to receive notifications from a Warehouse application. The sample application includes an Integration Bus message flow and an application definition file. For details of the sample application, and how you can use the sample application to help you to build your own message flow and application definition file, see iib-app-connect-trigger-pattern.

First, find or create everything you need:

• One of the following IBM Integration Bus deployments:
  • An IBM Integration Bus on Cloud account.
  • IBM Integration Bus Developer edition installed on your local machine.

  This is where we’ll deploy the Integration Bus message flow.

• IBM App Connect subscription (Personal account).
• (If you’re using Integration Bus Developer edition) Use your App Connect account to install and configure the IBM Secure Gateway Client and connect a private network. See Tutorial: Configuring a private network.
• (If you haven’t already connected App Connect to your Gmail account) The name and password of your Gmail account.
• Some means to check and send messages to the Warehouse application (Integration Bus message flow). For example:
  • You can check the flow in your web browser, and can use a REST client to send messages to the Warehouse application.
  • You can use cURL commands.

Next, set up your message flow on IBM Integration Bus on Cloud:

1. Download iib-app-connect-trigger-pattern-master.zip from GitHub and extract all the files into the C:\Warehouse directory.
2. If you’re using Integration Bus on Cloud, complete the following steps:
   1. Log in to IBM Integration Bus on Cloud.
   2. Upload the BAR file that’s in the set of files that you downloaded: C:\Warehouse\iib-app-connect-trigger-pattern-master\WarehouseNewStockEventToAppConnect\Warehouse.bar.
   3. After you’ve uploaded the BAR file, click Save to prepare the integration. When prepared, the status of the Warehouse integration is shown as “Stopped”.
   4. Select the Warehouse integration from the Integrations page.
   5. Click Public Endpoints, make a note of the Service URL, for example: https://da3bnd1c.ibmintegrationbus.ibmcloud.com, and turn off Basic Authentication.

      

   6. Go back to the Integrations view, start the Warehouse application, and refresh the browser until the status is “Running”.
3. If you’re using IBM Integration Bus Developer edition, complete the following steps:
   1. Start the IBM Integration Bus Toolkit.
   2. In the Integration Nodes pane, right-click the integration server, select Deploy, then click BAR from file system.
   3. Select C:\Warehouse\iib-app-connect-trigger-pattern-master\WarehouseNewStockEventToAppConnect\Warehouse.bar and click OK.

Your Integration Bus message flow is now running and waiting for notifications.

Then, configure your application definition file:

1. In the root of the C:\Warehouse directory, make a copy of the following files from the C:\Warehouse\iib-app-connect-trigger-pattern-master\doc\ directory:
   • warehousedefinition.yaml: This is the application definition file.
   • purple_jumper.txt: This is some data that we’ll use to invoke the message flow.
2. Edit C:\Warehouse\warehousedefinition.yaml:
   • If you’re using Integration Bus on Cloud, change host to the Integration Bus on Cloud Service URL (after https:// prefix) and schemes to https.

     

   • If you’re using Integration Bus Developer edition, change host to the Integration Bus host name and port; for example, localhost:7800.

     Note: If your IBM Integration Bus deployment uses SSL, change schemes to https.

     

The application definition file is now configured for your Integration Bus message flow.

Now, create your custom application in App Connect:

1. Log in to App Connect.
2. On the Applications page, click Add your application now.
3. Add an Application name (for example, Warehouse) and a description (for example, Integration Bus Warehouse application).
4. Make sure that the network is set appropriately:
   • If you’re using Integration Bus on Cloud, make sure that the network is set to None.
   • If you’re using Integration Bus Developer edition, make sure that the network is set to the private network that you configured.
5. Browse to the warehousedefinition.yaml file that you edited, click Open, then Apply.

Your custom application is now displayed on the Applications page, and can be selected as a first (source) application in a flow.

Then, create your flow:

1. From the Dashboard, click New > Create an event-driven flow.
2. Complete the following steps. If you navigate away from the flow at any stage, the flow is saved as a draft flow that you can complete at another time.
   1. Select Warehouse as your first application (source).
   2. Select newStock as the Warehouse trigger.
   3. Select Gmail as your second application (target).
   4. Select Create message as the Gmail action.
   5. If you haven’t already connected a Gmail account, click Connect to Gmail and follow the instructions to allow App Connect to connect to your Gmail account.
   6. Set up the Gmail action by completing the following fields.
      • To: Enter an email address (you can enter your own Gmail address or another email address to which you have access).
      • Subject: Type New stock in Warehouse.
      • Body: Populate the Body field by completing the following steps:
        1. Type New Stock: and then click the Insert a reference icon to show all the available source fields in the Warehouse application.
        2. Select id then type a hyphen.
        3. Repeat the previous step but select name, then color, and then size.

        

3. Enter a name that identifies the purpose of your flow, for example: New Stock details, and then click Exit and switch on. Your flow is displayed on your Dashboard and is listening for your event – the processing of a new stock item by the Integration Bus message flow.

Finally, test your flow:

1. Check that App Connect is listening to the Warehouse application.
   • In your web browser, go to https://iib_url/user01/warehouse/stock/hook. For example, for IBM Integration Bus on Cloud:
   • In a command window, change to the C:\Warehouse directory, then run the command: curl -X GET https://iib_url/user01/warehouse/stock/hook

   Where iib_url (the host value that you set in the warehousedefinition.yaml file earlier) depends on whether you’re using Integration Bus on Cloud or Integration Bus Developer edition:

   • Integration Bus on Cloud: iib_url is the Service URL for the public endpoint of the Warehouse application on Integration Bus on Cloud.
   • Integration Bus Developer edition: iib_url is the host name and port for the IIB integration node.

   If the response is [], the Warehouse application has not connected to the Integration Bus message flow.

2. Simulate the addition of new stock to the Warehouse.
   • In a REST client, use a POST action to https://iib_url/drive/newstock with the body set to a copy of the data in C:\Warehouse\purple_jumper.txt. For example (select the image to view at full size):
     
   • In a command prompt, run the command: curl -X POST https://iib_url/drive/newstock --data @purple_jumper.txt

     The data that you sent is displayed in the command window.

3. Go to Gmail and sign in with the Gmail account that you used for Gmail in App Connect. In your Sent folder, you should see the email that was sent via App Connect.
4. Log in to the email account that you entered in the To field of the flow and you should see the email in the inbox of that account.

You’ve created an App Connect custom application from an IBM Integration Bus message flow, and configured a event in the custom application to initiate an action in another application.

You can create flows for an API in IBM App Connect to allow a developer to quickly create an application that uses the data in your applications. For example, you might create flows for an API that update or create customers in your CRM system.

You begin by creating one or more models that define the structure of the data objects that your API will work with. And you define the operations that your API performs against that model, such as creating, updating, or retrieving data. App Connect flows implement those operations. The flow for an API has a request and a response, and one or more applications that contain the data that you’re accessing. Here’s a simple example of a flow for an API that creates a customer in your CRM system (in this case, known as a contact in Salesforce):

The following steps describe how to create flows for an API in App Connect.

1. On the Dashboard, click New, then Create flows for an API.
2. Enter a name for your API at the top of the page; for example, Customer API.
3. Enter a name for your model that reflects the type of object that your API will work with, then click Create model.

   For example, if your API will create and retrieve customer details from a CRM system, you might name it Customer.

4. Add the properties that are required to define the structure of your object that the API will work with.

   For example, if your API will update or retrieve a customer, you might add properties called CustomerID, FirstName, LastName, and EmailAddress. A valid property name has the following characteristics:

   • Each property name must be unique.
   • A property name can’t contain spaces, but you can use an underscore character (_) to separate words.
   • It must contain only letters, numbers, or the underscore character.
   • It must contain at least 2 characters.
   • It must begin with a letter or an underscore.

   You can either type in the name of a property, or click Select properties from applications to choose properties from one or more of the applications that you’re connected to.

   

   Properties of an API to create and retrieve a customer (Salesforce contact)

5. Define the properties:
   • Select Required for the properties that a consumer of your API must supply when they create or update objects.
   • Select ID next to the one property that your flow must return when creating an object or must be sent in a request to update or retrieve an object by using its ID.

     If the property that’s set as the ID is also marked as required, this indicates that your API doesn’t generate IDs automatically when creating objects, and that the user must provide ID values. For example, in the figure above the ID property is not marked as required because the Salesforce “Create contact” action that’s used in the API flow automatically generates the ID value when called by the API.

6. (Optional) You can create more models by clicking Create model. To delete a model, select Delete model from the menu.
7. Click Operations to define how the API will interact with the object. You can add operations to create an object, retrieve an object by using its unique ID, or update or create an object, where the object is updated if it exists, or created if it doesn’t.
8. Add the operations that you need.
9. For each operation, click Implement flow to create a flow that defines how each operation will work.

   You’ll see a basic flow in the flow editor, with a request, a response, and a space to add one or more target applications.

   Select the Request in the flow to see an example of the structure of the request, constructed from the properties in your model, with some sample data.

10. Add one or more target applications to the flow, between the request and response.

    This example uses the Salesforce “Create contact” action.

11. Map the fields from the request into your target application.
12. (Optional) You can also add some conditional logic to your flow. If you want your flow to do different things for different conditions, you can add one or more “IF” nodes to your flow. For more information, see How do I add conditional logic to a flow?
13. Click the Response in the flow to define the response that’ll be returned when the operation has completed successfully. Map the available fields from your target application.

    When you’re creating an object, typically only the ID from the target application will be returned in the response message. If you’re retrieving an object, the response message will show you all the fields that you’ve requested from the target application.

14. Click Done to return to your model.
15. When you’ve defined all your models and operations, start the API by selecting Start API from the menu.
    
16. To test your API, click the Manage tab, then use the URL, Username, and password with your preferred technique to invoke API operations; for example, the Linux command line and curl, the HttpRequester add-on for Firefox, or another utility like Postman.
    
    

    Postman utility used to call an API POST operation to create a Contact in Salesforce (Click the image to view full size.)

    
    Note that the username and Password are set in the request header, and that the request body does not include the API ID property (CustomerID) because that’s set by Salesforce.
    
    

    Postman utility used to call an API GET operation to retrieve a Contact from Salesforce (Click the image to view full size.)

17. To manage your API, click the Manage tab, then click Download API to download your API document, which you can import into your API management tool. We’ve provided the URL, user name, and password that your API management tool will need.

You’ve created your API! On the App Connect dashboard, flows for APIs are identified by the API icon. You can start and stop them in the same way as any other flow. You can open an API while it’s running, but you have to stop it before you can edit it.