This chapter contains the following topics:
Section 10.1, "Understanding Business Services and HTTP POST"
Section 10.2, "Using Business Services for an HTTP POST Request"
JD Edwards EnterpriseOne enables you to use a business service to communicate with a third-party system using HTTP POST. In this scenario, a business function is invoked by a request from a JD Edwards HTML web client, which in turn calls a business service to make an HTTP POST request. You provide callback information in the posted data for the third-party system to send an asynchronous reply to the request. When the callback reply is received from the third-party system, the published business service, which is included in the callback information, is invoked. The response is returned to the JD Edwards EnterpriseOne HTML web client.
This feature uses the correlation data manager and HTTP adapter service. The correlation data manager maintains correlation data, which is the callback information for HTTP communication. You write code for the business service to get correlation data from the Correlation Data Manager. Correlation data can then be passed in your XML payload or in the HTTP header. You use the HTTP Adapter to post data to external sites. HTTP Adapter uses HTTPPostRequest to send data and HTTPPostResponse to receive a response.
This table identifies the classes that you use with the HTTP Post feature:
| Method (API) | Description |
|---|---|
| HTTPAdapterService | Provides utilities to post messages to external HTTP services. |
| HTTPPOSTRequest | Represents the request format for an HTTP adapter service of a POST operation. |
| HTTPPOSTResponse | Represents the response format for an HTTP adapter service of a POST operation. |
| BSSVCorrelationDataManager | Provides access to correlation data. Correlation data provides the callback information for asynchronous HTTP communication. |
Correlation data provides the information that the third-party system needs to respond to the JD Edwards EnterpriseOne request. Correlation data consists of this information:
Callback HTTP listener servlet.
UserName/environment/role/token for authentication.
Callback published business service name.
Callback published business service method.
DXAPIROUTE information.
The correlation data is compiled into a URL that is provided to the third-party system. The third-party system uses this information to post data to the business service. Access to correlation data is provided through the CorrelationDataManager interface.
This code sample shows how to access the correlation data manager:
IBSSVCorrelationDataManager correlationData = context.getBSSVCorrelationData Manager();
The business service sets the business service name, method, and callback business function in the correlation data. These are the methods that the business service uses:
void setCallbackBSSVName(java.lang.StringbssvName) void setCallbackBSSVMethod(java.lang.String bssvMethod) void setXAPICallbackBSFN(java.lang.StringxapiCallbackBSFN)
This sample code shows how to use these methods:
correlationData.setCallbackBSSVName(oracle.e1.bssv.JRH90I33. RI_HTTPListnerProcessor.java); correlationData.setCallbackBSSVMethod(receiveRSSRsponse); correlationData.setXAPICallbackBSFN(NotThereYetBSFN);
The business service gets a callback URL from the CorrelationDataManager. This URL is passed to the third-party system so that the third-party system can post data to the business services server. You use this method for the business function to get the callback URL:
String getCallbackURL (boolean secureMod)
The getCallbackURL method requires a Boolean parameter that indicates whether the callback URL to be created is using secure mode. A secure mode URL is prefixed by https. A nonsecure mode URL is prefixed by http. This table shows the constants that you use to indicate whether the URL is to be secure:
| Constant | Description |
|---|---|
| USE_NON_SECURE_MODE | Use for secureMode parameter if SSL is not required. |
| USE_SECURE_MODE | Use for secureMode parameter if SSL is required. |
You can pass correlation data to the third-party system by placing each data item in the HTTP header. This code sample shows the version of the POST method you should use for putting data items in the HTTP header:
oracle.e1.bssvfoundation.http.HTTPPOSTResponse postMessage(oracle.e1. bssvfoundation.http.HTTPPOSTRequest p1, int CorrInHeaderMode)
The parameter CorrInHeaderMode specifies whether correlation data needs to be passed in the HTTP header and the format.
This table defines the constants that you can use for the CorrInHeaderMode parameter:
| Constant | Description |
|---|---|
| NO_CORRELATION_IN_HEADER | Tells the method that correlation data is not required in the HTTP header. |
| CORRELATION_IN_HEADER_WITH_NON_SECURE_CALLBACK | Tells the method to put all correlation data in the HTTP header with a nonsecure (http) callback URL. |
| CORRELATION_IN_HEADER_WITH_SECURE_CALLBACK | Tells the method to put all correlation data in the HTTP header with a secure (https) callback URL. |
This code provides an example of how to use these constants:
res = service.postMessage(req, HTTPAdapterService.CORRELATION_IN_ HEADER_WITH_NON_SECURE_CALLBACK);
You use the HTTPAdapterService to post XML data to external sites. You create the HTTPPostRequest object first. HTTPPostRequest contains the XML data to be posted as well as the URL where data is to be posted. Then, depending on whether you are using HTTP or HTTPS, the appropriate method from HTTPAdapterService is invoked to post the data. This example code shows how to use HTTPAdapterService to post XML data to external sites.
//Make HTTP Call HTTPAdapterService service = context.getHTTPAdapterService(); HTTPPOSTRequest req = new HTTPPOSTRequest(internalVO.getSzPayloadIn()); HTTPPOSTResponse res = null; req.setUrl(internalVO.getSzURL()); res = service.postMessage(req, HTTPAdapterService.CORRELATION_IN_HEADER_WITH_ NON_⇒ SECURE_CALLBACK);
The business services server uses a listener servlet (HTTPCallbackListenerServlet) to receive incoming messages from third-party systems. Received messages contain callback information, which is used to associate the message with the correct request.
The business services server uses the HTTPCallbackListenerServlet to listen for messages from third-party systems. This servlet starts when the business services server is started. The listener servlet listens for incoming XML messages that use HTTP. Third-party web sites must use the callback URL provided by the business services HTTP POST request. The address of the servlet is returned by the getCallbackURL() method. This URL is available in the XML payload or in the HTTP header. The listener servlet is responsible for calling the published business service method that is provided in the callback URL.
Note:
The listener servlet does not require any configuration.The listener servlet functions in this way:
The servlet listens for XML/HTTP messages from external web sites.
Upon receiving a message, the servlet reads all of the query parameters that were sent as part of the callback URL. If the number of query parameters do not match the number of parameters sent, the servlet throws a ServletException to the third-party web site.
Next, the query parameters are decoded and the user is authenticated. If authentication fails, the servlet throws a ServletException.
When authentication succeeds, the servlet sends a response to the external web site indicating that the message was successfully received.
Note:
The servlet does not wait for the response from the published business service call. The servlet returns a standard message received response or throws an exception if the message is not received correctly.The servlet then checks whether the authenticated user has authority to call the specified published business service method. If the user has authority, the published business service method is called, and the payload is passed in to the value object of the published business service method. The published business service method called from the listener must follow the methodology requirements.
The business service can send a notification message to the JD Edwards EnterpriseOne HTML web client. The business service uses this static method in the BSSVSendXAPIMsgToClinet.java class.
public static void sendNotifyMsgToClient(IContext context, String szData)
This example shows code for sending a notification message:
//Make HTTP Call HTTPAdapterService service = context.getHTTPAdapterService(); HTTPPOSTRequest req = new HTTPPOSTRequest(internalVO.getSzPayloadIn()); HTTPPOSTResponse res = null; req.setUrl(internalVO.getSzURL()); res = service.postMessage(req, HTTPAdapterService.CORRELATION_IN_HEADER_WITH_ NON_SECURE_CALLBACK);