This help page covers the optional keywords SubmitForm and SubmitVariable. These keywords let you invisibly submit information from the Software Update Wizard on the user's client PC to your own web server, as if it had been submitted from a form on a web page.
You can use this feature in conjunction with a standard FormMail script (not supplied) to receive email updates whenever a user updates their software using the Software Update Wizard.
The information which can be transmitted in this way can be anything which fits into an http GET or POST request.
If you would like to pass custom information into the POST request (e.g. customer name, licence number etc.) you can get your application to create and write to registry keys on the user's computer. Within your Software Update Wizard script, you can create temporary variables that read the contents of these registry key values using the SubmitVariable keyword (see below). The Software Update Wizard can then transmit the values of the registry keys within the http: GET or POST request using a SubmitForm keyword line in a Software Update Wizard script.
Please note that the user of your software will be unaware that this information is being submitted and the process will be completely invisible to him or her. The Software Update Wizard is a software component for bona fide software developers to add value to their software and assist their users in keeping up to date with their software. PowerProgrammer asks that, in using the functionality provided with this keyword, you respect the privacy laws and morals of your country, and use this functionality strictly for the purpose it was intended - helping developers provide users with software updates at minimum cost and effort.
There are a number of FormMail scripts available, and you may find your ISP already offers one as part of your account. Alternatives are:
http://www.scriptarchive.com/formmail.html - Matt's Script Archive
http://nms-cgi.sourceforge.net/scripts.shtml - NMS Project FormMail
Although SubmitForm supports both GET and POST, our experience is that not all form mail scripts support the GET option. Check the script documentation to see if GET is supported, and note the syntax option for POST described below in this help topic.
This keyword lets the Software Update Wizard mimic an html form in submitting information from the client to your web server. It programmatically generates an http GET or POST statement and sends it to the target web server.
An example of this syntax is:
SubmitForm=<POST><DEBUG>http://www.myhost.co.uk/cgi-bin/mailform?Name=<USERNAME>&Computer=<COMPUTERNAME>&Message=The
update of Prophecy to V2.01 completed OK for this user<Referrer=http://www.myhost.co.uk/contact.html>
(Note: in the script file, all the text must be on a single line.)
The following table breaks the syntax in the example down into its component parts:
| Syntax | Explanation |
|---|---|
| SubmitForm= | The keyword. |
| <POST> | Optional keyword - if used the Software Update Wizard will submit the request as a POST request. If omitted it will submit the request as a GET. |
| <DEBUG> |
Optional keyword. If used and the script generates a web page in response
to the submission then the html of the page will be displayed in a message box by
the Software Update Wizard. This may be helpful in testing / debugging this option
as the returned page sometimes suggests reasons for why the email notification could
not be generated. If there is a problem with the SubmitForm keyword and no page is returned (e.g. the url does not exist, or the form mail object on the web server does not have the appropriate permissions to execute) then it is possible that no page will be returned or displayed with this option. An error will then be written to the WebUpdateSvc4.log file to indicate failure. Needless to say, you should ensure you do NOT use this option for released update scripts, but it may be helpful in debugging your script as you develop it. |
| http://www.myhost.co.uk/cgi-bin/mailform | The URL of the server script which is going to receive the GET / POST information. |
| ?Name=<USERNAME> | The first 'field' from the web page 'form' which will be submitted in the GET / POST statement. Note that "<USERNAME>" will be expanded at run time by the Software Update Wizard into the name of the logged on user. |
| &Computer=<COMPUTERNAME> | The second field of information which will be submitted in the GET / POST statement. Note that "<COMPUTERNAME>" will be expanded at run time by the Software Update Wizard into the name of the computer running the Software Update Wizard. |
| &Message=The update of Prophecy to V2.01 completed OK for this user | The third field of information in the GET / POST statement. You can submit as many fields as you like, up to the limit of a GET statement. |
| <Referrer=http://www.myhost.co.uk/contact.html> | This is an optional part of the syntax, which,
if used, must appear at the end of the SubmitForm keyword line.
Its purpose is to 'spoof' the server script which processes the GET / POST command that the information has come from a web page form residing within the server's domain and not from the Software Update Wizard. Why do you need this? Say you are using a standard, minimum service ISP. They will not let you run any third party processing on their servers, with which to collect this information. However, most will provide a form mail script to collect information from web page forms and email it to you or put it into a database. In order to prevent use of their scripts by non-customers, many ISPs verify that the page which generated the GET / POST information originates from their own servers space. If the http GET / POST request originates outside the ISP's server space the request is rejected. The ISPs use the 'Referrer' part of the http request headers (the information your browser sends with each request but that you don't see) to verify that the request originated from one of their pages. By providing referrer information the Software Update Wizard can fool the script into accepting the GET / POST request. Therefore, in the sample syntax shown we have set the referrer for the GET / POST request to be a page from our own web site. Please note that as far as the Software Update Wizard is concerned, the page contact.html which is specified in the example syntax as the referring URL does not have to actually exist. However, if your ISP is clever (and has processing power to burn!) they would be sensible to check that, not only does the referrer come from their server space but also that the page specified actually exists! You will have to discover whether this is an issue for your ISP by trial and error! If you have your own server, you will probably not need to use the Referrer syntax, as you have total control over what is accepted or rejected by the server. |
Debugging form submissions can be problematic. If you switch SuperLogging on in the WebUpdateSvc4.ini file you can verify that the GET or POST request was made and the full contents of the GET or POST http: request.
However, if the log file says the request was successfully submitted this only means the Software Update Wizard submitted it successfully to the target server. It does not necessarily mean that the FormMail handler successfully parsed the contents and sent you the email.
While you are attempting to debug your script you should include the <DEBUG> option in your SubmitForm line (see above). This will show you the web page that your formmail would have presented to the user had the submission originated from a standard web page form. The page you see should give pointers to the problem.
If the page you see using the <DEBUG> option in your SubmitForm looks OK there may be additional requirements for successful posting which are introduced by your isp. For example, one user reports that SubmitForm works successfully with FormMail V1.92 © 1995 - 2002 Matt Wright only if both 'email' and 'recipient' parameters (highlighted in red) are provided, as shown:
SubmitForm=
This keyword lets you access string values from the client PC's registry. This is useful where, for example, your application has squirreled away some information that needs to be transmitted by the Software Update Wizard in a SubmitForm keyword line.
For example, suppose your application maintains a usage count of the number of times the client user has used your program. Your program writes this information to a registry item, e.g. HKEY_LOCAL_MACHINE\SOFTWARE\MyApp\Usage, as a text data item, as shown in the following screen extract from the Windows Registry Editor, regedit.exe:
In order to include the data at this registry location in a SubmitForm keyword line you need to create a variable for the SubmitForm line to use, and then include it in the SubmitForm line, as shown in the following example:
SubmitVariable <USAGEDATA>=HKEY_LOCAL_MACHINE\SOFTWARE\MyApp\Usage
SubmitForm=http://www.dataper.demon.co.uk/cgi-bin/mailform?Name=<USERNAME>&<USAGEDATA>
Note that the registry key name is appended to the registry key path in the SubmitVariable keyword line - compare the example syntax with the registry editor screenshot above it.
The SubmitVariable keyword line creates the <USAGEDATA> variable and the SubmitForm line submits it as part of the http: GET request which the Software Update Wizard submits to the target URL.. At run-time, the Software Update Wizard accesses the computer's registry and obtains the text data in the specified key, so that, assuming the data at the key in the example is "127" then the GET request submitted will expand to
http://www.dataper.demon.co.uk/cgi-bin/mailform?Name=<USERNAME>&<USAGEDATA>=127
The default for this keyword is to read the specified registry key using the SYSTEM security context (assuming the Software Update Wizard is running as a service application). Therefore the key HKEY_CURRENT_USER relates to the SYSTEM user identity, not that of the logged on user. If you wish to read a value from the logged on user's HKEY_CURRENT_USER you should append the text<AsUser> to the SubmitVariable line, as in: