Message Image  

App Connect

Using the Integration API with ACE v11 

Thu July 23, 2020 10:47 AM

Introduction

In IBM App Connect Enterprise V11.0.0.5, the Integration API has been re-introduced so that you can administer your integration nodes, integration servers and their deployed resources using a Java Application.

The REST Administration API is used by the Integration API to send requests and handle responses that are sent back.

Here is an example REST request being made using curl to a local integration node and the JSON response that is sent back. The same REST request can be made using Java through the Integration API and model classes are provided which allow you to easily access specific fields in the response.

New Classes in Integration API

In ACE v11.0.05, these new Java packages and classes have been provided:

com.ibm.integration.admin.proxy
This package has new classes to use for administering an integration node, integration server and deployed resources.

com.ibm.integration.admin.model
This package has classes which are a model representation of an integration node, integration server and deployed resources. You can use get methods to access specific properties.

com.ibm.integration.admin.http
This package has classes which allow you to send direct requests and receive responses to/from a local or remote integration node or integration server.

com.ibm.integration.admin.logger
This package has classes which allow you to enable service trace to log requests and responses between your Java client and the integration nodes or integration servers.

Classes in the package com.ibm.broker.config.proxy are now deprecated. Limited capability is supported in V11. You should now look to migrating your Java code to use classes in com.ibm.integration.admin.proxy instead.

The classes connect to the node or server over HTTP and issue REST requests to the integration node or integration server and process the REST responses. If the node or server is local, then the connection is made to a Unix Domain Socket or a Named Pipe (on Windows).

Pre-requisite JAR files

In order to use the Integration API to send REST requests and process the JSON responses, some JAR files must be added to your CLASSPATH. If you have run the mqsiprofile, then they are automatically added.

Proxy Classes

The IntegrationNodeProxy and IntegrationServerProxy classes in com.ibm.integration.admin.proxy are the starting point for using the Integration API.

You can connect to a local or remote integration node using the IntegrationNodeProxy class. It has the following constructors:

  1. To use the class from within a JavaCompute node, you can call the constructor without passing any parameters.
  2. To use the class with a local integration node, you just need to supply the name of the integration node.
  3. To use the class with a remote integration node, you need to supply the hostname and REST Admin API port. If Admin Security is enabled, then you need to supply the userid, password and a boolean to indicate whether to send the requests using HTTP or using HTTPS.

You can connect to a local or remote integration server using the IntegrationServerProxy class. Note that, you cannot connect to a node-owned server. It has the following constructors:

  1. To use the class from within a JavaCompute node, you can call the constructor without passing any parameters.
  2. To use the class with a local integration server, you just need to supply the name of the integration server and the location of the work directory.
  3. To use the class with a remote integration server, you need to supply the hostname and REST Admin API port. If Admin Security is enabled, then you need to supply the userid, password and a boolean to indicate whether to send the requests using HTTP or using HTTPS.

These ACE resources can be administered using the Integration API classes:

There is a proxy class for each of the main resource types:

Model Classes

Each proxy class has a corresponding model class for processing the JSON response:

To process the JSON responses, the model classes in com.ibm.integration.admin.model, can be used to drill down into each response section to extract the piece of information that you are trying to access.

For example, the JSON response for the query on the integration node that was shown at the top of this article is modeled by these classes in the com.ibm.integration.admin.model.node package.

Model Caching

Each proxy class will cache the model after it has been obtained from the integration node or integration server. Each call to get the properties has a refresh option. If you need to refresh the model, set refresh to true otherwise it will return the existing model.

Example Code

Here is a simple code snippet which shows how to get a proxy for a node-owned server called ‘Server1’ and then lookup a specific application called ‘myApp’ so that it can be stopped and then started again:

IntegrationServerProxy Class

The IntegrationServerProxy class allows you to administer several resources. There are getter methods for several resources:

You can use three different methods for deploying a BAR file:

  • Specify the File object for the BAR file
  • Specify an InputStream and the name of the BAR file
  • Specify the path to the BAR file

In addition, you can stop, start and delete deployed resources:

You can also stop and start an integration node owned integration server, but you cannot start/stop an independent integration server, in this case an exception will be thrown.
ApplicationProxy, RestApiProxy, ServiceProxy and MessageFlowProxy all have start/stop methods.

Debugging

Service trace can help diagnose any issues with your classes or help the IBM Support team to debug the issue. When running as a stand alone Java application, tracing can be enabled using IntegrationAPI.class contained in package com.ibm.integration.admin.logger:

Below is a sample service trace of a call to getIntegrationServerByName:

HttpClient and HttpResponse

In addition to the proxy and model classes, there are two classes called HttpClient and HttpResponse which can be used to send a direct REST request and then process the REST response. These classes underpin the proxy classes. You may want to use these classes if there is no specific method that you want to use in the proxy classes.

The HttpClient class can be used with a local or remote integration node or integration server. When accessing a local integration node or integration server, a Unix Domain Socket or Named Pipe is used.

