Ag eStandards 5.4 WSDLs and Implementation Guideline

WSDL Download

Chem_eStandards_5.4_WSDLs.zip

Introduction

Web Service Description Language (WSDL) files referencing Chem eStandards version 5.4 XML schemas are available now to leverage in your business operations. This implementation guideline provides an approach that allows your technical team to adapt these WSDLs, exposing only the capabilities that you have physical back-end implementations that integration with your business applications.   

First note on API Security

The recommended approach is that these WSDL files are referenced in an API Gateway in your DMZ to enforce API security principles. The API Gateway will point to the service implementation in your backend application or middleware. The API security topic is out of scope for this implementation guideline.

Quick Overview of the WSDLs.

There are five Chem eStandard WSDL available, organized by business process category.  

The WSDLs are available at www.oagi.org or here.The standard WSDLs expose documents that have been known to be implemented by businesses as of the time of their inclusion.



It is the intent that AgGateway member companies will create an implementation-specific WSDL for the capabilities that they have software code implementations.    The WSDL will allow developers to ...

Typical Implementation Process

The Overall Implementation Process is similar to the following.

Understand your Business Goals

It is important to understand the overall value proposition, and return on investment for the integration.  Typically the value proposition is related to either business efficiency that may be gained, or regulatory in nature.


Describe Partner interactions with a Sequence Diagram

A sequence diagram shows at high level who initiates a messages and when the messages are exchanged.  If you need more detail, consider the use of Business Process Modeling Notation (BPMN), and illustrate the activities that precede the message exchange as that will provide more contextual information such as what data may be required.  A scenario for each process area is show in this implementation guideline.

Order Management

By looking at this sequence diagram, you will notice that the Customer.wsdl implements two messages; the OrderResponse and the Confirm.  The Seller.wsdl implements three messages; OrderCreate, OrderChange and Confirm.  

It is up to your business when to implement OrderChange.  In many AgGateway implementations, the first OrderResponse rejects order, and people talk on phone, update orders in both seller and customer systems.  The next OrderResponse accepts order, and sometimes an unsolicited OrderResponse is sent.

From an architectural view, the initial OrderResponse should inform Buyer which lines cannot be fulfilled by Seller.  The Buyer would update Order as appropriate, with OrderChange (options: cancel, provide line level change)





websequencediagram.com code

title AgGateway Order Management
Customer->Seller: OrderCreate
Seller-->Customer: Confirm
Seller --> Seller: verifyInventory
Seller -> Customer: OrderResponse
Customer --> Seller : Confirm
Customer-->Customer: reviewDemand
Customer->Seller: OrderChange
Seller-->Customer: Confirm
Seller --> Seller: verifyInventory
Seller -> Customer: OrderResponse
Customer --> Seller : Confirm

Finance

There two defined scenarios for Invoice processing; either by individual invoices (which is best suited for messaging or publishing scenarios), or a list of invoices.   A best practice is proposed but currently cannot be implemented without additional messages in Chem e-Standard.  A Freight Invoice scenario is also discussed.

Processing Individual Invoices

The recommendation from an architectural view is to process individual invoices one-by-one to manage payload sizes and not lose transactions or hold up processing if one of the invoices in the list has a data quality issue. Challenges to consider in this approach is that the Customer needs to expose Invoice API and may not have the API Gateway infrastructure to support this, and a Seller has many customers, therefore large number of endpoints that need to be managed.


 

title AgGateway Invoice
Seller->Customer: Invoice
Customer->Seller: InvoiceResponse 

InvoiceList

Considering finance departments process data in a batch-centric, InvoiceList is the most typical approach and suitable to model with web services.  The customer will issue a query request for outstanding invoices, usually based on date or other parameters, and the InvoiceList response is returned.  It should be forwarned that the InvoiceList payload could be very large.  Work-arounds include 1) query by DateTimeRange and more frequent polling, 2) ensure your integration leverages HTTP chunking (see section 3.6.1), and verify that your firewall and load balancer rules are setup properly to allow longer sessions to avoid time-outs.


title AgGateway InvoiceList
Customer->Seller: InvoiceListRequest 
Seller->Customer: Invoice 

Best Practice: Invoice Processing (currently not possible in v5.4)

