A web handler logically groups services using a JSON file to identify the version, service name, and handler details. Progress recommends grouping named services using a custom web handler file. A ROOT.handlers file groups unnamed services within each web application. Enable the WEB transport to deploy a web handler service to a PAS for OpenEdge production instance.

Use a custom web handler file to deploy named services

To deploy named services, perform the following steps:
  1. Create a custom web handler file.
    1. Create the required directory structure for storing the web handler file, for example: 
      oepas1/webapps/sportsOnline/WEB-INF/adapters/web/invoiceCustomer
      Note: In this example, the instance-name is oepas1. The webapp-name is sportsOnline. The serviceName is invoiceCustomer.
    2. Create a new custom web handler file with a .handlers file extension. This JSON file defines the version number, service name, and details for the custom web handler, for example:
      Figure 1. invoiceCustomer.handlers
      {
    "version": "2.0",
    "serviceName": "invoiceCustomer",

    "handlers": [
        {
            "uri": "/clients/{custnum}/history",

            "class": "reviewCustomer",
            "enabled": true
        },
        {
            "uri": "/clients/{custnum}/orders/{ordernum}",

            "class": "invoiceCustomer",
            "enabled": true
        }
    ]
}
      Note: Setting serviceName to "invoiceCustomer" makes this a named service. The uri pattern matching is general to more specific.
  2. Add the underlying business logic supplied by the service developer to the PROPATH by extracting the code to a standard PROPATH directory, for example: 
    oepas1/webapps/sportsOnline/WEB-INF/openedge
    Note: The instance-name is oepas1. The webapp-name is sportsOnline.
  3. Deploy the web application.
    1. Use the Proenv utility to navigate to the /bin directory of the target instance where you want to deploy the web handler.
    2. Run the deploySvc command and specify the web application name and the location of the zip file, for example:
      deploysvc.{sh|bat} -a sportsOnline sportsOnline.zip
      Note: The -a option identifies the sportsOnline web application. The sportsOnline.zip contains the invoiceCustomer r-code.
  4. Test the service.
    1. Start the PAS for OpenEdge instance.
    2. Test the web handler in a web browser, for example:
      http://hostname:port/sportsOnline/web/invoiceCustomer/clients/{custnum}/history
Note: The webapp-name is sportsOnline. The service-name is invoiceCustomer, and the uri value from the invoiceCustomer.handlers file is clients/{custnum}/history where {cust-num} is replaced with a valid customer number.
Note: The "uri" may include regular expressions as part of the path parameters. For a complete list of regular expressions in the path parameter, see regex.

Use the ROOT.handlers file to deploy unnamed services

To deploy unnamed services to a web application, perform the following steps:
  1. Create the required directory structure for storing the ROOT web handler file, for example:
    oepas1/webapps/sportsOnline/WEB-INF/adapters/web/ROOT
    Note: In this example, the instance-name is oepas1. The webapp-name is sportsOnline. ROOT replaces the service-name.
  2. Create a ROOT.handlers file to define the version number, service name, and details, for example:
    Figure 2. ROOT.handlers
    {
    "version": "2.0",
    "serviceName": "",

    "handlers": [
        {
            "uri": "/clients/{custnum}/history",
            "class": "reviewCustomer",
            "enabled": true
        },
        {
            "uri": "/clients/{custnum}/orders/{ordernum}",
            "class": "invoiceCustomer",
            "enabled": true
        }
    ]
}
    Note: Setting serviceName to "" makes this an unnamed service. The uri pattern matching is general to more specific.
  3. Add the underlying business logic supplied by the service developer to the PROPATH by extracting the code to a standard PROPATH directory, for example: 
    oepas1/webapps/sportsOnline/WEB-INF/openedge
    Note: The instance-name is oepas1. The webapp-name is sportsOnline.
  4. Deploy the web application.
    1. Use the Proenv utility to navigate to the /bin directory of the target instance where you want to deploy the web handler.
    2. Run the deploySvc command and specify the web application name and the location of the zip file, for example:
      deploysvc.{sh|bat} -a sportsOnline sportsOnline.zip
      Note: The -a option identifies the sportsOnline web application. The sportsOnline web application contains the invoiceCustomer r-code.
  5. Test the service.
    1. Start the PAS for OpenEdge instance.
    2. Test the web handler in a web browser. The URL can be accessed using the following format:
      http://hostname:port/web/sportsOnline/clients/{custnum}/history
      Note: The service name invoiceCustomer is not included in the URL. This offers more flexibility by removing the name of the service from the URL.

Migrate web handlers from OpenEdge 12.1 or earlier

System administrators use the tcman export command to migrate web handlers from the old format of the openedge.properties file into the new web handlers JSON format version 2.0. The migrated URLs remain compatible with the older version. To migrate web handlers, perform the following steps:

  1. Obtain the r-code that supports the web handler service for the OpenEdge 12.1 or prior instance from the developer.
  2. Create a target PAS for OpenEdge instance using OpenEdge 12.2 or later. If you are not deploying to the ROOT ABL web application, deploy a supporting ABL web application to this instance.
  3. Move the r-code to the PROPATH of the instance, for example, instance-name/webapps/ROOT/WEB-INF/openedge or instance-name/webapps/webapp-name/WEB-INF/openedge.
  4. From the /bin directory of the target instance, run the tcman export command on the older instance to export the ABL application and all of its supporting web applications and services into an OpenEdge Application Archive file, for example:
    proenv>WRK122\oepas122\bin\tcman export -appName oepas1 -instanceDir C:\OpenEdge\WRK121\oepas1\

    This process reads the web handler configuration from openedge.properties, strips them from the file, and adds them to the WEB-INF/adapters/web/ROOT/ROOT.handlers file.

    If you had an ABL application called myABLApp with the web applications SportsWebApp and EntityWebApp, and each web application has the web handler configuration in the openedge.properties file. Then the exported OpenEdge Application Archive contains the following handler files:
    <CATALINA_BASE>/webapps/SportsWebApp/WEB-INF/adapters/web/ROOT/ROOT.handlers
<CATALINA_BASE>/webapps/EntityWebApp/WEB-INF/adapters/web/ROOT/ROOT.handlers
  5. Deploy this OpenEdge Application Archive package to the PAS for OpenEdge instance using tcman import, for example:
    proenv>WRK122\oepas122\bin\tcman import C:\OpenEdge\oepas1.oear
  6. Start the PAS for OpenEdge instance.
  7. Test the web handler service in a web browser. It can be accessed using the same URI as the previous version of the web handler service.

Reload web handlers online

System administrators can reload web handler contexts without restarting the PAS for OpenEdge instance so that web handlers can be updated or published dynamically online. Administrators can use the tcman jmx refreshWeb command to reload the web handler context whenever a web handler is published or updated.

For more information, see Refresh web handlers for an ABL web application (jmx refresh).

Supported JSON formats for web handler information file

OpenEdge 12.2 and later supports versions 1.0 and 2.0 of the web handlers file. Use version 2.0 of the web handlers file to keep current.

Figure 3. Web handlers JSON Version 1.0
{
    "version": "1.0",
    "serviceName": "SportsSvc",
    "handlers": [{
        "className": "SportsSvc",
        "URIs": [
            "\/webHandlers",
            "\/some-data",
            "\/customers\/{custnum}\/orders\/{ordernum}",
            "\/customers\/{custnum}\/orders",
            "\/customers\/{custnum}",
            "\/customers"
        ]
    }]
}

The web handlers version 1.0 is the format that Progress Developer Studio generates in OpenEdge 12.2 and later.

Figure 4. Web handlers JSON Version 2.0
{
  "version": "2.0",
  "serviceName": "",
  "handlers": [
    {
      "uri": "/WebHandlers",
      "class": "WebHandlersHandler",
      "enabled": true
    },
    {
      "uri": "/customers/{custnum}/orders/{ordernum}",
      "class": "CustomerService",
      "enabled": true
    }
  ]
}

Web handlers JSON version 2.0 is the format generated when migrating older web handler properties using tcman export.