Original publish date - 13-10-2017
Authors - Kim Clark, Mark Ketteman

Create an API in IBM App Connect and call it from IBM Business Process Manager 

This article explores how to create an API in App Connect and then create a reusable, external service to call the API in IBM BPM.

When you create a process application, you want to focus on business value, not on the complexity of the underlying technology. With integration, you often must learn details that you'd rather not know about. However, modern cloud-based applications, such as Salesforce, typically come with web-based APIs that intend to make integration easier. Indeed, in recent years, IBM® Business Process Manager (BPM) has made tremendous advances in its support for REST APIs. But, APIs are typically complex to use, with subtle error handling and relatively complex data models. Often developers want a specific and simple use case of an API that is only a small subset of what its full API does. Because IBM BPM enables code-free process creation, you also want to create and extend your connections to external services in a code-free manner, which is where IBM App Connect comes in.

You can consider IBM App Connect as the "cloud connector" for IBM BPM, simplifying interaction with cloud-based applications. By using IBM App Connect, you can compose APIs in a code-free flow designer. You can also provide connectors to a wide range of common software-as-a-service (SaaS) applications, including Salesforce, as used in the example in this tutorial.
This tutorial demonstrates how IBM App Connect can simplify the task of creating a contact with Salesforce. The connectors in IBM App Connect are not just technology connectors. For example, the Salesforce connector is programmed to make a secure connection with Salesforce and manage many common error conditions. It also detects which of the many Salesforce APIs to use to perform all of the common actions and what the common objects are, such as a contact look-alike.
By following the example in this tutorial, you will learn how to use the capabilities of Salesforce in IBM App Connect to perform a code-free implementation of a simplified API for IBM BPM to consume. You also see how to use that API thanks to the REST functions in IBM BPM.

This tutorial has two key tasks. First, you learn how to create an API in App Connect. Second, you create a reusable, external service to call the API in IBM BPM. If you already know how to do the first task, you can skip it and start with the second task to create the external service. 
Try IBM App Connect

Try IBM BPM

Prerequisites

IBM App Connect account
Salesforce developer account

 By having a Salesforce developer account, you can sign in with your IBM App Connect user ID and password to make calls to Salesforce APIs. A Salesforce developer account is not the same as a normal Salesforce user account.

Create an API in App Connect

In this part, you create and expose a simple API to create a contact in Salesforce. The following example shows how this new contact will look in Saleforce when you are done.

This example is the simplest possible API that you can create. Even then, you will see that you can use it to expose a more complex Salesforce API with a much simpler data model. This API also provides a placeholder so that you can add more sophisticated capabilities to it later. Before you begin, log in to your Salesforce account.

1. Log in to IBM App Connect from the home page. You see a dashboard of your integrations. If you are using App Connect for the first time, your dashboard will be empty.
2. Click New. You see two options:
   Event-driven flow. Your integration uses its built-in connectors to listen to a source of events (such as adding new customers to a campaign in Marketo) and runs the flow each time that an event occurs.
   Create flows for an API. The flow exposes itself as an API and waits for a consuming application to start it.
3. To implement the API, select Create flows for an API.
   
   

   The event-driven flow and API flow options

   Similarities in flows. The underlying flow in this example looks similar to an event-driven flow and uses the same visual tools, such as the flow editor, connectors, and data map. However, the flow has some subtle differences. For example, in an event-driven flow, you must first configure a connector to the triggering application. The initial data model is enforced by the shape of that triggering event. Also, a notion of a "response" does not exist because the whole flow is asynchronous. Also, no "caller" is waiting for a response from the flow. In this example, where you create an API, you can define the shape of the data that the API will use for the request and response (the "model"). Then, the flow will finish with a "response" to the caller.

4. To expose an API, determine how you want the request data for the API to look. You can enter the request model manually by using the following simple form.
   
   
   Create the API data model
   
   

   In many cases, it makes sense to base the API on one of the systems that you will call during the flow. In this case, that system is Salesforce.

5.  Click Select properties from applications, select Salesforce, and choose the field definitions from there. 