The recommended Best Practice is currently not available using Chem e-Standard without the addition of an InvoiceRequest message (not available in v5.4).  The goal of this best practice would be to query for a list of available invoices using the InvoiceListRequest message and returning the InvoiceList message.  This is a variation of the InvoiceList scenario above with the exception that InvoiceList contains only a limited set of data specifically a list of Invoice Identifiers (IDs).  The customer would then iterate over the list of invoices and one-by-one retrieve the detailed Invoice by request the specific invoice by its ID.  All the messages in this scenario are small in sized, and seller's system is likely able to handle this load since it does not have to prepare a large payload.  Firewire and load balancer time-out settings can be set to realistic values.

 

FreightBill

A FreightBill is the same as the Invoice and is often noted as the CarrierInvoice.  The buyer of transportation services would need to expose the FreightBill operation in their API Gateway and return the Confirm as shown.  Please note this is not always the ShipTo location but the BillTo Party.

title AgGateway Finance FreightBill
Carrier->Seller: FreightBill
Seller->Carrier: Confirm

PaymentDetail

PaymentDetail is comparable to the Remittance Advice, when a payment amount is provided and detail regarding what invoices are paid.

title AgGateway Finance PaymentDetail
Customer->Seller: PaymentDetail
Seller->Customer: Confirm


Logistics

ShipNoticeList faces a similar challenge as InvoiceList where the payload can be load.  It is recommended to poll for invoices more frequent than once per day; e.g., every 15 minutes.

The last thing you want is truck to show up and the ShipNotice related to that truck has not be processed ahead of time.

The sequence diagram below also shows the DeliveryReceipt of the shipment.  The DeliveryReceipt is a recommended message to inform the Seller if all the items / quantities have been accepted (transferred ownership), or whether some product will be returned (e.g., quantity issues, damaged product, etc.).
 
 

title AgGateway Transportation
Customer->Seller: ShipNoticeListRequest
Seller->Customer: ShipNoticeList
Customer-> Seller: DeliveryReceipt
Customer-> Seller: DeliveryReceipt
Customer-> Seller: DeliveryReceipt


Create Your WSDL

The following is an example of an implementation WSDL that imports multiple standard WSDLs and exposes only the capabilities implemented.  This is a good starting point if you wish to download it and clone/ modify it to meet your business scenario.

WinFieldAgGateway.wsdl



It should be noted that each WSDL has its own namespace, with the following URNs.  There is no need to edit the standard WSDLs but only edit your company specific WSDL from which an implementation will be constructed.

WSDL

Namespace for this WSDL

urn:cidx:names:specification:ces:wsdl:finance:5.4.0

urn:cidx:names:specification:ces:wsdl:inventory:5.4.0
urn:cidx:names:specification:ces:wsdl:ordermanagement:5.4.0
urn:cidx:names:specification:ces:wsdl:quality:5.4.0
urn:cidx:names:specification:ces:wsdl:transportation:5.4.0

These show up in the definitions element of you member company specific WSDL:

<definitions
name="WinFieldImplementationOfAgGatewayWebServices"
targetNamespace="www.winfield.com/aggateway/webservices"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns="www.winfield.com/aggateway/webservices"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:cidx="urn:cidx:names:specification:ces:schema:all:5:4"
xmlns:inv="urn:cidx:names:specification:ces:wsdl:inventory:5.4.0"
xmlns:fin="urn:cidx:names:specification:ces:wsdl:finance:5.4.0"
xmlns:om="urn:cidx:names:specification:ces:wsdl:ordermanagement:5.4.0"
xmlns:tran="urn:cidx:names:specification:ces:wsdl:transportation:5.4.0"
>

Import the required Chem e-Std WSDLs

The WSDLs you need will be dependent on the scenario you need.  The sample member company specific WSDL illustrates four imported WSDLs

<wsp:UsingPolicy xmlns:n1="http://schemas.xmlsoap.org/wsdl/" n1:Required="false"/>
<import location="ChemEStdFinance.wsdl" namespace="urn:cidx:names:specification:ces:wsdl:finance:5.4.0"/>
<import location="ChemEStdInventory.wsdl" namespace="urn:cidx:names:specification:ces:wsdl:inventory:5.4.0"/>
<import location="ChemEStdOrderManagement.wsdl" namespace="urn:cidx:names:specification:ces:wsdl:ordermanagement:5.4.0"/>
<import location="ChemEStdTransportation.wsdl" namespace="urn:cidx:names:specification:ces:wsdl:transportation:5.4.0"/>


