PingGateway 2024.11

Create and edit routes with Structured Editor (deprecated)

This section describes basic tasks for creating and deploying routes in the structured editor of Studio.

The structured editor of Studio is deprecated. For more information, refer to the Deprecated section of the Release Notes.

Creating simple routes

  1. In PingGateway Studio, create a route:

    1. Go to http://ig.example.com:8080/openig/studio, and select Create a route.

    2. Select Structured to use the structured editor.

  2. Enter the URL of the application you want to protect, followed by a path condition to access the route. For example, enter http://app.example.com:8081/my-basic-route.

    The route is created, and menus to add configuration objects to the route are displayed.

  3. On the top-right of the screen, select and Display to review the route.

    A route similar to this is displayed, where the path condition is used for the route name:

    {
  "name": "my-basic-route",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/my-basic-route')}",
  "handler": "ReverseProxyHandler"
}

Change the basic settings of a route

  1. In Studio, select ROUTES, and then select a route with the icon.

  2. On the top-right of the screen select Route settings.

  3. Using the on-screen hints for guidance, change the name, condition, or other features of the route, and save the changes.

  4. On the top-right of the screen, select and Display to review the route.

Adding configuration to a route

After creating a route in the structured editor, you can add filters, decorators, scripts, and other configuration to the route.

Add other configuration to a route

  1. In Studio, select ROUTES, and then select a route with the icon.

  2. Select one of the configuration options, and follow the on-screen hints to select configuration settings.

    For routes to test with the examples in the Gateway guide, refer to Example routes created with Structured Editor (deprecated).

Add other filters to a route

Use this procedure to add any filter type to the configuration.

  1. In Studio, select ROUTES, and then select a route with the icon.

  2. Select Other filters > New filter > Other filter.

  3. In Create filter, select a filter type from the list, enter a name, and optionally enter a configuration for the filter.

    Studio checks that the JSON is valid, but doesn’t check that the configuration of the filter is valid. If the filter configuration isn’t valid, when you deploy the route it fails to load.

    When you save, the filter is added to the list of other filters but is not added to the configuration.

  4. Enable the filter to add it to the configuration.

    If you disable the filter again, it is removed from the route’s chain but the configuration is saved. Simply enable the filter again to add it back in the chain.

Managing the route chain

The Chain view lists the filters in the order that they appear in the configuration.

Some filters have a natural position in the chain. For example, so that an authenticated user is given the correct permissions, an authentication filter must come before an authorization filter. Similarly, so that an authorization token is transformed, an authorization filter always comes before a token transformation filter.

Other filters have a flexible position in the chain. For example, an AssignmentFilter can be used before a request is handled or after a response is handled.

When the position of a filter is fixed, it is automatically placed in the correct position in the chain; you cannot change the position. When the position of a filter is flexible, the icon is displayed, and you can drag the filter into a different position in the chain.

Select Chain to view and manage the filters in the chain as follows:

  • When the icon is displayed, drag a filter up or down the chain.

  • Select to edit a filter.

  • Select Realm Settings to disable and remove a filter from the chain.

For information about chains, refer to Chain.

Deploy and undeploy routes

Deploy a Route

  1. In Studio, select ROUTES, and then select a route created with the structured editor (with the icon).

  2. On the top-right of the screen, select and Display to review the route.

  3. If the route is okay, select Deploy to push the route to the PingGateway configuration.

    If the route configuration is not valid, or if a service that the route relies on, such as an AM service, is not available, the route fails to deploy.

    If the route deploys successfully, Deployed is displayed and the Deploy button is greyed out.

  4. Check the $HOME/.openig/config/routes folder in your PingGateway configuration to see that the route is there.

    By default, routes are loaded automatically into the PingGateway configuration. You don’t need to stop and restart PingGateway. For more information, refer to Prevent the reload of routes.

  5. Check the system log to confirm that the route was loaded successfully into the configuration. For information about logs, refer to Manage logs.

Undeploy a Route

  1. In Studio, select ROUTES and then select a route with the status Deployed.

  2. On the top-right of the screen, select and Undeploy, and then confirm your request.

    The route is removed from the PingGateway configuration. On the Studio screen, the route status Deployed is no longer displayed and the Deploy option is active again.