7 Migrating to a Helidon-Based Web Services Manager

Learn how to migrate Oracle Communications Billing and Revenue Management (BRM) Web Services Manager from an application server to a standalone, Helidon-based system.

Topics in the document:

• What Changes When Migrating to Helidon-Based Web Services Manager

• Migrating OAuth 2.0 Configuration to Helidon-Based Web Services Manager

• Migrating Web Services Manager Customizations

What Changes When Migrating to Helidon-Based Web Services Manager

Migrating from Web Services Manager deployed on an application server to Helidon-based Web Services Manager includes the following changes:

• Input Requests Remain Unchanged

• Changes to Web Services Manager URLs

• Changes to Web Services Manager Error Response Format

Input Requests Remain Unchanged

When you migrate to Helidon-based Web Services Manager, you can retain the input request structure used with Web Services Manager deployed on an application server. No changes to existing input requests are required when you migrate to Helidon-based Web Services Manager.

Changes to Web Services Manager URLs

Replace the Web Services Manager URLs used by your existing clients and integrations with the corresponding Helidon-based Web Services Manager URLs.

For example, the URL for the PCM_OP_READ_OBJ opcode (XML-element service) changes as follows:

Previous Web Services Manager URL:

https://hostname:port/BrmWebServices/BRMReadServices_v2

New Web Services Manager URL:

https://hostname:port/metro/jaxws/BRMReadService

To view the new URLs for all Web Services Manager services, use the Web Services Manager services URL:

https://hostname:port/metro

where hostname is the host name or IP address of Web Services Manager, and port is the configured Web Services Manager port. The default HTTP port is 8080.

Changes to Web Services Manager Error Response Format

If your existing clients or integrations parse the SOAP fault response returned by application-server-based Web Services Manager, update them to process the Helidon-based SOAP fault structure. The following examples show the previous and new response formats for the ERR_NAP_CONNECT_FAILED error.

Previous Web Services Manager error response

The following example shows the error response from Web Services Manager deployed on an application server. Detailed diagnostic information appears in the <faultstring> element, and the <detail> element contains a <BRMWebServiceFault> element.

<S:Fault xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:ns1="http://www.w3.org/2003/05/soap-envelope">
   <faultcode>ns0:Server</faultcode>
   <faultstring>
      DeterminateError - ERR_NAP_CONNECT_FAILED
      CreateConnections Error RetryableError - ERR_NAP_CONNECT_FAILED
      PCPConnection.java:0: ErrBuf Fields:
      Error=ERR_NAP_CONNECT_FAILED    Loc=PCP
      Field=UnknownField0    Rec=0    reserved=0
      Facility=0    MessageID=0    Time=7:13 AM    Version=0    Reserved2=0
      Args=&lt;none&gt;
      Nested Error:
      &lt;none&gt;
      :0: ErrBuf Fields:
      Error=ERR_NAP_CONNECT_FAILED    Loc=Unknown Location
      Field=UnknownField0    Rec=0    reserved=0
      Facility=0    MessageID=2    Time=7:13 AM    Version=0    Reserved2=0
      Args=&lt;none&gt;
      Nested Error:
      &lt;none&gt;
   </faultstring>
   <detail>
      <BRMWebServiceFault
         xmlns="http://xmlns.oracle.com/BRM/schemas/BusinessOpcodes">
         <faultCode>Server</faultCode>
         <faultString>Processing Failed</faultString>
      </BRMWebServiceFault>
   </detail>
</ns0:Fault>

Helidon-based Web Services Manager error response

The following example shows the corresponding response from Helidon-based Web Services Manager. The new response places the BRM error identifier in the <faultstring> element and provides <location>, <field>, <record>, <reserved>, <facility>, and <messageID> as separate elements under <detail>.

<S:Fault xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <faultcode>S:Server</faultcode>
   <faultstring>ERR_NAP_CONNECT_FAILED</faultstring>
   <detail>
      <location>Unknown Location</location>
      <field>UnknownField0</field>
      <record>0</record>
      <reserved>0</reserved>
      <facility>0</facility>
      <messageID>2</messageID>
   </detail>
