Part 9: Simplify Integration to third-party applications – Post new Invoice notifications from QuickBooks Online to your Slack Channel

SAP Cloud Platform Open Connectors simplifies and accelerates connectivity to third-party cloud applications. It provides robust, feature rich, pre-built connectors to an extensible library of over 160 of the most popular third-party cloud applications. Customers can easily build API compositions across the different connectors and can wrap multiple operations in a single request.

Using the Formulas from SAP Cloud Platform Open Connectors, composing scenarios becomes a matter of configuration rather than coding, and moving the necessary logic out of applications and into SAP Cloud Platform Open Connectors. This helps keep your code less complex and more maintainable.

A common use case for Formulas is sending or posting notifications whenever there is new entity created in a third-party application, for example, you might like to post a message on your team’s Slack channel whenever a new Invoice is created in your QuickBooks online system. In this blog, we would showcase a simplified integration of posting a Slack message whenever a new Invoice is created in the QuickBooks Online application.

For more blogs on SAP Cloud Platform Open Connectors , ref the blog series.

Prerequisites

• SAP Cloud Platform trial tenant
• SAP Cloud Platform Open Connectors tenant
• Test or Sandbox tenant in QuickBooks Online or any other finance application that you would like to connect to from SAP Cloud Platform Open Connectors.
• Test or Sandbox tenant in Slack or any other collaboration application that you would like to connect to from SAP Cloud Platform Open Connectors.

Note:- In this blog, we have used a third-party application from the Collaboration hubs which is Slack and Financial Hubs which is QuickBooks Online. You are free to use any other third-party application of your choice for this exercise.

Connect to Collaboration Hubs (Slack) from SAP Cloud Platform Open Connectors

In this section, steps to seamlessly and securely connect to the third-party cloud applications via SAP Cloud Platform Open Connectors has been covered. SAP Cloud Platform Open Connectors is available for test, explore and try out in SAP Cloud Platform trial. If you have not enabled SAP Cloud Platform Open Connectors in your trial tenant, refer this blog to enable it.

In the blog Simplified connectivity to third-party collaboration hubs application, detailed steps to connect to Slack connectors has been covered and can be followed to create an authenticated connections to your Slack tenant using SAP Cloud Platform Open Connectors. In this section we showcase creating a dedicated Slack Channel for the Accounts Team using the newly created connectors.

• Logon to your SAP Cloud Platform trial and Navigate to the Neo Environment.

• From the services tab, search and select Open Connectors tile and click on the Go to Service link.

• You would be navigated to SAP Cloud Platform Open Connectors Home or Landing page.

• Click on the Connectors tab to view all the available pre-built, feature rich connectors and the created authenticated connections for these connectors. Next to the connectors, the number of created authenticated connectors to respective third-party application is shown numerically like seen in the screen shot.

• Hover over the numeric authenticated connectors (1) and click on expanded Instances button to navigate to the created instances view.

• You would be navigated to the available instances for your selected connectors, which is Slack in this scenario.
• Hover the available authenticated connectors for your Slack tenant and then Click on the option API Docs to open up the interactive API Documentation in the Open API Specification format.

• Using the POST operation for the resource /channels, a dedicated Slack Channel for the accounts team can be created using the simplified APIs from SAP Cloud Platform Open Connectors.
• In case you would like to use an existing channel from your Slack tenant then by executing the GET operation for the resource /channels, you would be able to view all the available dedicated channels and the channel id for each of the available channel.
• Click on the Try It Out button and in the body parameter, the following request snippet can be provided to create a dedicated channel named accountsteam and then click on the Execute button to send the request to your Slack tenant.

{
"name": "accountsteam"
}

• After the dedicated Slack channel for your accounts team is created, the API would return  information about the channel id of the newly created channel. This channel id from the response would have to be noted down and would be required to post messages to this channel.

• Open your dedicated Slack tenant to view the newly created channel named accountsteam. The notifications about the invoices generation from third-party financial hubs would be posted in this channel.

Enable events and configure events callback to listen to changes from your third-party applications

SAP Cloud Platform Open Connectors Events Framework provides a uniform mechanism for subscribing to events from API providers like HubSpot, QuickBooks, or Dropbox. The Events Framework gives you the flexibility to receive notifications to your app regarding user activity by having the connectors subscribe to API provider events.

In the blog Simplified connectivity to third-party financial hubs application, detailed steps to connect to QuickBooks Online connectors has been covered and can be followed to create an authenticated connections to your QuickBooks Online tenant using SAP Cloud Platform Open Connectors. In this section, steps to subscribe to events for change notifications on Invoices from QuickBooks online has been captured.

• Navigate to Instances tab in SAP Cloud Platform Open Connectors.
• From the available authenticated connectors select settings button next to the authenticated connector created to your QuickBooks Online tenant.
• From the actions list, select Edit to change the created authenticated connector instance and enable it for events.

• From the Event Configuration section, switch on the Events Enabled toggle switch to enable the events.
• In the Event notification callback URL specify the call back URL as https://api.openconnectors.ext.hanatrial.ondemand.com/elements/api-v2/events/{{page.key}} to return events to the connectors. This events can then be received in the Formulas that would be created in the next section.

Note: – The host of the call back URL may vary based on the data centers of SAP Cloud Platform Open Connectors. For example, for the Europe Rot data center the URL would be https://api.openconnectors.ext.hana.ondemand.com/elements/api-v2/events/{{page.key}}

