Overview

In an increasingly connected world, it is highly likely that some of the data needed to process an application already exists somewhere. This feature extends LearningBuilder's ability to talk directly to external systems and reduces the need to rely on human-entered data.

This feature allows the system to make a configurable HTTP request to a 3rd party system and store the raw response in a Workflow attribute.

If the response is not directly usable and needs to be parsed or formatted in a specific way, a custom C# script (managed in-app in the Sys Admin area) can be used to transform the response before it is saved in target attribute.

Feature set

• The entire HTTP request is managed via a Template Attribute. This allows it to support:

  • GET and POST requests

  • HTTP basic authentication

  • Arbitrary payload content built dynamically from other Attribute values

• The raw HTTP response can be saved directly into a target Attribute with no special configuration

• An optional C# script can be constructed (by a SysAdmin) to parse/transform the response before saving it

• Configurable request timeout (API results are processed synchronously, so extended timeouts are discouraged)

Sample External API Request template

Template follows the fiddler markup which has a request line followed by header values.

Then there should be a blank line (blank line 7 is required) followed by any body content.

@{
	var environment = Model.Environment;
	var url = @Model.Hostname + "/API/Diagnostic/Echo?Env=" + @Model.Environment;
}
POST @url HTTP/1.1
Content-Type: application/json

{
   "Environment": "@Model.Environment"
}

For testing purposes, LearningBuilder exposes an echo endpoint (/API/Diagnostic/Echo) which reflects back the request data. You can use this endpoint to confirm that the request template is well-formed before connecting with the real third party system. Use /API/Diagnostic/Echo?HideHeaders=true, if you would like to hide the headers from the response.

In release v11.0.0, we added Model.Environment and Model.Hostname to the template model so that behavior can change based on environment (DEV, QA, UAT, SUPPORT, PROD, etc.) These properties are only verified to be loaded for the Call External API behavior.

Other Required UI Configuration

The Call External API behavior also requires a LongText attribute to store the response received for that API call. You will need to configure this attribute before configuring the behavior itself; you cannot save behavior configuration without a valid response attribute.

Custom response processing

If the raw response provided by the 3rd party API cannot be used as-is, for instance if the API returns a complex JSON or XML object and you need to extract a tiny piece of that object to store in a Workflow Attribute, then a custom C# script can be used to process the response. 

This script:

• Must be created/edited by a SysAdmin in the Sys Admin → App Configuration → Custom Scripts page

• Must contain an entire C# class declaration that implements the IExternalApiResponseProcessor interface

• Must return a string

If defined, the raw response is passed through this function before being saved in the target attribute.

NOTE: This will only store into a SINGLE attribute, we cannot use this script to save multiple attributes.

NOTE: As of 9.3, the script is NOT validated or compiled upon save. Please ensure that you fully test any changes to the script.

Workaround For Multiple Attributes

Jason Bray (Unlicensed) to fill out