16 Integration with External Applications

RIBforExt is the Oracle Retail Enterprise Integration component designed to address the connectivity requirements for 3rd Party integrations in a hybrid cloud topology where the RIB is deployed in the Retail Integration Cloud Services.

In a hybrid cloud scenario customers no longer have access to RIB's JMS server and cannot directly publish and subscribe to messages on the JMS topics. The RIB-EXT app is designed to fill that gap, it provides Web Service based APIs to publish to and subscribe from the RIB's JMS from third party systems.

RIBforEXT has all of the RIB flows available for the deployment time configuration based on the customer use cases.

RIB-EXT out-of-the-box provides the complete set of publishers, subscribers and retry adapters needed for the external application to integrate with Oracle Retail applications using RIB infrastructure.

The selective list of publisher and subscriber adapters needed by each specific external application is defined by the customer's implementation team.

Surrounding text describes integration-with-extapps.png.

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 Integration Bus Integration Guide and for information on plugable jar, see the Client Connector For Oracle Retail Integration Cloud Service 19.1.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-19.1.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:

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:

Include rib-injector-services-web-19.1.000.war 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 "rest-app". Under <app-in-scope-for-integration>, change EXT from javaee-app to rest-app:

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 RibExtConnectorServiceImplPak19.1.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-19.1.000.jar
commons-logging-1.2.jar
rib-public-api-19.1.000.jar
retail-private-int-common-util-19.1.000.jar
retail-public-payload-java-beans-19.1.000.jar
retail-public-payload-java-beans-base-19.1.000.jar
retail-rest-service-common-util-19.1.000.jar
rib-private-common-19.1.000.jar

Listed below is the publisher ReST service endpoint (pattern) exposed by rib-ext to which the client can hook.

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 E, "Sample Files" for 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 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 E, "Sample Files" for sample files (application.wadl, Resource file, Sample request/response, etc.).

A Reference implementation for injector service is provided, See Appendix A, " 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.

Monitoring Integration

To monitor live statistics of various components involved in RIB integration system like RIB adapter, error hospital, JMS server, RTG provides a live monitoring application called the Retail Integration Console (RIC).

The RIC is the user interface application designed to provide a unified view of the RTG integration products within the business context of the Oracle Retail applications. It provides near real time statistics regarding the message flows, JMS topics, historical trends of each message family, performance comparisons, and static information like application configuration.

For more information, see the Oracle Retail Integration Console User Guide.

See Appendix D, "Sample Data from Integration Monitoring Service" for sample code.