Definition of web requests

Contents 1 Example 2 <webrequest> 2.1 <secfields> 2.1.1 <field> 2.2 <request> 2.2.1 <plex-parameter> 2.2.2 <parameter> 2.2.3 <stoponerror> 2.3 <request-list> 2.3.1 Attributes 2.3.2 Examples 2.4 <importrequest> 2.5 <response> 2.5.1 <error> 2.5.2 <reaction> 2.6 Reaction Types 2.6.1 <filter> 2.6.2 <save-parameter>

Example

A web request that could be called by the name 'MyUpdate'.

There is only one request with the name 'MyUpdate' defined . It has one extra defined web parameter that could be passed with the name 'HeaderID' and some common parameter that are inherited by the 'extends="Update"' attribute.

The parameter 'HeaderID' is secured against Web Parameter Tampering (only for those requests with secured fields a generated parameter 'h' will be checked).

The response of this request has two reactions. One 'default' reaction that uses the default style and is filtered by the 'DictionaryEdit.xslt' and one reaction the is selected when the return code has the value 'OK'.

<webrequest name="MyUpdate">
  <secfields>
    <field name="HeaderID"/>
  </secfields>
  <request name="MyUpdate" extends="Update">
    <plex-parameter type="web" name="UpdateKey_HeaderID">HeaderID</plex-parameter>			
  </request>
  <response>
    <error type="default" name="DEFAULT"/>
    <error type="reaction" name="READY" response="MyUpdate" value="OK"/>
    <reaction type="DEFAULT" target="DISPLAY" localized="true" name="/WEB-INF/resources/common/DictionaryEdit.xslt"/>
    <reaction type="READY" target="DISPLAY" usedefaultstyle="false" name="/WEB-INF/resources/@common_html@/ready.xslt"/>
  </response>
</webrequest>

<webrequest>

<webrequest name="MyWebrequest">

Attributes

name :Name of the request as it will be used in the URL. REQUIRED

http://127.0.0.1/MyApp/aServlet?request=MyWebrequest

needlogin : true|false used by optional LoginFilter if forward to a LoginPage is necessary, but should be set for the Login Page OPTIONAL

usedefault : true|false used to inherit requests from an optionally defined default <abstract-webrequest>, set to false ignores the default OPTIONAL

extends : <name of an abstract-webrequest> to inherit requests from a <abstract-webrequest>, if found overrides the default <abstract-webrequest> OPTIONAL

<secfields>

A list of web parameter names, which should be checked against parameter tampering.

  <secfields>
    <field name="HeaderID"/>
  </secfields>

Attributes

useSession: true|false Useage of SessionId in hash code. Useful for anonymous requests.

<field>

Attributes

name :Name of parameter REQUIRED

<request>

<request name="MyFindBrowseRequest" extends="FindBrowse">

Attributes

name :Name of the request as defined in the Controller Configuration. In most cases the request name is identically to the Plex-XML function the is called by the servlet. REQUIRED

--> There is a special request name 'Echo' that has no Plex-Function as request. You could us it e.g. if you like to get the result of a XSLT-Transformation without running through a Plex-Function before.

cache :true|false

cachetime : if cache is true specifies the time how long the cached entry will be valid, defaults to 5 minutes

type :static

localized :true|false

extends :abstract-request-name

default-parameter :true|false

asynchron :true|false

false: (default) If you have more then one request in you web-request this request is executed synchron and the next request in this web-request will be started after the request is ready.

true: The request is send to another thread where asynchronous requests are executed one by one. The next request in this web-request won't have to wait until the asynchronous request is ready. The request get's an immediate result :<message>job #xxx submitted.</message>. You can use an asynchronous request e.g. if you like to send an e-mail after a new record has been saved and the user won't have to wait until the e-mail has been prepared and send.

<plex-parameter>

A field / value that is mapped to an input parameter in a Plex function.

<plex-parameter type="web" name="UpdateKey_KeyField">RequestName</plex-parameter>

Attributes

type :Type of parameter REQUIRED

fix :There is a fixed value for this parameter. It can't be submitted by a web request.

<plex-parameter type="fix" name="Input_ParameterFix" value="this value is fix"/>

web :The value of this parameter is submitted by a web request.

<plex-parameter type="web" name="UpdateKey_KeyField">RequestName</plex-parameter>

