4 Implementing RIB-EXT

RIB-EXT is an Oracle Retail Integration Application that provides necessary communication channel for external applications to publish and consume message from RIB's JMS on cloud and premise.

Note:

For more information on WDSL's, see the Oracle Retail Cloud Service Integration Guide and for information on plugable jar, see the Client Connector For Oracle Retail Integration Cloud Service 21.0.000 (Patch) available on My Oracle Support.

External Application as a Publisher (soap-app)

For external applications to publish to the RIB JMS on cloud, it needs to use a publishing webservice provided by rib-ext .The WSDL URL of publishing service is as follows:

http://<rib-ext-host>:<port>/ApplicationMessagePublishingServiceBean/ApplicationMessagePublishingService?wsdl

An external application can publish messages using the above webservice only when rib-ext is configured as a soap-app.

External Application as a Subscriber (soap-app)

For an external application to consume the message from the RIB's JMS on cloud, it has to host the Injector Service. Injector Service is a SOAP webservice that is made available as a pluggable jar.

Subscriber adapters in rib-ext makes a SOAP call to Injector service to send the message to the external application. The WSDL URL of injector service is as follows:

http://<external-app-host>:<port>/ApplicationMessageInjectorBean/InjectorService?wsdl

The following example describes the steps to configure an external application to publish and subscribe using RIB on cloud:

Include rib-private-app-plugin-21.0.000.jar in to the external application deployable file for example, ext-app.ear/lib.
In the rib-deployment-env-info.xml file, configure the EXT application to be of type "soap-app". Under <app-in-scope-for-integration>, change EXT from javaee-app to soap-app:

<app id="ext" type="soap-app" />

Replace the existing rib-app section for rib-ext with a copy of the rib-app section for rib-sim (an existing soap-app). Edit the properties so that they apply for rib-ext.

For example:

<rib-app id="rib-ext" type="soap-app">
<deploy-in refid="rib-ext-wls1" />
<rib-admin-gui><message-flow id="901">
<web-app-url>https://www.example.com:<port>/rib-ext-appserver-gui/index.jsp</web-app-url>
<web-app-user-alias>rib-ext_rib-admin-gui_ user-name-alias</web-app-user-alias>
</rib-admin-gui>
<error-hospital-database>
<hosp-user-alias>rib-ext_error-hospital-database_ user-name-alias</hosp-user-alias>
</error-hospital-database>
<app-database-not-applicable />
<notifications>
<email>
<email-server-host>mail.example.com</email-server-host>
<email-server-port>25</email-server-port>
<from-address>admin@example.com</from-address>
<to-address-list>admin@example.com</to-address-list>
</email>
<jmx />
</notifications>
<app id="ext" type="soap-app">
<end-point>
<url>https://www.example.com:<port>/ApplicationMessageInjectorBean/InjectorServ ice?WSDL</url>
<ws-policy-name>policyA</ws-policy-name>
<user-alias>rib-ext_ws_security_user-name-alias</user-alias>
</end-point>
</app>
</rib-app>

ws-policy-name should be configured with a value "policyA".
Make sure the rib-ext_ws_security_user-name-alias user is a member of the ext_ integration_users group in the EXT WebLogic domain. Make sure the EXT services are up and running and can be called via the SOAP UI using the credentials that will be entered during RIB compilation.
Compile and deploy RIB.

External Application as a Publisher (rest-app)

For external applications to publish to the RIB JMS on cloud, it needs to use a publishing webservice provided by rib-ext. The end point of publishing service is as follows:

Table 4-1 APIs and Rest End Points

API	Rest End Point
Application WADL	http://<rib-ext-host>:<port>/rib-<app>-services-web/resources/application.wadl
Ping resource	http://<rib-ext-host>:<port>/rib-<app>-services-web/resources/publisher/ping
Publish resource	http://<rib-ext-host>:<port>/rib-<app>-services-web/resources/publisher/publish

An external application can publish messages using the above webservice only when rib-ext is configured as a rest-app.

External Application as a Subscriber (rest-app)

For an external application to consume the message from the RIB's JMS on cloud, it has to host the Injector Service. Injector Service is a ReST webservice that is made available as a pluggable jar.

Subscriber adapters in rib-ext makes a ReST call to Injector service to send the message to the external application. The End Point of injector service is as follows:

http://<external-app-host>:<port>/ rib-injector-services-web/resources/injector/inject

The following example describes the steps to configure an external application to publish and subscribe using RIB on cloud:

n Include rib-injector-services-web-21.0.000.war in to the external application deployable file for example, ext-app.ear/lib.
n In the rib-deployment-env-info.xml file, configure the EXT application to be of type "rest-app". Under <app-in-scope-for-integration>, change EXT from javaee-app to rest-app:

n Replace the existing rib-app section for rib-ext with a copy of the rib-app section for rib-rce (an existing rest-app). Edit the properties so that they apply for rib-ext.

For example:

<rib-app id="rib-ext" type="rest-app">
  <deploy-in refid="rib-ext-wls1" />
  <rib-admin-gui><message-flow id="901">
    <web-app-url>https://www.example.com:<port>/rib-ext-appserver-
