Skip to main content

OCI Standards

Updated

An OASIS Certified Integration is a formal coordination, development, contract, and implementation of integration between OASIS and a 3rd party. It is meant to allow both sides to advertise the synergy that has been allowed through close coordination between Ingen and the 3rd party. A list of manufacturers and their levels of certified integrations can be found here.

 

Managing Expectations

These standards exist to product a consistent user experience, minimize support costs and help maintain the connectivity over time.  By conforming to these standards, the manufacturer is identifying itself as serious and capable of working with Ingen Software in developing a good solution. A well-designed system using serious integration processes that is supported long term by the factory opens doors for everyone.

Regarding, imported data from outside systems, we are very strict on key rules. Competitors might be more permissive on allowing data into their system. That is fine. However, here are a few of the reasons why we don’t take an overly permissive approach:

  • Can't track what we don't know about (i.e., using side system to track replacement parts)
  • Keeping customers updated on all material on the job - including replacement parts
  • Unified process for tracking any shipping issue (e.g. no date, missed date, re-dated, etc.)
  • We have developed machine learning based prediction tools that require dependable data

Bottom Line:

  • The factory is serious about integration
  • The factory is capable and has sufficient resources (human and financial)
  • The factory will help us support the integration

 

Requirements for Any Solution

    • One-time setup for agency
    • Secure Connection - login credentials per agency (not per user)
    • Web-enabled implementation (OASIS client sends request to web service)
    • Service is running properly at least 95% of the time
    • Logging of error or bad data
    • The 3rd party must designate a contact that is readily available to:
      • Manage the solution project on the 3rd party’s behalf
      • Provide technical support for the 3rd party’s implementation of the solution

 

Certification Levels

Companies that work with Ingen on integration with their systems will be awarded formal OASIS Certified Integration Levels. The total number of OASIS Certified Integrations is denoted by a roman numeral.  For example, if a company has three OASIS Certified Integrations, then the awarded level will be III. Note: any integration requiring manual drag/drop or cut/paste will not count as a Certification Level.

The third party will be authorized to display the OASIS Certified Integration badge for the appropriate level if the certification is maintained. Ingen will provide the badge once the integration is completed. The third party will also be listed on Ingen’s website showing their certified level. At a minimum the third party’s name will be listed, however the third party’s logo and a link to their website will be added if the third party approves. 

 

Specifications

Acceptable File Formats and Payloads

Today there are too many well-defined ways of formatting data to be exchanged between different data systems. There is rarely a reason to “roll your own”. The most common and preferred formats are JSON and XML (with or without .xsd).

OASIS does have a native format for most of the OASIS integration points (e.g., orders). That format is known as an o2o file format and is defined using XML. This format can be used as a starting point for discussion when integration with OASIS. However, any agreed upon protocol used for integration should not be considered o2o. The best option is to do a mapping of whatever the protocol is (e.g., an XML format based on the current o2o standard) and map into the OASIS data model. Or developers will:

  • Always parse all inbound payloads
  • Map the parsed payload into any required OASIS memory objects
  • Then send to the internal OASIS processor

EDI will not be considered as a solution as it simply does not have the expressive power to meet the need.  CSV and XLS spreadsheets are also not a valid format.

Acceptable Protocols

FTP and all related protocols will not be part of the solution.  Email will not be part of the solution and indicates a level of capability that raises serious concerns.

The current preferred protocols:

  • JSON and REST
  • XML and SOAP (with or without .wsdl)

For non-data formats (like a PDF file of the customer):

  • MIME encoding (REST and SOAP http protocols)
  • BASE64 encode or HEX encode the binary data and send as JSON or XML text (string)

Data Logging

The OASIS attachments are critical to the long-term support of any integration. The following will be required:

  • All inbound and outbound payloads will be stored as an attachment in the related transaction
  • Responses will not be combined (e.g., save each send or receive as a separate attachment)
  • Use a file name with a proper extension (e.g., json, .xml)
  • Do not over-write the files … create a new one
  • Distinguish the name by the action: “New PO Send.xml”, “New PO Response.xml”, “New PO.pdf”