response :The value of this parameter is the value of a field from a response of a previous request.

<plex-parameter type="response" name="FindFields_GenWhereValue" field="Output_SearchHeaderID" response="FormSearchHInsUpd"/>

the special attribute value response="*" is allowed to search for the field in ALL responses of the webrequest

session :The value of this parameter is the value of a session property.

<plex-parameter type="session" name="Input_SessionID">session.ID</plex-parameter>

request :The value of this parameter is the value of a request value extracted from the HTML header. Valid values are "request-uri", "request-url", "protocol", "remote-address", "remote-user", "locale", "user-agent", "referer".

<plex-parameter type="request" name="Input_IPAddress">remote-address</plex-parameter>

request-uri --> /security/aServlet

request-url --> http://127.0.0.1:8080/security/aServlet

protocol --> HTTP/1.1

remote-address --> 127.0.0.1

remote-user --> ?

locale --> de

user-agent --> Mozilla/5.0 (Windows; U; Windows NT 6.0; de; rv:1.9.0.7) Gecko/2009021910 Firefox/3.0.7 (.NET CLR 3.5.30729)

referer --> http://127.0.0.1:8080/security/aServlet?request=oldrequest

name :Name of the parameter in the Plex function. The first part is the variable (e.g. Input, UpdateKey) and the second part after the '_' is the field name.

shape : Optional. Attribute shape="Date5" could be used to parse a month/year ("12/10") value to a date 5.0 field (11012).

format: Oprional. Format of the input field. Could be used to parse a ISO-Date in an UpdateKey e.g. format="yyyy-MM-dd".

encryption : INTERN The field value is encrypted while it is handled between the servlet and your Plex-Function. Useful for e.g. passwords so you won't see the real password/value in log-files, dumps and while debugging. !!!This doesn't effect the encryption between the browser and the servlet. You should use HTTPS for that!!!

index : used for Plex-Array Input Fields, use "*" to map all Fields or a number (starting with 1 ) to map to a specific index

<plex-parameter type="web" encryption="INTERN" name="Input_Password">Pwd</plex-parameter>

<parameter>

A parameter that is passed over to the XML result without an input field in the Plex function. Very helpful if you like to control/customize XSLT generation.

<!-- Example for a fixed value that is passed to your XML result -->  
<parameter type="fix" name="xsl_Mode" value="none"/>
<!-- Example for a web request value (refresh) that is passed to your XML result -->  
<parameter type="web" name="ParRefresh">refresh</parameter>

Attributes

type :Type of parameter REQUIRED

fix :There is a fixed value for this parameter. It can't be submitted by a web request.

file:Special type for file uploads. See FileUpload for an example.

name :Name of the parameter in the XML result

value :Value of the parameter in the XML result

Example parameter type 'file':

  <parameter type="file" name="File1" webfield="File1">
   <plex-parameter type="web" name="FileInput_DocFileLocalPath">original</plex-parameter>
   <plex-parameter type="web" name="FileInput_DocFileMimeType">contenttype</plex-parameter>
   <plex-parameter type="web" name="FileInput_DocFilePath">newname</plex-parameter>
   <plex-parameter type="web" name="FileInput_DocFileSize">size</plex-parameter>
  </parameter>

<stoponerror>

successcode :anerrorcode

<request-list>

A request-list is a list of different Requests that are stored in:

• a local XML file
• an external XML file that is uploaded
• a XML file and a XSLT request filter that builds the request list by processing the XML with the XSLT filter
• generated from the XML Elements of a Response

Attributes

url:Name of an URL( "http:" or local "file:" URL), or a local resource within the application which should produce a valid XML document - optionally filtered to produce valid requests, OR

webfield:A field from a webrequest that contains a reference to an upload file

field: A field from response that which contains the file name to use

response:Response name that contains field attribute, OR

response:Response name whose XML Element(s) are used to generate the Request List ( webfield and field attributes must not be present!)

Examples

Example of a request-list that is generated form an XML input file by a XSLT-Filter.

<webrequest name="ImportSecurityMenu">
 <request-list url="/WEB-INF/initialise/SecurityMenu.xml">
  <filter>/WEB-INF/security/filter/BuildMenu.xslt</filter>
 </request-list>

 <response>
  <error type="default" name="DEFAULT"/>
  <reaction type="DEFAULT" target="WEBREQUEST" name="Start"/>
 </response>
