SolidWorks Events and Functions

A list of functions and events available when building a CAD Extension for SolidWorks PDM Professional.

Before you begin

SolidWorks Extension events and functions

• When you create a CAD extension, the items below are available only if the extension for SolidWorks PDM Professional is installed and that class is included: see how to set up your CAD Extension project to include these functions. 
• Usually, you would follow an event-driven design architecture to call some of the functions in the list below from one of the output builder events.  For example, the output builder event OnAfterBuild is an ideal event whose occurrence would cause the SolidWorks PDM Professional function  CheckInFile below, so you can check the freshly-built file into your vault.  See the detailed examples in the various functions below.  
• The list below is not an exhaustive list of all PDM functions.  For that information, consult the PDM vendor's web site, such as this link.

Testing your SolidWorks PDM Professional Extension

Examples

Event	Function	Description	Notes
	GetSettings	Gathers any builder-specific settings from a configuration file on that builder machine.	If the local settings file EntPdmExtSettings.xml exists on the output builder, those settings are copied into the Settings variable. If this local settings file is missing, it is created with empty settings and an error is returned. Example: EntPdmExtSettings.xml is a fine place to store the username/password your builder would use to log in to the SolidWorks PDM vault.  In this way you don't have to store that information in Epicor CPQ and can maintain good separation of systems for security purposes.
OnLogin	Login	Connects to the vault.
	ResolvePathToResults getVaultRootPath	Returns the vault's root path
OnGetLatest	GetLatest	Returns the latest version of the component from the vault	Usually this is the best way to retrieve a component, assembly, or other item from the vault.  You honor the vault's version control.
OnGetExistingFilePath	GetExistingFilePath	Returns existing filepath if the item is in the vault or returns an empty string if it doesn’t exist.	Use this function to check if an item already exists in the vault.  Perhaps you don't even need to build it.
OnAddFileToVault	AddFileToVault	Not suggested for use	You should not have to call this in your code: use CheckInFile instead.  After the file is checked in, if the filetype is defined in a vault workflow, then your file will be added to the vault automatically.  If the filetype is not part of a workflow in your vault, then the file will not be added to the vault. This function is only valuable as a possible workaround to a failed checkin process. As a workaround, it could check to see if output is a certain file type then checks it into the vault.
OnCheckInFile	CheckInFile	Given a file, checks the file into the vault.  The file should be added to the vault automatically.	If your file check-in failed, try performing that same check-in using the same user credentials, but manually through the vault's user interface.  If that also fails, then you know the problem is with a vault setting, such as a missing workflow.
OnEnd	End	Cleans up driver events
OnChangeDrwTemplateFileName	ChangeDrwTemplateFileName
	RunTemplate	Given a template (a folder structure, usually), clone that structure into a certain location in the vault.	A useful technique when the check-in process is not a simple file, but rather a sub-hierarchy of files and folders.  Create the folder hierarchy as a template, then simply run the template to create that sub-hierarchy in your vault as often as needed.
	RenameFolder	Renames a specified folder to a new folder name.	After RunTemplate has created a sub-hieararchy, you can rename the root of that folder to be the item number, for example.
	FindFile	Searches the vault for a file name, it returns True if file is found and False if it has not been found. Optionally, it can also return the path to the file.
	SetFolderVariableValue	Set metadata on a folder	Maintain your datacards

The VB.NET Project will compile to a .dll file which will appear in the 'C:\KBMax CPQ\Extensions\PDMs' folder on the computer running Visual Studio. You need to upload this .dll to Epicor CPQ into the Resources > templates > extensions > pdms 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.

OnBeforeBuild

This event occurs just before the entire build is about to start.  A great place to set up connections and basic preparations.

				Private Sub IExtension_OnBeforeBuild(config As Configurator, quoteProduct As QuoteProduct, build As Build) Implements IExtension.OnBeforeBuild
				Dim user As String
				Dim pwd As String

				'If we have connection information from the local settings file, use it.
				If Not String.IsNullOrWhiteSpace(m_settings.User) AndAlso Not String.IsNullOrWhiteSpace(m_settings.VaultName) Then
				user = m_settings.User
				pwd = m_settings.Pwd

				'Logs into vault, returns true if user logs in or is already logged in
				If Not (EPDMHelper.Login(user, pwd, m_settings.VaultName)) Then
				Me.m_settings = Nothing
				End If
				End If
				End Sub
			

OnBeforeBuildOutput

