Web Interface URL Format

This section discusses the exact format of the request you must send to the Web-Activator to get a successful response.

Test First:

Before you start work on constructing the parameters the Web-Activator needs to generate Activation Codes, you should test to ensure you have deployed it correctly and it has sufficient permissions to execute on your server properly. To perform this test, simply call the Web-Activator directly through a web browser. For example, if you have deployed your Web-Activator to a sub-directory on your site called "scripts", open a web browser and input the URL: "http://www.mysite.com/scripts/cgiacodegen.exe". When called like this the Web-Activator should respond immediately with a message that it is online. If you do not get this message, check your permission settings on the server and try again.

Security:

Never link your customer directly to the Web-Activator. Never give the customer the URL where your Web-Activator lives. The Web-Activator should only ever communicate to your "authentication layer" directly. Often this is as simple as providing your merchant services provider the URL where your Web-Activator lives (in this case the merchant services provider acts as an authentication layer). Or, if you process your own credit card payments, your server side code will act as the authentication layer and when a payment is successfully processed, will link to the Web-Activator to get an Activation Code, which is then parsed on your server and sent to the client (possibly along with their receipt).

URL Format:

The format of the URL you must assemble for the Web-Activator has three basic components. Examples are given at the bottom of the page. Also, please have a look at the Example Web-Activator HTML provided in this SDK.

The URL format is best understood by breaking it down into its components:

Component A: This is simply the http path to your server and the directory where the Activation Code Generator is deployed. The part of the URL may be something like: "http://www.YOUR_DOMAIN.com/scripts"

Component B: This is the name of application. This part of the path is always: "/CGIACodeGen.exe/GenCode"

Component C: This is the most important part of the URL. It is the parameter string. Like other parameter strings it is started by the question mark "?". Individual parameters, as usual, are separated by the ampersand "&". The Web-Activator parses and actively uses two of the parameters you pass for its logical processing:

The GenCode parameter which is mandatory.
The Configuration parameter which is optional.

The most important parameter is the GenCode parameter. The GenCode parameter is the one the Web-Activator will parse and will ultimately control how (or even if) it responds.

The Configuration parameter controls the Web-Activator communication. You can control how it responds, to what requests it responds, what the content of the response will be and what format it will take. It also controls details of if and how it should log its activity to a file on the server. Much more detail is provided about the configuration parameter and how it works in Web-Activator Communication.

Other parameters may be ignored, or optionally logged to the log file. The section below describes how to construct these parameters.

GenCode Parameter

The Web-Activator expects a GenCode parameter. This parameter, by default, is a single parameter identified as "user_text". It must contain at least three pieces of information:

The file name of the License Project File prefixed by the case-sensitive string "*F*". This must come first in the user_text parameter. E.g.: "*F*LicenseFileV1.lpj"
The Authorization Request Code input by the customer prefixed by the case-sensitive string "*C*" This must come second in the user_text parameter. E.g.: "*C*ED19-FBCD-EEB6-D0D0"
The parameter value used to generate the Activation Code. There are two types, numeric and date. Each type has its own identifier. You must prefix the parameter with the case sensitive "*P*" string in the case of a numeric parameter, (E.G.: 0, 100, 652 etc.) or the case sensitive string "*DT*" string in the case of a date parameter, in the format YY-MM-DD (E.G.: 03-06-21 for June 21, 2003). Even if you do not need a parameter for a code, you must provide a (numeric type) zero. This must come last in the user_text parameter. E.g.: "*P*0", "*P*100", "*DT*03-06-21" etc.

An example of a default style of GenCode parameter is:
"user_text=*F*SSLicFile10.lpj*C*ED19-FBCD-EEB6-D0D0*P*0"

You can control the identifier used with a configuration file (if "user_text" is not acceptable or your merchant requires you to use a different name).

Configuration Parameter (optional)

The configuration parameter controls if the Web-Activator loads settings from a Configuration File on the server by identifying the configuration file name. (Note you can still use a configuration file if you wish without using a configuration parameter, see: Web-Activator Communication)

The configuration parameter is identified and parsed by the Web-Activator by searching the entire query for the *CFG* specifier. If the config file specifier (*CFG*) is found anywhere in the query it is assumed that the sub-string following it is the Configuration File name (and relative path). The end of the sub-string following it is assumed to be the next following ampersand (&), or the end of the query whichever comes first. This means that if you pass the configuration parameter as a separate item, it may have any identifier.

If it can find the Configuration File name in the query, and load it successfully, the query is then processed and an Activation Code is generated and returned according to the settings in the Configuration File.

If a Configuration File name specifier (*CFG*) is not found in the query - then the Web-Activator looks in its current directory for the default file which must be named: "configDEFAULT.txt" If that file (configDEFAULT.txt) is present - an attempt to load it is made and its settings are used.

If a Configuration File name specifier (*CFG*) is not found in the query, and the default file is not present - then default settings are used for all configuration parameters.

Therefore, if you choose to use the optional configuration parameter, you have two choices. Either one works equally well:

Pass the configuration parameter as a separate parameter identified by any identifier.
Pass the configuration parameter concatenated to the end of the GenCode parameter. (preferred)

If you pass the configuration parameter as a separate parameter identified by any identifier, your parameters might look like this:
?t=*F*LicFileV1.lpj*C*ED19-FBCD-EEB6-D0D0*P*0&myConfig=*CFG*configDir/config4.txt

If you pass the configuration parameter concatenated to the GenCode parameter, your parameter might look like this:
?t=*F*LicFileV1.lpj*C*ED19-FBCD-EEB6-D0D0*P*0*CFG*config4.txt

Examples:

Because of the length of some of these examples, we have dropped components "A" and "B" (from the diagram at the top of this page) and just show the parameters. In all these examples you can assume that the parameters shown are prefixed by the HTTP path and application name in exactly the same way (for example they all start with: "http://www.YOUR_DOMAIN.com/scripts/CGIACodeGen.exe/GenCode")

This example is the full URL for a call to the Web-Activator using the default settings (no configuration at all). This example shows using a numeric parameter (0). The default HTTP method is GET.

?user_text=*F*LicFile1.lpj*C*ED19-FBCD-EEB6-D0D0*P*0

This example is the full URL for a call to the Web-Activator using the default settings (no configuration at all). This example shows using a date parameter (June 21, 2005). The default HTTP method is GET.

?user_text=*F*LicFile1.lpj*C*ED19-FBCD-EEB6-D0D0*DT*05-06-21

These next two examples are the full URL for a call to the Web-Activator using a configuration file named "config4.txt". These examples show using a numeric parameter (55). The second one locates the configuration file in a sub-directory named "configDir/"

?t=*F*LicenseFileV1.lpj*C*ED19-FBCD-EEB6-D0D0*P*55*CFG*config4.txt

?t=*F*LicenseFileV1.lpj*C*ED19-FBCD-EEB6-D0D0*P*55&myConfig=*CFG*configDir/config4.txt
This example illustrates that other parameters can be passed too. For example, the configuration file may indicate that these are to be logged to a log file on the server for you use later.

?cfg=*CFG*config4.txt&t=*F*LicenseFileV1.lpj*C*ED19-FBCD-EEB6-D0D0*P*0&testParam9=test

Note: The SoftwareShield Web-Activator only comes with the Internet and Server Editions of the SoftwareShield System.