Sharing data and processing from on-premises activities with on-cloud SaaS applications, by using an on-cloud callable flow

Configure the integration server to connect callable flows:

In this section we use App Connect on IBM Cloud to configure callable flows, to enable secure connectivity between flows running in App Connect on IBM Cloud and in the integration server in your on-premises App Connect Enterprise.

1. Sign in to IBM App Connect on IBM Cloud.
2. On the Dashboard, click the Callable flows icon
3. Click Connect callable flows.

   

   (Click image to view full size.)

   This opens the Synchronize your on-premises agent dialog.

   

   (Click image to view full size.)

4. Click Download the configuration; this opens a dialog to save the agentx.json file.

   Leave the Synchronize your on-premises agent dialog open (note the dialog contains instructions for installing the agent into the work directory of the integration server in App Connect Enterprise).

5. After saving the agentx.json file, copy the file to the work directory of the integration server in App Connect Enterprise: workdirectory/config/iibswitch/agentx
6. In your on-premises ACE software, if the integration server is not running, start it; for example, in the toolkit right-click the server and then click Start, or in the console run the IntegrationServer command like the following example:

   IntegrationServer --name myServer --work-dir c:\myaceworkdir\myServer

   Check the console log (To view in the toolkit, you might need to Refresh the server entry under Independent Resources.) You should see messages that indicate ...The integration server component 'agentx' has been started; for example:

   component starting: "agentx"
   Starting agentx with config folder: 'C:\Users\IANLarner\IBM\ACET11\workspace\myServer\config\iibswitch\agentx'
   2020-06-29 13:31:51.082740: The connection agent for remote callable flows has established a connection to the Switch server with URL 'wss://ibm-sw-aaaahbbbcccciqiz.eu-gb.ace.ibm.com:443/'. 
   2020-06-29 13:31:51.088324: The integration server component 'agentx' has been started. 
   component started: "agentx"
   

7. Switch back to the App Connect Designer window and then test the agent connection:
   1. Click Test your agent

      You should see at least 1 agent found. Secure communications for callable flows has been established between IBM App Connect on IBM Cloud and the integration server in your local IBM App Connect Enterprise.

   2. You can now close the Synchronize your on-premises agent dialog.

You have established secure connectivity between flows running in App Connect on IBM Cloud and in the integration server in your on-premises App Connect Enterprise.

Import the enterprise integration project into the toolkit, then deploy the ACE flow provided

In this section we use the App Connect Enterprise Toolkit (Enterprise Toolkit) to create and deploy a flow into an on-premises ACE integration server. The ACE integration flow implements a REST API and uses a CallableFlowInvoke node to call the event-driven flow that is running in App Connect on IBM Cloud.

(Click image to view full size.)

Rather than create the integration project from scratch, we import the project interchange file, PI_LeadXML2ACoIC.zip, used to develop this tutorial.

1. Download the project interchange file by clicking the link above and saving the file to your local machine.
2. Open the toolkit.
3. Import the project into the toolkit. For example, click File > Import, select IBM Integration > Project Interchange, select the downloaded file, then click Finish.

   A new project called LeadXML2ACoIC appears in the Application Development view of the toolkit. It contains the definition for the REST API with a subflow, called addlead.subflow, that performs the on-premises activities for the Add lead operation, and calls the flow in App Connect on IBM Cloud. The project also contains a BAR file that you can deploy to an integration server, and a flow definition file that you can import to App Connect on IBM Cloud (described later).

   

   (Click image to view full size.)

   • Input accepts input for the subflow, passing the JSON data values for FirstName, LastName, Email, and Company; for example: InputRoot.JSON.Data.FirstName.
   • Assign Local Id creates a unique identifier for the new lead, and assigns it to the local environment variable ‘Id’: OutputLocalEnvironment.Variables.Id.
   • Call flowin AConIC calls the flow in App Connect on IBM Cloud with the flow name Call to update-create SF lead, passing the local environment values and the input JSON data values. When the called flow has finished it returns the ID of the Salesforce lead as the local environment value SfLeadId.
   • Construct XML Message converts the incoming data into an XML format, including the addition of the unique identifier (Id) and the Salesforce lead ID (SfLeadId).
   • Write to file appends the XML data directly to a file on the file system, using a new line for each new entry. The directory and filename are configured on this node.
   • Output sends a response to the caller of the REST API.

   Ref: Creating a REST API from scratch by using the IBM App Connect Enterprise Toolkit.

   You can open the REST API Description in the REST API Editor, to display and modify information about the REST API; for example:

   • In the Header section, the REST API base URL field displays the current base path for the REST API. All resources in a REST API are defined relative to its base path. You can edit this field to modify the base path of the REST API. You can also see the URL to use to access the operations in the REST API.
   • In the Resources section, you can see the POST addLead operation for the Lead resource type (/leads). This operation is invoked by POST http://:/leadsxml/v2/leads (a combined URL from what you can see in the Header and Resources operation sections).
   • In the Model definitions section, you can see the definition for the JSON data that you can use for the Request and Response Schema type in the addLead operation.

   

   (Click image to view full size.)

   

   (Click image to view full size.)