gui/index.jsp</web-app-url>
    <web-app-user-alias>rib-ext_rib-admin-gui_ user-name-alias</web-app-user-alias>
  </rib-admin-gui>
  <error-hospital-database>
 
    <hosp-user-alias>rib-ext_error-hospital-database_ user-name-alias</hosp-user-alias>
  </error-hospital-database>
  <app-database-not-applicable />
  <notifications>
    <email>
      <email-server-host>mail.example.com</email-server-host>
      <email-server-port>25</email-server-port>
      <from-address>admin@example.com</from-address>
      <to-address-list>admin@example.com</to-address-list>
    </email>
    <jmx />
  </notifications>
  <app id="ext" type="rest-app">
    <end-point>
      <url>https://www.example.com:<port>/rib-injector-services-
web/resources/injector/inject" </url>
      <ws-policy-name>policyA</ws-policy-name>
      <user-alias>rib-ext_ws_security_user-name-alias</user-alias>
    </end-point>
  </app>
</rib-app>

ws-policy-name should be configured with a value "policyA".
Make sure the rib-ext_ws_security_user-name-alias user is a member of the ext_ integration_users group in the EXT WebLogic domain. Make sure the EXT services are up and running and can be called via the SOAP UI using the credentials that will be entered during RIB compilation.
Compile and deploy RIB.

How to implement ReST Client to Call the Publisher Service

In order to publish messages to RIB via ReST service, a standard JAX-RS client API can be used. We provide a few helper libraries and payload jars (RBO contracts) packaged inside RibExtConnectorServiceImplPak21.0.000_eng_ga.zip to be used on the classpath of a client application. In other words, these libraries should be packaged as part of the application war/ear file.

Required Libraries are as below.

application-message-publishing-service-consumer-21.0.000.jar
commons-logging-1.2.jar
rib-public-api-21.0.000.jar
retail-private-int-common-util-21.0.000.jar
retail-public-payload-java-beans-21.0.000.jar
retail-public-payload-java-beans-base-21.0.000.jar
retail-rest-service-common-util-21.0.000.jar
rib-private-common-21.0.000.jar

The following table contains the publisher ReST service endpoint (pattern) exposed by rib-ext for a client to hook to:

Table 4-2 APIs and URLs

API Info	URL
Application WADL	http://<examplehost>:<port>/rib-<app>-services-web/resources/application.wadl
Ping resource	http://<examplehost>:<port>/rib-<app>-services-web/resources/publisher/ping
Publish resource	http://<examplehost>:<port>/rib-<app>-services-web/resources/publisher/publish

See Rest Publisher Pseudo Code for sample code.

How to Implement Injector Service (CONSUME messages from RIB) using ReST

Here is the Rest service contract detail:

Keep the path as Injector/inject.
```
@Path("/injector")
```
Use POST for this service. As the input message object itself has identifier (message type- CRE/MOD) they don't need to use the PUT/PATCH. they can use message type to build the implementation logic.
```
@POST
@Path("/inject")
@Consumes({MediaType.APPLICATION_XML})
```

The input would be MediaType.APPLICATION_XML and the structure would be 'ApplicationMessage' object. (See Appendix A, "Sample Files" xsd).

<xs:element name="ApplicationMessage">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="family" type="string25"/>
      <xs:element name="type" type="string30"/>
      <xs:element name="businessObjectId" type="string255" minOccurs="0"/>
      <xs:element ref="ApplicationMessageRoutingInfo" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element name="payloadXml" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>
</xs:element>

Customer can utilize the payload.properties file for validation of message family and type. (See Appendix A, "Sample Files" for sample payload.properties)

Return type should be JSON, see below example:

String message = "{\"message\": \"Inject successful.\"}";
return Response.ok(message, MediaType.APPLICATION_JSON).build();

For exception response customer needs to follow the structure of exceptionVO.

public class ExceptionVo
{
    public String getStatus()
    {
        return status;
    }
    public void setStatus(String status)
    {
        this.status = status;
    }
    public String getMessage()
    {
        return message;
    }
    public void setMessage(String message)
    {
        this.message = message;
    }
    public String getStackTrace()
    {
        return stackTrace;
    }
    public void setStackTrace(String stackTrace)
    {
        this.stackTrace = stackTrace;
    }
    public int getStatusCode()
    {
        return statusCode;
    }
    public void setStatusCode(int statusCode)
    {
        this.statusCode = statusCode;
    }
    public ExceptionVo(int statusCode, String status, String message, String stackTrace)
    {
        this.statusCode = statusCode;
        this.status = status;
        this.message = message;
        this.stackTrace = stackTrace;
    }
    public ExceptionVo()
    {
    }
    public String toString()
    {
        return (new StringBuilder()).append("ExceptionVo{statusCode=").append(statusCode).append(", status=").append(status).append(", message=").append(message).append(", stackTrace=").append(stackTrace).append('}').toString();
    }
    int statusCode;
    String status;
    String message;
    String stackTrace;
}

See Appendix A, "Sample Files"Appendix for sample files (application.wadl, Resource file, Sample request/response etc.).

Note:

A Reference implementation for injector service is provided, See Reference Implementation of Injector Service Using Tomcat for details.

Error Handling

The RIB infrastructure provides a mechanism called RIB error hospital to handle and manage the error messages. When the publishing or subscription of a message fails in the rib-ext for some reason, it lands in error hospital with a reason code. The retry adapters in the rib-ext application are responsible for retrying the messages in error hospital.

Oracle RIB Hospital Administration (RIHA) is a Weblogic application that allows the management of messages in error hospital. Some of the RIHA operations include:

Viewing error messages
Editing error messages
Retrying error messages
Stopping error messages

For more information, see the Oracle Retail Integration Bus Hospital Administration Guide.