JobEntrySvc For REST needs documentation

We are moving to a rest API interface for creating of JobEntries. It appears that this is all localized to
the Erp.BO.JobEntrySvc REST entry. Using the fat (.net client) and tracing we have gotten traces
for:

  1. New Job and Save (basically creating the job header)
  2. Create Demand Link (make to stock)
  3. Add and delete operations for the job

Bart Ellia told us at EIC that was all we needed. Well, I beg to differ.

When one looks at the trace for the New Job, getNextJobNumber and then Save. One finds a trace with 118 BO method calls. Even when one filters down to just the JobEntrySvc Calls, it is 39 steps.
I then filter to remove duplicates and I get these 11 steps:

|Erp.Proxy.BO.JobEntryImpl|GetNextJobNum|
|Erp.Proxy.BO.JobEntryImpl|GetList|
|Erp.Proxy.BO.JobEntryImpl|ValidateJobNum|
|Erp.Proxy.BO.JobEntryImpl|GetNewJobHead|
|Erp.Proxy.BO.JobEntryImpl|CheckPrePartInfo|
|Erp.Proxy.BO.JobEntryImpl|ChangeJobHeadPartNum|
|Erp.Proxy.BO.JobEntryImpl|ChangeJobHeadRevisionNum|
|Erp.Proxy.BO.JobEntryImpl|CheckForChanges|
|Erp.Proxy.BO.JobEntryImpl|Update|
|Erp.Proxy.BO.JobEntryImpl|GetDatasetForTree|

I suspect all we really need is three

  1. GetNextJobNum
  2. GetNewJobHead
  3. Update (or UpdateEx, not sure)

But even then the actual call for Update takes a POST body packet of size 1448 rows. Most are not needed but which ones are needed? What are the minimal set needed, to make the most basic job entry?

In addition, I suspect that instead of doing this purely with custom methods, there are ODATA methods (that call UpdateEx in the background) that make our job simpler. But what is the sequence of methods to call, and which ODATA calls do we use to create a job? Swagger is very silent on that subject.

the same question needs to be asked for the other two operations:

Adding a Make to Stock, calls the following:

  • PreCheckNewJobProd
  • GetNewJobProd
  • CheckJobProdMakeToType
  • ChangeJobProdMakeToType
  • ChangeJobProdMakeToStockQty

What are the ODATA equivalents, if any, and what should one provide as the arguments?

And finally, adding a Operation to a jobEntry will do the following:

  1. call Erp.Proxy.BO.JobEntryImpl.InsertOperationOP()
    which returns a Erp.Tablesets.JobEntryTableset

Well, what ODATA calls does one do to mimic this?

Bart might be right that Trace is your friend. But it is clear Epicor REST developers are going to need more friends than just trace to do such tasks.

Why are you recreating something that works fine in E-10? What’s your end goal? (other than just trying to piss off someone who spends a lot time helping people)

And yes, I will agree that REST is a bit over hyped right now, It’s handy, but isn’t a magic wand that just works. There’s a lot of work that has to be done to use it.

3 Likes

Swagger is an automatically generated help file. To expect it to explain everything to you isn’t realistic.

3 Likes

When you Trace, you have to determine what you want to call and not – You dont always have to call everything if you are confident you dont need everything, and in some cases people use UpdateExt.

If you go to the Custom Objects Link in Swagger it will show you all the Methods and even if it doesnt you can still call all the BO Methods (they are there).

You can get the BO .chm from EpicWeb which documents the Signature of the Methods and shows what needs to be passed in.

If you want the Implementation Details you must purchase the SDK or use .NET Reflector to study the .dlls.

1 Like

If your looking for more training Epicor Education does have a REST v1 Basics and REST v1 Advanced Course.

1 Like

UpdateExt stands for Update External and is a good choice for this type of interaction because it will make other intermediate calls so you don’t have to. The actual logic it performs is internal to the service, so you’re likely not going to get more info on that without testing. Because the dataset metadata is more accessible in the ICE BLTester, I’d recommend trying to perform GetNextJobNum then UpdateExt using the ICE BLTester until you get exactly what you want in the dataset, then construct your REST json to pass the exact fields you entered in the BLTester. Then, if you want to reduce transfer datasize, start paring away things that look unnecessary until you hit an error.

