6 Versioning JD Edwards EnterpriseOne Web Services

This chapter contains the following topics:

• Section 6.1, "Overview"

• Section 6.2, "Published Business Services"

• Section 6.3, "Business Services"

• Section 6.4, "JD Edwards EnterpriseOne as a Web Service Consumer"

Important:

This chapter is intended primarily for JD Edwards EnterpriseOne software engineers who design and develop business services and published business services. If you create your own web services, you can use this chapter as a guide for creating versioned web services.

6.1 Overview

When a web service exposes an interface in the form of a WSDL, that interface is assumed to be static from that point on. The published interface for a web service is considered as a service contract, and the methods and inputs to those methods are intended to remain unchanged for the life of that web service. However, over time, it may become necessary to change the behavior or interface of an existing JD Edwards EnterpriseOne web service to provide enhanced processing or to add fields. When you enhance an existing web service, it is very important that you do not change the original methods and interfaces. This chapter provides concepts and procedures for enhancing business services by creating a version of the original business service.

6.2 Published Business Services

JD Edwards EnterpriseOne provides web services, called published business services, for public consumption. The methods and interfaces are exposed in the final web service WSDL. You cannot change the original method names, the original names of the published value object classes, and the original web service behavior without affecting the consumer of the business service. Only new optional processing can be introduced without versioning. Conceptually, optional processing is a kind of invisible change where there is some way (for example, a service constant) to get existing functionality and new functionality from an existing method without changing the interface, as well as maintaining the availability of the original processing.

6.2.1 Determining if Versioning Is Required

Basically, any change to the published interface requires that you create a version of the published business service. The following diagram is provided to help decide whether you should create a version of the original method name or published value object class name or whether the processing is changed:

Figure 6-1 Determine whether to version a published business service

Description of "Figure 6-1 Determine whether to version a published business service"

6.2.2 Naming Conventions for Versions

If you determine that you must change the behavior or interface of an existing published business service, you can create a version of the original published business service. When you create a version of a published business service, the name of the versioned published business service must clearly indicate that it is a version of an original published business service. This enables users of the web service to choose the version with the desired behavior and interface.

Changes requiring versioning require new methods and value objects with a version appended to their name; for example, myMethodV2 and ValueObjectV3. For field changes, you may need to version multiple value objects, depending on the depth of placement of the new fields.

For example, a published business service exposes the method processAddressBook. An enhancement request requires that 10 new address book fields be exposed and processed by the method. The new method name will be processAddressBookV2. The original value object that will contain the new fields is called AddressBook. You copy the original value object, AddressBook to a new value object called AddressBookV2. Then you create a new top-level value object named processAddressBookV2 that contains the new version of the value object (AddressBookV2) and maps to the new fields.

6.2.3 Creating a Published Business Service Version

The following high-level steps are provided to help you create versions to a published business service:

1. Determine where new and changed fields exist in the published value object.

   Version the containing class and all classes above it in the published value object hierarchy.

2. Version the methods that use the top-level value object in the published Manager class.

3. Add and change fields within the internal value object (not a hierarchy.)

4. Add and change internal functionality (business function or input/output calls) in the internal business service.

5. In the new published value object version, change and add mappings in the mapFromPublished method.

6. Test both the original and the new version of the business service.

6.2.4 Example: Correct Field Names and Format of Interface

This section provides an example of the process for creating a version of a JD Edwards EnterpriseOne published business service.

This example change involves modifications made in the published business service only. The business service is JP010000. A field is incorrectly named isEntityTypeNettingIndicator but it should be isARAPNettingUsed. Use these steps to create a version of the published business service.

1. Create a new version of the value object where the field resides.

   1. Create a copy of the AddressBookResult value object and name it AddressBookResultV2.

   2. Inside AddressBookResultV2, change the field isEntityTypeNettingIndicator to isARAPNettingUsed.

   3. Create a copy of ShowAddressBook and name it ShowAddressBookV2.

   4. InsideShowAddressBookV2, change all references in mapFromPublishedMethod to ShowAddressBookV2, including the name change for the isARAPNettingUsed field.