4. Check that the toolkit is connected to your integration server (such as when created and started in the toolkit earlier). If it is connected, it is shown in the Integration Explorer view:

   

   Tip: If the integration server is not shown as connected, complete these steps to connect the server…

   1. In the Integration Explorer view, right-click Integration servers, and then click Connect to an integration server. In the Connection details dialog, enter the host name and port for the integration server. Ensure that the port matches the value of the adminRestApiPort property that was specified in the server.conf.yaml file (in this example, the port is 7600, and the host name is localhost). If the integration server is secured, you must also specify the user name and password.
   2. Click Finish. The connection for your integration server is now displayed in the Integration Explorer view in the toolkit.
5. The project contains a BAR file called LeadXML2ACoIC.bar, which contains the callable flow, ready to be deployed. Deploy the BAR file to the integration server you intend to use for the tutorial; for example, drag the BAR file and then drop it onto the integration server.

   (In addition to the callable flow, the project includes the YAML configuration file for a flow exported from App Connect on IBM Cloud, called: Call to update-create SF lead.yaml. This file will be used later to create a flow in App Connect on IBM Cloud.)

   In the ACE log, you should see the flow deployed successfully and listening for the REST API:

   2018-06-11 13:01:01.827403: The connection agent for remote callable flows has established a connection to the Switch server with URL 'wss://ibm-sw-*****************.eu-gb.ace.ibm.com:443/'.
   ...
   2018-06-11 13:25:56.083516: About to 'Start' the deployed resource 'LeadXML2ACoIC' of type 'RestAPI'.
   2018-06-11 13:25:56.089092: Listening on HTTP URL '/leadsxml/v2*'.
   Started native listener for HTTP input node on port 7800 for URL /leadsxml/v2*
   

   Note the port number and URL that are part of the URL used to call the REST API; for example: http://localhost:7800/leadsxml/v2/leads

In App Connect on IBM Cloud, configure and start the callable flow

In this section we configure the event-driven flow in App Connect on IBM Cloud (without any coding). This flow is to be triggered when called from the ACE flow. The flow then updates or creates a Salesforce lead, then sends an email to notify a Sales rep, and finally returns the Salesforce lead ID to the ACE flow to complete the on-premises processing of the lead.

(Click image to view full size.)

To import the flow, from the dashboard select New > Import flow..., copy or select the flow definition file, then click Finish. This imports the flow and opens it in the Flow editor.

After importing the flow, click the action nodes to check the configuration and if needed connect to your own application accounts. Also, for the Slack / Create message action select a channel (or user) where you want to post the message.)

