Create, Configure, and Call External APIs

External APIs are predefined collections of API calls that are executed in sequence within the same context, effectively turning FintechOS Studio into an API client with advanced capabilities.

Create External APIs

  1. Open FintechOS Studio in Developer mode and navigate to the Main Menu.
  2. Select Ecosystem > External APIs. This opens the list of external APIs.
  3. Click Insert to add a new External API. This opens the Add External API page.
  4. In the page that opens, enter a Code and, optionally, a Name for your External API.
  5. Click Save and Close.

This creates an empty External API. To add API calls to the External API, you need to configure the External API.

Configure External APIs

  1. Open FintechOS Studio in Developer mode and navigate to the Main Menu.
  2. Select Ecosystem > External APIs. This opens the External API List page.
  3. In the External API List, double click the External API you wish to edit. This opens the Edit External API page.
  4. In the External API Details grid:
    • To add a new API call to the pipe, click the Insert button.
    • To edit an existing API call, double click the API call from the grid.
  5. In the page that opens, fill in the API call's details and click the Save and Close button at the top right corner of the page when done. For details on how to set up an API call, see the following:
    SettingDescription
    CodeAPI call's code. This setting is filled automatically based on the following schema [External API code].[API call Order No.]. For details, see Create, Configure, and Call External APIs and OrderNo.
    NameEnter a descriptive name for API call.
    OrderNoThe 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 FintechOS 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_[External API Detail Code]" value=[base URL]/>

    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.

    BaseURLBase URL part of the API call's path ([base URL]+[endpoint]).
    MethodNameEndpoint part of the API call's path ([base URL]+[endpoint]).
    HttpMethodHTTP request method used by the API call. Available options are: GET, POST, PUT, and DELETE.
    hasHttpAuthenticationCheck to make httpAuthenticationType mandatory.
    httpAuthenticationTypeAllows 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 FintechOS Studioweb.config file in a text editor and add the following entries in the <appSettings> section:

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

    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.

    additionalHeadersCode for additional configurations to include in the HTTP request header.
    StopOnErrorWhen 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.
    beforeJSCustom 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 };
    afterJSCustom 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;
    expiresInSecondsMultiplierThe number of seconds after which the authentication token expires.
    secToWaitBeforeStartConfigures a delay in seconds before running the API call.
    retryOnErrorCheck 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.
    numberOfRetriesNumber of attempts to resend an API request if the API call fails (if the retryOnError setting is enabled).
    secToWaitBeforeRetryNumber of seconds to wait before resending an API request if the API call fails (if the retryOnError setting is enabled).
    Pass response in main resultIncludes 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.
    logRequestLogs the call's HTTP request details in the FTOS_IntegrationProcessInstanceDetailLog entity for debugging purposes.
    logResponseLogs the call's HTTP response details in the FTOS_IntegrationProcessInstanceDetailLog entity for debugging purposes.
    External API Detail ParametersDefines the parameters that will be passed to the API endpoint. For details, see External API Call – Parameters.
    External API Detail DependenciesDefines 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);

    This screen configures each parameter that will be populated and passed by the API call to the REST API web service. Parameter settings must match the specifications of the called REST API.

    Parameter SettingDescription
    IntegrationProcessDetailAPI call's code (see Code).
    ParameterType
    • Query – Parameter is appended to the API call's path.
    • Body – Parameter is passed in the HTTP request body.
    • Formdata – Parameter is passed using the multipart/form-data media type.
    isMandatoryParameter is mandatory.
    isEnumListCheck if the Body type parameters are passed in the HTTP request in enumeration format (a single line JSON such as {firstName: "John", lastName: "Doe"}).
    NameParameter name.
    IsAuthentificationUserApplicable for all non-Body parameters with isEnumList not checked.
    IMPORTANT!  
    Do not set user-id static parameters in this screen. See httpAuthenticationType for details on how to configure authentication credentials.
    IsAuthentificationPasswordApplicable for all non-Body parameters with isEnumList not checked.
    IMPORTANT!  
    Do not set password static parameters in this screen. See httpAuthenticationType for details on how to configure authentication credentials.

    You can use the beforeJS and afterJS settings to set up custom JavaScript code to be executed before and after an API call. The following objects are available in this context:

    ObjectDescription
    instanceIdID of the External API instance.
    integrationProcessDetailIdID of the API call.
    contextEntityNameName of the entity for which the External API is run.
    contextUniqueIdID of the contextEntityName record.
    runAsyncEither true or false depending if the External API is run asynchronously or not.
    requestParamsBeforeJsIncludes static parameters and their values to be passed to the HTTP request.
    requestParamsParameter - value pairs to be passed to the API call. You can edit this object to include requestParamsBeforeJs and/or dynamic parameters, such as an authentication token obtained in a prior step or values from the contextEntityName record.
    IMPORTANT!  
    This is a mandatory object that must be returned by the beforeJS code.
    skippedFromBeforeJsIf set to true, the API call is skipped. Otherwise, it should be set to false.
    IMPORTANT!  
    This is a mandatory object that must be returned by the beforeJS code.
    responseAsStringHTTP response of the API call in string format.
    resultAsjsonIndicates if the API call was successfull (resultAsjson.isSuccess = true;) and the response message (resultAsjson.message = "!OK!";).
    IMPORTANT!  
    This is a mandatory object that must be returned by the afterJS code.

Call External APIs

To call a External API, use the FTOS_IntegrationProcessLibrary object and callIntegrationProcess method:

Copy 
var integrationProcessId = FTOS_IntegrationProcessUtils.getIdFromCode("FTOS_IntegrationProcess", "code", restPipeCode);
var ip = new FTOS_IntegrationProcessLibrary();
ip.logEnabled = false;            
var response = ip.callIntegrationProcess(integrationProcessId, contextEntityName, contextUniqueId, requestParams, runAsync);
 

where:

ParameterDescription
integrationProcessIdExternal API ID based on the pipe's code (see Create, Configure, and Call External APIs for details).
contextEntityNameName of the entity for which the External API is run.
contextUniqueIdID of the contextEntityName record.
requestParamsIncludes static parameters and their values to be passed to each API call in the following format:
Copy
requestParams[External API code].[API call Order No.] = {[parameter 1]:[value 1], [parameter 2]:[value 2], ...};

For example:

Copy
requestParams["P01.01"] = {CUI: "36438401", CNP: "78787878"};
requestParams["P01.02"] = {CUI: "36438401", CNP: "78787878"};

These parameter values will be available in the API call's custom JavaScript code in the requestParamsBeforeJs object.

runAsyncIf set to true, runs the External API as an asynchronous process.
responseThe resulting response of the External API call will have the following format:
Copy
response:{
    "ipInstanceId": "523ee20b-705c-45b3-b881-caeec1bde15e",
    "isSuccess": true,
    "errorMessage": null,
    "mainResponse": {
        "P04.02": {
            "requestId": 89696.0,
            "errorMessage": null,
            "IsSuccess": true
        }
    }
}
Copy
var ip = new FTOS_IntegrationProcessLibrary();

var integrationProcessId = FTOS_IntegrationProcessUtils.getIdFromCode("FTOS_IntegrationProcess", "code", "P04");
var requestParams = {};
requestParams["P01.01"] = {CUI: "36438401", CNP: "78787878"};
requestParams["P01.02"] = {CUI: "36438401", CNP: "78787878"};

ip.logEnabled = true;
var response = ip.callIntegrationProcess(integrationProcessId, "P666", "31a85d94-0c9c-429b-8bc6-8c4a5e2d91a7", requestParams, false);