OpenAPI Apps

OpenAPI apps use the flexibility of OpenAPI queries to deliver and present data in a highly customizable way.
capm360
HID_OpenAPI_Applications
OpenAPI apps use the flexibility of OpenAPI queries to deliver and present data in a highly customizable way. OpenAPI apps allow custom content to be served to OpenAPI app views on dashboards and context pages. You can build your own apps or you can select from various available apps. You can then deploy and display these apps in
NetOps Portal
.
The following video demonstrates how to download, deploy, and add OpenAPI apps to
NetOps Portal
:

In this article:
OpenAPI App Development
OpenAPI apps are made up of HTML, JavaScript, CSS, and metadata contained in a zip file. Generally, apps use
NetOps Portal
web services and OpenAPI.
Use the following process to guide you through the OpenAPI app development and testing process:
  1. If one exists, find a similar OpenAPI app to use as the basis for your new app.
  2. Set up a local folder to house the files for the app. Use a single directory that contains all the required directories and files for the app.
  3. Create the
    appConfig.properties
    file. This properties file is required for deployment in
    NetOps Portal
    and for the App View. See the following documentation for information about the contents of this file.
    The
    appConfig.properties
    file must reside in the top-level single directory referenced in the previous step.
  4. Use OpenAPI QueryBuilder to create sample OData queries for your app. Save the output from these queries as to a static file. Start developing your code with the static data.
    After development, static data is useful for debugging to ensure that your parsing code works correctly.
  5. Build a demo page. Ensure that the page can load the static data. Also, ensure that it can save the data to a variable attached to the window object. To enable browser debugging tools, add the debugger statement in the JavaScript code. Use the browser debugging tool to look at the data that came over, and verify that part of the app worked.
  6. Start parsing parameters. Include the URL you used to get the original data, and use a parameter to switch into debug mode. Use parameters from the URL to the build OpenAPI query. Use the console.log function to log any URL to the console, such as console.log("url: " + url).
  7. Pick the JavaScript libraries that you want to use for your app. Look at existing apps for examples and copy the libraries into your app folder. Remove unnecessary files.
  8. Start writing the app.
    • If the data includes multiple items, start with one item first.
    • At this stage, do not focus on the app appearance. However,
      do
      include CSS classes in the resulting HTML to make it easier.
    • Put your labels in a single place in your code, in case you localize the app.
  9. When you have something working, deploy the app to your
    NetOps Portal
    test system. Verify that it works on a remote server. If you refactor your code to get it to work remotely, there is less code to refactor at this stage.
  10. Zip the app folder, including the properties file and deploy the app through the UI.
  11. To test the app in the UI, create a dashboard, and add two app views to the dashboard. Edit one of the app views, and select your app from the drop-down list. If the app does not appear in the drop-down list, something in the
    appConfig.properties
    file is incorrect.
    After the app appears in the first view, edit the other app view and add the same app. This test ensures that the app can support multiple instances on a single page.
  12. Continue to work locally, and periodically redeploy the app to the test system. If you update the URL in the metadata, edit the app view. Reselect the app to get the updated URL.
  13. Use a more restricted user account to verify that the app still works correctly. If your app is context or time range aware, change the associated controls and verify that your app responds correctly.
  14. If appropriate, use the redirector to add context page links to your app. The redirector makes the app feel like a native part of the system.
  15. When the app is complete, consider contributing your app to the GitHub repository for others. Before you add the app to the repository, remove any personal information.
