Figuring out Epicor Web Service
One of the bigbenefits of Epicor is that every business object has a corresponding web service call. This is a big plus if you are in the business of integrating disparate systems, which my company is often tasked to do. However, putting this feature into practice isn’t as easy as I had hoped. This article provides a step-by-step outline of how you can map the options within Epicor to corresponding business methods, and ultimately your web services.
- Turn off Epicor system monitor in the Windows task tray (right click -> exit).
- Go into your Epicor application. The test I performed here is for Order Shipping, found in Material Management/ShippingReceiving/General Options/Customer Shipment Entry.
- Turn on tracing (Options/Tracing Options)- select ‘Enable Trace Logging’, ‘Exclude client processing from method timing’ and ‘Write Full Data Set’. Click Apply.
- Ship the order (or whatever process in Epicor you are tracing).
- Launch E9 performance diagnostics tool.
- On the Client Diagnostics tab, click the ‘…’ button next to “Client Trace File Path” to browse for the trace file specified in the Epicor Tracing Options screen.
- Once selected, click “generate diagnostics”.
- This will generate a table of all the methods called during the tracing process. To filter, click the filter icon next to ‘Object Name’ in the table headings and select whichever object you want to see.
- List of Objects & Methods involved in this particular test of order shipping, which was to ship all items on the order (CustShip object):
|Object Name||Method Name|
|CustShip||GetNewShipHead||Epicor.Mfg.BO.CustShip: This business object contains 122 methods. GetNewShipHead: Inserts a new row in the DataSet with defaults populated.|
|CustShip||GetHeadOrderInfo||This method displays the customer/address information when the OrderNum field in the header changes. Shouldonly be called for new Customer Shipments, or Customer Shipments w/o lines|
|CustShip||BuildShipToCustomerList||If the Order has releases to multiple Customers, this will return the list of available Customer shiptos to selectfrom|
|CustShip||BuildShipToList||If the Order has releases to multiple shipto’s, this will return the list of available shiptos to select from|
|CustShip||UpdateMaster||? Looks like generic method ?|
|CustShip||POGetNew||This method creates a new packout record for the customer shipment packout screen. can pass in a OrderNumor PackNum or Both.|
|CustShip||POGetDtlList||This method copies the available Order Release lines to the PackOut datatable for update|
|CustShip||MarkShipmentLines||This method sets all the temp-table records to be shipped (Ship all button selected)|
|CustShip||UpdateMaster||? looks like generic method ?|
|CustShip||PreCreateMassShipDtl||This method checks to see if it’s okay to copy the available Order Release lines to the ShipDtl datatable for updatein Mass Shipments|
|CustShip||CreateMassShipDtl||This method copies the available Order Release lines to the ShipDtl datatable for update|
Lookup each object in the ICE_SDK25_BO_Methods.pdf manual. A description of each method is included.
10. Figure out which methods are required and which are not, based on your unique business rules and configuration. This is a manual analysis task. Sorry.
11. Using WS-Tester, navigate to the URL where your Epicor web services are located, for example: http://servername/EpicorServices/
12. Double-click the service to pull in all available methods. This may take a few minutes to complete.
13. Search for the appropriate method in the dropdown box (under the service details tab). Enter the necessary credentials and appropriate parameters. Click ‘invoke’.
14. The step above tests the web service against your Epicor system and returns a result. If the test fails, you probably didn’t include the proper credentials, used an invalid company code, or had invalid data.
15. If the test is successful, you can use the results & return values to see what the method returns back.
NOTE: If you are using another tool to build out your XML and web service calls (such as SOAPUI), you may find WS-Tester can help identify differences in XML or SOAP headers that may prevent the SOAPUI calls from successfully completing. Below are a couple different methods for determining differences:
Microsoft Internet Information Services (MIIS) Tracing
- Make sure MIIS Tracing is enabled (http://msdn.microsoft.com/en-us/library/aa529559.aspx)
- open MIIS Manager
- expand your Epicor application server
- expand Sites/Default Web Site/
- click on whichever service URL you are communicating with
- click ‘Explore’ on the upper right hand part of the screen under ‘Action’
- Right click the ‘Web’ config file and open with Notepad
- Locate the ‘<microsoft.web.services3>’ section
- Make sure that the following exists:
<trace enabled=”true” input=”C:\temp\InputTrace.webinfo” output=”C:\temp\OutputTrace.webinfo” />
- If this line already exists, exit the file and proceed to the next bullet
- If this line was added, save the file and exit. The IIS server will have to be restarted
- Go through the exact same WS-Tester steps that you will have to do during automated processing
- Open the ‘C:\temp\InputTrace.webinfo’ file in notepad and search for the method name for which you are looking for the XML call
- Copy the XML from the trace file into SOAPUI. If the transaction fails, you may need a few corrections to namespaces or the ‘Security’ header section, but the data in the body section should all be valid
- Start WS-Tester and get it set up, but do not click “invoke” yet.
- Launch Wireshark and start a packet capture on the appropriate network interface.
NOTE: Do not do this if you are running WS-Tester on the Epicor server – it will be difficult to narrow down the traffic if you run Wireshark on a server. For faster/easier results, I recommend running WS-Tester and Wireshark from your local machine.
- Click “invoke” on WS-Tester to initiate the web service.
- When complete, stop the packet capture on Wireshark.
- From Wireshark, click on the first TCP (SYN) packet connected to the invoking of the method and click ‘Analyze’, ‘Follow TCP stream’. You’ll receive a nicely formatted conversation between your system and the Epicor web services server, showing all data sent. Use this to compare to your web service call from the other tool. Chances are, there is a difference somewhere. Here are two common problems we found:
- Missing elements sent in a GetNew call: The Epicor BO_Methods manual lists many elements as “optional”, but they really aren’t. The GetNew often requires a bunch of default values to be passed. When you run the web service through WS-Tester, you’ll see the default values being passed and must recreate this in your other tool.
- Slight differences in SOAP header information.
After you have worked through each web service and method, and can send the web service from WS-Tester and SOAPUI, you can create the exact same SOAP message within any system required to communicate with Epicor.
Good luck — and may the force be with you.