</webrequest>

...
<!-- Daily import of exchange rates from EZB -->
<request-list url="http://www.ecb.int/stats/eurofxref/eurofxref-daily.xml">
 <filter>/WEB-INF/financial/resources/import-kurse-ezb-job.xsl</filter>
</request-list>
...

...
<!-- Import from file system -->
<request-list url="file:///c:/Temp/Aktivitaeten.xml">
 <parameter type="web" targetfield="fooID" field="Key_fooID" response="foo" />  
 <filter>/WEB-INF/financial/resources/import-activity-alt.xsl</filter>
</request-list>
...

...
<!-- request list built from a file where the name comes from a response -->
<request-list response="upload" field="FileName_DocFilePath">
  <filter>/WEB-INF/somefilter.xslt</filter>
</request-list>
...

...
<!-- request list from an uploaded file -->
<request-list webfield="File1">
  <filter>/WEB-INF/somefilter,xslt</filter>
</request-list>
...

<!-- request-list built from the response node itself from a response -->
<webrequest name="listExample1">
  <request name="listData" extends="FindBrowse"/>
  <request-list response="listData">
    <filter>/WEB-INF/listDataToRequests.xslt</filter>
  </request-list>
  ...
</webrequest>

<importrequest>

you can use this special type of request to import files previously uploaded ( or otherwise accessible from the Server). The Default-Implementation can import CSV files into the database. it generates a XML request for each row in the file.

 <importrequest name="RunImport">
   <parameter type='web' targetfield='locale' field='Locale' response='Echo' />
   <parameter type='web' targetfield='language' field='Language' response='Echo' />
   <parameter type='web' targetfield='filename' field='FilePath' response='Echo' />
   <parameter type='web' targetfield='requestname' field='ImportRequestName' response='Echo' />
   <parameter type='web' targetfield='type' field='ImportType' response='Echo' />
   <parameter type='web' targetfield='separator' field='ImportDelimiter' response='Echo' />
   <parameter type='web' targetfield='quotechar' field='ImportQuoteChar' response='Echo' />
   <parameter type='web' targetfield='charset' field='ImportCharSet' response='Echo' />
   <parameter type='web' targetfield='filterfunction' field='ImportFilterFunction' response='Echo' />
   <parameter type='web' targetfield='formatname' field='FunctionFormat' response='Echo' />
   <parameter type='web' targetfield='skipFirstLines' field='ImportHeaderLines' response='Echo'/>
 </importrequest>

Parameters

• locale : passed through to the XML request
• language : passed through to the XML request
• filename : the full path to the import file ( must be from the server point of view!)
• requestname : the name of the request generated ( should be the name of an Import Request)
• type : 'CSV' for Default-Implementation
• separator : a character used as field delimiter (default:;)
• quotechar : a character used as String delimiter(default:none)
• charset : a character set name (default: System charset)
• filterfunction: name of an implementation of the Java Interface de.bodow.dataimport.CSVFilter ( default: de.bodow.dataimport.DefaultCSVFilter) to enable some customization
• formatname: format name to be used within the generated request
• skipFirstLines: skip the first n lines eg. because it contains header information

<response>

...
<response>
 <error type="default" name="DEFAULT" />
 <reaction type="DEFAULT" target="NOTHING" />
</response>
...

<error>

Attributes

type :default|reaction

name :einName

response :einrequestname

value :ein errorcode-Wert

<reaction>

Reactions defines how to react on a reault of a request.

Attributes

target :Kind of reaction that your request should have REQUIRED

type :correspond to the definition of an <error>-Element to choose the desired reaction

name : Names of a XSL Filter or Name of a WebRequest

mime : MIME-Type of your response could be used for downloads or XMLHttp-Requests

text/javascript : a XMLHttp-Request expects and executes pure javascript as response

text/xml : a XMLHttp-Request expects XML as response. It could be processed by javascript.

text/html : HTML respone. Cloud be set foor sendmail to send a mail in HTML format.

application/octet-stream : File-Download. E.g. when your request creates a XML-Document that should be offered as a download.

usedefaultstyle :true | false

localized :true | false --> Use messages-{0}.xslt for translation. See Translation in XSLT for more information about translation in xslt's.

Reaction Types