6. Decide which actions you want the API to perform. In this example, you want to create a contact in Salesforce. Click Create contact. Later, you will add the Retrieve contact by ID option and the Replace or create contact option.
   
   
   Choosing the operation you want to implement
   
   

7. Click Implement flow.
   

   
   Implementing a flow
   
   

   You now see a basic flow diagram with a request and a response step, and a plus sign (+) so that you can add more actions in the flow.
   

   

    Basic flow diagram showing an example request object
   
   

   You also see an example of the JSON that a caller of the API must provide.

8. Set up the next action—a call to Salesforce to create a new contact—that the flow will perform:

• a. Click the + sign to see the list of applications that App Connect can connect to.

• b. Scroll down, and click Salesforce. You now see a list of actions that you can perform on Salesforce.

• c. Click Create Contact. Be careful not to select the "Create Contract" option, which is a different action.
  

  
  Choosing Create Contact on Salesforce
  
  

• d. In the form that shows the data fields that you can send to a Create Contact on Salesforce, populate these fields with data from the request model that you created earlier. If you use similar names, you can click Auto match fields to pre-populate the form automatically. If you scroll down, you see that the relevant fields are populated.
  

  
  The form with data to send to Salesforce
  
  

  If the objects you are mapping from have different names, you can manually map them. You'll see an example of manual mapping later when you prepare the response data. At the top of the list, you see the Account ID field in Salesforce to which the Id field from the request model is automapped.
  

  
  The automapped Contact ID field
  
  

• e. Leave the Account ID field blank on the Create Contact step because, in this example, the caller of the API does not have an Account ID. Salesforce creates the Account ID and returns it to you.
  

  
  Cleared ID field so that it is populated in the Create Contact step in Salesforce
  
  

  Flow editor features.
  We chose a simple flow so that you can complete this section and move onto the configuration in IBM BPM as quickly as possible. However, keep in mind that the flow editor has many more features. You can include conditional steps, and perform multiple actions to many different applications.

• f. Click Response and decide how you want the response to look. As mentioned previously, Salesforce creates the Account ID during the "Create Contact" action. Therefore, map the Account ID data back into the response. 

• g. Click the list icon to the right of the Id field to display the References list. From this list, you can map data from any part of the preceding flow. In this example, you can get data from the original request or from the response you received from the Create Contact we performed on Salesforce. Choose the Contact ID from the response from Salesforce.
  

  
  Mapping the response from Salesforce
  
  

  If you click the fx icon to the right of the ID field, you can perform more sophisticated actions to create the data to map into the field. This level of detail goes beyond the purpose of this tutorial.
  

  
  Mapping the Contact ID from the response from Salesforce
  
  

9. Click Manage to see the information that is available. You don't need this information yet, but you will need to know where to find it later.
   

   
   Manage tab showing information for an API caller
   
   

   On this page, the Download API button downloads the API definition, which the calling applications (IBM BPM in this tutorial) will need. IBM App Connect uses the industry standard Open API Specification format, which is formally known as Swagger.
   By default, APIs are always set up with a basic authentication mechanism, such as https and user credentials. If many applications will reuse an API, the API requires a more sophisticated gateway, which is the Manage API with IBM API Connect button. You can use this button to add more security, such as OAuth, and perform traffic management to control the throughput of requests to the API to protect downstream systems.
   You can also set up different API usage plans. IBM API Connect also provides a developer portal that you can immediately use to explore how to use the API, self-administer the plans that you want to use, and monitor your use with customizable analytics. You can even monetize the API by charging different amounts for each plan.
   For security reasons, the API definition file doesn't include the URL, user name, and password that are needed by anyone who calls this API. This information is provided separately on the page with a simple mechanism to copy them to the clipboard.

10. Enter a name for the API that you will use in the dashboard. You can add this name any time during the flow creation. Click Done to return to the dashboard. On the dashboard, you see the new flow as an icon summary, which indicates that it is an API (rather than an event-driven flow) and connects to Salesforce. The API defaults to the Stopped state.

11. Click the More actions (three dots) icon to the right of the flow, and then click Start API.
    

    
    Starting the API

You now have a secured but publicly available API that is ready for use in any application that has the credentials. 

Create an external service configuration in IBM BPM