Bart et al.'s work on REST is to extend the accessibility of the contract logic to an API. So, requirements such as expanded datasets are a result of the requirements of the service rather than the opened interface. Again, there may be more details in trying to use the contract first through the BLTester.

Also, have you tried QuickJobEntry? The purpose of this service is to automatically perform a lot of these steps if you have already have a configured BOM.

2 Likes

High five buddy!

4 Likes

You will always need to filter out noise from the trace when you are automated coding something. A vast majority of the BO calls in the smart client are for UI updates, filling drop downs, filling description fields etc. REST is just an interface to call the BOs like anything else (C#, WPF, BLTester, etc) no special sauce there. What you are describing right now is a deficiency in understanding that particular BO nothing to do with documentation of REST. So yes trace is your friend, but you still have to make the call on what you want to do with the information presented nothing else is going to tell you that.

3 Likes

I wish it was as good as Update… :slight_smile: UpdateExt can also be the Devil and cause RowMod Issues, _UD Columns not to populate among other things… We had so much issues with Service Connect, switched to .Update – never had a single XML Crash. =)

3 Likes

Yeah it’s a hunt an peck in Epicor what works and doesn’t work for a particular use case sometimes. There are about 1MM ways to skin the Epicor cat.

I understand fully about the REST interface being a work in progress, and also agree with the approach exposing the full BO API and then going back and helping developers with the documentation, etc.

I also am quite aware of the distinction between custom methods and ODATA methods, and how to switch in the swagger interface between them (and how long it takes to render the custom methods in swagger).

Thanks for the tip about the CHM file, that will be very useful, and the ICE BLTester , which I am unaware of, (and don’t know where to find or operate).

BTW, I think someone is mis-reading how we view the help from Bart. We really appreciate it. And he is also fully on-board about us simplifying JobEntry (the current interface is good for geeks who think in terms of tree hierarchies of menus and forms, and we have huge training and quality issues, since manufacturing folks are not CS Ph.d. (like myself)).

The issue still remains whether one uses BLTester, QuickJobEntry or others. there is no clear mapping to the ODATA versions of the methods, which seem much cleaner for assembling the parts, material, and other elements of a job.

It looks like this is possible, but how does one tackle figuring out what methods to call and in what order?

I think your PhD may have something to do with the questions and problems you are having. No offense, I am sure you are a very smart man. But you have to stop with Theory and Assumptions, as a matter of fact, you should not be writing Production intended REST Code with guesstimates, its like playing with fire.

I dont know you, you dont know me. But I would suggest you go an tinker for a week, break stuff, play around with BL Tester, play around with Epicor. All hands-on deck. Decompile, Debug, Read the Docs, all those answers are there. As a matter of fact, do so much testing that the server catches on fire :slight_smile:

You struggled for a week if not more with CORS, yet all the answers we gave you came from helpfiles and google. We don’t know all the answers, but what we do know is where to look to find the answers.

BL Tester you will find under the Utilities folder where your Epicor has been installed on the Server (where the Deployment Packages are). BL Tester will only test 1 Method you specify, it wont give you the full trace.

To answer the question how does one know which methods to call? Easy, Experience. Spend time in Epicor understanding the Process/Workflow of Creating a Job, Scheduling a Job. Adding BPMs etc…

The Trace will Trace everything, but do you need GetDataSetForTree, GetList? No. Do you need * CheckJobProdMakeToType? Probably not. The one thing they teach in Systems Analysis is “It Depends”… Do you need it? It Depends, you can make a Job without any of those, but if you want more assurance and quality data you might want to add a few more.

Learn how to navigate via .NET Reflector, dotPeek, dnSpy. There is no easy way, just experience and long hours. I’ve spent my first 3yrs of Epicor 80hrs a week tinkering and I still know very little.

6 Likes

what the heck @hasokeric? you couldn’t commit several million lines of code to memory in three years?

4 Likes

But only 1 that works properly in all cases (including the ones you’ve not dreamt up yet)

The trick is finding it without testing every option first, I’m still working on this part and I suspect most others here are too :wink:

1 Like

It can definitely be a frustrating experience for sure. I just try to remember to be grateful that I have the ability to customize and interact with Epicor at this level at all.

If you come at it with more of a mindset that you are hacking someone else’s product to do what you want (like modding a video game) and not like a professional well documented API (such as the .NET Framework) it can help set your expectations of what the experience will be like.

3 Likes

@hasokeric I am certainly not going to get into any personal barb trading. I can’t see why you are taking this so personally.

What we are looking for (and have contract $$ to pay for) is authoritative information about what JobEntry does. That is, someone who is actually knows what the BO does and what the equivalent ODATA or if not there, custom methods to:

  1. Create basic job header
  2. Add Make to stock (demand link)
  3. Add Operations

As for why REST?

  • Well you have Microsoft walking away from WCF
  • You have EPICOR doing all their new front end (Kinect) with REST
  • You have the Bart (Software architect at Epicor) tell us REST is a better choice

And if you have 40+ years of experience all over the software industry, then you know when it is time to stop wishing for return to the past:

  • CORBA ORB (gee seemed like a great idea at the time)
  • SOAP WSDL
  • or WCF (which if you read the writing on the wall is headed the same way).
  • and our customers (us government) loves ODATA (look at odata.gov)

Maybe the future is GraphQL (would like to know what Epicor thinks).

But really, in this case, some folks business needs allow them to work with REST, GraphQL and that is great, and others will be using WPF and WCF and thick clients. As one pundit here said there are lots of ways to do this.

But what is not desired is someone who wants to spend hundreds of hours of precious consult $$ to explore and experiment to read the entrails of EPICOR traces. For a person who knows how JobEntry works, this is a 10 minute question. That is what is needed.

So maybe I can provide a little clarity on what we intended to solve with REST from the tools development perspective. When we built out REST v1 the mission was to make our existing APIs easier to get at using a REST interface, but not to try and solve the much larger surface of - how do we make super easy APIs for each business object.

So what REST is for us is a RESTful-ish veneer over the existing APIs which makes it significantly faster to get started with integrations, makes simple things like querying out BO data simpler to get at, and in a limited way makes API integrations against the OData a bit more resilient to underlying ERP changes since you can send and pull partial data you need. But it’s not all candy and roses - from a tooling perspective we can’t automatically solve making complex APIs which we have thousands of into simple to use APIs. To do that someone has to carefully redesign each one. So under the rest veneer all of the same data validation, sequencing, etc that’s baked into that very large set of services is still in play in the same way and we intentionally provided the direct mapping POST methods. So we provide generated swagger & odata $metadata that describes the services, but generally speaking our complex business object services have logic too complex to express in that fashion. Fields aren’t just required they’re required when x, but not y. Records can be saved only after certain other actions have taken place so there’s multi-api-call-sequencing that matters. That’s what ui trace is good for - understanding the sequence & details in which the ERP Client uses the existing BO services.

So all that said you should use rest for the reasons you enumerate - it’s the same api you’re hitting when in WCF there so that’s not really any easier you have to figure out the same complex sequence of events for the same complex business objects in the same way. WRT mapping to OData it is not always 100% possible to do so and sometimes you will need to use the custom methods (aka the direct business object api). Update in odata in particular as everyone has noted maps to UpdateExt. These are generated methods that attempt to simplify updates to a BO and sequence events - how well these services encompass the full scope of behaviors in the direct API varies and may not always be appropriate so sometimes you do need to call one of the custom methods.

Here’s my 2c on GraphQL - We think the GraphQL is niceand it’s built with a lot of the same problems as OData in mind namely that it helps build a lighter payload, be more resilient to underlying changes in the API, and has good query semantics. We might add it eventually as an option, but for the moment we think OData is solving the same set of problems for us and we have more important harder things to solve in the API that would get you all more value such as api keys with imbued security (maybe), standard oauth2, improved metadata and swagger, better help, import/export services for bulk operations, custom facade services to let you craft your own updateExt type of simple services atop the complex apis, etc.

11 Likes

