SubmitForm - Additional Information

This help page covers the optional keywords SubmitForm and SubmitVariable. These keywords let you invisibly submit information from the Web 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 to receive email updates whenever a user updates their software with the Web Update Wizard.

The information which can be transmitted in this way can be anything which fits into an http GET or POST request.

Your application can create and write to registry keys on the user's computer as part of its normal execution. Within your Web Update Wizard script, you can create temporary variables that read the registry key values using the SubmitVariable keyword (see below). The Web Update Wizard can then transmit them within an http: GET or POST request using a SubmitForm keyword line in a Web Update Wizard script.

Please note that the user of your software will be unaware that this information is being submitted - the process will be completely invisible to him or her. The Web 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.

SubmitForm=

This keyword lets the Web 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 Web 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 Web 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 Web 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 Web Update Wizard into the name of the computer running the Web 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 Web 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 Web 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 Web 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.

SubmitVariable=

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 Web 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 Web Update Wizard submits to the target URL.. At run-time, the Web 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 Web 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:

SubmitVariable <USAGEDATA>=HKEY_CURRENT_USER\SOFTWARE\MyApp\Usage<AsUser>

SubmitVariable - Notes

The registry key name must be appended to the registry key path in the SubmitVariable keyword line - compare the example syntax with the registry editor screenshot above it in the text above.
For clarity we have omitted the optional "Referrer=" part of the SubmitForm syntax - see above.