Now, you use the API that you created in IBM App Connect within a process in IBM BPM. You set it up so that it is easier to reuse in multiple parts of a process and other process applications.

This tutorial is written for users who are newer to IBM App Connect but who are familiar with IBM BPM. Therefore, the details in this section focus on how you set up connectivity to IBM App Connect.

To connect to any API from IBM BPM, you must create an External Service in IBM BPM. An external service defines operations, their input and output data, and a server configuration that contains information about how to connect to the host server. In this tutorial, the server definition holds connectivity detail for the API on IBM App Connect (URL, port, credentials, and so on).
You can change these details at run time when the process moves through the various environments, such as test, staging, and production. An administrator can change the server definition—for example, if the endpoint URL is different—at run time. In this section, you create an external service to hold the operations, inputs and outputs, and server configuration of the REST API that you created in App Connect: 

1. Log in to IBM BPM Web Process Designer.
2. Create a Process Application or Toolkit.
3. Create an external service. Select Services-> External Service.
   
   
   
   Create an external service
   
   
4. Select Java, REST, or Web Service to discover the REST API.
5. Back on the IBM App Connect Manage page, download the API definition to your local storage. The API definition file is a YAML file that uses the OpenAPI 2.0 specification, which is often called a Swagger document.
6. Rename the downloaded YAML file from the hard disk drive with a logical name for the external service, such as 'Salesforce New Contact'.
7. On the next page, select the operation. In this example, you created only one operation in IBM App Connect. If you implemented a full suite of operations, you will see them here.
8. When prompted by IBM BPM, create a new server.
   Server configuration.
   The use of server in this step refers to a server configuration, not to the creation of a new BPM server. It is more like a binding definition to hold the credentials and URL for this particular external service. The name comes from the fact that the early binding credentials were to external "servers," such as IBM Operational Decision Manager (ODM) and Content Management. IBM BPM prefills a name that is based on the name of your external service. Through this server concept, you can set up various settings based on different environments, for example: separating API URLs and credentials for development, test, and production. Managing the separate API implementation versions in IBM App Connect is another area where IBM API Connect can help. You can control which API implementations that each version routes to and control who has access to each.
9. To see the definitions of your external service in IBM BPM, expand Operations, Input, and Output. IBM BPM automatically creates the Business Object artifacts that correspond to the JSON structures that are described in the YAML file of the API.
10. Select the top-level name of the external service, and click Binding. The binding (server) definition of the external service opens.
    
    
    Exploring the definition of the external service
    
    
11. Add the credentials for the API here. From the Manage tab in App Connect, populate the default credentials (copy them to the clipboard).
    (For security reasons, these credentials aren't in the swagger definition file.)
12. Create a BPM Service Flow (a flow with no human interaction) to house the integration. You can place this flow in a toolkit and reuse it in multiple applications.
13. Add a service task, and wire it from the start node to the end node.
• a. On the Implementation tab, select the external service and operation that you created previously to provide the calling mechanism for the API.
  
  
  Service flow with a service task activity that uses the external service
  
  
• b. On the Data Mapping tab, set IBM BPM to auto-create variables for the inputs and outputs of the service flow that is based on the API definition.
  
  
  Map the data to and from the external service call
  
  
• c. On the Variables tab for the service flow, expand the input variable. Click Has Default, and enter the first name, last name, and email address.
  
  
  Enter the test data into the default value of the input object
  
  
14. Test it. Click debug, and then click play. The new Salesforce Contact Id is returned and visible in the debugger.
    
    
    New Salesforce Id created and visible in the debugger after a test

The result is visible in the Salesforce user interface.

Conclusion

In this tutorial, you learned how to simplify interaction between IBM App Connect and IBM BPM with Salesforce. You can then expand this simplified API to provide more sophisticated functions with Salesforce or to enrich the data with information from other applications. For example, you can ensure that you do not create duplicates in Salesforce. You can create a new contact in other systems. Or, you can send notifications by email or SaaS tools, such as Slack, to inform your team that you created a new contact. The possibilities are endless. 
To see the art of the possible with IBM App Connect, see the videos on the Big Blue Helps YouTube channel.
IBM App Connect
IBM App Connect Enterprise