For what my opinion is worth… i doubt much - As noted, REST has provided a much quicker and painless way to interface the system. Since it’s introduction in 10.1.500, I’ve seen nothing but positive strides in it’s overall usefulness in the system. I take solace in knowing that it (as is much of E10) is a growing beast that is sure to get better with time and input from users such as ourselves. Just the fact that the @Bart_Elia, @bconner, @Olga. @Rich (and the several many other official experts) are gracing our community is proof of Epicor’s commitment to getting our real world experiences and turning them into better vNexts.

After all my fawning over REST, it’s all too true what @bconner says. The REST exposes the BL but there is inherent complexity in that logic. It’s a tall hurdle most of us here have had to jump (and trip over as @hasokeric notes). That’s why our community here is so epic - you have people who have had the same hard knocks, willing to share experiences and give advice. Outside of the free advice that you can get from the forums, there are also two other more direct approaches - 1) I think Epicor offers an SDK course that might give a much deeper dive into the architecture and best practices of the system ( I could stand to learn those myself) 2) Hire a development consultant to not just do the work, but to teach you how to do it. (Shameless plug)

3 Likes

Dr. Just to clear the air, you are more than welcome here. In other words what I meant to say was slow down a bit, revisit the fundamentals of Epicor Under The Hood and you will struggle less. You are rebuilding Job Entry to make it easier for your users, but it will be a long road unless you give yourself 14-60 days to get the fundamentals down. As soon as you asked about GetList, GetDataSetForTree and Tracing 101, it was clear that you needed to slow down a bit. Confidence can be a double edge sword.

You do realize every upgrade you will have to do rigorous testing, Job Entry isn’t ABC Code Entry. 1 Mistake and MRP Crashes, 1 Mistake and Scheduling Fails, 1 Mistake and everyone in the company will come to you and say “Yechezkal! YOUR SYSTEM DOES NOT WORK!” As if you wrote the whole ERP Application, suddently Epicor becomes “Your System”.

We try not to spoon-feed as a community, often times we do - but we’d rather guide towards the answers and teach someone to fish. Sometimes those answers may sound like a “fu” to a person, but the intend always is, you will thank me later. Just ask @Hari_Dutt who just wants a simple BPM :slight_smile: since February.

We want you to keep posting, but give yourself some time to read the Architecture Guide, ICE Tools Guide and understand Epicors N-Tier Application Setup, how it utilizes Entity Framework and how it has “Entity Framework Triggers” (not db triggers). BELIEVE Me you will stumble upon a simple method that will keep you there stuck for a month all because there is internal Trigger Code overwriting you. You will start dreaming about a villain called “Row has been modified by another user” chasing you and trying to eat you.

I understood your intent as you want to learn the Framework and Epicor, and become the best one can be, so I guided you towards that – slow down, hit the books and practice, practice, practice.

We also try to guide folks towards the right solution, for example you want to make the Job Entry easier because your Mfg Folks struggle with it? To me that is not a reason you should customize, it just means a failed Training Program. We have a VERY Complicate Job Entry - a single Job can have 1000 operations and 50,000 materials, 80 Sub-Assemblies, 100 Child Jobs, building Vehicles 1 mistake and guess what happens? RECALL, Government Fines, Millions of Dollars Lost and as a Publicly Traded Company we are under Investigation and our Stock Drops. But somehow our English and Non-English speaking Computer illeterate people navigate it just fine. Perhaps Re-Train and hire someone who specializes in Training who speaks to the people, who can mix emotions with logic and resonate. Plus Job Entry should always be accessed by Engineers and Subject Matter Experts and if they are struggling, do you have the right people for the role?

I Customized the Packout HandHeld Screen for 3 months, a tiny little itsy screen spitting out labels, how hard can it be? Every upgrade I find myself debugging as Epicor adds more PCID stuff to it, breaking my stuff. I remember @Chris_Conn staying awake for days to Freight and Unfreight a Shipment, how hard can it be – we got the trace… :slight_smile: I guess its much harder in practice. @josecgomez was struggling with Updating a Job due to an Epicor Bug he had to use UpdateExt, everything seemed simple, this was after he already had reached his 6+yrs of Epicor Under The Hood Experience.

