Wednesday, July 2, 2008

Pro/WebLink: Tips On Getting Started

Pro/WebLink is one of the free PFC based API's available for automating Pro/Engineer. Although the documentation and marketing literature is focused on using Javascript with Pro/WebLink, VBScript can be used if that is more to your taste.

Developers interested in writing Pro/WebLink application have to overcome a number of hurdles. Most of these are related to the Internet Explorer and Mozilla security models, because Pro/WebLink applications typically must run within the context of the Pro/Engineer embedded web browser. This differs from the VB API (new with Wildfire 4.0), which runs outside of the Pro/Engineer process and has far fewer security issues to worry about.

While security is not the only problem facing Pro/WebLink developers, it is the most common problem in my experience. In this article I'll discuss the necessary steps in setting up your environment to run Pro/WebLink applications.

Pro/ENGINEER Configuration

Use of Pro/WebLink requires that the config.pro option WEB_ENABLE_JAVASCRIPT be set to ON (the default is OFF). In Windows, if this option is set to ON when Pro/ENGINEER is started, pfcscom.dll will be registered as a COM server. This contains all of the Pro/WebLink functionality.

Generally this works very well, but I have seen problems where the DLL doesn't get registered, or some other similar problem occurs preventing the Pro/WebLink application from functioning. The workaround is to run the application as an administrative user first, then the program works for everyone. Fortunately, I have only seen one user affected like this, otherwise the workaround would get really annoying.

None of that is relevant in Unix, as the required XPCOM technology is already present in the embedded Mozilla browser. However, I have seen rare instances where the Mozilla profile in the user's unix home directory has become corrupted. The resolution is to delete the profile. Pro/Engineer will recreate it upon startup.

HTML SCRIPT Tag

When setting up your Pro/WebLink programs, you are likely to include one or more files containing your Javascript code. A common one to use, although it is not absolutely necessary, is the PTC supplied pfcUtils.js file. If you are going to use such functions as pfcCreate() and pfcGetProESession(), you need to make sure you include pfcUtils.js correctly to avoid confusing errors, such as "Object Expected".

You also need to ensure that the SCRIPT tag entry in your HTML code correctly locates the pfcUtils.js file. For example, this entry will find the bom2excel.js file if it is placed in the same folder as the HTML file, and the pfcUtils.js file if it is in the parent folder:

<SCRIPT LANGUAGE="JavaScript" type=text/javascript src="../pfcUtils.js"></SCRIPT>
<SCRIPT LANGUAGE="JavaScript" type=text/javascript src="bom2excel.js"></SCRIPT>
 

Your web browser may not complain in an obvious way if it cannot find one of your Javascript programs, making the resulting errors hard to diagnose. If using a web server, make sure that the web server process has sufficient permissions to read the HTML and JS files, otherwise you'll wind up with the same problems, but it will that much harder to diagnose.

Web Browser Security Models

Overcoming the security requirements of Wildfire's various supported web browsers is often frustrating because the requirements are not inherently obvious and the documentation can be hard to find. With Wildfire 4.0, Mozilla is the supported browser on Unix platforms and Internet Explorer is the browser for Windows. Both have different mechanisms and rules concerning security.

Using digitally signed applications allow the developer to bypass some security roadblocks by requesting enhanced functionality based on the user's "trust" of the developer. Digital signatures are far beyond the scope of this article however.

Internet Explorer Security

Internet Explorer security is based on zones: Internet, Local intranet, Trusted sites, and Restricted sites. Each zone has it own security settings enabling or disabling certain functionalities. Using the "Custom Level" button, each option can be enabled or disabled selectively. If you change any of the security options, you may need to restart Pro/Engineer for the changes to take effect in the embedded web browser.
It is recommended that you do not reduce security for the Internet zone. It would be better to add the web site to the Trusted sites zone, then adjust the security for that zone.

Internet Explorer will decide to which zone your application applies depending on how you access it. If you access your program from a web server using a fully qualified domain name (i.e. www.yahoo.com) for a site that is not in your Trusted sites list, Internet Explorer will consider it part of the Internet zone. Using an internal web server (i.e. without top level domain: .com, .org, .co.uk, etc) or accessing the program from your hard drive or a network hard drive, will cause Internet Explorer to use the Local intranet zone. Not surprisingly, the Trusted sites zone will apply to a site that is in the Trusted sites list, even if it is an internal web server.

Pro/WebLink applications need a couple of settings defined for the zone that will be used by your application. Some of these may already be the default for you. As PTC recommends in the documentation, the option "Initialize and script ActiveX controls not marked safe for scripting" should be set to "Prompt". If you are interacting with Excel from Pro/WebLink, this option may need to be set to "Enable".


Ensure that the option "Active Scripting" is set to "Enable".

Mozilla Security

Mozilla has some good security functionality in which a script can request enhanced functionality allowing the user to accept or deny the request. That's why you see some UniversalXPConnect requests in Pro/WebLink examples. The code has to ask for enhanced privileges to connect to Pro/Engineer and do something useful.

When the Pro/WebLink application is served from a web server, the code and HTML must be digitally signed (together) for this request process to work. To make matters worse, a very unusual jar:http: URL must be used to interact with the resulting JAR file that contains the code and HTML.

A workaround is not to use a web server, but instead access the code and HTML from the file system using a file: type URL. For Pro/WebLink applications, the user is generally prompted only once for enhanced privileges, then is good to from then on.

Review

Keeping some of these issues in mind will help you get up and running with Pro/WebLink avoiding many of the pitfalls and frustrations.

  • Set WEB_ENABLE_JAVASCRIPT to ON in your config.pro file
  • Ensure that HTML and JS files are located correctly
  • Make sure that the web browser security requirements are satisfied