2. Create a new published method.

   1. Copy the existing getAddressBook method and paste it at the end of the class.

   2. Change the name of the copy to getAddressBookV2.

   3. Within getAddressBookV2, change all references to the value object ShowAddressBook to the new value object ShowAddressBookV2.

6.3 Business Services

Business services, commonly called internal business services, perform a specific task. Internal business services do not have a public interface; methods and interfaces are called by published business services. You can change methods and value objects as long as the change to the internal business service does not affect the behavior of the published business service that calls it.

Because the methods and interfaces of internal business services are not public, it is practical that these will be reused, and may be called by both the new version and the existing version of the published business service. The internal business service can provide existing behavior for the existing method while still providing new behavior for the new method; the internal business service does not require renaming or version numbers. However, if the behavior is different, you create a new method or you could copy the original method and append a version number to the method that you copied.

For the internal value object, new non-required fields can be added without affecting the published business service. Typically the internal value object contains all of the fields that could potentially be passed into a business function or input/output call. So it is likely that the field is already included in the internal value object. Fields may be moved from one internal value object to another. You can make these changes to the internal business service without affecting the public interface.

6.3.1 Determining if Versioning is Required

Use the following diagram to help decide whether you should create a version of the original method name and value object class name:

Figure 6-2 Determine whether to version an internal business service

Description of "Figure 6-2 Determine whether to version an internal business service"

When determining whether to version an internal business service method or internal value object, you should focus on the behavior of the internal business service. The goal is to maintain the existing behavior for the existing published methods while still providing a new behavior.

You may want to employ a technique where a version parameter is passed to the internal function. When called from the original published business service, a value of V1 is passed in the parameter and when called from a new version published business service, a value of V2 is passed. Within the internal business service logic, only new logic is performed if the parameter is V2. This keeps original logic intact while allowing additional functionality for V2.

6.3.2 Example: Enhancement that Includes New Fields and Associated Processing

This section provides an example of the process for creating a version of a JD Edwards EnterpriseOne internal business service and then creating a version of the published business service that calls the internal business service version.

This example change involves modifications made at all levels of the business service Java code. This example is approached from the published interface through the internal business service to the JD Edwards EnterpriseOne business function calls. The published business service is JP010020 and the internal business service is J0100021.

Use these steps to create a version of the internal business service and the published business service that calls it:

1. Determine where the new fields belong in the value object.

   In this example, the top-level published value object is called ProcessCustomer. The fields are related to invoicing information, so the new fields will be updated to the Invoice object.

2. In JDeveloper, do the following in the value object folder of the business service:

   1. Create a copy of ProcessCustomer and name it ProcessCustomerV2.

   2. Create a copy of Invoice and name it InvoiceV2.

   3. Inside ProcessCustomerV2, change the current member reference from Invoice to InvoiceV2.

   4. Inside ProcessCustomerV2, change all references in mapFromPublishedMethod to InvoiceV2.

3. Create a new published method.

   1. Copy the existing processCustomer method and paste it at the end of the class.

   2. Change the name of the copy to processCustomerV2.

   3. Within processCustomerV2, change all references to the value object ProcessCustomer to the new value object Process CustomerV2.

4. Evaluate and change the internal business service.

   1. The new fields must be added to the internal business service, too. You can add the new fields to the internal value object, InternalProcessCustomer, by just adding them as additional members in the class.

   2. Modify CustomerProcessor to pass the new value object fields to CustomerMBF, which is already called. Because these are new non-required fields, it does not matter if they are blank, as they would be called from the existing business service. The processing functions as it always has when fields are blank, and when these new fields are passed in, they will be processed as expected.