The Format for the appConfig.properties File
Use the following format for the
appConfig.properties
file:
appName=
App Name
description=
Optional app description
url=
Required_URL_parameters
height=
height in pixels
supportedContext=
context_code
  • appName
    A unique name for the app
  • (Optional)
    description
    A description that appears in the App View when you select the app
  • url
    The app URL and URL parameters
    For information about URL parameters in
    NetOps Portal
    , see Browser Views.
  • (Optional)
    height
    The height of the app view in pixels
    Default:
    250
  • (Optional)
    supportedContext
    The context where the app appears in the app view. You can use this parameter to restrict the available apps to specific contexts. For example, if you specify only value
    i
    , the app is available only in app views on interface context pages and the app is unavailable at the dashboard level.
    Values:
    • d:
      Device
    • i:
      Interface
    • s:
      Server
    • r:
      Router
    • g:
      Group
    • nc:
      None, appears in all contexts
    Default:
    nc
    To designate multiple contexts, separate the values with a comma.
Example:
appName=Percentile Trend App description=This is a Percentile Trend App url=index.html?id={ItemIdDA}&startTime={TimeStartUTC}&endTime={TimeEndUTC}&metric=im_UtilizationIn height=750
supportedContext=i,d
App Development Best Practices
Use the following best practices for developing OpenAPI apps:
  • Use only internally-sourced JavaScript libraries. If you need libraries for your app, include the library in the app folder. Also include any files that describe the license terms of the library.
  • To avoid the app from breaking, do no use any
    NetOps Portal
    JavaScript, CSS, or images.
  • Test the app to verify that it works at scale and with different configurations. Many apps depend on system resources, such as web services. Verify that the app is not generating unnecessary load.
  • Build test modes into the app to help debug problems. Add an optional parameter that switches the app from using a web service API to a canned set of data included in the app.
  • If you distribute the app to other users, verify that no private information is included. Sanitize the static data files that are included for debugging.
  • Use relative paths and never include the full URL. If the system is behind a firewall, or changes DNS names, using full URLs breaks the app. Using relative paths helps the transition between working locally and then deploying the app.
  • Verify that the app works in an iframe. Both the Browser View and App View use iframes to isolate the apps from the rest of the page.
  • The OpenAPI uses Data Aggregator item IDs.
    NetOps Portal
    IDs are not recognized. Use the Data Sources web services to convert between the Data Aggregator item ID and the
    NetOps Portal
    ID. For more information, see Data Sources Web Service.
  • To access OpenAPI data, the request must come from an app on the
    NetOps Portal
    host. The app deployment places the app folder on the
    NetOps Portal
    host.
  • For direct OData queries in the apps, use the relative path for the
    NetOps Portal
    system to use the OpenAPI proxy:
    /pc/odata/api/...
Download an App
Various apps are available on GitHub. These applications are supported through GitHub open-source collaboration:
Copyright (c) 2018 CA Technologies
The MIT License
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
Follow the steps:
  1. Go to https://github.com/CA-PM.
    A list of available apps with descriptions appear.
  2. Click the app that you want to download.
    The contents of the app, a sample visualization, and readme instructions appear.
  3. Click
    Clone or download
    , and then
    Download ZIP
    .
  4. Save the files to your preferred directory.
The app is downloaded.
Deploy an App
To deploy OpenAPI apps, load the app through
NetOps Portal
. You can deploy apps while the system is running. App deployment does not require a restart. For successful deployment, the app must meet the following requirements:
  • The app files are contained in a single folder.
  • The folder includes the
    appConfig.properties
    file.
  • The app folder is zipped in a ZIP file.
  • The maximum ZIP filesize is 100 MB.
This procedure requires the Administrator role.
Follow the steps:
  1. Hover over
    Administration
    ,
    Configuration Settings
    , and then click
    App Deployment
    .
  2. Click
    Browse
    , select a zipped app, and then click
    Open
    .
  3. Click
    Add
    .
    The app is copied to the user app directory. Use the App Viewer to show the app in
    NetOps Portal
    .
Display an App in
NetOps Portal
Use the app view in
NetOps Portal
to display an app.
PDF and CSV printing and emailing options are unsupported for app views.
Follow the steps:
  1. Add or edit a dashboard or page for the intended item context.
  2. Add an app view for the app.
  3. Select the app for the view.
  4. Update the parameters and height as desired.
  5. Click
    Save
    .