Epicor Functions: Hello World

I’ve been recommending Epicor Functions a lot so I wanted to demystify it a bit so people see the value. While you can call Epicor Functions from BPMs, etc. - I’m more interested in how you can define your own API into Epicor. At the core of functions is the Library and your functions live there. You can then call your functions from REST v2. Here’s a little Hello World example for functions.

First, you need to give yourself security to do functions. This is done through Groups and not the Options tab of User Account Maintenance. I’m not going to explain this here but this makes me a super-user for Functions.

Next, open up the Epicor Function app and create a library:

Next, add references to the Business Objects that you will use. Here I’m choosing Tip of the Day.

Authorize the Companies that can use the library:

Next create the name of your function:

Define your inbound and outbound parameters. To keep it simple, I’m just returning a tip as a string.

Design the function JUST LIKE A BPM! I’m calling the BO and assigning the TipText to my return variable.

OK, that’s it for the library. Now the REST part. One big difference is that security is better in REST V2 so you need to define an Application Key. Click New, fill out the Name, Description, and Expiration date.

When you save, it will generate a key for you. SAVE IT. This is the last time you will see it.

image

You can add Access Scope where you define what this application key has access to. This makes external REST calls FAR MORE secure than using REST v1. In this case, I don’t care and left it blank.

OK, now we’re ready to test our API. Get your API KEY. I’m going to use Insomnia but you can use Postman or Postwoman too. Here’s the URL format:

Note the “staging” in the URL. This means the library has not been released to production yet. We’re just testing now. Make sure you add the x-api-key to your header:

Execute the call with a POST:

Yay! All that’s left is to promote the library to production:

image

Now remove “staging” from the URL:

And execute it:

I hope that gets everyone thinking about what you can now do with Epicor Functions. Remember, you need to be on 10.2.500+.

11 Likes

@Mark_Wonsil - Fantastic tutorial! Thanks.

What happens after the expire date? Is there any point to having a shorter or longer expire date? And then tracking it so you know to extend it periodically?

I have not tested the expiry functionality but I would assume it would stop working. Note, this is not security by obscurity since you have to authenticate first. Since REST is ALWAYS encrypted, the API-KEY should not be visible over the wire but like any “secret”, it may get out. If that happens, then you can regenerate the key as well. This if very similar to Azure Application IDs, which I believe have a limit of three years.

As for managing the key for your client apps, that’s a different conversation. There’s a whole ecosystem around secrets management: GitHub, Azure Key Vault, Hashi Corp’s Vault, …

3 Likes