The CAD Extension allows any Epicor CPQ Output Builder to interact not just with the CAD software, but also with the operating system. Perform automated tasks beyond the standard Output Builder functionality by building a CAD extension.
Specifically, the CAD extension is a block of code you write, based on libraries from Epicor CPQ and other vendors, to perform just about anything you would do manually as a CAD designer. The extension you write has...
- access to the most common Epicor CPQ objects needed to drive your CAD outputs (the custom product, the quote, etc.).
- a debug environment, where your error messages are sent to the Epicor CPQ server log for easy access.
- access to all the API functionality offered by the CAD software.
- if necessary, access to SolidWorks PDM Professional vaults.
- if necessary, access to the full Epicor CPQ API through the .Net library
-
if necessary, the ability to import many other .NET libraries, so you can perform other functions found in those libraries.
However, in exchange for this flexibility, the CAD Extension also requires some work on your part:
- You should be familiar with the Vb.NET language.
- If using SolidWorks PDM Professional, you should know the manual steps which you plan on automating.
- You should know how to use the Visual Studio IDE, where .NET code is written.
- You need to write your own extension code in .NET, by combining the appropriate libraries above with custom logic you write yourself. Fortunately, we provide a Visual Studio template that handles most of the work for you, and we have step-by-step instructions for setting up a CAD Extension project to guide you.
- You will compile your extension project into a .dll file. Usually there is a .dll for each output that needs to be created. Therefore, there may be several .dll files you must create and manage.
- You must ensure your extension .dll files are stored in Epicor CPQ as described below. By doing so you can test and deploy them, and Epicor CPQ can automatically distribute them to all of your output builders.
Theory
The CAD Extension you write is based on an event-driven architecture. Epicor CPQ follows a series of events as it creates your output file: of most interest are Output Builder Events, and CAD Events. These events happen predictably during the build process, and each event is a "hook" for you to add your own customization as the build progresses. The Output Builder events are always run and are usually used to set up and run the CAD events, which by default are not automatically run. These events are defined in the RuleExtension.vb class.
The RuleExtension.vb Class
The RuleExtension class defines the basic functionality of the CAD extension. It instantiates the IRulesExtension class from KBMax.Extensions.dll.
The class has several variables defined that give access to the different objects in Epicor CPQ
- m_build: the build object
- m_conf: the configurator object of the current build
- m_quote: the quote object of the current build
- m_utilities: simplifies access to configurator fields and their values
The class subroutines and functions are defined in two regions as shown in the image below. The Output Builder and CAD Events regions.
By default, Output Builder Events are always executed and CAD Events are not. The CAD Events are usually subscribed in the ‘OnBuildOutput’ subroutine. It is recommended that the configurator Id be used in your logic to determine whether to add the events or not.
Accessing Configurator Field Values
Using configurator field values in the logic of customizing outputs is a common occurrence. To that end, as part of the template, the 'ExtensionUtilities' class is instantiated as 'm_utilities' in the RuleExtension.vb class. 'ExtensionUtilities' provides methods to access field objects in general, and their values specifically. For accessing complex types such as user-defined classes and arrays in the configurator, using JSON is recommended.
Commonly used methods of 'ExtensionUtilities'
| Method | Argument(s) | Returns |
|---|---|---|
| GetConfiguratorByName | Name of configurator (string) | Configurator (Object) |
| GetInputFieldByName | Name of field (string) | Field (Object) |
| GetInputFieldValueByName | Name of field (string) | Value of the input field (Object) |
| GetOutputFieldByName | Name of field (string) | Field (Object) |
| GetOutputFieldValueByName | Name of field (string) | Value of the output field (Object) |
Testing your CAD Extension
The VB.NET Project will compile to a .dll file which will appear in the 'C:\KBMax CPQ\Extensions\Rules' folder on the computer running Visual Studio. You need to upload this .dll to Epicor CPQ into the Resources > templates > extensions > rules folder in the Epicor CPQ admin tool. If you do not have these subfolders in your resources directory, simply create them. Once there, the .dll will be automatically distributed to all Output Builders that process builds. Anytime the project is changed and a new .dll compiled, it needs to be updated into this same folder in the admin tool. There may be several dlls, one each for multiple projects, in this folder. During runtime, they are all automatically evaluated to see if they apply to the current build.
Debugging
Runtime debugging of the extension can be accomplished as follows:
- Kill the Output Builder if it is running.
- Open the extension project in Visual Studio. Insert debugging breakpoints as required. Make sure the 'Debug' properties of the project are set as outlined in step 8 of the project setup example.
- Run the project. This will compile the project and launch a new instance of the Output Builder.
- Run the configurator and submit a configuration for build. The Output Builder will execute the build and halt execution when the breakpoints are reached. You can then step through the code line by line in Visual Studio.
Deployment
After being initially tested in your -dev environment, the extension dll file is deployed into -test and -prod environments just like any other resource in the templates directory: through the standard deployment process. After deployment, Epicor CPQ automatically distributes the .dll from the Templates > Extension folder to all output builders, and ensures these local copies are always up-to-date.
See Also
Installing and Setting Up a CAD Extension Project
How to set up a CAD Extension project using Visual Studio Community 2022.
Output Builder Events
List of Builder Events and when they are executed.
CAD Events
List of CAD Events, when they are executed, and the CAD API Objects available to them.
AutoCAD Events & Functions
AutoCAD, like other CAD systems, can also be automated through an Epicor CPQ CAD Extension.
SolidWorks PDM Professional Events & Functions
A list of functions and events available when building a CAD Extension for SolidWorks PDM Professional.
Using JSON Serializer/Deserializer to pass data to CAD Extension
You can pass complex data – beyond simple text and numbers -- to the CAD Extension through a technique called serialization.