Create a contact in Salesforce as part of your business process
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.
- IBM App Connect
- Salesforce developer
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.
- 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.
- Click New. You see two options:
- Event-driven flow. Your integration uses its
built-in connectors to listen to a source of events (such
adding as 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
- Event-driven flow. Your integration uses its
- To implement the API, select Create flows for an API.
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.
- 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.
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
- Click Select properties from applications, select
Salesforce, and choose the field definitions from
- 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.
- Click Implement 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
You also see an example of the JSON that a caller of the API must
- Set up the next action—a call to Salesforce to create a new
contact—that the flow will perform:
- Click the + sign to see the list of
applications that App Connect can connect to.
- Scroll down, and click Salesforce. You now
see a list of actions that you can perform on Salesforce.
- Click Create Contact. Be careful not
to select the “Create Contract” option, which is a different
- 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
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
- 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
- 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.
- 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.
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.
- Click the + sign to see the list of
- 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.
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
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.
- 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.
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
- Click the More actions (three dots) icon to the right
of the flow, and then click Start 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:
- Log in to IBM BPM Web Process Designer.
- Create a Process Application or Toolkit.
- Create an external service. Select Services-> External
- Select Java, REST, or Web
Service to discover the REST API.
- 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
- Rename the downloaded YAML file from the hard disk drive with a logical
name for the external service, such as
- 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.
- When prompted by IBM BPM, create a new 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.
- 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.
- Select the top-level name of the external service, and click
Binding. The binding (server) definition of the
external service opens.
- 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.)
- 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
- Add a service task, and wire it from the start node to the end
- On the Implementation tab, select the
external service and
operation that you created previously to
provide the calling mechanism for the API.
- 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.
- 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.
- On the Implementation tab, select the
- Test it. Click debug, and then click
play. The new Salesforce Contact Id is returned
and visible in the debugger.
The result is visible in the Salesforce user interface.
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 Integrate Watson and Salesforce with IBM App Connect video.