you can pass parameters to most of the Reactions. Which parameter you can use depends on the type of the reaction.

WEBREQUEST : Another Web-Request

 <reaction type="DEFAULT" target="WEBREQUEST" name="UserIDTab">
   <parameter type="web" response="newLDAPUser" field="Output_UserIdentifier" targetfield="UserIdentifier"/>
 </reaction>

• the usable parameters depends on the expected parameters of the target Webrequest, the reaction itself does not use any parameters

FORWARD : like WEBREQUEST but if a forward request was set by the LoginFilter that request is executed instead.

 <reaction type="DEFAULT" target="FORWARD" name="GetInitialSessionParm1"/>

• the usable parameters depends on the expected parameters of the target Webrequest, the reaction itself does not use any parameters

DISPLAY  : Send the response back to the requester mostly used to display an HTML Page as response

 <reaction type="DEFAULT" target="DISPLAY" localized="true" stytuscode="200" name="/WEB-INF/resources/common/DictionaryEdit.xslt">
   <filter>/WEB-INF/xmlfilters/preparesomething.xslt</filter>
   <parameter type="fix" targetfield="ContentDisposition" value="attachment"/>
   <parameter type="web" response="CopyData" field="LocalFileName" targetfield="LocalName"/>
 </reaction>

• the nested <filter>-Elements are optional to allow you to extend the XSLT-Chain, <filter>-Elements are inserted at the beginning of the chain.
• the LocalName Parameter can be used in combination with ContentDispositon to allow a Download instead of a Display. Both Parameters defaults to null, therefore normally no Content-Dispositon Header is generated.
  Possible Values for ContentDisposition are "attachment" and "inline".
• statuscode is an optional parameter. You could us it to set the HTTP status code. By default it is set to 200 OK. List of codes http://en.wikipedia.org/wiki/List_of_HTTP_status_codes

BINARY  : Send binary data back to the requester

 <reaction type="DEFAULT" target="BINARY">
   <parameter type="web" response="DocFilShow" field="Output_DocFilePath" targetfield="DocName"/>
   <parameter type="web" response="DocFilShow" field="Output_DocFileMimeType" targetfield="DocMime"/>
   <parameter type="web" response="DocFilShow" field="Output_DocTypeStdPath" targetfield="DocPath"/>
   <parameter type="web" response="DocFilShow" field="Output_DocFilePath" targetfield="LocalName"/>
   <parameter type="fix" targetfield="ContentDisposition" value="attachment"/>
 </reaction>

• DocPath and DocName are used to tell the server which file is to be sent back. DocMime is used set the MimeType ResponseHeader(optional). ContentDisposition and LocalName are used as described above, but ContentDispostion defaults to "inline" and if no LocalName is given, the docName is used as LocalName

SENDMAIL  : Send an Email (Server, SMTP-User and Password could be stored in System-Parameter)

<response>
 <error type="default" name="DEFAULT"/>
 <reaction type="DEFAULT" mime="text/html" target="SENDMAIL" name="/WEB-INF/helpdesk/style/ActMainSendMailHelp.xslt">
  <parameter type="web" targetfield="server" response="MainSendMail" field="ControlOutput_MailServer" />
  <parameter type="web" targetfield="user" response="MainSendMail" field="ControlOutput_MailSMTPUser" />
  <parameter type="web" targetfield="password" response="MainSendMail" field="ControlOutput_MailSMTPPW" />
  <parameter type="web" targetfield="subject" response="MainSendMail" field="ControlOutput_MailSubject" />
  <parameter type="web" targetfield="plaintext" response="MainSendMail" field="ControlOutput_MailPlainText" />
  <parameter type="web" targetfield="attachment" response="MainSendMail" field="ControlOutput_MailAttachment" />
  <parameter type="web" targetfield="to" response="MainSendMail" field="ControlOutput_MailAddressTo" />
  <parameter type="web" targetfield="cc" response="MainSendMail" field="ControlOutput_MailAddressCC" />
  <parameter type="web" targetfield="bcc" response="MainSendMail" field="ControlOutput_MailAddressBCC" />
  <parameter type="web" targetfield="from" response="MainSendMail" field="ControlOutput_MailAddressFrom" />
  <parameter type="web" targetfield="replyto" response="MainSendMail" field="ControlOutput_MailAddressReplyTo" />
  <success-page usedefaultstyle="false" name="/WEB-INF/resources/@common_html@/ready.xslt"/>
  <onsuccess>
    <reaction type="DEFAULT" target="DISPLAY" localized="true" name="/WEB-INF/resources/common/DictionaryView.xslt">
      <filter>/WEB-INF/xmlfilters/preparesomething.xslt</filter>
    </reaction>
  </onsuccess>
  <error-page name="/WEB-INF/resources/common/Error.xslt"/>
  <onerror>
    <reaction type="DEFAULT" target="DISPLAY" localized="true" name="/WEB-INF/resources/common/DictionaryView.xslt">
      <filter>/WEB-INF/xmlfilters/preparesomething.xslt</filter>
    </reaction>
  </onerror>
 </reaction>