HttpClient

The HttpClient allows you to use the different REST verbs: GET, POST, PATCH and DELETE on ACE resources:

HttpResponse

The HttpResponse class can be used to access the REST response. It can be be used to get the last URL request that was used by the IntegrationNodeProxy or IntegrationServerProxy by using the getUrlPath()

The parseResponseBody() method is useful to get a model representation of the response body, for example:

IntegrationNodeModel intNodeObject = lastHttpResponse.parseResponseBody(IntegrationNodeModel.class);

Example Code using HttpClient and HttpResponse

The following code snippet shows how you can use the HttpClient and HttpResponse classes. It sends a REST request to a Node-owned integration server and uses the IntegrationServerModel class to parse the response. This is the equivalent to using the IntegrationServerProxy class and is shown for comparison. Obviously, it is easier to use the IntegrationServerProxy class as it does the bulk of the work for you!

You may want to use the HttpClient and HttpResponse classes to access deployed resources which do not have proxy classes or models, for example deployed Policies or a specific Message Flow Node in a Message Flow.

Deprecated Classes

Classes in the package com.ibm.broker.config.proxy are deprecated. Some classes like BrokerProxy and ExecutionGroupProxy can be used but not all. One way to ease your migration is to use BrokerProxy::getNewIntegrationNodeProxy() or ExecutionGroupProxy::getNewIntegrationServerProxy() methods. These methods return an IntegrationNodeProxy or IntegrationServerProxy representation of the integration node or integration server. It is recommended to migrate to using classes in com.ibm.integration.admin.* packages.

Summary

In this article, I have described how to use the new packages and classes in the Integration API provided in App Connect Enterprise v11.0.0.5.

The classes in com.ibm.integration.admin.proxy and com.ibm.integration.admin.model packages allow you to administer your integration node or integration server and their deployed resources. The HttpClient and HttpResponse classes underpin the proxy classes. They can be used directly if required.

The classes in com.ibm.broker.config.* are deprecated. It is strongly recommended for Java applications to be migrated to use the new classes in the com.ibm.integration.admin.* packages.

You can read further information about the Integration API in the Knowledge Center here: https://www.ibm.com/support/knowledgecenter/SSTTDS_11.0.0/com.ibm.etools.mft.doc/be43410_.htm

You can view the Javadoc for the Integration API in the Knowledge Center here: https://www.ibm.com/support/knowledgecenter/SSTTDS_11.0.0/com.ibm.etools.mft.cmp.doc/index.html?view=embed

