Sometimes you may want to launch your configurator with some fields filled in already, based on external data. For example, you may want to pass into the configurator information about where it is being launched from, or information that came from an earlier process. This can be useful if you want the configurator to be aware of the context from which it was called, or if you want to pass into the configurator data which can change the way it works. You can also pass in data that the configurator won't use, but will pass along to another downstream process.
Three techniques are available, depending on how you want to launch your configurator:
1. Passing parameters into your configurator from a form on the source web page
Usually, the configurator is launched through the Embed API on some other web page you maintain. You can bind the configurator to a form on this page, so any fields in that form are passed in to the configurator. This form can be hidden.
Consider this simple web page, which contains nothing but some standard Embed API code:
If you want to pass into your configurator one or more fields of data, simply create those fields in a hidden form on the page, and ensure that your configurator has fields with the same name. Then use the data-bind-to-form parameter to bind to that HTML form (here, by using the generic term "form", we bind to all HTML forms that may be on the page).
Our modified web page now reads:
Now, if the configurator launched from this page has a field with the matching name of "websource", it will be automatically populated with the text "DE". You can easily pass multiple fields of data into your configurator using this technique.
2. Passing Parameters into your Configurator directly, through the URL Parameters (Query String)
Sometimes you may not want to launch a configurator through the Embed API. For example, you may have a configurator that launches directly from a URL:
https://your-domain.kbmax.com/configurators/test/269
If you create a value rule to pull keys from the "parameters" map, and place that data into fields, for example...
Then you can use URL query string data in your configurator. Notice the updated URL:
https://your-domain.kbmax.com/configurators/test/269?param1=42¶m2=hello%20world
URL parameters are limited in length
You can place as many key/value pairs into the URL as you like... but there's no guarantee that they will all be processed. Web browsers truncate (chop the end from) the URL string of any resource they open. Usually, most web browsers accept a long URL (for example, in 2023, Chrome accepts over 200 characters). But each web browser is different. If you find that the data you're placing into the URL using this technique is making a very long URL string, then you may want to use a different technique which is not impacted by this web browser limit. See the information here on the setFields() call.
3. Passing Parameters into your Configurator directly, through HTML
You can accept an arbitrary number of unknown parameters embedded directly in the HTML of the viewer DIV by adding a "data-parameters" line to the DIV in the parent HTML. It must contain a valid JSON string of key:value pairs. Here's the same first code block, only with one new line added. That new line of code passes the same two parameters from the previous example:
4. Passing parameters into your configurator from a Salesforce.com integration
5. Checking your inbound parameters
If you are embedding Epicor CPQ into your salesforce instance, you can pass salesforce information into your configurator as it launches. For example, maybe your configurator has a "Installation Site Info" page, with fields like address, city, state, and postal code. If all this information has already been gathered in Salesforce, there's no need to ask for it again. Learn more about how you can pass info from salesforce into Epicor CPQ.
Regardless of how you passed parameters into your configurator, you may want to see that data for debugging purposes. The Get block includes a object of all parameters passed into the configurator when it launched. Here's a useful technique to see those parameters:
- In your configurator, create a hidden administrative page, if you don't have one already.
- Create a page called "P-Admin". Set the visibility of the page to false.
- Create a loaded rule that sets the visibility of that page to true if the current user is an administrator.
- Create an HTML element on that hidden admin page, with the name of "H-LaunchParams".
- Create a loaded rule that copies the get.Parameters into that HTML element as a JSON string, so they're easy to see.
Adding a line break after every comma in the JSON can make it more readable for humans.
Don't trust inbound data
These examples are very simple. For security purposes, you should treat the data entering your configurator through query strings as though a malicious person typed it in. Don't pass it directly to your business logic or use it in a query. Rather, sanitize it, have it drive a conditional statement, or otherwise insulate your configurator's fields from this external data. You have no guarantee that the parameter will be what you expect, or even will exist at all.
Consider the impact of changed data
If information is passed into your configurator using these techniques, be aware that this information can change over time. These changes can cause problems if you don't plan for them. You should consider the following issues that result from using query strings.
- After your configurator has launched for user A, the parameters user B would get a few seconds later could be different. How would that effect your configurator?
- If someone saves their configuration (based on these parameters) and returns to it tomorrow, they may not pass in the same parameters, or even pass in any at all. How should your configurator take that into account?
- Parameters are easy to see and edit as a user. What would happen to your configurator if a user edited the parameters and re-loaded? Or shared their parameters with another user?