Now that the overall build has started, one or more output documents can be part of that build.  This event occurs just before each of those output documents are generated: t he CAD driver is not initialized.  In the code below, note how all fields from the configurator can be read, such as a field called "ConfigurationCode".  In this example, we tell the SolidWorks PDM to run a template (which can duplicate a pre-built folder subhiearchy in the vault to store our upcoming documents), then we rename the folder our template just created with the configuration code, and we add that code and other metadata to the folder in the vault so it's easy to find.  

				Private Sub IExtension_OnBeforeBuildOutput(config As Configurator, output As Output, pathToResults As String, isRoot As Boolean, configCode As String) Implements IExtension.OnBeforeBuildOutput
				Dim configurationCode = config.GetAllFields.Find(Function(c) c.Name = "ConfigurationCode").Value
				Dim pathToTempFolder As String = EPDMHelper.GetVaultRootPath(m_settings.VaultName) + "\Projects\x"    Dim pathToProjectFolder As String = pathToTempFolder.Replace("x", configurationCode)

				Try
				EPDMHelper.RunTemplate(EPDMHelper.GetVaultRootPath(m_settings.VaultName), "Foo Company\Bar Project")
				EPDMHelper.RenameFolder(pathToTempFolder, configurationCode)
				Catch X As Exception
				Throw New Exception(System.Environment.NewLine + "Actual Error Message: " + System.Environment.NewLine + X.Message)
				End Try

				EPDMHelper.SetFolderVariableValue(pathToProjectFolder, "project number", configurationCode)
				EPDMHelper.SetFolderVariableValue(pathToProjectFolder, "drawnby", "Epicor CPQ")
				EPDMHelper.SetFolderVariableValue(pathToProjectFolder, "ExternalID", config.id)

				End Sub

			

OnBuildOutput

Just as a specific output file is about to be built, the CAD driver is initialized (the CAD system has started).  Now you can add CAD driver events if they are required. In this example, we first confirm if the output file is set as "enabled" in Epicor CPQ (this flag may be set true or false in the configurator's output rules).  Only if it's enabled do we associate the functions we write, like m_driverEvents_OnCheckInFile, as handlers to events.

A function handling a driver event. 
Logging errors and informative messages.

				Private Sub IExtension_OnBuildOutput(output As Output, driver As Driver, pathToResults As String) Implements IExtension.OnBuildOutput
				If m_settings Is Nothing AndAlso Not EPDMHelper.IsInit AndAlso Not Me.Enabled Then ' Checks to see if settings have been correctly loaded
				m_driverEvents = Nothing
				Return
				End If
				If TypeOf driver.Events Is CadDriverEvents Then ' Checks to see if assigning cad driver events only to the output that creates CAD
				m_driver = driver
				End If
				m_pathToResult = pathToResults
				If driver IsNot Nothing AndAlso driver.Events IsNot Nothing Then ' If build type is false it skips adding driver events
				m_driverEvents = driver.Events
				'the M_* functions added as handlers here are functions you write to satisfy your custom needs.  Create only what you need.
				AddHandler m_driverEvents.OnChangeDrwTemplateFileName, AddressOf M_driverEvents_OnChangeDrwTemplateFileName
				AddHandler m_driverEvents.OnAddFileToVault, AddressOf M_driverEvents_OnAddFileToVault
				AddHandler m_driverEvents.OnCodifyNewFilePath, AddressOf M_driverEvents_OnCodifyNewFilePath
				AddHandler m_driverEvents.OnGetExistingFilePath, AddressOf M_driverEvents_OnGetExistingFilePath
				AddHandler m_driverEvents.OnGetLatest, AddressOf M_driverEvents_OnGetLatest
				AddHandler m_driverEvents.OnCheckInFile, AddressOf M_driverEvents_OnCheckInFile
				AddHandler m_driverEvents.OnEnd, AddressOf M_driverEvents_OnEnd
				Me.Results = driver.Result
				Else
				m_driverEvents = Nothing
				End If
				End Sub
			

Here's an example of a private function designed to handle an event.  In the previous example, we saw how private functions like this one were added as handlers for specific driver events.  Note how we use Log and LogError to pass any messages from the SolidWorks PDM along so they can be seen.

				Private Function M_driverEvents_OnCheckInFile(filePath As String) As Boolean
				    If m_settings IsNot Nothing AndAlso EPDMHelper.IsInit AndAlso Me.Enabled Then        ' the extension is enabled so we try to check in the file
				        Dim errMsg As String = ""        If EPDMHelper.CheckInFile(m_settings.VaultName, filePath, m_settings.WaitForCheckIn, errMsg) Then
				            Me.Results.Log(String.Format("PDM Enterprise: Successfully checked in thefile:'{0}'.", filePath, errMsg), eLogId.EPDM_Extension_Message)
				            Return True
				        Else
				            Me.Results.LogError(String.Format("PDM Enterprise: failed to check in the file:'{0}', with the error:'{1}'.", filePath, errMsg), eLogId.EPDM_Extension_Message)
				            Return False
				        End If
				    Else        ' the extension is not enabled so we return true because nothing happened here
				        Return True 
				    End If
				End Function