Wiki

Case Status
Log In

Wiki

 
Manufacturers Integrating with…»OASIS Specialization»Configuring oasis.xml for the …»External Browser Web Configura…
  • RSS Feed

Last modified on 5/9/2019 9:09 AM by User.

Tags:

External Browser Web Configurator Configurator

Overview

A configurator is the best way to utilize business rules in a software system to help users create a valid catalog number that can be built. Additionally, pricing and other information may be returned with the configured item. The result is better access to what product can be built for the sales force and the manufacturer is not overwhelmed with simple quote requests.

Creating a website configurator is common in the market today. The only issue today is that a typical sales agency will represent 50 or more manufacturers - each with their own website, and login. Integrating with OASIS allows the sales agency personnel to work in the same environment for all their factories and easily configure items using you configurator - securely.

Unlike the previous configurator method, this method uses the computer's default browser to access the manufacturer configurator. The result is better support for new and evolving HTML standards.

NOTE: the old "AUTO", "FX" and "VB" options will no longer be supported after December 31, 2019. Unfortunately the technologies used in those methods are being discontinued by the companies that created them. Essentially we can no longer receive support for those products and similar products are not adequate. The core reason for the changes is the industry wide shift to HTML 5 - a "living specification". Changes to HTML 5 are happening rapidly and it is better to launch a well supported browser from OASIS than to try to build a browser in OASIS.

How Does it Work?

There are two very similar methods. The "redirect" method and the "JSON" method.

Redirect

  1. Once the oasis.xml file is read, OASIS will make a call to an OASIS web service known as CMQ (Configurator Message Queue).
  2. CMQ will return a session identifier and a URL to call the manufacturer web browser.
  3. OASIS will request from the operating system to launch the user's default browser using the URL returned by CMQ. Included in the request is the URL to return to CMQ.
  4. The browser interacts with the web configurator.
  5. When the configuration is complete, the web configurator must send a redirect to CMQ including the configuration information.
  6. The browser opens a page in CMQ using the URL from the web configurator - this data is stored to be returned to OASIS
  7. (N) During this time, OASIS is "polling" CMQ for the closing of the session. This happens when the web configurator does the redirect to CMQ.

JSON

For more complex data transfers, the web configurator can call CMQ directly with a more complex data payload. In most cases, this will require custom code in OASIS to process the more complex data.

  1. Once the oasis.xml file is read, OASIS will make a call to an OASIS web service known as CMQ (Configurator Message Queue).
  2. CMQ will return a session identifier and a URL to call the manufacturer web browser.
  3. OASIS will request from the operating system to launch the user's default browser using the URL returned by CMQ. Included in the request is the URL to return to CMQ.
  4. The browser interacts with the web configurator.
  5. When the configuration is complete, the web configurator calls CMQ directly delivering the data in JSON.
  6. The browser opens a page in CMQ using the URL from the web configurator - this data is stored to be returned to OASIS
  7. (N) During this time, OASIS is "polling" CMQ for the closing of the session. This happens when the web configurator does the redirect to CMQ.

oasis.xml

Use the following entry in the oasis.xml to start the configurator:

<OASISSpecialization>
  <configurator active="Y" browser="EXTERNAL" brand="cmq_brand"/>
</OASISSpecialization>

 

cmq_brand is assigned by the support team at Ingen Software.

Configuring CMQ

The OASIS Configurator Message Queue (CMQ) is maintained and supported by Ingen Software. Requests to add new entries to CMQ must be made to the support center (support@OasisSalesSoftware.com). The following information needs to be provided:

  • Base URL to access the configurator.
  • Syntax of the URL for sending the catalog number (partial or complete) that the user may have typed into OASIS.
  • How to include a session ID for CMQ - this session ID MUST be retained by the configurator to complete the session.
  • Whether the redirect or JSON method is to be used to complete the session.
  • If the configurator is capable of receiving a redirect to dynamically redirect to different CMQ instances.
  • Any other information that must be provided when starting the configurator session (e.g. userID, database ID).

With the information, the technical team is able to configure CMQ to respond to OASIS requests and properly queue data between the user and the configurator.

CMQ Redirect URLs

The most common way to close a configuration session is to send a redirect to CMQ. The browser will then call CMQ using the new URL. The format is very specific:

https://???.OasisSalesSoftware.com/CMQ/CMQ?SessionID=cmq_session&Catalog=config_catalog& ...

The server part of the URL may be hard-coded to a specific OASIS load server or the service may let OASIS send the redirect= parameter on the initial URL to the configurator. The required parameters are SessionID and Catalog. All other ULR parameters are optional and are assumed to be URL encoded:

  • SessionID - the session ID used to start the configurator
  • Catalog - the catalog number to use in OASIS
  • Low - the low price
  • LowCommmission - the commission rate for the low price
  • Overageable - the price where the rep is allowed to add overage to the item
  • OverageableCommission - the commission of the base overage able price

CMQ JSON

To close out the session using a direct call to CMQ, use the base URL with a POST containing the JSON payload. The base URL to use is:

https://???.OasisSalesSoftware.com/CMQ/CMQ?SessionID=cmq_session

The server part of the URL may be hard-coded to a specific OASIS load server or the service may let OASIS send the redirect= parameter on the initial URL to the configurator. The SessionID is not required when sending a JSON payload, but useful when debugging issues as the user can see the session ID in the browser address bar.

{"SessionID": ".....","configuration":{ ... JSON ... }}

The session ID is required in the JSON payload and the configuration may be arbitrarily complex for CMQ. However, OASIS by default will only understand a JSON configuration object containing the keys shown above as parameters in the redirect method.

Another nice option with using JSON is that the configuration object may actually be changed to an array of configured items:

{"SessionID": ".....","configuration":[{ ... JSON ... }]}

Examples

Example initial URL to start the configurator:

http://web2.OasisSalesSoftware.com/OASIS/UI?PageID=PLUConfigurator:manufacturer:RV:part:ABC&redirect=http://localhost:8080/CMQ/CMQ?SessionID=BRANDX_2019-04-25_08.31.34.452-10002

Only the SessionID and the redirect are important for this example. The rest of the items are specific to the configurator being used.

Example CMQ redirect URL to complete the configuration:

http://web2.OasisSalesSoftware.com/CMQ/CMQ?SessionID=RV_2019-04-25_10.17.57.931-10001&Catalog=SCL-42-4-CLR-B&Low=37.50&LowCommission=5.00&Overageable=47.50&OverageableCommission=10.00

This URL is formatted as required by CMQ.