5. Return to the value object ProcessCustomerV2 and add new code to mapFromPublishedMethod that maps the new published value object fields to the new internal value object fields.

6. Test both the new processCustomerV2 and the original processCustomer methods.

6.4 JD Edwards EnterpriseOne as a Web Service Consumer

JD Edwards EnterpriseOne can consume web services from third-party systems. Although these web services do not expose a contract in the form of published methods and interfaces, they may need to be changed to take advantage of third-party enhancements or new services. Because JD Edwards EnterpriseOne business functions call the methods of the third-party web services, any new version or method must be added as new code that is called by the business function. You must determine how to control which version of the business service the business function calls. You might consider using a processing option or a service constant to control the behavior.

The only reason for changing a business service that consumes a third-party web service is that the third-party web service has changed. The following scenarios illustrate how to control the behavior of the business services using a processing option or service constant.

Scenario 1: A third party web service has changed--use a processing option

For this scenario, you should version method or value objects by appending a version number to the name. Most likely, the third-party service that changed is also versioned. The new version of the business service method is called directly from the JD Edwards EnterpriseOne business function, which may or may not pass new data to the changed third-party web service. You can create a new JD Edwards EnterpriseOne processing option to control the version of the business service method that is called and the data that is passed to it.

Scenario 2: A third-party web service has changed--use a service constant

An alternative to Scenario 1, is that the existing method could call the new method based on a service constant that controls what version is being called. In this scenario, all of the data passed from the business function must be the same for both versions. This scenario minimizes the impact to existing business function calls while allowing you to control what version of the third-party service is called.

Scenario 3: The consumer business service is calling a free web service that has been updated

You have decided to upgrade the consumer business service to use the new version of a free web service. There will be no impact to users of the consumer business service if the business service starts calling the new version of the free web service without giving the user the option to use the previous version. There is no need to version the consumer business service. You can enhance the JD Edwards EnterpriseOne web service to use the new version of the free web service providing no backward compatibility is required.

6.4.1 Determining if Versioning is Required

Use the following diagram to help decide whether you should create a version of the original method name and value object class name:

Figure 6-3 Determine whether to version a consumer business service

Description of "Figure 6-3 Determine whether to version a consumer business service"

6.4.2 Creating a Version to a Consumer Business Service

The following high-level steps are provided to help you create versions to business services that consume third-party web services:

1. Determine where new and changed fields exist in the value object.

   Version the containing class and all classes above it in the value object hierarchy.

2. Version the method that uses the top-level value object in the Processor class.

3. Call the new method from a JD Edwards EnterpriseOne business service and do one of the following:

   • Create a processing option to call the new or old method.

   • Create a service constant to call the new method from the existing method.

6.4.3 Example: Enhancement to Call Latest Version of a Third-Party Service

This section provides an example of the process for creating a version of a JD Edwards EnterpriseOne business service that consumes a third-party web service.

In this example, a JD Edwards EnterpriseOne consumer business service calls a third-party service for weather forecast. Originally, the web service used only a zip code as input, but now it accepts city and state, too. The consumer business service is J8500001.

Use these steps to create a version of the internal business service and the published business service that calls it:

1. Create a new version of the value object to include the new fields; for example:

   Create a copy of GetWeatherInput and name it GetWeatherInputV2.

2. Within the WeatherProcessor class, create a copy of the method getWeather and name it getWeatherV2.

3. Use the endpoint of the new version of the weather forecast service to create a new proxy for the service, and name the new proxy ProxyV2.

4. In the new getWeatherV2 method, change the code to call the method from the new proxy, ProxyV2.

5. To support either version of the service, create processing options or system settings that indicate that city and state can be used.

6. Enhance the JD Edwards EnterpriseOne applications and business function to follow the settings and allow users to enter city and state, as well as to include the values in the XML generated by the business function that calls the business service.

7. Modify getWeatherV2 to map the new city and state fields from the value object to the input of the web service call.