In this article, I describe how to expose CRUD operations on Salesforce objects using a newly defined REST API in IBM Integration Bus by using new capability delivered in IBM Application Integration Suite 1.0. This fixpack contains many new features which include:
- Enhancements to the REST API Editor so that a REST API can be created from scratch.
- Enhancements to the Graphical Data Mapping capability so that model definitions can come from a Swagger document or a JSON schema.
- A Salesforce Request node which allows connectivity with Salesforce so that records can be created, retrieved, updated or deleted for Salesforce objects such as Accounts, Contacts and Leads.
Salesforce is a leading CRM software and enterprise cloud ecosystem. By using the Salesforce Request node, you can integrate your business critical applications in your organization with Salesforce. For example, you can synchronize your master list of customers, products, prices and other business critical data with your key applications. Salesforce has many different type of objects such as Accounts, Contacts, Leads and Opportunities. By using IBM Integration Bus, you can develop message flows to interact with these Salesforce objects and with a host of other service endpoints such as SAP and Oracle.
This article will show how these three new features can be used together to receive message data, transform it and send it to Salesforce. I will describe the steps to define a REST API which allows you to create, retrieve, update and delete a Salesforce Contact. The scenario will show how to quickly create a new REST API, transform the message that is received using the graphical mapping capability and send the message to Salesforce using the Salesforce Request node.
If you want to use the Salesforce Request node you need to purchase IBM Integration Bus as part of the IBM Application Integration Suite bundle. You can use the Salesforce Request node in
developer mode while you are developing and testing your flows, but you cannot deploy the flow into a production environment until you have modified the integration node to run in
applicationIntegrationSuite mode. You do this by running mqsimode:
mqsimode integrationNodeName –o applicationIntegrationSuite
In order to connect to Salesforce from IBM Integration Bus, you need to create a Salesforce Connected App.
Fill in the following:
- Connected App Name (you can call it IBM Integration Bus)
- API Name
- Contact Email
- Callback URL (Set the Callback URL to any valid secure URL. The URL will not be used by your IBM Integration Bus Connected App).
- Select Enable OAuth Settings
- Choose Full access (full) from Available OAuth Scopes
The security token will have been sent to your email address. Now, you have the information needed to connect to Salesforce:
- Salesforce Userid
- Salesforce Password
- Security Token
- Consumer Key
- Consumer Secret
You need to create a security identity for the Salesforce credentials which are stored using mqsisetdbparms. The password must be suffixed with the security token that was supplied to you by Salesforce. You should create the security identity by running mqsisetdbparms like this:
Now that you have your security credentials set up, you can create a REST API to expose CRUD operations on Salesforce objects. There is a link from Quick Starts in the toolkit, or you can select File -> New -> REST API
Each operation will be implemented by a subflow. You can change post1, get1, put1 and delete1 to use more meaningful names which will form the name of the subflow. For example, you could change them to createContact, getContactById, updateContactById and deleteContactById.
Next, you create a new model definition which is used by the Request and Response body for each REST API operation. Define a model called ContactDetails which is a JSON object and contains three children: Forename, Surname and Area, each of which are JSON strings as follows:
Now you need to add a mapping node to the subflow so that the flow can transform the REST request message that is received to a format that is understood by Salesforce.
In IBM Integration Bus v10.0.0.4, sample JSON schemas have been provided for Salesforce objects in install_dir/server/sample/Salesforce directory, where install_dir is the directory in which you installed IBM Integration Bus. The relevant schema can be imported into your application or shared library so that you can use it as the input or output message map in a Mapping node.
The JSON schema must reside in either a REST API or in a shared library.
You are going to use the swagger.json for the input message map and the Contact.json as the output message map in the map used by the Mapping node. Select the Mapping node from the Transformation drawer and drag and drop it onto the flow editor:
To configure the mapping node, double click on it. You will see a dialog showing that you can map the input and output for a REST API operation. This is a new option that has been provided in 10.0.0.4:
After clicking Finish, you see the initial map that is created. If you expand JSON and then Data on the Input map you can see the ContactDetails data type that you defined. The output message body for the operation is currently BLOB as the operation had no response body data defined for it.
The map is created with the output for directly building the REST API response, however in our case we first need to invoke the salesforce request node, so we will adjust the output to provide the JSON data required. You need to delete the output message assembly that was created and replace it with the message map for Contact.json. Simply click on the output Message Assembly and click Delete. Now click on the “Add an output object” button, select Contact.json and click OK.
You have now defined the transformation for the REST API request message to be transformed into a format which is compatible with Salesforce.
- The Salesforce URL is the url of the external Salesforce system to which you are connecting.
- The Operation can be one of Create, Retrieve, Update or Delete.
- The Salesforce object can be chosen from a list of objects or a custom object name can be specified. Here, we choose Contact.
- The security identity is the value that was used when storing the Salesforce credentials using mqsisetdbparms. Here we have specified SF1.
- The timeout value is in milliseconds. This is the time that Salesforce Request node waits for a response to be received from Salesforce.
It is possible to override node properties so that they are set dynamically while the flow is running. The values are set under the LocalEnvironment.Destination.Salesforce.Request subtree.
You have now implemented the createContact POST operation in the subflow. The subflow does the following:
- Receives the REST request for the createContact POST operation
- Transforms the message so that it is in the correct format for Salesforce to process.
- Sends the message to Salesforce.
- Receives a response message from Salesforce. The response message contains the same data as the input message that was sent to Salesforce, augmented with the Salesforce ID for that newly created object.
- Returns the response message to the originating client who sent the createContact request.
After deploying the REST API, you can administer the REST API in the IBM Integration Bus Web User Interface. By clicking on the REST API and then selecting the API tab, you can see details for the REST API. It shows that the createContact operation has been implemented but the other operations have not been implemented yet. It also provides a link to the swagger.json file which was generated automatically for the REST API.
If you copy the REST API Definitions URL http://localhost:7800/Demo/v1/swagger.json and paste it into a swagger.io, you can send in a request message. You will need to configure the HTTP listeners for your integration server so that they respond to and permit cross-origin requests from a web browser. This can be done by running this command:
mqsichangeproperties integrationNodeName -e integrationServerName -o HTTPConnector -n corsEnabled -v true
Operations for retrieving a contact, updating a contact or deleting a contact can be implemented in a similar way.
I have demonstrated new features that have been added in IBM Integration Bus v10.0.0.4. The Salesforce Request node allows you to interact with Salesforce through a message flow. This opens up the possibility of connecting Salesforce with many other endpoints using different transports. The REST API Editor has been enhanced so that you can define a REST API from scratch without needing an existing Swagger document. The Editor will generate a Swagger document for you. The Graphical Data Mapper has been extended so that JSON data types can be modelled using a JSON schema or a Swagger document. I have shown that these three features can be used together if required to access Salesforce through a REST API.
Note: All company, product, or service names may be trademarks or service marks of other companies.