</S:Fault>

Migrating OAuth 2.0 Configuration to Helidon-Based Web Services Manager

You can continue to use the same resource server on your identity provider that you used to secure SOAP APIs with application-server-based Web Services Manager, provided that the authorization server issues access tokens compatible with Helidon-based Web Services Manager.

Helidon-based Web Services Manager validates OAuth access tokens locally by using the token-signing certificate. The OAuthAccessTokenUrl, OAuthOldOAM, and OAuthDomainName properties used with WebLogic-based Web Services Manager are no longer required.

To migrate your OAuth 2.0 configuration to a Helidon-based Web Services Manager:

1. Obtain the OAuth token-signing X.509 certificate in PEM format from your existing authorization server. The certificate must contain the RSA public key corresponding to the private key used to sign RS256 JWT access tokens. Copy the certificate to a directory that Helidon-based Web Services Manager can access.

   See "Obtaining the Token-Signing Certificate". If you use Oracle Access Management (OAM), see "Retrieving the Token-Signing Certificate".

2. Open the BRM_home/apps/brm_wsm/config/Infranet.properties file in a text editor.

3. Remove the following WebLogic properties from the file:

   • OAuthAccessTokenUrl

   • OAuthOldOAM

   • OAuthDomainName

4. Add or modify the following entries in the file:

   infranet.isOAuth=true
   infranet.certificatePath=certPath/certFile.pem

   where:

   • certPath is the directory containing the OAuth token-signing certificate.

   • certFile is the name of the certificate file.

5. Save and close the Infranet.properties file.

6. Restart Web Services Manager to apply the changes.

Migrating Web Services Manager Customizations

When you move to Helidon-based Web Services Manager, you can reuse some existing customization artifacts. However, you must update their deployment and configuration settings for the new environment. The required changes depend on the type of customization.

Table 7-1 summarizes which customization artifacts you can reuse and which deployment configurations you must replace, add, or update for Helidon-based Web Services Manager.

Table 7-1 Reusing and Updating Web Services Manager Customizations

Customization	Reuse or Retain	Replace or Remove	Add or Update
Custom fields for exposed opcodes	Existing custom field definitions.	No replacement or removal is specified.	Update the applicable XSD file and deploy it to the location specified by webservices.schema.location.
Unexposed BRM opcodes for XML-element services	Existing XSD and WSDL files.	Replace the application-server-specific service deployment configuration with the Helidon-based endpoint configuration.	Generate sun-jaxws.xml, package the required artifacts in a JAR file, and configure webservices.descriptor, webservices.loadcustomschema, and BRM_WSM_CLASSPATH_EXT. If you use a new service group, generate a service implementation class.
Unexposed BRM opcodes for XML-string services	Existing BRM opcodes. For an existing service group, extend the service implementation class to include the additional opcodes.	Replace the application-server-specific endpoint deployment configuration.	Create or update the service implementation class, configure sun-jaxws.xml, package the required artifacts in a JAR file, and configure webservices.descriptor and BRM_WSM_CLASSPATH_EXT.
Custom opcodes for XML-element services	Existing XSD and WSDL files. You can reuse CustomFields.jar if available.	Replace the application-server-specific service deployment configuration.	Generate the service implementation class and sun-jaxws.xml, package the service artifacts in a JAR file, and configure infranet.custom.field.package, webservices.descriptor, webservices.loadcustomschema, and BRM_WSM_CLASSPATH_EXT.
Custom opcodes for XML-string services	Existing BRM custom opcode and field definitions. Reuse of previous service implementation artifacts is not specified.	Replace the application-server-specific endpoint deployment configuration.	Generate CustomFields.jar from the existing custom opcode and field definitions. Configure the XML-string service implementation and endpoints, and package the compiled implementation class and sun-jaxws.xml in a JAR file. Configure webservices.descriptor and add the full paths of both JAR files to BRM_WSM_CLASSPATH_EXT.

For instructions on each customization type, see these topics:

