Integration service web page

The integration service web page contains links to the JavaScript client API file, details of the JavaScript client API methods, details of the errors that might be returned from the integration service, and sample code that a JavaScript developer can add to a JavaScript application to call the JavaScript client API.

The integration service web page is described using an example integration service. The following screen capture shows the configuration of the example integration service in the IBM App Connect Enterprise Toolkit.
The image is a screen capture of an integration service that is defined in the IBM App Connect Enterprise Toolkit.
When a JavaScript client API is generated, you can access the integration service URL by using a web browser, and then click the JavaScript Client API link to display the web page. The web page has two sections.
File
The File section contains a link to the service_name.js file, where service_name is the name of the integration service. In the example, the file is called creditReport.js. The file can be downloaded by clicking the link.
Note: You only need to download the file if you are developing a Node.js application.
Methods
The Methods section contains details of each method that is defined in the integration service. If there is more than one method that is defined in the integration service, then, at the top of the section, there are links to each method and you can click a link to navigate directly to the detail of the associated method.

For each method, there is a description, a list of the input and output objects, and any faults that are defined. The following image shows an example of a method, with the names of the input and output objects, and the names of two defined faults.

The image is described in the surrounding text.
For each method, there is a coding sample that you can copy and paste into your JavaScript application. The coding sample includes the following elements:
  • Sections that you might need to uncomment, depending on whether you are developing a JavaScript application for a Node.js environment, or for a web browser environment.
  • A comment that details the structure of the output variable, so that you know how to retrieve data from the integration service response.
  • One or more comments that detail the structure of any possible faults, so that you know how to handle errors that are returned from the integration service.
    Note: There is always a fault definition (unexpected error JSON variable) to represent any exception that is generated by IBM App Connect Enterprise. For more information about the different types of exceptions you might receive, see Exception list structure and Exception list tree. There might be one or more fault definitions (fault JSON variables) to represent any fault that is defined in the integration service.
  • Code for the input JSON variable. You amend the values for each element to be the values that you want to send to the integration service.
  • Code for the JavaScript routine that calls the integration service.

For information about the JSON conventions that are used in the JavaScript client API, and the limitations that are associated with the use of the API, see JSON conventions for calling an integration service by using a JavaScript client API.

The following is the coding sample for one of the methods that is defined in the example integration service:
/* Uncomment these lines if you are developing in a Node.js environment.

require("http");
require("./creditReport");

IBMIntegration.creditReport.IBMContext.hostname = "myhost.company.com";
IBMIntegration.creditReport.IBMContext.port     = 7800;			

*/

/* Uncomment these lines and put them in the <head> element of your HTML if you are developing in a browser environment.

<script type="text/javascript" src="/creditReport?resource=dojo.js"></script> 
<script type="text/javascript" src="/creditReport?resource=creditReport.js"></script>  

*/

/* This is an example of the output JSON variable.

var getApprovalResponseVar = 
{
  "approval" : 
  {
    "customer" : 
    {
      "id" : "idValue" , 
      "fName" : "fNameValue" , 
      "lName" : "lNameValue"
    } , 
    "account" : 
    {
      "sortCode" : "sortCodeValue" , 
      "accNo" : "accNoValue" , 
      "accType" : "accTypeValue"
    } , 
    "approved" : true
  } , 
  "balance" : 
  {
    "customer" : 
    {
      "id" : "idValue" , 
      "fName" : "fNameValue" , 
      "lName" : "lNameValue"
    } , 
    "account" : 
    {
      "sortCode" : "sortCodeValue" , 
      "accNo" : "accNoValue" , 
      "accType" : "accTypeValue"
    } , 
    "balance" : 1.0
  }
};

*/

/*  This is an example of the unexpected error JSON variable. 
    The penultimate property contains the actual exception thrown in IIB. 
    Search the product documentation for 'exception list structure' to view 
    the different types of exceptions and their contents. 

var unexpectedErrorVar = 
{
  "errName" : "Exception",
  ...
  "Label" : "{Label of the node where the exception occurred}",
  ...
  "{Exception name}" : {// penultimate property
      ... exception details ...      
  },
  "Input" : {
      ... input message that caused this exception ...
  }
};


*/

/* This is an example of the fault JSON variable.

var getApprovalFault1Var = 
{
  "errName" : "getApprovalFault1",
  "getApprovalFault1" : "getApprovalFault1Value"
};

*/

/* This is an example of the fault JSON variable.

var getApprovalFault2Var = 
{
  "errName" : "getApprovalFault2",
  "getApprovalFault2" :   {
    "identifier" : "identifierValue" , 
    "message" : "messageValue"
  }

};

*/

/* This is an example of the input JSON variable. */

var getApprovalVar = 
{
  "customer" : 
  {
    "id" : "idValue" , 
    "fName" : "fNameValue" , 
    "lName" : "lNameValue"
  } , 
  "account" : 
  {
    "sortCode" : "sortCodeValue" , 
    "accNo" : "accNoValue" , 
    "accType" : "accTypeValue"
  }
};


IBMIntegration.creditReport.getApproval( getApprovalVar, function( err, getApprovalResponseVar ){

  if (err) {
    console.log(" Failure for IBMIntegration.creditReport.getApproval() ");
    var errName = err.errName;
    if ( errName == "getApprovalFault1") {
      console.log("Fault getApprovalFault1 occurred.");
    }
    else if ( errName == "getApprovalFault2") {
      console.log("Fault getApprovalFault2 occurred.");
    }
    else if ( errName == "Exception") {
      console.log("Unexpected error occurred.");

      //To see the full details of the error, use JSON.stringify(err);

      //To retrieve only the exception, navigate to the penultimate property within the error
      var keys = Object.keys(err);
      console.log("Exception type: " + keys[keys.length-2]);
    }
  }
  else {
      console.log(" Success for IBMIntegration.creditReport.getApproval() ");
  }
} );