The exception to logging include:

  • Pricing and Configurator calls – although a debug flag should be setup to allow logging to the OASIS##.log files during troubleshooting
  • Any required lookup calls. A good example would be converting a decimal number to a GUID when sending an order. The lookup call does not have to be logged, although a debug flag could be used

Exception Handling

Exception handling considerations include the following:

  • Minimizing popups/nagging warnings for customer. Get the messages they need to see and suppress others.
  • Ensure ALL exceptions are logged. Even suppressed messages need to be logged somehow.

Transmission Times (Introducing in 2024)

When a thread is created to monitor the connection to a remote server (e.g. a manufacturer's backend), resources are consumed and retained during that time. Additionally the user is not able to understand what is happening - we just are blocked.  The key is to be realistic on system resources and limits on user patience

Philosophy:

  • Any call to a backend lasting longer than 60 is not good for the end user and will result in many web servers releasing the resources and returning a 500 type error.
  • Given that resource utilization during high demand times tends to compound exponentially, it would make sense to not have any design that would cost more than 15 seconds of wait time (1/4 the typical timeout).
  • Increasing timeouts is a poor design and will cause secondary issues (resource limits, DB locks and potentially data integrity issues with users retrying)
  • Some "larger transactions" must be supported.
  • To protect data integrity, user timeout should be just a few minutes - say 5 if pushed to pick a generous time. Anything above 1 minute and you risk the user just closing the browser and then re-trying the transaction resulting in multiple quotes/orders or whatever being submitted.

Thus, OCU will require the following moving forward in 2024:

  • Hard stop on anything taking longer than 15 seconds to allow for high demand times.  Let the user get back to work with a message that conveys it was taking too long.
  • Consistently causing high demand stops due to the design not meeting the 15 second limit may be decertified.
  • Long running requests need to broken into multiple calls. For example:
    • Send quote header
    • Send 50 lines (or so)
    • Add 50 more lines until done
    • Separate call for status update so the user is satisfied something is happening.

 

OASIS Certified Integrations

Dynamic Pricing

  • There are two parts to this service:
    • Product
      • Returns alphabetized list of complete parts that “start with” the value as it is entered in a quote/order
      • Product search begins with the 3rd (or more) characters
      • Minimum complete part length is 3
    • Price
      • Returns data for one complete part
      • At least two level of price returned is considered fully qualified
      • Levels of price and commission:
        • Low or Territory-specific
        • Overageable – the price that overage will begin
        • Book – can be included but not required
        • Customer-specific – can be included but not required
      • There should be no more than two requests required to get all possible pricing.
      • For each service, the value should be returned within 2 seconds (5 seconds or less required).
      • Any 3rd party requirements that require more than returning product and price for a request as described above may influence the certification decision.

Note: P2P Pricing is a standard “off-the-shelf” implementation that meets all standards defined. 

Batch updates have many detriments:

  • Requires agency interaction on a periodic basis
  • Not convenient for the agency
  • Places responsibility to keep accurate pricing in the hands of each agency
  • Require important resource time to complete the download
  • Become problematic if the file grows too large.

Any 3rd party implementing a batch update pricing solution will not receive a certified rating.

Configurator

  • 3rd party web site returns information via one of the following:
    • Redirect and standard part, price, and commission parameters for one part
    • JSON Post with standard part, price, and commission for one or more parts
    • JSON Post with information requiring a customized parse and application in OASIS
  • If returning alternate brand - pre-mapped in MFG Specialization required
  • The values should be returned within 2 seconds (5 seconds or less required).
  • Any 3rd party requirements that require more than returning standard product and price may not receive a certified rating.

Note: configurator Message Queue is a standard “off-the-shelf” implementation that meets all standards defined.

Request For Quote (Send/Receive)

  • Web service consumes supported data:
    • Quote Header (not a comprehensive list):
      • Database ID (or equivalent) – required
      • Quote ID (or equivalent) – required
      • Project Name
      • Location City/State
      • Bid Date
      • Expiration Date
      • Notes
      • Terms
      • Specifier Role and Name
    • Bill of Material (not a comprehensive list)
      • Catalog Number - required
      • Target Price - required
      • Brand * If sub brands are implemented then pre-mapping is required
      • Quantity
      • Fixture Type
      • Description
      • Notes
      • Unit Quantity
      • Part Quantity
    • Web service acknowledges receipt of request and provides relevant messages if the request is not accepted
    • Web service produces the following at a minimum
      • Quote ID
      • Catalog Number
      • Approved Price
    • The required time thresholds are broken down into two phases:
      • Send: The service must allow for sending each request within 5 seconds for a single quote and 2 seconds average per quote if performing a bulk send. It is understood that large quotes of greater than 100 lines might exceed these thresholds.
      • Response: After the send is complete, it is expected that a proper response (success, fail, error, etc) is returned within 5 seconds. This applies for both single quote or after a bulk update of quotes.
    • The integration must meet an 80% match rate for those transactions sent from OASIS.
    • Any 3rd party requirements that require more than a reception of targeted price requests and a corresponding response as described above may not receive a certified rating.

Forecast

  • The agency must be allowed to opt in/out of the whole service or portions of the following.
  • Project data:
    • DBID
    • Quote ID
    • Project Name
    • Location City and State
    • Bid Date
    • Last Update Date
    • Quote Status
  • Order data:
    • DBID
    • Order ID
    • Quote ID
    • Order Number
    • Sold To, Bill To, Ship To Information
    • Entry Date
    • Last Update Date
  • Specifier data:
    • Name
    • Role
    • Address
    • Account
  • Bill of material data:
    • Line Number
    • Quantity
    • Catalog Number
    • Fixture Type
    • Brand
    • Unit Quantity
    • Part Quantity
    • Sell Price – order lines only

Note: P2P Forecast is a standard “off-the-shelf” implementation that meets all standards defined. 

Inventory (Stock Status)

  • Web service receives request to supply inventory information for a part number
  • Web service returns well-structured inventory information only. Information can reflect quantities available at multiple locations.
  • Must include Catalog number, warehouse ID, and quantity.
  • The required return time for each request is 5 seconds minimum.
  • Web service acknowledges receipt of request and provides relevant messages if the request is not accepted

Order Send

  • Initial order submission support only (no syncing of change orders)
  • Web service consumes supported data:
    • Order (not a comprehensive list):
      • Database ID (for matching) – required
      • Order ID (for matching) – required
      • Customer ID – mapping from OASIS ID to 3rd party ID required
      • Create Date
      • Project Name
      • Customer ID
      • Notes
      • Terms
      • Ship To Address
      • Specifier Role and Name
    • Bill of Material (not a comprehensive list):
      • Line UID (for matching) – required
      • Brand, If sub brands implemented - pre-mapping is required
      • Quantity
      • Fixture Type
      • Part Number
      • Sell Price
      • Notes
      • MFG Quote
      • Part Quantity
      • Unit Quantity
    • Web service acknowledges receipt of request and provides relevant messages if the request is not accepted
    • Sales Order number is supplied in response as indicator of success of the process
    • All efforts must be made to facilitate Partial and Hold orders if the ERP system allows.
    • The required time thresholds are broken down into two phases:
      • Send: The service must allow for sending each request within 5 seconds for a single order and 2 seconds average per order if performing a bulk send. It is understood that large orders of greater than 100 lines might exceed these thresholds.
      • Response: After the send is complete, it is expected that a proper response (success, fail, error, etc) is returned within 5 seconds. This applies for both single order or after a bulk update of orders.
    • Any 3rd party requirements that require more than reception of order information and a corresponding response as described above may influence the certification decision.

Note: files output to ftp sites, email, etc. or that utilize EDI format will not receive a certified rating.

Order Status (Shipping)

  • There are two parts to this service:
    • Order Listing that returns list of orders with relevant changes since last request
    • Order Status that returns order status information for the order passed in the request
  • Database ID and Order ID must be returned for matching
  • Unique OASIS Line ID for each bill of material line must be returned for matching
  • Must include quantity shipped and date. Estimated dates and tracking information can be returned.
  • Web service must acknowledge receipt of request and provides relevant messages if the request is not accepted
  • The required time thresholds are broken down into two phases:
    • Send: The service must allow for sending each request within 5 seconds for a single order and 2 seconds average per order if performing a bulk send. It is understood that large orders of greater than 100 lines might exceed these thresholds.
    • Response: After the send is complete, it is expected that a proper response (success, fail, error, etc) is returned within 5 seconds. This applies for both single order or after a bulk update of orders.
  • If Order Send Integration is enabled, the Order Status integration must meet an 80% match rate for those transactions sent from OASIS.
  • Any 3rd party requirement that does not meet the standards described above may influence the certification decision

Invoices

  • There are two parts to this service:
    • Invoice Listing that returns list of invoices available for import since last request for invoices
    • Invoice Data that returns invoice information for the invoice ID passed in the request
      • Database ID and Order ID returned for matching – required
      • Invoice Number – required
      • Lot Invoices – amount of invoice to apply to the matching order
      • Detailed Invoices
        • Unique OASIS line ID of order lines for each bill of material line returned for matching – required
        • Quantity per line
        • Dollar amount per line
      • Web service must acknowledge receipt of request and provide relevant messages if the request is not accepted
      • The required return time for each request is 5 seconds minimum for a single invoice and 2 seconds average per invoice if performing a bulk update.
      • If Order Send Integration is enabled, the Invoice integration must meet an 80% match rate for those transactions sent from OASIS.
      • Any 3rd party requirement that do not meet the standards described above may influence the certification decision

Payments (Commission Reconciliation)

For payment downloads, the following is required:

  • Method to identify the month or ACH payment (e.g. december commission check)
  • invoice number and amount paid on that invoice

There are two parts to this service:        

  • Payment Listing that returns list of payments available for import since last request for payments
    • Payment Data that returns payment information for the payment ID passed in the request. It must include:
      • Database ID
      • Order ID
      • Invoice Number
      • Commission Amount
    • Web service must acknowledge receipt of request and provide relevant messages if the request is not accepted
    • If Order Send Integration is enabled, the Payment integration must meet an 80% match rate for those transactions sent from OASIS.
    • Any 3rd party requirement that do not meet the standards described above may influence the certification decision

To help the user identify issues, the following is recommended:

  • PO Number and Date
  • Invoice date (with invoice number and amount paid)
  • Customer Number
  • Brand (if multi-brand manufacturer)

Certification Review

Each connectivity solution will be reviewed every year to ensure basic standards are met.  The 3rd party will be notified that the review is happening and will receive the results of the review.  The review will include:

  1. Basic – Does the solution still return useful information to the OASIS user?
  2. Is the performance acceptable?
  3. Are excessive resources being used (e.g., CPU, disc, network)?
  4. Does the solution meet the requirements listed in this document?
  5. Is the solution still funded (contract, annual maintenance and support, etc.)?

If defects are found, the 3rd party will be notified.  Three months will be allowed for the defects to be addressed before any decertification actions are taken.

Ingen will send out Monthly Statistics to ensure the 3rd party is aware of any issue well in advance.  Any integrations that are not plumbed with logging of error or bad data will have that added before any decertification actions are taken.

Failed Certifications

Any integration that fails the certification will result in one of the following actions:

  1. The Certification will be removed, but the integration will still be supported. This will result in a drop in the OCI level and associated badge awarded.
  2. The integration will be labeled as non-supported but remain deployed to OASIS users. This will result in a drop in the OCI level and associated badge awarded.  The 3rd party will be refunded any unused maintenance and support fees pro-rated based on the number of months into the billing cycle.
  3. The integration will be deprecated and no longer be deployed. This will result in a drop in the OCI level and associated badge awarded.  The 3rd party will be refunded any unused maintenance and support fees pro-rated based on the number of months into the billing cycle.

 

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk