AppBus Integration API

The following capabilities are available as part of the integration capability of SmartHub.

Attribute-driven Configuration

The following attributes can be used in HTML to configure/customize the integration execution.

Field Attributes

Attribute Value Description
data-edit

Boolean value

Default: false

Controls if the field is supposed to be editable.
data-type

String value

Default: text

Controls what type of field it is.

Available types:

  • text - Displays a text field
  • textarea - Displays a multi-line text area
  • select - Displays a drop-down
  • email - Displays a text field with email format validation
  • tel - Displays a text field with phone format validation
  • password - Displays a text field with hidden value
  • time - Displays a time field with time format validation
  • number - Displays a text field with numeric format validation
  • range - Displays a slider 
  • checklist - Displays a vertical list of checkboxes
  • file - Displays a file picker
data-onblur

String value

Default: cancel

Controls what happens when you click outside a field that you are editing

  • Default Behavior: The edit is cancelled
  • Other Behaviors: Can be changed to submit.
    • This setting keeps the change (as if the check button for the field was chosen).
data-integration-mapTo

String value

Default: no value

  • Controls the name of the flow parameter that needs to be sent when making the call.
data-success-callback

String value

Default: no value

  • Function that should be called when the user finished editing the field.

  • The format is a full name function such as: 
    window.some.custom.namespaced.functionName
data-error-callback

String value

Default: no value

  • Function that should be called when the user finished editing the field, but the UI failed to update.

  • The format is a full name function like: 
    window.some.custom.namespaced.functionName
data-value

String value

Default: no value

  • The current value of the field being edited.

  • If this value is missing, the inner value of the HTML element is used instead.

  • If the field is type checklist then the value format is expected to be a JSON array like:
    data-value="[value1,value2]"
data-source

String value

Default: no value

  • Controls the list of available values when the field is a type that supports listing multiple options like - select or checklist.

  • The format of the field is a JSON array with properties value and text like:
    data-source="[{ value:1, text: 'Option 1'}, { value:2, text: 'Option 2'}]"
data-base64

Boolean value

Default: false

Used only for fields of data-type="file" to control if the field data needs to be sent via MULTIPART requests or as a normal JSON field using base64 encoding.

Trigger Button Attribute

These are the attributes used to configure the trigger button that runs the AppBus flow and sends the parameters:

Attribute Value Description
data-integration-url

String value

Default: no value

  • Relative URL pointing to the AppBus flow that needs to be executed.

  • Example: api/contoso/flow1
data-notify

Boolean value

Default: true

This controls if a notification should be displayed once the integration execution is finished.

Two types of notifications are supported:

  • Toast notifications
    • These are displayed in the page and unless the user has the page in front of him he will miss the notification
  • Browser/System notifications
    • These are displayed via the HTML5 Notification API.
    • They work only if the user accepts showing notifications when the system asks for configuration, otherwise the Toast notifications are used instead
    • Depending on the browser capability the notifications are either displayed by the browser itself or by the underlying Operating System (Example: Windows 10 notifications)
data-integration-type

String value

Default: GET

Controls what type of request the flow is configured to receive:

Typically:

  • POST

  • GET

  • MULTIPART

Note: When using MULTIPART the value for data-integration-mapTo property for non-file fields needs to be prefixed with data.
data-description

String value

Default: calling integration [data-integration-type] : [data-integration-url]

  • The message that should be displayed in the notification.
  • The same message is displayed regardless if the flow finished successfully or not.
  • The difference is the title of the notification - Success or Failure
data-success-callback

String value

Default: no value

  • Function that should be called when the API finished running the integration flow.

  • The format is a full name function like: 

    • window.some.custom.namespaced.functionName

data-error-callback

String value

Default: no value

  • Function that should be called when the API triggered errors while running the integration flow.

  • The format is a full name function, such as: 

    • window.some.custom.namespaced.functionName

data-long-running

Boolean value

Default: false

Controls behavior if the integration API call is long-running:

  • Returns a job ID and the UI waits for the job to finish:
    • Checks status every 500 ms
      or 
    • If the job is a normal API call (default), then once the call is finished, the API call is complete

JavaScript Integration API

The following JavaScript functionality is available via the integration capability:

Integration API Calls

  • To call the integration API manually, use the functions under window.SH.Services.IntegrationService. 

  • All functions return a promise, so you can wait for them to finish and read the result of the call.

Available Functions

The available functions are:

Function definition Sample call Comments
SH.Services.IntegrationService.RunGet(integrationProvider, integrationParams, queryString, headers) SH.Services.IntegrationService.RunGet("appbus", "api/contoso/flow1", "param1=value&param2=value", { header1: value1 }).done(function(result){ ... }); This runs a GET call for the flow and passes the query string parameters with the request
SH.Services.IntegrationService.RunPost(integrationProvider, integrationParams, postData, headers) SH.Services.IntegrationService.RunPost("appbus", "api/contoso/flow2", { param1: true, param2: "value2" }, { header1: value1 }).done(function(result){ ... }); This runs a POST call for the flow and passes the data object as the JSON request body
SH.Services.IntegrationService.RunMultiPart(integrationProvider, integrationParams, postData, headers) SH.Services.IntegrationService.RunMultiPart("appbus", "api/contoso/flow2", { param1: true, param2: "value2" }, { header1: value1 }).done(function(result){ ... }); This runs a POST call for the flow and passes the data object as the request body. This call uses multi-part body instead of JSON request body

Edit Capability API calls

To enable the edit capability for different types of forms for the functions under windows.SH.utils

Available Functions

The available functions are:

Function definition Sample call Comments
SH.utils.makeEditableForm(formElement) SH.utils.makeEditableForm(SH.$(".formContainer"))

Analyzes the child elements of the formContainer element for the following information:

  • Find all the elements that have data-edit="true" and make them editable
  • Find all the elements that have data-integration-mapTo="..." so that their value is passed to the flow when the trigger is executed
  • Find all the element that have data-integration-url="..." and make them trigger elements (that run the flows at click time)
    • If a form contains multiple elements with different data-integration-url parameters, each triggers its own flow, but the parameters are shared since all the trigger buttons read all the values from the parent form which is the same for all of them
    • If you want to separate the parameters use smaller containers that include only the parameters that you want for a specific trigger instead of showing them all together
SH.utils.makeEditablecontrol(controlElement) SH.utils.makeEditableControl(SH.$(".singleFieldForm"))

Reads the parent element of the singleFieldForm element and makes the parent an editable form. The requirements are:

  • The form should contain a single element with data-edit="true" that is editable
  • The same element that has data-edit="true" must also have data-integratio-url="..." and behaves as both an editable field and a trigger element

The method analyzes the elements for the following information:

  • Find all elements that have data-integration-mapTo="..." so that their value is passed to the flow when the trigger is executed
SH.utils.readEditedContent(formElement, callback) SH.utils.readEditedContent(SH.$(".formContainer"), function(data){ ... })

Analyzes the child elements of the formContainer element for the following information:

  • Find all the elements that have data-integration-mapTo="..." and read their values

And calls the callback function and passes it the data object where all the properties are mapped to the values of the corresponding elements that are mapped to them
SH.utils.showNotification(message, options) SH.utils.showNotification("This is a new notification")

Triggers a new notification in the UI. It supports 2 types of notifications:

  • Toast notification - DOM elements that are displayed in the UI on top of other elements but that the user might miss if the page is not currently in focus
  • Browser/System notification - Built-in HTML5 capability of the browser to either display the notification or forward the notification to the underlying operating system to display it
    • For this capability to work user needs to accept Notifications for the site - otherwise the capability falls back to Toast notifications

Certain extra options can be passed and possibly used by the function (depending on the type of notification that ends up being used):

Option name Description Comment
title

The title of the notification

Default: the title of the HTML page

Controls the title that will be displayed with the notification
duration

How long (ms) to display the notification

Default: 3000ms

This is only used by the Toast notification since the Browser/System notifications don't have a configurable duration
horizontalPos

The horizontal position of the notification

Default:right

This is only used by the Toast notification since the Browser/System notifications don't have a configurable position

Possible values:

left|center|right
verticalPos

The vertical position of the notification

Default:top

This is only used by the Toast notification since the Browser/System notifications don't have a configurable position

Possible values:

top|center|bottom
dismissable

Boolean value

Default: true

Controls if there's an [x] button displayed, so the user can close the notification manually
type

The type of the notification

Default: info

This is only used by the Toast notification since the Browser/System notifications don't have a configurable position

Possible values:

info|success|error

Because the function calls the HTML5 notification system, all options are passed to the Notification constructor, so any additional options used by the HTML5 Notification API can be specified in the option's parameter. See all possible options here.

Integration API: Available Functions

End Point

SmartHub exposes an API for this capability which has the following format:

  http(s)://smarthub.contoso.com/_integration/appbus/[relative AppBus API to call]?[query string parameters]

Methods

The API can be called with:

  • GET
  • POST - application/json
  • POST - multipart

Header

The API expects the X-SH-Authorization header to be sent with the value "Bearer <token>" where the token is the SmartHub token used for authentication