Epicor web service – step-by-step

By | 2012/06/25

Epicor Tracking OptionsFiguring 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.

  1. Turn off Epicor system monitor in the Windows task tray (right click -> exit).
  2. Go into your Epicor application.  The test I performed here is for Order Shipping, found in Material Management/ShippingReceiving/General Options/Customer Shipment Entry.
  3. Turn on tracing (Options/Tracing Options)- select ‘Enable Trace Logging’,  ‘Exclude client processing from method timing’ and ‘Write Full Data Set’.  Click Apply.
  4. Ship the order (or whatever process in Epicor you are tracing).
  5. Launch E9 performance diagnostics tool.
  6. 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.
  7. Once selected, click “generate diagnostics”.
  8. 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.
  9. 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

Wireshark Method

  • 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.

 

29 thoughts on “Epicor web service – step-by-step

  1. Paul Melnikow

    Thanks for this detailed post! Am I right that you’re not using Service Connect here?

    Reply
    1. lhomsher Post author

      Paul – yes, that is correct. We’re going directly to Epicor, using their BO methods and web service calls — no service connect. Let me know if I can help clarify anything else for you.

      Reply
  2. ModeratelyFunky

    Thanks for posting this. Started working through your steps until I got to 11. Can you let me know where to find WS-Tester?

    Reply
    1. lhomsher Post author

      I believe WS-Tester came as part of our Epicor purchase. Check in utilities, which is found here: //EpicorAppServer/epicor/Utilities

      Reply
  3. Fidela Ungerman

    An impressive share! I’ve just forwarded this onto a friend who had been doing a little homework on this. And he in fact ordered me dinner due to the fact that I stumbled upon it for him… lol. So allow me to reword this…. Thanks for the meal!! But yeah, thanks for spending time to discuss this matter here on your web page.|

    Reply
    1. lhomsher Post author

      Thank YOU for your comments and I’m glad you got a meal out of it 🙂

      Reply
  4. Rob Cowper

    Thanks for this – most useful. Yes, GetNew does have several ‘optional’ mandatory defaults -one just has to spend a day on DMT to see just how true that is!

    Reply
    1. lhomsher Post author

      Thanks for the comments, Rob! It’s nice to “meet” another Epicor web services user. You are right — DMT is a very useful tool!

      Reply
  5. Chris

    I’m consuming epicor web services extensively but am finding that it is terribly slow. It can take two minutes to call GetByID() on the JobEntryService. Anyway of speeding this up? It’s running on a $30,000 machine purchased in 2013 so it’s not a hardware problem. Doesn’t take two minutes to load via the epicor client, but using ws-tester or any other soap client takes forever!

    Reply
    1. lhomsher Post author

      Hey Chris – that is slow! I didn’t experience this using SoapUI or ws-tester. Perhaps something isn’t optimized properly on your server. Did you customize anything connected to JobEntryService within the Epicor application? Are all web services slow, or only JobEntryService? You might try hitting the web service while capturing the traffic in Wireshark, just to see if it’s getting hung up somewhere outside of Epicor. If Epicor seems to be the culprit, you can contact Epicor support. They have some great web service guys who can probably help you figure out the problem.

      Reply
  6. Asmoro

    Great article, thanks for sharing, it made me understand why always failed to acess epicor webservice with tools other than ws-tester.
    But now i am still struggling using SOAPUI plugins in eclipse to identify diference XML or SOAP and don’t know where to replace the copied of XML trace file into SOAPUI. I am newbie with this plugins.
    Would you show me how to do that? i am using partservice.asmx.
    thanks in advance.

    Reply
    1. lhomsher Post author

      Good question – I struggled to get the correct SOAP elements in place as well. I used Wireshark to capture the actual packets from WS-Tester. This allows you to actually see ALL of the web service request, including the SOAP portion. Since it all works beautifully with WS-Tester, you just need to see the details of what WS-Tester sends. Install Wireshark on your PC and start it up. Then start WS-Tester. When everything is ready, click ‘capture packets’ in Wireshark, then invoke your web service in WS-Tester. After WS-Tester comes back with a successful web service call, stop capturing packets in Wireshark, find the packet that sent the web service request (Wireshark’s “Follow TCP stream” is helpful), and look at the data sent in the packet. You should see the entire XML request including SOAP headers and auth elements. Simply copy/paste the SOAP portion into SOAPUI to ensure you have everything in its proper place the way Epicor wants it.

      Good luck!

      Lori

      Reply
      1. Asmoro

        Finally after a week struggling with SOAP headers and auth elements, i can create request SOAP using java and got the response.
        thanks Lori.

        Reply
        1. lhomsher Post author

          Excellent…so glad you got it working! SOAP headers can be difficult, and you must match what Epicor wants (perfectly). I do remember having to tweak some of the SOAP header attributes (like date/time and authentication info).
          Congrats on getting it to work!

          Reply
  7. Ajay kumar dubedi

    Hi, I was trying to integrate Salesforce and Epicore ERP system. I was not able to find ICE_SDK25_BO_Methods.pdf Can you please let me know the link to this pdf.

    Reply
    1. lhomsher Post author

      Ajay, I downloaded the original BO_Methods PDF using my Epicor customer login. There are tons of documents available to existing customers — and you can confirm that you are downloading the version that best meets your needs. Alternatively, you can try general searching, but no guarantee the version will match. Here’s one I found for version 9.05: http://www.scribd.com/doc/73735259/BOMethods-905-2
      Good luck with the salesforce integration!
      Lori

      Reply
  8. PalMik

    Some additional tips in here to speed up our API dev, thanks probably saved us a lot of hours.

    Reply
  9. Sibaram Panda

    Which automation tool is good for epicor testing? Anyone help me ?

    Reply
    1. lhomsher Post author

      I used WS-TESTER to test the Epicor APIs…I suppose it depends on the type of testing you wish to do. We did not use automated testing tools for our Epicor customizations.

      Reply
  10. Duc

    Hi!
    I follow your article and I see how I can void a payment through Epicor Web Service, but when I try to void a payment by API, everything run normaly but data on Epicor UI is not updated. Please help me to know a reason! Thank!

    here my C# code:

    //get list payment we can void
    var list = voidPayment.GetList(@”Company = ‘EPIC06’ AND Voided = false AND Posted = true AND ClearedPending = false AND ClearedCheck = false AND (PCashDeskID = null OR PCashDeskID = ”) AND (CheckNum 0 OR (CheckNum = 0 AND ApplyingPayment = true)) BY HeadNum”, 0, 0, out morePages);
    // select a payment to void
    var checkHedListRow = list.CheckHedList.FirstOrDefault(t => t.Name.Equals(“Vendor Name”));
    if (checkHedListRow != null)
    {
    //get void payment dataset
    var dataset = voidPayment.GetRows($”Company = ‘EPIC06’ and HeadNum={checkHedListRow.HeadNum}”, string.Empty, 0, 0, out morePages);
    //udpate data to void a payment
    dataset.CheckHed[0].VoidDate = DateTime.Today;
    dataset.CheckHed[0].RowMod = “U”;
    dataset.CheckHed[0].SelectedForAction = true;

    Console.WriteLine(dataset.CheckHed[0].Voided); // voided is false
    // void a payment
    voidPayment.Update(ref dataset);
    Console.WriteLine(dataset.CheckHed[0].Voided); // voided is true but data on UI is not updated!

    Reply
    1. lhomsher Post author

      Unfortunately, I don’t have a system that I can test your code through. However, one possibility is your UI has a business rule somewhere that may be preventing the void from showing properly. Epicor has rules that can apply at the UI and even at the data level. These rules may be applied at a higher level than your void, which may cause the UI to display different than you expect.

      Another possibility is that there are other fields required for a voided payment. Your Epicor support provider should be able to provide those details. Sorry I can’t be of more assistance. If you find out more, please come back and let us know the answer!

      Reply
      1. Duc

        Thanks for your help.
        I had go to server and checked on database, but ít’s still not updated.
        I have a question for you, if you know please help me!
        A question is:
        How I can create a payment with credit card and apply credit for payment in Account Payable feature?

        Thank you!

        Reply
        1. lhomsher Post author

          I’m sorry to say that I know nothing about credit card payments in Epicor. However, I do have some contacts who are Epicor gurus. One company I used back in 2012 was particularly good with Epicor customizations (Alternative Technology Solutions), but I see they had a bit of trouble with Epicor in 2013. It looks like Epicor now controls all of their Epicor services.

          Another idea I used in the past is to purchase a couple of hours from Epicor services/support and have them walk you through exactly what you need help with. I did this when I was trying to figure out Epicor’s APIs and it was the BEST 2 hours of support I’ve ever purchased. It allows you to focus into the exact transaction(s) of interest.

          Good luck – I’d be interested in hearing the results!

          Reply
          1. Duc

            Thank you so much!
            I will update result to you if I figured out

  11. Mark Kamoski

    Do you have a similar, basic example on how to use C# to read/write into Epicor using Service Connect?

    Reply
    1. lhomsher Post author

      Unfortunately I do not. The basic tools in my post will help you troubleshoot through required Epicor objects, methods, and data elements for specific transactions, regardless of the language you ultimately use to code the actual solution. We were using an integration server to pull it all together.

      I can connect you with a good Epicor implementation specialist if you’d like guidance for your particular project.

      Reply
  12. David

    Hello,

    Is it possible to take a straight XML file and import it into Epicor Vision? If not, what would you suggest an alternative would be? My data can only be in XML format.

    Thanks so much for the advice.
    David

    Reply
    1. lhomsher Post author

      It’s been a while since I’ve worked with Epicor, but I believe it handles XML very well. You shouldn’t have any problems importing XML.

      Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

*