• Migrating Custom Fields for Exposed Opcodes

• Migrating Unexposed BRM Opcodes for XML-Element Services

• Migrating Unexposed BRM Opcodes for XML-String Services

• Migrating Custom Opcodes for XML-Element Services

• Migrating Custom Opcodes for XML-String Services

Migrating Custom Fields for Exposed Opcodes

For custom fields on already exposed opcodes, use the custom field definitions from your existing application-server-based Web Services Manager deployment to update the applicable XSD file. For Helidon-based Web Services Manager, deploy the updated XSD file to the location specified by webservices.schema.location.

To migrate your custom fields for already exposed opcodes to your new Helidon-based Web Services Manager:

1. Update the appropriate XML Schema Definition (XSD) file with your custom fields.

2. Move the updated XSD file to the path specified in the webservices.schema.location entry in the BRM_home/apps/brm_wsm/config/Infranet.properties file.

3. Stop and restart Web Services Manager.

Migrating Unexposed BRM Opcodes for XML-Element Services

You can reuse the XSD and WSDL files from your existing Web Services Manager deployment. For Helidon-based Web Services Manager, you must configure the service deployment by using sun-jaxws.xml. You must also package the required artifacts in a JAR file and configure the required Infranet.properties entries. You must then make the JAR file available through BRM_WSM_CLASSPATH_EXT.

To migrate unexposed BRM opcodes for XML-element services to your new Helidon-based Web Services Manager:

1. Copy the XSD files to the directory specified by the webservices.schema.location property in the BRM_home/apps/brm_wsm/config/Infranet.properties file.

2. Generate the sun-jaxws.xml file using one of the following endpoints:

   • /configurations/endpoints/default (to get the default deployment descriptor)

   • /configurations/endpoints (to get a custom deployment descriptor, if already deployed)

3. To expose BRM opcodes under an existing service group:

   1. Update only the wsdl attribute with the path to the WSDL file that you place in a JAR file later in this procedure.

      <endpoint name="endpointName"
          implementation="pathToClass"
          url-pattern="urlPattern"
          wsdl="WEB-INF/wsdl/customDir/customWsdl"/>

      where:

      • endpointName is the logical name of the endpoint for the web service.

      • pathToClass is the fully qualified name of the implementation class.

      • urlPattern is the URL pattern to access the web service.

      • customDir is a custom directory created to avoid conflicts with the standard Web Services Manager WSDL files. Ensure that your custom WSDL is located in this directory.

      • customWsdl is the name of the WSDL file. Place your custom WSDL in this directory.

      For example:

      <endpoint name="JAXWS_BRMCustomService"
          implementation="com.oracle.communications.brm.wsm.jaxws.services.cust.BRMCustomServicePttImpl"
          url-pattern="/jaxws/BRMCustomService"
          wsdl="WEB-INF/wsdl/customDir/BRMCustomServices_v2.wsdl"/>

   2. Create a JAR file that contains your WSDL file and your edited sun-jaxws.xml file in the following structure:

      • WEB-INF/wsdl/customDir/customWsdl

      • sunjaxwsPath/sun-jaxws.xml

      where sunjaxwsPath is the path to the sun-jaxws.xml file that you created during this procedure.

4. To expose BRM opcodes under a new service group, create a JAR file that contains your WSDL file, the sun-jaxws.xml file, and the new implementation class:

   1. Generate the web service implementation class. See "Generating the Web Service Implementation Class for XML Element Services".

   2. Generate the sun-jaxws.xml file and add the new endpoint to it. See "Configuring XML-Element Service Endpoints".

5. Update the Infranet.properties file with the following new values:

   webservices.descriptor=sunjaxwsPath/sun-jaxws.xml
   webservices.loadcustomschema=true

6. Set the BRM_WSM_CLASSPATH_EXT environment variable to the full path of the JAR file you created.

7. Stop and restart Web Services Manager.

Migrating Unexposed BRM Opcodes for XML-String Services

