webMethods API Portal tutorial
The detault installation of API Portal has below list of predefined views:
- Home view (Default landing page)
- Gallery (API Gallery/ App Gallery / Package Gallery)
- Details view (API details / Application details / Package details )
- Tryout view
- Administraion settings view
- Managing APIs view
- Dashboard
- Pending approval view
- My activity stream view
- Terms and conditions view
- 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.
- We would like to access the static page from the top level navigation entry with in API Portal
- 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> |
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.
