Understanding Outbound Web Services

Epicor CPQ (as web service requestor) can send outbound requests for data to an external system, if that system provides a REST API. Some example use cases:

• Your configurator options must change depending on just-in-time inventory information from your ERP.
• Your configurator uses a commodity whose value changes often, like gold or platinum, and you want to ensure your prices are accurate at the moment.
• You want to look up the shipping cost for a quote from your third-party shipping provider.
• Your company already maintains a pricing service internally, and you want to re-use that business logic in your configurator, rather than re-building it.

The rest service block is contained inside the "web" toolbox.

There are two blocks connected to each other in the toolbox.

1. The first block instantiates a RestClient instance.
   By default, you can provide a BaseURL (which must include http:// or https:// ). By clicking on the + mutation button in the Snap block, you can also provide a default port number which will be passed into each request made via this RestClient instance.
2. The second block uses that RestClient instance to generate a RestResponse.
   You can select an HTTP method such as GET or SET, the content type, and the relative path to be added to the end of the BaseURL. To authenticate with the web service, this client supports basic, OAuth 1.0, and session-based authentication, as well as the ability to specify a port number and headers.  See the "technical notes" section below for more details.

The data you want from the other web server is found within the RestResponse.

After declaring the RestClient, you can use it many times with multiple HTTP Call blocks.

Example using Basic Auth

In the above example, a new RestClient instance is created. Then a call to https://example.com/api/items is madewith the two basic authentication parameters set. The call comes back as a RestResponse object, named "exampleItemsResponse" in this example. The response body is then deserialized into a map for use.

Further HTTP Calls can be made over this same connection without having to state the basic authentication parameters again:

Example using Session Auth

Assuming the rest service has an endpoint called /login which takes a username and password in JSON format, the first block will make the authentication handshake, which upon success, will reply with a cookie. This cookie is handled internally by the RestClient Snap block, and will be passed back in the next HTTP call (and any subsequent calls made via that same RestClient instance).

Example using OAuth 1.0

The parameters for the OAuth authentication follow the standards defined for OAuth.

Example using API Tokens

Some REST services require API keys or tokens for use, which are sometimes passed via a header.

Other services require a key, but allow you to pass that key directly in the get parameters.

Using a REST service as a Safe Function

For security purposes, and to prevent issues revolving around CORS, REST service blocks can only be called from a Epicor CPQ server, not from a user's computer or mobile device.  Therefore, to send an outbound web service request from an on-screen configurator, quote, or scene, simply create a safe function to wrap your rest service callout, and then refer to that safe function in your configurator, quote, or scene.

Here's the same REST call as above, only wrapped with a safe function.  This function takes the JSON from the web service and deserializes it into an array of "Movie" objects.

After your safe function is built, you can call it from a configurator or scene.  Here, for example, we use this "SearchMovie" safe function as the source for an option filter.

Technical Notes

The "HTTP Call" block gives a simple way to define your outbound connection, but offers more powerful options when you need it:

1. Only the most commonly used content-types are provided in the dropdown. If you need to use a different content-type, then blank the content-type field out and add a custom header by clicking the + button.
2. The URL is relative to the baseUrl provided by the RestClient instance.
3. The "Ensure success" checkbox determines how an error in the result should be handled. 
   1. Generally speaking, web services can fail for two types of reasons:
      • Connection errors.  The server connection could not be made at all.  For example, due to DNS or firewall issues, or the target server being down.
      • Error status codes. The server connection was made, but your callout resulted in a failure status code.  For example, you didn't provide the correct data (e.g., you sent a string instead of a number, or you sent an impossible date like 2023-12-32).
   2. If you check "Ensure success":
      When any connection error or error status code is encountered, your Snap code will abort and log an error.
   3. If it is left unchecked:
      Your Snap code will continue to run despite the error condition.  Handling this unusual situation is up to the code you write.  You should handle both types of error reasons:
      1. For connection errors, the result of the call may be a null.
      2. For error status codes, the result of the call will be a RestResponse instance, with that statusCode specified

Firewall Rules

In most cases, Epicor CPQ can reach out to another web service endpoint on the internet or within your company and successfully connect. It then authenticates (see the examples above) and exchanges information.

In some cases, however, that other web service endpoint may be protected by a firewall. If Epicor CPQ's hostname is not allowed by other system's firewall rules, then it will not successfully connect.

If you are using Epicor CPQ to connect to another web service, and receive no reply despite having the correct URL, first try to repeat the problem on your own workstation, using Postman or another web service tool. Then work with the IT organization supporting that endpoint to learn if a firewall could be an explanation for the problem. If so, they should add the hostname of yourEpicor CPQ dev, test, or production instance to their firewall rules. Your hostname is [subdomain]-dev.kbmax.com, [subdomain]-test.kbmax.com, or simply [subdomain].kbmax.com for production.

Why a hostname instead of an IP address?
Epicor CPQ is a cloud-based service based on Microsoft Azure. The IP addresses are dynamic, and subject to change without warning. While a ping from the command line shows the IP address at any one time, that IP address might change in the future. Only a hostname that resolves through DNS will always remain up-to-date. For more details, see Microsoft's instructions on accessing Azure resources by hostname and by "portal URL".