When you move XML-string services that expose additional BRM opcodes to Helidon-based Web Services Manager, you can retain the existing SOAP request structure.

To expose the opcodes under an existing service group, extend the existing service implementation class to include the additional opcodes. To expose the opcodes under a new service group, create a new service implementation class.

After you extend or create the service implementation class, complete these steps for Helidon-based Web Services Manager:

1. Generate the sun-jaxws.xml file and configure the required service endpoints in that file.

2. Package the compiled service implementation class and the sun-jaxws.xml file in a JAR file.

3. Update the webservices.descriptor entry in the Infranet.properties file to specify the path to the sun-jaxws.xml file.

4. Add the full path to the JAR file to the BRM_WSM_CLASSPATH_EXT environment variable.

5. Restart Web Services Manager to apply the changes.

See "Setting Up Web Services Manager to Support Unexposed Opcodes for XML-String Services".

Migrating Custom Opcodes for XML-Element Services

You can reuse your existing XSD and WSDL files and, if available, your existing CustomFields.jar file. For Helidon-based Web Services Manager, you must make the custom-fields JAR available to Web Services Manager and configure the custom-field package. You must also generate the service implementation and sun-jaxws.xml files and package the service artifacts in a JAR file. You must then update the Helidon-based Web Services Manager configuration.

To migrate custom opcodes for XML-element services to your new Helidon-based Web Services Manager:

1. Reuse your existing XSD and WSDL files.

2. If a CustomFields.jar file is available, reuse it.

   Otherwise, see "Making Custom Fields Available to Web Services Manager" to create a CustomFields.jar file.

3. Move the CustomFields.jar file to a path that is accessible by Web Services Manager.

4. Update the Infranet.properties file with the following new values:

   infranet.custom.field.package=package

   where package is the Java package name that contains the CustomOp class, such as com.portal.classFiles.

5. Add the full path of the CustomFields.jar file to the BRM_WSM_CLASSPATH_EXT environment variable.

6. See "Generating the Web Service Implementation Class for XML Element Services" to create and compile the implementation file.

7. See "Configuring XML-Element Service Endpoints" to create the sun-jaxws.xml file. Then create a JAR file, such as custom_services.jar, that contains the following files:

   • Compiled implementation file (.class file)

   • sun-jaxws.xml file

   • WSDL file

8. Update the Infranet.properties file with the following values:

   webservices.descriptor=sunjaxwsPath/sun-jaxws.xml
   webservices.loadcustomschema=true

   where sunjaxwsPath is the path to the sun-jaxws.xml file that you created during this procedure.

9. Add the full path of the custom_services.jar file to the BRM_WSM_CLASSPATH_EXT environment variable.

10. Stop and restart Web Services Manager.

Migrating Custom Opcodes for XML-String Services

When you configure XML-string services that use custom opcodes in Helidon-based Web Services Manager, you can retain the existing custom opcode definitions in BRM. You can also retain the SOAP request structure used by your existing clients. However, you must configure the custom web service implementation and deploy it in the Helidon-based environment.

To configure custom opcodes for XML-string services in Helidon-based Web Services Manager, complete these steps:

1. Use your existing custom opcode and field definitions to generate the CustomFields.jar file. See "Making Custom Fields Available to Web Services Manager" for instructions.

2. Create and compile the web service implementation class for your custom opcodes. See "Generating the Web Service Implementation Class for XML-String Services".

3. Generate the sun-jaxws.xml file and configure the custom service endpoints.

4. Package the compiled implementation class and the sun-jaxws.xml file in a JAR file. See "Configuring XML-String Service Endpoints".

5. Update the Infranet.properties file with the following entry:

   webservices.descriptor=sunjaxwsPath/sun-jaxws.xml

   where sunjaxwsPath is the directory that contains the sun-jaxws.xml file.

6. Add the full paths of the CustomFields.jar file and the JAR file containing your custom service implementation to the BRM_WSM_CLASSPATH_EXT environment variable.

7. Restart Web Services Manager to apply the changes.

For detailed instructions, see "Supporting Custom Opcodes for XML-String Services".