For the InvoiceList scenario, only the ChemEStdFinance.wsdl is required.  This shows the other WSDL commented out so if you need them later for another implementation project, they can be added back in.

<wsp:UsingPolicy xmlns:n1="http://schemas.xmlsoap.org/wsdl/" n1:Required="false"/>

<import location="ChemEStdFinance.wsdl" namespace="urn:cidx:names:specification:ces:wsdl:finance:5.4.0"/>

<!--
<import location="ChemEStdInventory.wsdl" namespace="urn:cidx:names:specification:ces:wsdl:inventory:5.4.0"/>
<import location="ChemEStdOrderManagement.wsdl" namespace="urn:cidx:names:specification:ces:wsdl:ordermanagement:5.4.0"/>
<import location="ChemEStdTransportation.wsdl" namespace="urn:cidx:names:specification:ces:wsdl:transportation:5.4.0"/>

-->

Edit Ports and Bindings

Ports

The port definition will contain a collection of operations, and each operation will reference messages for the input and output.  The messages are defined in the corresponding WSDL which subsequently reference elements in the Chem e-Standard XSD.  The sample company specific WSDL can be edited from this:

<portType name="WinFieldAgGatewayPortType">
<operation name="InvoiceListRequest">
<input message="fin:InvoiceListRequest"/>
<output message="fin:InvoiceList"/>
<fault name="WinFieldInvoiceListRequestServiceFault" message="fin:CESServiceFault"/>
</operation>
<operation name="ProductMovementReport">
<input message="inv:ProductMovementReport"/>
<output message="inv:Confirm"/>
<fault name="WinFieldProductMovementReportServiceFault" message="inv:CESServiceFault"/>
</operation>
<operation name="InventoryActualUsage">
<input message="inv:InventoryActualUsage"/>
<output message="inv:InventoryActualUsageResponse"/>
<fault name="WinFieldInventoryActualUsageServiceFault" message="inv:CESServiceFault"/>
</operation>
<operation name="ShipNoticeListRequest">
<input message="tran:ShipNoticeListRequest"/>
<output message="tran:ShipNoticeList"/>
<fault name="WinFieldShipNoticeListRequestServiceFault" message="tran:CESServiceFault"/>
</operation>
<operation name="PriceSheetRequest">
<input message="om:PriceSheetRequest"/>
<output message="om:PriceSheet"/>
<fault name="WinFieldPriceSheetRequestFault" message="om:CESServiceFault"/>
</operation>
</portType>

To this for the member company specific WSDL. in this case to expose the InvoiceListRequest operation that receives the InvoiceListRequest  message and returns the InvoiceList message:

<portType name="MemberNameAgGatewayPortType">
<operation name="InvoiceListRequest">
<input message="fin:InvoiceListRequest"/>
<output message="fin:InvoiceList"/>
<fault name="MemberNameInvoiceListRequestServiceFault" message="fin:CESServiceFault"/>
</operation>

</portType>

Do not edit the ChemEStd WSDLs!!

Bindings

The binding area defines the document style of the binding (not rpc), that the body is literal to the XSD definitions, how to handle faults (improvements needed), and the policy approach for authentication (this is currently commented out and left to the implementor).

<binding name="MemberNameAgGatewayServiceBinding" type="tns:MemberNameAgGatewayPortType">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="InvoiceListRequest">
<soap:operation soapAction="InvoiceListRequest"/>
<input>
<soap:body use="literal"/>
<!--
<wsp:Policy>
<wsp:PolicyReference URI="policy:userNameTokenPolicy"/>
</wsp:Policy>
-->
</input>
<output>
<soap:body use="literal"/>
</output>
<fault name="MemberNameInvoiceListRequestServiceFault">
<soap:fault name="MemberNameInvoiceListRequestServiceFault" use="literal"/>
</fault>
</operation>
</binding>

Service Name and URI address

The following is only an example of the service name and 
<service name="MemberNameAgGatewayService">
<port name="MemberNameAgGatewayServicePort" binding="tns:MemberNameAgGatewayServiceBinding">
<soap:address location="https://ws.MemberName.com/SOAP/AgGatewayWebServices_5.4"/>
</port>
</service>


Generate Code and Integrate to Backend


Now allows XSLT mapping tools to see data elements
 

Confirm visually in JDeveloper IDE

Member Implementations
 

Composite View



Only company implemented operations available