Try understanding Epicors “Phantom, Non-Stock, Purchased, Manufactured, View As Assembly, Pull As Assembly” flags, simple checkboxes that make or break your mfg process. Before we even began to Customize that portion, we ran 60 tests to understand the cause and effect. Not a single Epicor Guide or Epicor Specialist could help us, it was hands-on and practice, practice, practice. I doubt even Epicor knows about it as much as we do now, definitely all the consultants we had were a joke and the only contribution they gave within a 8hr/2 day period was… “Did you know, if you right click the tree, you can resequence?”… “No Sh*t, where were you the other 7hrs to contribute something, while we pay for all your travel expenses” lol Paid 5K for a Resequence Tip.

Many other Screens are like Job Entry, are you going to rebuild them all? Perhaps your company has chosen the wrong ERP System to begin with, or its a proper staffing issue. We upgraded to Epicor from IBM AS/400 (Terminal) so you can imagine the challenges we faced going from DOS to UI… “why doesnt the enter key, tab anymore?” - “Because use the TAB Key to Tab”. Also IBM AS400 is FAST!!! I mean FAST!!! MRP Full Regen 45min… Epicor 8hrs.

We just upgraded from 10.1 to 10.2 and immediately a request came in to customize Logged Invoice Entry, because Epicor now makes you search Purchase Points and not just Suppliers… But on the UI You can Filter by Supplier, the team immediately said “WE NEED A QUICK SEARCH!!!” The response was “No you dont, you need to train them how to filter it, because you will see this exact same issue on 50 other screens, are we going to customize them all?”… Sometimes Better Training, Training and Re-Training is the solution. EKM (Epicor Knowledge Mentor) can assist with making EUPs and Videos.

You have ambition I give you that, but always ask yourself am I solving the cause or symptom. Example: With the CORS Issue you were happy to have resolved the symptom, but not addressing the cause of potentially corrupt Instance, before you know it - you will hot-patch 30 other things. Hope all works out! Good Luck and Welcome to the Forums.

1 Like

One thing to mention, we had a group that did poorly, they have been trained several times. Then a few weeks ago they were re-trained, they are doing a killer job now… Turns out the problem wasn’t the people, it was the Trainer who spoke in a monotone voice and did not resonate, who knew the logic VERY WELL, when you speak in logic and process terms hes the master, guy memorized the whole Epicor Book. He can tell you more about something than Epicor Guide can.

But we gave them another Trainer who knew less but they understood him clearly! They even gave testimonials after the training, how this time they understood it all because the trainer explained to them the “WHY” with proper real-life examples, turned it into a challenge, made it fun, handed out golden stars… He Sold them on the WHY and the HOW became easy. This Trainer worked 15yrs on the Shopfloor so he spoke their language and was humble. Every 1hr he gave the class a 5min smoking break, and they were like OMG This Guy is THE BEST! Small things Matter.

Cause: Trainer
Symptom: People are struggling understanding XYZ Process, They must be not getting it. We must hire new people, these ones suck…

The same Trainer can train them a 100x, they still won’t get it. The New Trainer 1 attempt and they are now SME’s training other users and funny thing is they are now Cheerleaders and Supporters of the ERP Implementation. Win! Some people learn visually, some hands-on, some like lectures, you have to mix it all up.

" I hear and I forget/I see and I remember/I do and I understand "

Now someone has to tell Bob Smith that he sucks at human interaction despite doing the ERP Implementation 8yrs. Not going to be me.

Sometimes its difficult to look in the mirror, but perhaps the problem is the ERP Team, Managers, Supervisors or even Executives not providing the proper tools and time and not the Users.

Sometimes it is the Users, do an Audit perhaps you will find a few users “bypassing” Epicor and handling stuff via Excel, at one of our sites we had a Visio Map in the Conference Room taped on the wall Labeled “How to Bypass Epicor”. Why? Because the Plant Manager was the Cause, causing Users to follow merely orders.

Cause: Plant Manager
Symptom: Users, Supervisors, Managers were bypassing Epicor and using Excel, we should fire them immediately, for not following their training and because they havent been doing it, they already forgot what they got trained on - might as well get freshly open-minded resources who will accept the change.

2 Likes