The customer exit of the Application Integrator

[Former Member]

I'm sure you all know the How-To-Guide regarding the Application Integrator. If not, go to https://service.sap.com/ep60howtoguides and download the file "Using the Application Integrator". I'm referring to this document, so read it first if you don't know it.

Basically the AppIntegrator is kind of an URL iView, an iframe with a set of properties, but much more powerful. Moreover, it's possible to create SSO to the external application.

With the Generic component of the Application Integrator, you are able to integrate external web applications and pass arbitrary parameters. Since you want to invoke a web application in an iframe, you have to assemble a http request. Therefore, you use the URLTemplate property of the generic component.

"URLTemplate: Defines a template that is processed by the template processor in order to generate the application url"

How the template processor works is described in chapter 4.3 of the referenced document. You can use tags to add variables to your template. There are a lot of pre-defined tags and context that you can use, e.g. . You also can use arbitrary tags like .

The template processor will try to resolve the variable foo in the following way:

1. He will look for a custom provider that returns a String for the input parameter "foo". (if enabled, see General Configuration) 2. He will look for a request parameter called "foo". 3. He will look into the component profile, if a property called "foo" is present.

This weblog is especially about the custom provider of the Application Integrator which has to be implemented according to the description in chapter 6 of the referenced document.

I encounter questions about the customer exit regularly in the forums, so I decided to explain it step by step in this weblog.

Let's start with the assumption, that you have a web application that you want to integrate with the generic component and your URLTemplate looks like this:

<System.protocol>://<System.server><System.uri>?superparam=<foo>

<System.[SystemPropertyName]> stands for the system landscape context, the prerequisites are:

• you have to enter a system alias in the component property "System"
• you have to use a system template, were the properties "protocol", "server" and "uri" are present (otherwise you'll get an exception "invalid terminal property...")
  
  <foo> is resolved according to the way described above (see image). If the template processor gets null in every of the 3 steps, he will throw an exception ("Unable to process template [...] because <foo> is an invalid terminal property of the context...").
  
  Now we want to fill "foo" with a custom provider, because we have to do some processing to calculate the value or the value is simply not available in one of the pre-defined contexts.
  
  
  Implementing the provider
  
  Open your Netweaver Developer Studio and create a new Portal Application Project. As the next step you have to adjust the build path of your application. Open your project properties, go to "Java Build Path" and open the tab "Libraries". There you can add the appintegrator libraries as external jars or via a variable. You have to add the com.sap.portal.appintegrator_api.jar to the build path, it's located in com.sap.portal.appintegrator/lib in your portalapps directory.
  Then, use the wizard to create a new Portal Service. Call it however you like, I call it FooProvider for now.
  In order to use this portal service as a custom provider you have to implement the interface ICustomerParameterProvider.
  
  IFooProvider now looks like this:
  
  package com.sap.karsten;
  
  import com.sapportals.portal.appintegrator.parameter.ICustomerParameterProvider;
  import com.sapportals.portal.prt.service.IService;
  
  public interface IFooProvider extends IService, ICustomerParameterProvider
  {
    public static final String KEY = "com.sap.karsten.FooProvider";
  }
  
  
  Next, we have to implement the methods of ICustomerParameterProvider. Go to your imlementing class, click on "Source" -> "Implement Methods" and select all methods of ICustomerParameterProvider.
  
  The only method of interest is for now getParameter(..). For getProviderName() I simply return the service name(return mm_serviceContext.getServiceName();) for all other methods I return null.
  
  The template processor will call getParameter("foo") to resolve the tag <foo>. Now it's our turn. If we return null, the template processor will proceed and look into the request. If we return a String, the template processor will replace the tag <foo> with the returned String.
  
  This is how my getParameter(..) method looks now:
  
  public String getParameter(IPortalComponentRequest request, String id) throws Throwable
  {
    if("foo".equals(id))
    {
      return doSomeCalculations(request, id);
    }   else
    {
      return null;
    }
  }
  private String doSomeCalculations(IPortalComponentRequest request, String id)
  {
    String value = "some_calculated_stuff";
    return value;
  }
  
  
  Since getParameter(..) is called for every(!) property, it's really important to leave the method as soon as possible and return null for other properties than "foo". Doing calculations for every property can be very expensive!!
  
  In the case that the FooProvider is called with a property id "foo", you can calculate the value and return it. You've got a reference to the request object, so you really can do a lot of different stuff here.
  
  At last, we have to edit the portalapp.xml to register the FooProvider. How to do this is explained in chapter 6.1.1 of the referenced document, my portalapp.xml for the FooProvider now looks like this:
  
  <?xml version="1.0" encoding="utf-8"?>
  <application>
    <registry>
      <entry path="/com.sap.portal.appintegrator/customer_exits/parameter_provider/foo" name="FooProvider" type="service"/>
    </registry>
    <application-config>
      <property name="SharingReference" value="com.sap.portal.appintegrator"/>
      <property name="startup" value="true"/>
    </application-config>
    <components/>
    <services>
      <service name="FooProvider">
      <service-config>
        <property name="className" value="com.sap.karsten.FooProvider"/>
      </service-config>
      </service>
    </services>
  </application>
  
  
  The FooProvider is ready to deploy now.
  After deployment, you can check the successful registration in the portal registry browser.
  Go to "System Administration" -> "Support" -> "Support Desk" -> "Portal Runtime" -> "Portal Registry Browser" and navigate to the path "ROOT/com.sap.portal.appintegrator/customer_exits/parameter_provider"
  
  
  
  There you should see your Provider. In my example simply "foo".
  
  
  Testing the Provider
  
  In SP2 custom providers are enabled by default. Moreover, every appintegrator component will call the custom provider for every property. This can be a big performance hit! Therefore, in Netweaver releases you have a iview property "Customer Exits for 'ParameterProvider'", where you determine which provider the iview should use. In my example it's "foo", because I registered the FooProvider with the name "foo".
  
  Ok, the custom provider is deployed, registered and referenced in the iview. Now it's time to do a test. The tag <foo> should be resolved now. If there are still problems, you might activate the debug mode of the appintegrator (see Debug Mode).
  
  
  General Configuration
  
  As a prerequisite for using custom providers you have to enable them (for NW releases, for SP2 it's enabled by default).
  Go to "System Administration" -> "System Configuration" -> "Service Configuration" and open "Applications" -> "com.sap.portal.appintegrator" -> "Services" -> "Common_Configuration".
  There you set the property "Use_CustomerExit_ParameterProvider" to "true" and save.
  
  
  
  Next, restart the application by right-clicking "com.sap.portal.appintegrator" -> "Administrate"
  There you can restart the appintegrator and your change takes effect.
  
  
  
  
  Debug Mode
  
  Go the Common_Configuration just like it's described in "General Configuration" and set the property "DebugMode" to "true". Then restart the appintegrator like it's described in "General Configuration". When you launch the iview now, the debug screen is shown first and you can check your parameters and how they were resolved.
  
  
  
  Conclusion
  
  You should now be able to pass arbitrary parameters to any kind of web application. But that's not all. BWReports, BSPs, Web Dynpros, Transaction iviews etc - they are all integrated with appintegrator. Of course you can use custom providers there, too! I once implemented a custom provider, that switched the value of the iview property "System" dynamically. It was possible to connect different users to different backends with a single iview. It was also possible to switch to a different backend system at runtime with a dropdown box. How cool is that? I'm sure you get even better ideas what to accomplish, just think about it 😉
  
  Cheers, Karsten