{"id":2122,"date":"2016-12-12T02:08:04","date_gmt":"2016-12-12T10:08:04","guid":{"rendered":"https:\/\/www.microsoft.com\/reallifecode\/index.php\/2016\/12\/12\/integrating-an-existing-bot-platform-with-microsofts-bot-framework\/"},"modified":"2020-03-18T22:43:23","modified_gmt":"2020-03-19T05:43:23","slug":"integrating-an-existing-bot-platform-with-microsofts-bot-framework","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/ise\/integrating-an-existing-bot-platform-with-microsofts-bot-framework\/","title":{"rendered":"Integrating an Existing Bot Platform with Microsoft’s Bot Framework"},"content":{"rendered":"

Image: tabletop assistant<\/a> by Matthew Hurst<\/a>, used by CC BY 2.0<\/a><\/em><\/p>\n

Background<\/h2>\n

SMARKIO<\/a> is a suite of tools to help companies solve the puzzle of digital marketing. The suite includes integrated technologies that work on a website (such as trigger overlays, automated chats that replace web forms, and dynamic content). It also includes technologies like segments and workflows that trigger programmed actions (such as emails, SMSes, and integration with CRMs and external partners). In addition, it gathers online and offline conversion metrics to provide centralized reporting and tracking details.<\/p>\n

SMARKIO developed its own web-based bot stack that provides a holistic solution for bots. It has a content management dashboard for authoring and managing dialogs, a UX that includes the controls (buttons, cards, carousels, etc.) and a web chat control for their partners to embed chats on their own websites.<\/p>\n

\"Editing<\/p>\n

\"Editing<\/p>\n

SMARKIO\u2019s primary goal was to bring their existing dialogs to other channels like Skype and Facebook. Their content management system stores the dialogs as JSON files, and they wanted to load the dialogs from these files to other channels. This approach would allow them to continue using their dashboard for authoring and managing dialogs.<\/p>\n

Also, SMARKIO wanted to be able to update the dialogs at runtime, while the bot service is running and users might be chatting with it, without needing to redeploy or restart the bot service.<\/p>\n

The Problem<\/h2>\n

Microsoft\u2019s Bot Framework today does not support loading dialogs from external files. To implement a dialog now, a developer has to hard-code all of the dialog\u2019s steps in the bot service. As a result, there is also no way to support a scenario where an updated dialog can be dynamically reloaded without needing to restart the bot service.<\/p>\n

Also, we had to find a way to convert all of the dialogs written in SMARKIO\u2019s specific format into a Bot Framework-compatible format.<\/p>\n

The Engagement<\/h2>\n

We collaborated with SMARKIO to create a solution that would allow them to continue to use their current content management system while exposing those dialogs on different channels using Bot Framework.<\/p>\n

The layout for our solution is based on the use of the bot-graph-dialog<\/a> extension developed as part of our collaboration with Pager<\/a>. Since Pager had similar problems, we were able to use the same approach to support loading configuration-based dialogs from SMARKIO\u2019s backend, where they maintain their dialogs.<\/p>\n

To support loading the dialogs on demand, we extended the bot-graph-dialog<\/code> library to create extra functionality, as detailed in the next section.<\/p>\n

The Solution<\/h2>\n

The following list describes the sequence of the events in our flow. Next, we will focus on the key parts of the code that implement this sequence in our scenario.<\/p>\n

    \n
  1. Bot starts and loads a dialog<\/li>\n
  2. User starts talking to the bot, triggering the dialog<\/li>\n
  3. Dialog is changed on the backend<\/li>\n
  4. Backend triggers a load request to the bot<\/li>\n
  5. Bot reloads dialog and replaces it with the new one<\/li>\n
  6. User continues the chat<\/li>\n
  7. Bot identifies dialog was changed and resets the dialog<\/li>\n
  8. User gets a message that the dialog was updated and that he or she needs to restart the dialog<\/li>\n<\/ol>\n

    The full code that implements the above scenario can be found on GitHub<\/a>.<\/p>\n

    Dialog Format Transformations<\/h3>\n

    Since SMARKIO developed their whole stack and created their own language and format to author their dialogs, our first step was to convert their dialogs into a format that the bot-graph-dialog<\/code> extension can use. This task was straightforward and easily implemented in their dashboard. Now, every time someone adds or updates a dialog, a graph-bot-dialog<\/code> version is saved, ready to be fetched by the bot service.<\/p>\n

    Carousel control as it appears on Skype and Web Chat control, after transforming the dialog from SMARKIO\u2019s format to the graph-bot-dialog<\/code> format:<\/p>\n

    \"Bot<\/p>\n

    \"Bot<\/p>\n

    REST API to Expose SMARKIO\u2019s Dialogs<\/h3>\n

    In Pager\u2019s case, we loaded the dialogs from a database. Since the bot-graph-dialog<\/code> extension supports loading dialogs from any<\/em> external data source by providing a handler implementation we just had to implement this handler to fetch the dialogs from SMARKIO\u2019s backend. We did this by using a simple HTTP GET request to a REST API they exposed specifically for this purpose.<\/p>\n

    \n
    function<\/span> loadScenario<\/span>(<\/span>scenario<\/span>)<\/span> {<\/span>\r\n  return<\/span> new<\/span> Promise<\/span>((<\/span>resolve<\/span>,<\/span> reject<\/span>)<\/span> =><\/span> {<\/span>\r\n\r\n    var<\/span> uri<\/span> =<\/span> `<\/span><<\/span>SMARKIO<\/span>'<\/span>s<\/span> REST<\/span> API<\/span> endpoint<\/span>><\/span>\/${scenario}`<\/span>;\r\n<\/span>    console<\/span>.<\/span>log<\/span>(<\/span>`<\/span>loading<\/span> remote<\/span> scenario<\/span> $<\/span>{<\/span>scenario<\/span>}<\/span> from<\/span> $<\/span>{<\/span>uri<\/span>}<\/span>`<\/span>);<\/span>\r\n\r\n    request<\/span>(<\/span>uri<\/span>,<\/span> {<\/span> json<\/span>:<\/span> true<\/span> },<\/span> (<\/span>err<\/span>,<\/span> resp<\/span>,<\/span> body<\/span>)<\/span> =><\/span> {<\/span>\r\n      if<\/span> (<\/span>err<\/span>)<\/span> return<\/span> reject<\/span>(<\/span>err<\/span>);<\/span>\r\n      resolve<\/span>(<\/span>body<\/span>);<\/span>\r\n    });<\/span>\r\n\r\n  });<\/span>\r\n}<\/span>\r\n<\/code><\/pre>\n<\/div>\n
    Reloading Dialogs On Demand<\/h3>\n
    We modified the bot-graph-dialog<\/code> extension to support versions of dialogs. Each scenario file can now explicitly define its version. This feature can be used later on to check if a newer version of a scenario was loaded.<\/p>\n
    When a dialog is updated on the backend, we need to be able to notify the bot service about the change. Since the bot service is just a REST API service, it was easy to add another API call from the backend whenever a dialog was updated and saved. To do this, we call the new reload<\/code> method which was added to the GraphDialog<\/code> class for this purpose, which triggers an internal process that:<\/p>\n
      \n
    1. Fetches the updated dialog by calling the loadRemoteScenario<\/code> handler<\/li>\n
    2. Parses and replaces the existing dialog with the new one<\/li>\n
    3. Calculates a dialog version if it wasn\u2019t provided explicitly in the dialog\u2019s JSON<\/li>\n<\/ol>\n
      \n
      \r\n\/\/ endpoint for reloading a scenario on demand<\/span>\r\napp<\/span>.<\/span>get<\/span>(<\/span>'\/api\/load\/:scenario'<\/span>,<\/span> (<\/span>req<\/span>,<\/span> res<\/span>)<\/span> =><\/span> {<\/span>\r\n  var<\/span> scenario<\/span> =<\/span> req<\/span>.<\/span>params<\/span>.<\/span>scenario<\/span>;<\/span>\r\n  console<\/span>.<\/span>log<\/span>(<\/span>`<\/span>reloading<\/span> scenario<\/span>:<\/span> $<\/span>{<\/span>scenario<\/span>}<\/span>`<\/span>);<\/span>\r\n  var<\/span> dialog<\/span> =<\/span> dialogsMapById<\/span>[<\/span>scenario<\/span>];<\/span>\r\n  \r\n  return<\/span> dialog<\/span>.<\/span>graphDialog<\/span>.<\/span>reload<\/span>().<\/span>then<\/span>(()<\/span> =><\/span> {<\/span>\r\n    var<\/span> msg<\/span> =<\/span> `<\/span>scenario<\/span> id<\/span> '${scenario}'<\/span> reloaded<\/span>`<\/span>;<\/span>\r\n    return<\/span> res<\/span>.<\/span>end<\/span>(<\/span>msg<\/span>);<\/span>\r\n  })<\/span>\r\n  .<\/span>catch<\/span>(<\/span>err<\/span> =><\/span> res<\/span>.<\/span>end<\/span>(<\/span>`<\/span>error<\/span> loading<\/span> dialog<\/span>:<\/span> $<\/span>{<\/span>err<\/span>.<\/span>message<\/span>}<\/span>`<\/span>));<\/span>\r\n\r\n});<\/span>\r\n\r\n<\/code><\/pre>\n<\/div>\n
      This solution will only work if there is only one instance of the bot service. In the case where a bot service is scaled out to multiple servers, you\u2019ll need to use some sync mechanism to notify all instances about the change.<\/em><\/p>\n
      Identifying Dialog Version Changes<\/h3>\n
      When a dialog is updated while users are in the middle of it, the state of the session and the dialog data is no longer valid. Our approach was to notify the users that the dialog was updated and that they will need to start over.<\/p>\n
      To support that notification, we added the option of providing onBeforeProcessingStep<\/code> and onAfterProcessingStep<\/code> handlers that will be executed before and after processing each step in the graph. Using these handlers we were able to hook into the dialog\u2019s execution flow and check whether there was a version update before executing each step.<\/p>\n
      \n
      \/\/ Intercepts changes in a scenario version before processing each dialog step<\/span>\r\n\/\/ If there was a change in the version, restart the dialog<\/span>\r\nfunction<\/span> onBeforeProcessingStep<\/span>(<\/span>session<\/span>,<\/span> args<\/span>,<\/span> next<\/span>)<\/span> {<\/span>\r\n\r\n  \/\/ \"this\" is the GraphDialog instance that invoked this handler<\/span>\r\n\r\n  \/\/ Gets the current dialog version<\/span>\r\n  var<\/span> dialogVersion<\/span> =<\/span> this<\/span>.<\/span>getDialogVersion<\/span>();<\/span>\r\n\r\n  \/\/ If we didn't keep the dialog version, store it in the privateConversationData<\/span>\r\n  if<\/span> (<\/span>!<\/span>session<\/span>.<\/span>privateConversationData<\/span>.<\/span>_dialogVersion<\/span>)<\/span> {<\/span>\r\n    session<\/span>.<\/span>privateConversationData<\/span>.<\/span>_dialogVersion<\/span> =<\/span> dialogVersion<\/span>;<\/span>\r\n  }<\/span>\r\n\r\n  \/\/ If the version we stored in the privateConversationData is different than the current one-<\/span>\r\n  \/\/ we have a dialog update event. Restart the dialog.<\/span>\r\n  if<\/span> (<\/span>session<\/span>.<\/span>privateConversationData<\/span>.<\/span>_dialogVersion<\/span> !==<\/span> dialogVersion<\/span>)<\/span> {<\/span>\r\n    session<\/span>.<\/span>send<\/span>(<\/span>\"Dialog updated. We'll have to start over.\"<\/span>);<\/span>\r\n    return<\/span> this<\/span>.<\/span>restartDialog<\/span>(<\/span>session<\/span>);<\/span>\r\n  }<\/span>\r\n\r\n  return<\/span> next<\/span>();<\/span>\r\n}<\/span>\r\n<\/code><\/pre>\n<\/div>\n
      If the version<\/code> field in the root of the dialog object is specified, this will be considered the scenario version. If the version is not specified, the bot will assign it a version by hashing the content of the JSON file.<\/em><\/p>\n
      The Code<\/h2>\n
      Please refer to the bot-graph-dialog<\/a> extension that was used to support this solution, as well as to the bot-trees<\/a> project that can be used as a reference for how to use this extension. The specific reference for this case study is the loadOnDemand.js<\/code> file.<\/p>\n
      Opportunities for Reuse<\/h2>\n
      This code story demonstrates how to integrate an already existing bot platform with Microsoft\u2019s Bot Framework to easily expose the bot\u2019s dialogs on the various channels that the Bot Framework supports. This approach can be used as a reference to create solutions for similar scenarios. Also, scenarios that require the loading of bot dialogs from an external data source like files, databases or remote APIs can leverage the bot-graph-dialog<\/code> extension by using similar methods.<\/p>\n","protected":false},"excerpt":{"rendered":"
      How to expose dialogs on multiple supported channels easily by integrating Microsoft Bot Framework with an existing bot platform.<\/p>\n","protected":false},"author":21349,"featured_media":12600,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[13],"tags":[249,331],"class_list":["post-2122","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-bots","tag-microsoft-bot-framework-mbf","tag-smarkio"],"acf":[],"blog_post_summary":"
      How to expose dialogs on multiple supported channels easily by integrating Microsoft Bot Framework with an existing bot platform.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/posts\/2122","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/users\/21349"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/comments?post=2122"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/posts\/2122\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/media\/12600"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/media?parent=2122"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/categories?post=2122"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/tags?post=2122"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}