13 comments on"Using the Integration API with ACE v11"

  1. Vikash Dubey March 19, 2020

    Hi,

    In new IntegrationNodeProxy class only limited number of Methods are available, there is no such method to get IntegrationNode properties like, getShortDescription(), getLongDescription(),refresh(),getBrokerLongVersion(),disconnect(),getTargetHost(),getConfigurableServices()..etc. So, is there any way we can implements these methods in IBM ACE v11.0.0.7 .
    Same goes for IntegrationServers as well, com.ibm.integration.admin.proxy.* does not have enough methods for properties details of IntegrationServer, like we used to have in com.ibm.broker.config.proxy.* API .

    Reply (Edit)
    • SanjayNagchowdhury March 23, 2020

      Hi,

      There is no replacement for getShortDescription(),getLongDescription(),getBrokerLongVersion(),disconnect(),getTargetHost(),getConfigurableServices() methods in ACE v11.

      The Integration API in v11 uses REST calls to communicate with an Integration Node or Integration Server. If you start a node and issue a GET request on it (curl -X GET http://localhost:4418/apiv2) , you will get back:

      {
      “name”: “FP8_NODE”,
      “type”: “integrationNode”,
      “uri”: “/apiv2”,
      “properties”: {
      “defaultQueueManagerName”: “”,
      “httpConnectorPort”: 7080,
      “httpsConnectorPort”: 7083,
      “restAdminListenerPort”: 4418,
      “restAdminListenerIPCSocket”: “/Users/sanjayn/aceconfig/FP8_NODE.uds”
      },
      “descriptiveProperties”: {
      “productName”: “IBM App Connect Enterprise”,
      “version”: “11.0.0.8”,
      “buildLevel”: “ib000-L200318.17215 (S000-L200318.16524)”,
      “platformName”: “Mac OS X”,
      “platformArchitecture”: “x86_64”,
      “platformVersion”: “10.15.2”
      },
      “active”: {
      “processId”: “68363”
      },
      “children”: {
      “servers”: {
      “hasChildren”: true,
      “name”: “integration-servers”,
      “type”: “integrationServers”,
      “uri”: “/apiv2/servers”
      }
      }
      }

      These values are available through com.ibm.integration.admin.model.node.IntegrationNodeProperties and com.ibm.integration.admin.model.node.IntegrationNodeDescriptiveProperties

      If you wish to refesh your model of the Integration Node you can use: com.ibm.integration.admin.proxy.IntegrationNodeProxy:getIntegrationNodeModel(true) to refresh the node details.

      Please also note that Configurable Services are now replaced by Policies.

      You can interrogate Policies that are deployed using Java as well

      Hope that helps

      Thanks

      Sanjay

      Reply (Edit)
    • SanjayNagchowdhury March 23, 2020

      Please see my response to the comment by vikashkumar.dubey@hcl.com

      Reply (Edit)
  2. Tom Lowry December 27, 2019

    Is there a way to get the Deploy date for a message flow using the IntegrationAPI? I have found how to get the modified date using flowModel.getDescriptiveProperties().getLastModified() but I see no methods for getting the deploy date. I was able to do this in the IB10 API with thisFlow.getDeployTime() where thisFlow was a MessageFlowProxy object. I am trying to migrate some of my general utilities to ACE and would like to be able to query a message flow for the information. thanks.

    Reply (Edit)
    • SanjayNagchowdhury January 02, 2020

      Hi Tom,

      In ACE V11 we have moved away from storing meta-data alongside the artefacts we run.
      For a standalone integration server a user does not have to deploy.
      They can place the artefacts in the run directory and just run against them.
      Therefore in this scenario there is no concept of BAR file or deploy time for such a BAR file.

      In ACE V11, standalone servers and node owned servers share the same architecture.

      Currently, there is no method for getDeployTime() in ACE V11.
      We are looking into adding more in-depth logging capability.

      Once the capability is in place and exposed through our Administrative REST API, we will provide methods in the Integration API to access this.

      Thanks

      Sanjay

      Reply (Edit)
  3. DuaDua August 19, 2019

    So in this year, have any fixpack for modify UDF-Properties in runtime ? Because we need it in this year, for new project.

    Reply (Edit)
    • BenThompsonIBM August 20, 2019

      Hi DuaDua,
      Due to revenue recognition rules we’re unable to guarantee particular future features for specific dates … however we are very closely tracking the requirement (for delivery in a future v11 fix pack) for just such an action in the administrative REST API (and as per this article, also reflected in the Java integration API). It is likely that this POST action would be implemented to deliberately not persist flow UDP changes at server restart.
      Cheers,
      Ben

      Reply (Edit)
  4. Hiep August 12, 2019

    i’m using ACE v11.0.0.5
    i wan’t to use some funtions: getUserDefinedPropertyNames()/getUserDefinedProperty()/setUserDefinedProperty()
    i see at https://www.ibm.com/support/knowledgecenter/en/SSMKHH_10.0.0/com.ibm.etools.mft.doc/ac00325_.htm
    and do the tutorial
    But the packge MessageFlowProxy don’t have that function.
    Is it right ?
    And how can I get/set the UDPs from IBM API.
    thanks alots

    Reply (Edit)
    • BenThompsonIBM August 13, 2019

      Hi. In ACEv11.0.0.5 you can get the value of a user defined property using the REST API (HTTP GET http://localhost:4418/apiv2/servers/myservername/applications/myappname/messageflows/myflowname). The REST API capabilities are also available (FP5) directly through the Java Integration API. We don’t currently offer the equivalent to set the value of a user defined property, but this is a known requirement and is on our roadmap for a future fix pack.

      Reply (Edit)
  5. hung August 09, 2019

    I installed ACE 11.0.0.4. And I using this version.
    But I cant import package: com.ibm.integration.admin.proxy.*
    Maybe it not include this package.
    I just import pakage: com.ibm.broker.config.proxy.*
    I cant find the “admin” folder in install_dir\server\sample.
    Please, how can I import this packge ?

    Reply (Edit)
    • Ian_Larner August 09, 2019

      @hung,
      You need ACE v11.0.05.
      The new Java packages and classes were introduced with the Integration API in IBM App Connect Enterprise V11.0.0.5.
      Regards,
      Ian

      Reply (Edit)
  6. matthiasblomme August 01, 2019

    Are there any replacements for
    com.ibm.broker.config.proxy.BarEntry
    com.ibm.broker.config.proxy.BarFile
    com.ibm.broker.config.proxy.DeploymentDescriptor

    Or are they not being deprecated?

    Reply (Edit)
    • SanjayNagchowdhury August 05, 2019

      Hi Matthias,

      The classes and their methods are deprecated. What were you trying to do exactly with these classes?
      You can deploy a BAR file to an Integration Server using com.ibm.integration.admin.proxy.IntegrationServerProxy.deploy

      There is an example Java file which shows how to deploy in:

      /server/sample/admin/IntegrationAPI/DeployBAR.java

      Read Instructions.txt in the same directory. There are other examples in the same directory too.

      Thanks

      Sanjay

      Reply (Edit)

#AppConnectEnterprise(ACE)
#ACEV11
#integrationAPI
#integrationnodes
#rest_apis
#integrationservers
#Java