• (Optional) Creating the callable flow from scratch
  1. In App Connect on IBM Cloud, click the Dashboard link, then select New > Event-driven flow.

     This opens the Flow editor, and prompts you for how to start the flow.

  2. Click the Toolbox tab, and then select Callable flow as the starting point. This adds a Callable flow / Input node and a Callable flow / Reply node to the flow.
  3. Add an action to update or create a Salesforce lead.
     1. In the flow diagram, select the (+) after the Callable flow / Input node.
     2. In the Applictions list expand Salesforce > Leads, and then select Update or create Lead as the Salesforce action.

        If the desired Salesforce Lead already exists it will be updated; otherwise, a new Salesforce Lead will be created.

     3. If you haven't already connected a Salesforce account, click Connect then follow the instructions to allow App Connect to connect to your Salesforce account.
     4. Define the conditions for Salesforce to update an existing Lead.

        Under *Where, add enough conditions to uniquely identify one Salesforce Lead.

        If there's more than one record in your target system that matches the conditions when you run the flow, you'll see an error for the flow on the dashboard, and the flow won't update or create any records. For example, maybe you have more than one lead with the same first and last names. So to match a lead, use unique data, such as their email address or a combination of conditions.

        In this case, the condition values are taken from the message JSON data passed to the callable flow input. For example, I added conditions for FirstName, LastName, Email, and Company.

        Add each condition value as follows (or copy the values from below):

        1. Select Callable flow / Input … Message.JSON.Data (for example, using the Insert a mapping icon ).
        2. Click Message.JSON.Data and then select the Edit expression. Add the data value name from the message JSON data.

        This should give the following values:

        • Where - equals value
        • First Name - {{$Trigger.message.FirstName}}
        • Last Name - {{$Trigger.message.LastName}}
        • Email - {{$Trigger.message.Email}}
        • Company - {{$Trigger.message.Company}}
     5. Populate the target fields in Salesforce.

        App Connect automatically completes the mapping to target fields specified in the Where conditions, showing each such field with a message that indicates the value used in the Where condition will be used.

        

        (Click image to view full size.)

        For any other fields that you want to update or create for the Salesforce Lead, click the Insert a mapping icon , then select and edit from Callable flow / Input … :

        For example, the Description field is used to record the generated local lead ID from the local environment tree Id variable. For this field, create the mapping by selecting Callable flow / Input … LocalEnvironment.Variables, and then editing the expression as shown:

        On-prem Lead ID = {{$Trigger.localEnvironment.Id}}
        

  4. Add an action for Slack to send a message to a suitable channel or user:
     1. In the flow diagram, select the (+) after the Salesforce node.
     2. In the Applications list expand Slack > Messages, select Create message, then select a channel or user, and then populate the message text field; for example:

        Lead created or updated with data from on premises. 
        FirstName = {{$Trigger.message.FirstName}}
        LastName = {{$Trigger.message.LastName}}
        Salesforce Lead ID = {{$SalesforceUpdateorcreatelead.Id}}
        On-prem Lead ID = {{$Trigger.localEnvironment.Id}}
        

  5. Configure the data that is to be returned to the ACE flow:
     1. In the flow diagram, click the Callable flow / Reply node.
     2. Under LocalEnvironment.Variables, click the Add property link, then give it the name SfLeadId (leave the type as String).
     3. Click the Edit mappings link, then for the SfLeadId value map Salesforce / Update or create lead > Lead > Lead ID
     4. Under Message.JSON.Data, use the Add property link to add the following properties (leave the type as String):
        • First Name - {{$Trigger.message.FirstName}} (or Salesforce / Lead > First Name)
        • Last Name - {{$Trigger.message.LastName}} (or Salesforce / Lead > Last Name)
        • Email - {{$Trigger.message.Email}} (or Salesforce / Lead > Email)
        • Company - {{$Trigger.message.Company}}

        Click the Edit mappings link, then for each property map the value from the Message.JSON.Data (and edit the expression as before) or from the Salesforce / Update or create lead > Lead.

  6. Give your flow the name: Call to update-create SF lead

     The flow name needs to match the application name that the ACE flow uses to invoke this callable flow.

Start and check the callable flow:

1. To exit and start the flow, open the options menu [⋮] in the banner and click Start flow; then click Dashboard.

   Otherwise, just return to the Dashboard, You can start the flow from there, as outlined in the Test the flow step.

2. Switch to the Callable flows view (click the Callable flows menu on the left of the window); you should now see the new callable flow provided by App Connect on IBM Cloud. Note that the Application name must match the name that was specified when creating the flow.

   

   Tip: If you do not see the new callable flow in the Callable flows list, refresh the browser window to update the list.