Adding a new static HTML content to webMethods API Portal

webMethods API Portal tutorial

The detault installation of API Portal has below list of predefined views:

  1. Home view (Default landing page)
  2. Gallery (API Gallery/ App Gallery / Package Gallery)
  3. Details view (API details / Application details / Package details )
  4. Tryout view
  5. Administraion settings view
  6. Managing APIs view
  7. Dashboard
  8. Pending approval view
  9. My activity stream view
  10. Terms and conditions view
  11. Support view

If there some minor changes that we would like todo in above views, we can use the Self Service Cusomization (SSC) todo the changes. Often times preshipped views may not be sufficient enough. Often we would like to add a free-flow static content with your API Portal. As part of this article we will try exploring a way to add new HTML static content to webMethods API Portal.

Requirements

For the sake of demo, we will take a case study where we would like to include a static HTML content within API Portal. Assuming that the static page provides some detailed information about different developers who contributed for the APIs listed on your Portal. 

  1. We would like to access the static page from the top level navigation entry with in API Portal
  2. Static content only be visible to a authenticated users only.

For simplicity we will refer Copernicus portal home as $COP_HOME = $$SoftwareAG\API_Portal\server\bin\work\work_apiportalbundle_s\base\webapps\ROOT

Adding new view

Template

Template contains the static HTML content for rendering the new page. You can create the new view template in $COP_HOME\WEB-INF\config\apiportal\templates (team.html)

<div id="api-header-container"></div>
<div class="container-fluid">
.........
</div>
<div id="api-footer-container"></div>

As we can see above the template contains two placeholder div elements for the inclusion of header/footer view. Other than those two, the static content that we would like to create can be placed as it is in the template file. The sample used in this demo is accessible here.

View configuration

View configuration dictates how the view is composed. In our case, the new view being introduced ("team") view is composed of 

  • header view
  • main content
  • footer view

Create the view configuration file $COP_HOME\WEB-INF\config\apiportal\views (team.xml)

<?xml version="1.0" encoding="UTF-8"?>
<view instance="team" istop="true" sscCustomizable="true" sscDisplayName="team" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="xsd/view.xsd" version="0.0.3">
    <layout xsi:type="template">
        <property name="template" file="team.html"/>
        <!-- Header View -->
        <view ref="apiHeader" instance="apiHeaderInstance">
            <property name="tplContainerId" value="api-header-container"></property>
        </view>
        <!-- Footer View -->
        <view ref="apiFooter" instance="apiFooterInstance">
            <property name="tplContainerId" value="api-footer-container"></property>
        </view>
    </layout>
   <wires></wires>
</view>

As we can see above, the new view(team) includes the view reference to header(apiHeader) and the footer(apiFooter) and refers the template created in previous step. 

Note: name of this file(team.html) and name of the view(team) must be matching. With these two file changes we are almost 80% done on our journey to introduce a new view.

Top level navigation

We would like to display the "Team" link as part of top level navigation component which is inside the header view.

Add a new entry for the top level navigation components instance configuration located in $COP_HOME\WEB-INF\config\apiportal\instances\topLevelNavigation (apiHeaderInstance-topLevelNavigation1.xml)

<?xml version="1.0" encoding="UTF-8"?>
<topLevelNavigationInstance showText="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="xsd/topLevelNavigation.xsd" version="0.0.2" collapsible="true">
    <entry>
        <view>gallery</view>
        <name>base.topLevelNavigation.gallery.DBI</name>
    </entry>
    <entry>
        <view>packages</view>
        <name>base.topLevelNavigation.domains.DBI</name>
    </entry>
    <entry>
        <view>apps</view>
        <name>base.topLevelNavigation.mashup.DBI</name>
    </entry>
    <entry>
        <view>support</view>
        <name>base.topLevelNavigation.support.DBI</name>
    </entry>
    <entry>
        <view>team</view>
        <name>base.topLevelNavigation.team.DBI</name>
    </entry>
</topLevelNavigationInstance>

Create localization content

We would like to have a localizable content in the top level navigation and hence we need to provide a localized content for the key we have provided in previous step. Create a  localization entry in  $COP_HOME\WEB-INF\config\apiportal\localization\plugin\base(base.properties)

base.topLevelNavigation.team.DBI=Team

Enforce ACL

We would like to make the view to be visiible only to registered users. To make the new view only to be visible to registered users we need to have the entry in role configuration file located in $COP_HOME\WEB-INF\config\apiportal\roles. Below table summarizes the roles and corresponding configuration files.

Role mapping

Role file
Guest(Unauthenticated user) rd_guest.xml
Consumer(Registered user) rd_viewer.xml
Provider rd_admin_publishing.xml
Administrator rd_admin_portal.xml

In our case, we would like to show the view only to registered users and not expose to unauthenticated users. So we can create a entry in rd_viewer.xml by specifying the view id(team).

Reload configuration

Congratulations. Almost done!!  Now to make the file level changes to take effect navigate to http://host:port/#default/reloadConfig and reload the configuration changes.

Solution we built so far

Caution: As we have seen this approach is based on modification sets(which are file based configurations). The fixes for webMethods API Portal refreshes the configuration files as part of fix installation. This might cause the changes that we have done in above steps to be lost and we might have to redo it after fix install.

team.html (3.5 KB)

team.xml (773 Bytes)