</response>

• the <success-page> and <error-page> elements tell the system what page to display when everything was ok or there was an error sending the mail. both can have nested filtered Eleements as in DISPLAY Reactions
• as more complex alternatives to <success-page> and <error-page> now the <onsuccess> and <onerror> Child Elements are allowed to process a normal reaction, i.e. forward to another webrequest, do nothing or any other reaction
• plaintext: is for a mulitpart message with HTML-Part (from XSLT) and plaintext part for those who can't read HTML-Emails. This is often used for newsletters.
• attachment: when used, this parameter should contain the name and path of a file, which is attached to the mail, if used the plaintext parameter is ignored

NOTHING  : no reponse

 <reaction type="DEFAULT" target="NOTHING"/>

EXPORT_OO  : Export to OpenOffice/Excel/PDF/.. via OpenOffice Server

 <reaction type="DEFAULT" target="EXPORT_OO">
   <parameter type="fix" targetfield="template" value="/WEB-INF/limon/OOTemplates/OOTable.ods"/>
   <parameter type="fix" targetfield="delete-temp" value="true"/>
   <parameter type="fix" targetfield="LocalName" value="ExportOOo.pdf"/>
   <parameter type="fix" targetfield="format" value="PDF"/>
   <parameter type="fix" targetfield="calc-column-width" value="true"/>
 </reaction>

• ContentDisposition and LocalName are used as described above, but ContentDispostion defaults to "inline" and LocalName defaults to a temporary generated file name.
• If LocalName does not contain a "." the value of the format Parameter converted to lowerCase is used as extension.
• The required template parameter should point to a special ODF Template, which can contain XSLTs instead of XML, to produce the real ODF File. The delete-temp defaults to false(Hmmh should be true i think) and controls the deletion of some intermediate Files necessary to produce the Ouput. The "calc-column-width" parameter defaults to false and when set to true let OpenOffice Calc calculate column width to "optimal width" which is especially useful, when creating PDF output.

SAVEFILE : save resulting Document to the Server File System

 <reaction type="DEFAULT" target="SAVEFILE" localized="true" usedefaultstyle="false" name="/WEB-INF/limon/style/X1_FB_publicView.xslt">
   <parameter type="fix" targetfield="filename" value="testpv.html" />
   <parameter type="fix" targetfield="directory" value="c:\temp" />
   <success-page usedefaultstyle="false" name="/WEB-INF/resources/@common_html@/ready.xslt"/>
   <error-page name="/WEB-INF/resources/common/Error.xslt"/>
 </reaction>

• can use <filter>-Elements like DISPLAY, but instead display the result, save it to a file on the Server. The name of the targeg file is constructed from the parameters filename and directory.
• the <success-page> and <error-page> elements tell the system what page to display when everything was ok or there was an error saving the file.

REDIRECT : redirect to an external URL

 <reaction type="DEFAULT" target="REDIRECT">
   <parameter type="web" targetfield="url" response="ReportSel" field="Output_ReportURL" />
 </reaction>
or
 <reaction type="DEFAULT" target="REDIRECT">
  <parameter type="fix" targetfield="url" value="http://www.allabout.de" />
 </reaction>

• the only parameter is url which should contain a valid URL for the redirect. Especially useful for embedding parametrized requests to external System like Reporting Tools. Your application could construct the URL and "call" the external System.
• the Browser will get a "302 Moved Temporarily" status and the new URL.

<filter>

<save-parameter>

Save an output parameter in application server session.

<save-parameter response="SessionAndUser" field="ControlInput_SessionID" targetfield="session.ID"/>