External API Call – Settings

Setting Description
Code API call's code. This setting is filled automatically based on the following schema [External API code].[API call Order No.]. For details, see How to create an External API and OrderNo.
Name Enter a descriptive name for API call.
OrderNo The order in which the API call is executed in the pipe. This allows you to configure multiple API calls to be executed in sequence in the same External API.
baseUrlIsKeyInConfigFile Check to use the base URL defined in the Innovation Studio web.config file for the API call's path ([base URL]+[endpoint]).
NOTE
Checking this option, disables the BaseURL field.

To configure a base URL in the web.config file, open the web.config file in a text editor and add the following entry in the <appSettings> section:

Copy
<add key="FTOS_IntegrationProcessBaseUrl_[<i>External API Detail Code</i>]" value=[<i>base URL</i>]/>

The External API's code and the API call's order number in the External API detail code are optional. For example:

  • To use a base URL for the first API call in the P04 External API, enter:
Copy
<add key="FTOS_IntegrationProcessBaseUrl_P04.01" value="http://www.example.com/example_Api"/>
  • To use a base URL for all the API calls in the P04 External API, enter:
Copy
<add key="FTOS_IntegrationProcessBaseUrl_P04" value="http://www.example.com/example_Api"/>
  • To use a base URL for all the API calls of all the External API, enter:
Copy
<add key="FTOS_IntegrationProcessBaseUrl" value="http://www.example.com/example_Api"/>

If multiple base URL definitions in the web.config file are applicable for the same API call, the first one will be applied.
BaseURL Base URL part of the API call's path ([base URL]+[endpoint]).
MethodName Endpoint part of the API call's path ([base URL]+[endpoint]).
HttpMethod HTTP request method used by the API call. Available options are: GET, POST, PUT, and DELETE.
hasHttpAuthentication Check to make httpAuthenticationType mandatory.
httpAuthenticationType Allows you to select Basic HTTP authentication based on user-id/password pairs (RFC7617) or Bearer tokens based authentication (RFC6750).

To configure a user-id/password authentication scheme, open the Innovation Studio web.config file in a text editor and add the following entries in the <appSettings> section:

Copy
<add key="FTOS_IntegrationProcessAuthUser_[<i>External API Detail Code</i>]" value="[<i>user-id</i>]"/>
<add key="FTOS_IntegrationProcessAuthPassword_[<i>External API Detail Code</i>]" value="[<i>password</i>]"/>

The External API's code and the API call's order number in the External API detail code are optional. For example:

  • To set credentials for the first API call in the P04 External API, enter:
Copy
<add key="FTOS_IntegrationProcessAuthUser_P04.01" value="guest"/>
<add key="FTOS_IntegrationProcessAuthPassword_P04.01" value="guest"/>
  • To set credentials for all the API calls in the P04 External API, enter:
Copy
<add key="FTOS_IntegrationProcessAuthUser_P04" value="guest"/>
<add key="FTOS_IntegrationProcessAuthPassword_P04" value="guest"/>
  • To set credentials for all the API calls of all the External API, enter:
Copy
<add key="FTOS_IntegrationProcessAuthUser" value="guest"/>
<add key="FTOS_IntegrationProcessAuthPassword" value="guest"/>

If multiple credentials in the web.config file are applicable for the same API call, the first one will be applied.
additionalHeaders Code for additional configurations to include in the HTTP request header.
StopOnError When checked, if an error occurs during the API call, the remaining API calls in the sequence will not be executed. Otherwise, the External API will attempt to run the next API call in the sequence.
beforeJS Custom JavaScript code to be executed before the API call. For details, see External API Call – Custom JavaSript Reference.
IMPORTANT!
When this page is saved/refreshed for the first time, the following code is automatically added in the beforeJS text box:
Copy
var instanceId = "$$instanceId$$";
var integrationProcessDetailId = "$$integrationProcessDetailId$$";
var contextEntityName = "$$contextEntityName$$";
var contextUniqueId = "$$contextUniqueId$$";
var runAsync = "$$runAsync$$";
var requestParamsBeforeJs = {};
requestParamsBeforeJs = $$requestParamsBeforeJs$$;

/*set token example*/ 
/*requestParamsBeforeJs["TOKEN"] = getAuthorizationTokenFromIntegrationProcessDetailId(instanceId, integrationProcessDetailId);*/ 

////mandatory return object
return {requestParams: requestParamsBeforeJs, skippedFromBeforeJs: false };
afterJS Custom JavaScript code to be executed after the API call. For details, see External API Call – Custom JavaSript Reference.
IMPORTANT!
When this page is saved/refreshed for the first time, the following code is automatically added in the afterJS text box:
Copy
var responseAsString = "";
responseAsString = $$responseAsString$$;
var instanceId = "$$instanceId$$";
var instanceDetailId = "$$instanceDetailId$$";
var contextEntityName = "$$contextEntityName$$";
var contextUniqueId = "$$contextUniqueId$$";
var runAsync = "$$runAsync$$";

var responseAsJson = JSON.parse(responseAsString);
log("responseAsJson:"+ toJson(responseAsJson));

/*save token example*/
/*
if(responseAsJson.TOKEN){
    update("FTOS_IntegrationProcessInstanceDetail", instanceDetailId, {authorizationToken: responseAsJson.TOKEN, authorizationTokenObtainedOn: responseAsJson.TOKEN_DATE});
}else{
resultAsjson.isSuccess = true;
resultAsjson.message = "Nu a putut fi obtinut tokenul:" + (responseAsJson.errorMessage?responseAsJson.errorMessage:"null");
}
*/
////mandatory return object
var resultAsjson = {};
resultAsjson.isSuccess = true;
resultAsjson.message = "!OK!";
return resultAsjson;
expiresInSecondsMultiplier The number of seconds after which the authentication token expires.
secToWaitBeforeStart Configures a delay in seconds before running the API call.
retryOnError Check to resend the API request if the API call fails (the resultAsjson object has the isSuccess key set to false). The number of retries is set by the numberOfRetries setting.
numberOfRetries Number of attempts to resend an API request if the API call fails (if the retryOnError setting is enabled).
secToWaitBeforeRetry Number of seconds to wait before resending an API request if the API call fails (if the retryOnError setting is enabled).
Pass response in main result Includes the API call's response in the response object of the External API. Otherwise, it will be available only within the External API's context in the responseAsJson variable in the afterJS setting.
logRequest Logs the call's HTTP request details in the FTOS_IntegrationProcessInstanceDetailLog entity for debugging purposes.
logResponse Logs the call's HTTP response details in the FTOS_IntegrationProcessInstanceDetailLog entity for debugging purposes.
External API Detail Parameters Defines the parameters that will be passed to the API endpoint. For details, see External API Call – Parameters.
External API Detail Dependencies Defines the API calls that must be completed successfully prior to running the current API call.
IMPORTANT!
If the dependency is based on a security context where the dependee call must pass an authorization token to the current API call, check the hasAuthorizationToken setting and add the following code in the beforeJS textbox:
Copy
requestParamsBeforeJs["TOKEN"] = getAuthorizationTokenFromIntegrationProcessDetailId(instanceId, integrationProcessDetailId);