• From the Configure polling section, select the resources for change notifications. In this example, we select the option for only Invoices and uncheck all other options.
• The default change notification interval is 15 minutes, this could be changed or set to a value as required by your integration scenario. In this exercise, it was set to 5 mins.
• Click on the Update button to save all your changes to the selected authenticated connector instance.

Create a Formula and Formula Variables for posting notification to Slack

Formulas enables building of API compositions across the different connectors and wrapping multiple operations in a single request. In this section, we capture steps to create a Formula to Post a message on the Slack channel whenever there is any update on the invoices in the QuickBooks tenant.

In this example, the trigger will be based on an event — when an invoice is created or updated in QuickBooks Online. This trigger will kick off the formula to post notifications to the Slack channel. In order to post message to a dedicated Slack channel, the id of the channel is required. This is explained in the section Connect to Collaboration Hubs (Slack) from SAP Cloud Platform Open Connectors.

• Navigate to the Formulas page by selecting the tab Formula.
• On the Formulas page, click Build New Formula Template.

• Click Build New Formula.

• Enter a name for your formula like “PostInvoiceToSlackChannel”, and then click Create.

• Choose the trigger. Triggers define how the formula starts. Because we want to automatically post notification on the Slack channel when any invoice is created or updated in QuickBooks Online, we’ll use an Event trigger.
• Click on the add Event Button.

• Enter the Connector Instance Variable field as ${config.sourceInstance} and then click Save button

• In the Add Formula Step, Select JS Filter (true/false) . Using JS filter, simple conditions can be checked. In this example, using the JS filter step we will be checking if the events is raised for invoices resources and if the event type is of type create or update.

• In the Create filter step, enter the name of the step as IsNewInvoice and then using JavaScript snippet check for the events type and event object type.
• Click on Save button to create the filter step.

let theEvent = trigger.event.eventType;
let theObject = trigger.event.objectType;

done((theEvent === 'CREATED' || theEvent === 'UPDATED') && (theObject === 'Invoices' || theObject === 'invoices'));

• On Success of the JS filter step, we will create a message to post the data into the Slack channel. Click on the IsNewInvoice step that you just created, and then click Add On Success.

• In the Add Formula Step, Select JS Script . Using JS Script, the message to be posted to the Slack channel with link to the updated or created invoices in QuickBooks Online tenant can be created.

• In the Create script step, enter the name of the step as CreateMessage and then using JavaScript snippet the message for the Slack channel can be created.
• Click on Save button to create the filter step.

let objectId = trigger.event.objectId.replace("|0","");
let message = "Dear team an Invoice is ready for your review. To view more click here <https://c18.qbo.intuit.com/app/invoice?txnId=" + objectId + ">";

done( {
"text": message
});

• Next we will create the step to post the message to the Slack Channel via the Connector Instances to Slack Connectors. Click on the CreateMessage step that you just created, and then click Add On Success.

• In the Add Formula Step, Connector API Request . Using Connector API Request step, the post message created in the previous step can be posted via an existing authenticated Slack connectors instance.

• In the Create Element Request step, enter the name of the step as PostMessage. Specify the Connector Instance Variable as ${config.targetInstance}, method as POST and API as                     /channels/{your_slack_channel_id}/messages

• Set the body value to ${steps.CreateMessage} so the message created in the step CreateMesage can be used as the payload for the Post message flow to post the message to the Slack Channels.
• Click on Save button to create the connector step.

• Next we create the variables to the connectors instance which was used in the Formula steps. Variables can represent authenticated connector instances or values. When you actually run a formula by creating a formula instance, you replace the variables with actual authenticated connector instances or values.
• Click on Variables to create the variables named sourceInstance and targetInstance.

• Click on the option Connector Instance to create the variable named sourceInstance. This variable would be used to set the connector instance of the source system which is QuickBooks Online.

• Enter name as sourceInstance and then click on Save button.

• Click on the option Connector Instance to create the variable named targetInstance. This variable would be used to set the connector instance of the target system which is Slack.

• Enter name as targetInstance and then click on Save button.

Create a Formula Instance

The formula instance actually performs the posting of the invoice change notification to Slack channel. In this case we’re going to associate the QuickBooks Online connector instance with the sourceInstance formula variable, and Slack connector instance with targetInstance. Whenever you create a new invoice in QuickBooks, the trigger for the formula kicks off when an event occurs at the connector in the sourceInstance variable, which then kicks off the logic in the formula.

• Navigate back to the main Formulas page.
• Hover over the PostInvoiceToSlackChannel tile, and then click Create Instance.

• Enter the name of the Formula instance say postinvoicetoslack
• Click on sourceInstance .

• Select the QuickBooks Online instance that you authenticated earlier (myquickbooks).

• Click on targetInstance .

• Select the Slack instance that you authenticated earlier (myslack).

• Click on Create Instance button to create the Formula instance.

Post invoice notification from QuickBooks Online to Slack channel

• Log on to your QuickBooks Online tenant and then create a new Invoice.

• Wait a few minutes, in this example we had the set the polling interval for 5 minutes, If the polling interval is set to a higher value then you would have to wait for that time period.
• Go to your Slack channel and you would see the new invoice notification post.

More blogs on SAP Cloud Platform Open Connectors available in SAP Community.