webforms service user manual

Revision 101 2011-05-06 Webforms service User Manual of 39

WebForms serviceUser Manual

Prepared byEnriko Käsper, TietoEnator

February 2010Version 1.4

User Manual

Version management and approvalNo Date Changes Author0.1 13.12.2004 Creation of the document Enriko Käsper0.2 19.01.2005 Reorganised chapters + wording + “User

groups” changed to “User roles”Enriko Käsper

0.3 21.07.2008 Minor issues corrected Søren Roug1.0 10.09.2008 XML/RPC information added Søren Roug1.1 23.04.2009 Context parameters and external systems

chapters addedEnriko Käsper

1.2 16.09.2009 Chapters about XML files management and backup files added. Language chapter removed. Screen-shots updated.

Enriko Käsper

1.3 23.09.2009 Text review. Added instructions how to create multilingual forms, use lookup files and get and create empty instance file. CDR integration chapter revised.

Enriko Käsper

1.4 01.02.2010 Added instructions about saving instance into different XML file using XSL transformation

Enriko Käsper


Contents1. WEBFORMS SERVICE.......................................................................................................... 5

2. PUBLIC FUNCTIONALITY.................................................................................................. 6

2.1. WEBFORMS REPOSITORY............................................................................................................62.1.1. Browse WebForms repository.......................................................................................62.1.2. View XML Schema WebForms......................................................................................72.1.3. View/Test WebForms.....................................................................................................72.1.4. View lookup data in XML Files area.............................................................................8

3. WEB FORM AUTHOR’S FUNCTIONALITY................................................................... 10

3.1. CREATE A NEW WEBFORM.......................................................................................................103.1.1. A XForms skeleton.....................................................................................................103.1.2. Empty instance file......................................................................................................113.1.3. Save instance file.........................................................................................................113.1.4. Save instance to different XML file.............................................................................133.1.5. XML lookup files.........................................................................................................143.1.6. Multilingual webforms................................................................................................143.1.7. WebForm actions........................................................................................................15

3.2. CREATE A NEW WEBFORM FOR XML DEFINED IN DATA DICTIONARY.............................................163.2.1. Get draft WebForm from Data Dictionary..................................................................163.2.2. Revise the draft WebForm...........................................................................................173.2.3. Empty instance file......................................................................................................173.2.4. Data Dictionary code lists...........................................................................................173.2.5. Data Dictionary template WebForm...........................................................................18

3.3. WEBFORMS TIPS & TRICKS.....................................................................................................183.3.1. How to add an HTML editing field into webform........................................................183.3.2. How to split webforms for editing large XML instance files.......................................183.3.3. How to use context parameters on webforms..............................................................203.3.4. How to store the instance file into several XML files..................................................21

3.4. WEBFORMS LIMITATIONS..........................................................................................................223.5. XFORMS REFERENCES..............................................................................................................233.6. ADD NEW WEBFORM TO REPOSITORY.........................................................................................233.7. WEBFORM PROPERTIES.............................................................................................................243.8. WEBFORMS FILE HISTORY.........................................................................................................253.9. ADD IMAGES AND STYLES TO WEBFORMS....................................................................................263.10. XML FILES MANAGEMENT.....................................................................................................27

3.10.1. Add an XML file........................................................................................................273.10.2. Delete XML File........................................................................................................293.10.3. Edit XML file.............................................................................................................30

3.11. HOSTS MANAGEMENT.............................................................................................................323.12. PURGE BACKUPS HISTORY........................................................................................................32

4. EXTERNAL SYSTEM FEATURES..................................................................................... 33

4.1. INTEGRATIONS WITH CDR (FOR CDR ADMINS)...........................................................................334.1.1. Query Web Forms.......................................................................................................334.1.2. Deliver with WebForms...............................................................................................334.1.3. Edit with WebForms....................................................................................................344.1.4. Create new file with WebForms..................................................................................35


4.2. INTEGRATIONS WITH DATA DICTIONARY......................................................................................364.3. XML-RPC METHODS............................................................................................................36


1. WebForms ServiceThe WebForms service is one option for delivering XML data into the central data repository - CDR, and it is getting more and more popular. The logic how data provider reaches to web forms is handled already in CDR. After user's input WebForms service produces automatically valid XML files as deliveries into user's relevant CDR envelope. The users can pre-fill the web forms with data coming from last year’s deliveries and make the updates as needed. They can also start to fill out an empty web form. Data reporters do not need any other special software for filling data on webforms but ordinary web browser.

The technology behind the WebForms service is called XForms. WebForms authors write the web forms in XForms language and store the forms in WebForms repository. The main difference between the well-known HTML forms and XForms is that XForms-based web form gathers and processes XML data using an architecture that separates presentation, purpose and content. Unlike the original HTML forms, the creators of XForms have used a Model-View-Controller approach. The "model" consists of one or more XForms models describing form data, constraints upon that data, and submissions. The "view" describes what controls appear in the form, how they are grouped together, and what data they are bound to. CSS can be used to describe a form's appearance.

The web forms solution is more suitable for questionnaire type of dataflows, where the resulting XML file contains the simple answers for the given questions. It's also possible to build up a form for table-structured data. But the current approach of rendering the web forms might have serious performance issues, when trying to load large XML files with several hundreds of spreadsheet rows.

The Webform’s data – like field names, field types and code lists – can be defined in the Data Dictionary. It won’t be possible to automatically generate a web form from Data Dictionary that is also user friendly. Therefore it is only possible to generate a web form from DD as a draft. This form is then edited by an author and stored in the WebForms repository. Each form is dedicated to maintain one type of XML file only – identified by the file’s XML Schema or DTD.

The following functionality will be described in the next chapters:

➢ WebForms Repository - public functionality

➢ Guidelines for creating web forms

➢ WebForms Repository - functionality for web form authors

➢ WebForms integration with other systems


2. Public functionalityThis chapter gives an overview of WebForms service public functionality. It describes the read-functionality that is available for all user roles. The next chapter gives the exact guidelines how to administrate the service and create and deploy new web forms. WebForms are stored in the repository, where special parameters can be stored. The web forms are created in the XForms language. The creators of the web forms should have some basic knowledge in XML and XForms for creating new web forms. As the web forms are based on the data definitions for the dataflow, then it’s possible to use some help from the Data Dictionary, because the some metadata like field names and types are already defined there.

2.1. WebForms repository

2.1.1. Browse WebForms repositoryWebForms Service doesn’t have many web pages in its' user interface. There are only pages for WebForms repository and XML Files area. WebForms repository is a web-based database for storing web forms and their attributes. View functionality is available for all users. The opening view of the repository lists all available web forms stored in the database. One web form file is dedicated to one type of an XML file. One XML Schema can have several web forms. In the context of the Data Dictionary, each dataset and each dataset table have its own XML Schema. So we can say that one dataflow can have several web forms. The first column of the table contains the XML Schema and the second column displays the title of XML Schema. After clicking the XML Schema, the next page with web forms per one XML Schema will be opened.

Illustration 1: WebForms Repository opening view screenshot


2.1.2. View XML Schema WebFormsThe XML Schema WwebForms page lists all web forms available for one type of XML file. There can be several web forms listed in the table, but only one web form can be the default web form tickled in front of the row. Default web form is opened when user selects to edit data with web forms on CDR envelope page. If the form does not have default property, then they can opened from the default web form or they are inserted only for testing purposes. The first column of the table shows whether the form is default or not, the second column shows the title of the form, the third column is the file name and the fifth column is for the date and time, when the file was last modified. It’s possible to open/download the web form file by clicking on the file name. By clicking on the web form title the next page with detailed info for one web form will be opened. The next page has also testing possibilities.

Illustration 2: XML Schema WebForms screenshot

2.1.3. View/Test WebFormsView WebForms properties page has 2 parts. The first one shows all properties assigned to one web form. It has the XML Schema name and title, web form title, file name and default form attribute. The last field is for some detailed description about the web form. It’s possible to only view properties in this page. The second part of the page is dedicated to testing the web form. The users can select the browser ability they have in their computer. By default the ordinary web browser with JavaScript capabilities is selected. If user has an instance file with the same type of XML Schema available in the Internet (in CDR envelope for example), then he/she can insert the URL of the instance file into the next input field. If the source file has been left empty, then the empty instance file is used in the web form. If the XML Schema references to the Data Dictionary, then the URL instance file is calculated automatically. It’s not possible to use all functionality of web forms in this environment. For example saving the file into a CDR envelope is possible only, when user enters to web form from the CDR envelope. But validation, adding and deleting rows


functionality should be operational. It is impossible to give detailed guidelines here of using specific web forms, because the functionality will be implemented by the web form authors – data managers or administrators with skills in XForms language.

Illustration 3: Test WebForms screenshot

2.1.4. View lookup data in XML Files areaWeb Forms may use several “helper” XML files containing code-lists, translations and any other lookup data. These XML files are stored in XML Files area. The files are publicly available and they can be downloaded by clicking on the name of XML file.


Illustration 4: XML Files screenshot


3. Web form author’s functionalityTo create a new web form you must know the syntax of XForms. Web form authoring in essence means to use the declarative approach to page building. Everything you'll write are tags, attributes and CSS rules. You'll not need to write any Javascript or (beware) Java to make things run. You don't even need to understand how all AJAX, XForms magic is done behind the scenes. But you should have an understanding of XHTML, CSS and basic XForms.

The WebForms service uses XForms server-side implementation called Chiba that transforms the actual XForm to HTML. Some guidelines for creating and understanding webforms implemented in XForms language can be found from Chiba's userguide: http://www.chiba-project.org:8080/chiba/ChibaUserGuide.pdf . As the XForms is a quite new technology, there are not many XForms editors, but ordinary XML editors are good enough for checking the well-formedness of the file.

The beauty of using WebForms service and XForms for collecting data is that the authors don't have to set up a separate web application, but they can implement all the business logic in one web form and upload it to WebForms repository. The rest is done by the service.

The following chapters give a brief overview what has to be done for setting up a new web form. You can either create a form from the scratch, and we recommend you start from an existing form, or if you have your data structure defined in Data Dictionary, you can use it to get started.

3.1. Create a new WebForm

3.1.1. A XForms skeletonStarting from the scratch you need to create a skeleton for the web form. XForms itself is not a standalone markup language, but it is embedded into the XHTML document. To embed XForms into XHTML you have to watch only a few things:

• put the XForms Namespace on the root Element of your document.

• add a <xforms:model> tag to the head section of your XHTML document (or 'f' if you have choosen that for your prefix).The model itself has the following important children:

instance – is the root Element for the data you work with

bind – adds constraints and types to certain selected data nodes

submission – defines loading and saving operations (interaction with some datasource)

action – if you want to listen for events during model-initialization

• add some XForms UI to the body of your document. In this example a <xforms:group>

• bind some of your controls to the model data


http://www.chiba-project.org:8080/chiba/ChibaUserGuide.pdf

http://www.chiba-project.org:8080/chiba/ChibaUserGuide.pdf

Example of XForms skeleton:

<?xml version="1.0" encoding="UTF-8"?><html xmlns="http://www.w3.org/1999/xhtml"xmlns:xf="http://www.w3.org/2002/xforms">

<head><title>hello</title><xf:model id="hello-model">

<xf:instance id="default" src="http://instanceURL" xmlns=""/><xf:submission id="finish" f:action="http://submissionUrl"

f:method="post" replace="instance" f:encoding="UTF-8"/>(..)

</xf:model></head><body>

<h1>Webform title</h1><xf:group>

<xf:input ref=“foo“><xf:label>Foo</xf:label>

</xf:input></xf:group>

</body></html>

3.1.2. Empty instance fileWeb form needs to know the location of the default instance file. Usually it is a file stored in the CDR envelope. WebForms service passes the instance file URL to XForms as a context parameter called “instance” and this can be evaluated on XForms as following:

<xf:instance id="default" src="{$instance}"/>There are cases when the WebForms service does not know the instance file URL. It happens when the file is not yet created into the envelope or the form is activated from the WebForms repository. Since this is the pre-requisite of XForms that it has to know the structure of XML file, then in these cases the location of empty instance file should be written into web form. It can be achieved with the following syntax:

<xf:instance id="default" src="{$instance}"/><xf:instance xmlns="" id="emptyinstance">

<data/></xfinstance>



<f:submission id="get-emptyinstance" method="post" action="xml/habides-derogations-instance.xml" replace="instance" ref="instance(xforms:if(string-length(chiba:context('instance'))=0,'default','emptyinstance'))" />

<f:action ev:event="xforms-ready">

<f:send submission="get-emptyinstance" name="xforms-submit" /></f:action>

3.1.3. Save instance fileYou should use the submission element that posts the form to WebQServlet with mode=save or mode=finish parameters for saving the instance file back into CDR


http://instanceURL/

http://instanceURL/

http://instanceURL/

envelope. The servlet knows the logic and credentials of how to store/create the XML into CDR envelope. The response of the request is an XML with some data about save results. Use the following code for saving the data and displaying the save results for user:<xf:model>

<xf:instance id="default" src="{$instance}"/>

<xf:submission id="finish" f:action="{$base_uri}WebQServlet?mode=finish&instance_id={$instance_id}" f:method="post" replace="instance" f:encoding="UTF-8" instance="saveresult" validate="false">

<xf:message ev:event="xforms-submit-error">Error on saving data!</f:message>

<xf:load ev:event="xforms-submit-done" resource="{$base_uri}WebQServlet?mode=envelope&instance_id={$instance_id}" show="replace" />

</f:submission>

<f:submission id="savedraft" action="{$base_uri}WebQServlet?

mode=save&instance_id={$instance_id}" method="post" replace="instance" encoding="UTF-8" instance="saveresult" validate="false">

<f:message ev:event="xforms-submit-done" ref="instance('saveresult')/message" />

<f:message ev:event="xforms-submit-error">Error on saving data!</f:message>

</f:submission>



<xf:instance xmlns="" id="saveresult"><result>

<code desc="Result code: 0-ERROR;1-OK">-1</code><message desc="Save result message" /><result_time desc="Result time" /><last_modified desc="Last modified" />

</result></xf:instance>

<xf:bind nodeset="instance('saveresult')/code" id="has-save-info"

relevant=". > -1" type="integer" /><xf:bind nodeset="instance('saveresult')/last_modified" id="save-success"

relevant="../code=1" /><xf:bind nodeset="instance('saveresult')/message" id="save-error"

relevant="../code=0" />

(...)</xf:model><body> <xf:group id="webq_sys_mess" appearance="minimal" bind="has-save-info" class="system-msg">

<xf:output bind="save-success"> <xf:label>Content saved: </f:label>

</xf:output><xf:output bind="save-error">

<xf:label>Save failed: </f:label></xf:output>

</xf:group>

(...)<xf:trigger id="tr_savedraft">

<xf:label>Save</f:label><xf:hint>Saves the current status of the file into the CDR envelope,

without moving away from the web form</f:hint><xf:action ev:event="DOMActivate">


http://instanceURL/

<xf:send submission="savedraft" name="xforms-submit" /></xf:action>

</xf:trigger><xf:trigger id="tr_finish">

<xf:label>Save & Close</f:label><xf:hint>Saves the file into the CDR envelope and opens the envelope

page</f:hint><xf:action ev:event="DOMActivate">

<xf:send submission="finish" name="xforms-submit" /></xf:action>

</xf:trigger>(...)

<body>

It's possible to use the following request parameters in save actions:

instance_id – (mandatory) default instance file URL

title – (optional) sets title attribute in CDR envelope

restricted – (optional – true, false, undefined) if the parameter value is true, the file will be restricted from public view in CDR envelope. If the parameter value is false, the file will be publicly available in CDR envelope. If the value is not specified, then CDR default value is used.

3.1.4. Save instance to different XML fileIt is possible to store the instance file into different XML file, optionally using XSL transformation before storing the content. You should use the submission element that posts the form to WebQServlet with mode=savexml request parameter. The response data is in XML format having the same structure as save and finish actions have. To be able to use the transformation, xsl parameter should be added with the xsl file name that is stored in Conversion Service xsl repository.

It is possible to use the following request parameters in savexml action:

instance_id – (mandatory) default instance file URL

file_name – (mandatory) If the parameter value is just a file name, then the file will be stored in the same envelope as default instance file. If the parameter value is full URL, then it can be stored another envelope.

title – (optional) sets title attribute in CDR envelope

restricted – (optional – true, false, undefined) if the parameter value is true, the file will be restricted from public view in CDR envelope. If the parameter value is false, the file will be publicly available in CDR envelope. If the value is not specified, then CDR default value is used.

xsl – (optional) Conversion Service XSL stylesheet file name or conversion ID. The XML file will be transformed before storing it into CDR envelope.

Example:

The following example stores the default instance XML into separate file in the same envelope called “confidential.xml”. The file is transformed into another format using


“transform_secret.xsl” in Conversion Service before storing it into CDR envelope. Restrict from public view flag is raised in CDR envelope.

<xf:model><xf:instance id="default" src="{$instance}"/>

<f:submission id="savexml" action="{$base_uri}WebQServlet?mode=savexml&instance_id={$instance_id}&file_name=confidential.xml&restricted=true&xsl=transform_secret.xsl&title=Secret%20data" method="post" replace="instance" encoding="UTF-8" instance="saveresult" validate="false">

<message ev:event="xforms-submit-done" ref="instance('saveresult')/message" />

<f:message ev:event="xforms-submit-error">Error on saving data!</f:message></f:submission>

...

</f:model>

3.1.5. XML lookup filesUsually web forms use several helper XML lookup files. They can contain code lists for select elements, translations for UI labels, error messages or empty instance files. WebForms repository has an area for storing these kind of lookup files. The chapter 3.10.XML Files management describes closely how to upload a XML file into WebForms repository. The lookup files can be loaded into the web form memory using the following code snippet:<xf:instance xmlns="" id="regions" src="xml/habides_nuts2_lookup.xml"/>

3.1.6. Multilingual webformsFollow the steps below for making your web form multilingual:

1. Define reporting language in instance XML root element using xml:lang attribute<?xml version="1.0" encoding="UTF-8"?><root xml:lang="en"> (...)</root>

2. Create XML file for holding translations of labels – it is easier to maintain the translations, if they are stored in a separate XML file. The lookup file for labels can be in any format, but it is suggested to use some standardised format - eg. TMX (Translation Memory eXchange) (http://www.lisa.org/Translation-Memory-e.34.0.html) that is vendor-neutral open XML standard for the exchange of Translation Memory. The benefits you gain from using TMX format:

• flexibility of using different translations editing tools

• the translations are reusable in the next web forms

• the solution is future proof against technology changes

The example of translations in TMX format:


http://www.lisa.org/Translation-Memory-e.34.0.html

http://www.lisa.org/Translation-Memory-e.34.0.html

http://instanceURL/

<tmx version="1.4"> <header creationtool="Manual" creationtoolversion="1.x" datatype="plaintext" segtype="paragraph" adminlang="en" srclang="en" o-encoding="utf-8"></header><body><tu tuid="h1"> <tuv xml:lang="en"> <seg>Questionnaire on the implementation of Directive 1999/13/EC</seg> </tuv> <tuv xml:lang="fr"> <seg>Questionnaire sur la mise en œuvre de la directive1999/13/CE</seg> </tuv> <tuv xml:lang="de"> <seg>Fragebogen über die Durchführung der Richtlinie 1999/13/EG</seg> </tuv></tu></body></tmx>If any translation is unknown, then it make sense to use English term in the missing

value to make sure that something is displayed on web form. Or the other possibility is to to use “???” in the missing term to be able to find the missing translations later.

3. Detect the language on web form xforms-ready event and store the value in helper instance:<xf:action ev:event="xforms-ready"> <f:setvalue ref="instance('helper')/lang" value="value="xforms:IF(count(instance('report_languages')/lang[.=instance('default')/@xml:lang])=0,'en',instance('default')/@xml:lang)"" /></xf:action>The value constraints tries to use the same language for labels as used for reporting (xml:lang). If there are no translations for labels in reporting language then use default 'en'.

4. Create bindings for labels depending on the selected language<xf:instance xmlns="" id="labels" src="xml/webform-labels.tmx" /><xf:bind nodeset="instance('labels')/body/descendant::tu/tuv[@xml:lang=instance('context')/lang]"> <xf:bind id="b-label-h1" nodeset=".[parent::tu/@tuid='h1']/seg" /> (...)</xf:bind>

5. Bind labels values and form controls<body> <h1> <xf:output> <xf:label class="heading" bind="b-label-h1" /> </xf:output> </h1> (...)

<xf:input bind="b1-surface-area"><xf:label bind="b-label-heading1-surface-area" />

</xf:input> (...)</body>

3.1.7. WebForm actionsThe web form communicates with WebForms service through the Chiba processor using AJAX technology and web form author shouldn't take care of these actions. There are also some WebForms service specific custom actions that can be executed through


WebQServlet request. For example, if the web form author wants that a button should open an envelope, then the trigger should call WebQServlet with mode=envelope parameter. WebQServlet can be called with the following parameters:

1. ?mode=save – use it inside <f:submission src=““> on post call. Saves the XML file into envelope

2. ?mode=finish – use it inside <f:submission src=““> on post call. Saves the XML file into envelope and opens the envelope page

3. ?mode=opensave – use it inside <f:load resource=““>. Loads the envelope page after finishing the filling out the web form.

4. mode=envelope – opens a CDR envelope

5. mode=feedback – opens the file feedback from CDR

3.2. Create a new WebForm for XML defined in Data Dictionary

3.2.1. Get draft WebForm from Data DictionaryIt’s possible to download a draft web form for each dataset table from the Data Dictionary. The functionality is available for data definers and administrators. Data Dictionary does not create the web form from scratch. First it requests a template form from WebForms Service and then it adds some data into the template. The form is called draft, because it is not usable immediately. It must be checked manually and probably some styling should be done after downloading it. Data Dictionary does the following changes to the template web form for creating the draft web form:

6. Writes all table elements with labels inside <f:repeat id="???"> element in XForms template

7. changes the repeat element id and nodeset attributes to table names

8. adds bind elements for each DD element with data types and constraints

9. adds code lists into select1 elements

10.adds help texts into hints elements e.g.: <f:hint>Definition</f:hint>

11.adds insert elements into addline trigger and set values to empty string for each element. E.g.:

<f:action ev:event="DOMActivate"> .. <f:insert at="count(/dd8:GeneralCharacterisation/dd8:Row)" nodeset="/dd8:GeneralCharacterisation/dd8:Row" position="after"/> <f:insert at="count(???)" nodeset="???" position="after"/> <f:setvalue f:ref="/dd8:GeneralCharacterisation/dd8:Row[index('i1')]/dd37:EWN-Code"/> - i1 = repeat id <f:setvalue f:ref="/dd8:GeneralCharacterisation/dd8:Row[index('i1')]/dd37:Name"/> ... </f:action>


3.2.2. Revise the draft WebFormIf the draft web form has been downloaded from Data Dictionary, then it should be manually revised and changed if needed. The created web form can be tested after uploading it into the WebForms repository.

This chapter lists some changes that have been done to the draft web form for making it more usable after downloading it from Data Dictionary.

1. Some specific constraints can be added into the bind elements in the situations, where one field depends on another. For example the rule, where the field should be filled only when the previous field has ’yes’ value, can be implemented with the following constraint:

<f:bind id="selected_water_abstraction_purpose" type="string" nodeset="instance('selected')/dd8:Row/dd37:water_abstraction_purpose" constraint="(string-length(.)>=0 and string-length(.)<=64 and string(../dd37:water_abstraction) = 'yes') or (string-length(.)=0 and string(../dd37:water_abstraction) != 'yes')"/>

2. If hints or labels have strange characters, then these should be escaped.

3. New triggers (buttons) can be added to the web forms for setting field values. E.g.<f:label>Restore line</f:label> <f:action ev:event="DOMActivate">

<f:setvalue f:ref="/dd8:GeneralCharacterisation/dd8:Row[index('i1')]/@status" value="xforms:IF(/dd8:GeneralCharacterisation/dd8:Row[index('i1')]/@status='deleted','valid',/dd8:GeneralCharacterisation/dd8:Row[index('i1')]/@status)"/> </f:action>

4. The default view of the data is like a huge table. For the groundwater bodies web forms example 2 pages approach were implemented. It can be done with <f:switch> and <f:case> elements, where one case is only showed at the moment. The data is transformed between pages with helper instance and setvalue elements.

5. New styles can be written into the header of the form between style tags.

6. New CSS stylesheets and images files can be referenced in XForms. The files should be uploaded also into the repository.

3.2.3. Empty instance fileWebForms service knows the location of all Data Dictionary instance files. If the service gets a request without instance file parameter, then it resolves the XML Schema URL and extracts the dataset table identifier from it. The service passes the DD empty instance file URL for web form. Consequently you don't have to use magic described in chapter 3.2.3. Empty instance file, but just use the ordinary instance declaration:

<xf:instance id="default" src="{$instance}"/>

3.2.4. Data Dictionary code listsAll the code lists defined in Data Dictionary are available in XML format. The XML can be used on WebForm for displaying the code list in selections or in help texts. The XML is accessible from the following URL:


http://instanceURL/

http://dd.eionet.europa.eu/CodelistServlet?id= 6585 &type=TBL&format=xml

You only have to use the correct dataset table identifier instead of red—coloured identifier.

3.2.5. Data Dictionary template WebFormData Dictionary gets the template XForm from the WebForms repository. The form is saved with an abstract XML Schema reference – http://dd.eionet.europa.eu. There should be always one default web form available for that schema. Otherwise Data Dictionary is not able to create the draft web form for the dataset table. But the template can be improved by administrators for this service. Even if some changes are done, some basic things should remain the same in the template file, because DD parses the file and searching predefined tags for inserting data. For example, there should be:

• <f:model> - DD adds bind and instance data here

• <f:repeat id="???" appearance="compact" nodeset="???"> - DD adds fields here

• <f:insert at="xforms:index('???')" nodeset="Row" position="after" /> - DD adds fields to be inserted here

Data Dictionary downloads the template web form from the following URL: http://webq.eionet.europa.eu/GetXFormTemplate

3.3. WebForms Tips & Tricks

3.3.1. How to add an HTML editing field into webformIf your webform needs a feature, where user can format inserted text using bold, italic, headings etc., then just create a <f:textarea> control with f:mediatype='text/html' attribute. For example:

<f:textarea ref=”text” f:mediatype='text/html'><f:label>This is HTML editing field</f:label>

</f:textarea>

Then the textarea control is converted into HTML editing field in the user interface. Users can use the feature only if their browser JavaScript is turned on. The formatting data is stored as escaped HTML elements in the instance XML file. When converting the instance XML file back to HTML with XSL transformation, then don't forget to use disable-output-escaping="yes" attribute in <xsl:value-of ...> element, then the HTML uses the user defined formatting.

Chiba uses FCKeditor 2.3 for displaying HTML editor fields. (http://www.fckeditor.net)

3.3.2. How to split webforms for editing large XML instance filesLarge XML instance file may cause scalability and performance problems. If there are several repeat elements or HTML editing textareas on the form, then the loading time of


http://www.fckeditor.net/

http://webq.eionet.europa.eu/GetXFormTemplate

http://webq.eionet.europa.eu/GetXFormTemplate

http://dd.eionet.europa.eu/CodelistServlet?id=6585&type=TBL&format=xml



the webform might be very long. The problem is deeper in Internet Explorer, where javascript loads all the HTML elements at form start-up and the browser may hang up for several seconds. The first solution for overcome the problem would be to split the form elements with XForms switch and case elements. This allows to lessen the number of elements displayed for the user at the time and allows to divide the form into different tabs or wizard pages. But this solution doesn't help much, because even though the elements from non-active xforms:case are hidden for user, the javascript loads all the elements at start-up.

There is a solution in WebQ for splitting up the large webform into several smaller webforms for editing different parts of the same XML instance file. It's possible to upload several webforms for one type of XML file. When changing the forms from xform, it's needed to save the changes made to instance XML file. WebQ allows to store the XML file temporarily in WebQ tmp folder, when submitting the XML file into following URL “WebQServlet?mode=savetmp”. Then the changes made in one webform are not lost and it's not needed to store the changes directly into real repository. After storing the xml in WebQ, then it's possible to load a new form by changing the form URL in request parameters. Use “WebQServlet?mode=changeform&form=new_form.xhtml” URL for loading the new form. Do not forget instance_id parameters in both calls. Read the following code examples for getting better understanding about changing the webforms.

The following code example contains the submission definition that sends the default XML instance file into WebQ system for storing the file into tmp folder.



<f:submission id="savetmp" action="{$base_uri}WebQServlet?mode=savetmp&instance_id={$instance_id}" method="post" replace="none" encoding="UTF-8" validate="false"/>

The following code example contains xforms:trigger definition that calls “savetmp” submission and after that loads a different form from WebQ.

<f:trigger id="tr_changeform"><f:label>Go to Next page</f:label><f:action ev:event="DOMActivate">

<f:send submission="savetmp" name="xforms-submit" /><f:load resource="{$base_uri}WebQServlet?

mode=changeform&form=/xforms/waste-policies-factsheet2.xhtml&instance_id={$instance_id}" show="replace" />

</f:action></f:trigger>

When the instance file is stored temporarily in WebQ, then the instance parameters in request URL should change to following “instance=tmp/tmp-webq-.......xml”

3.3.3. How to use context parameters on webformsThere is a set of useful context parameters that can be used on webforms. The parameters are:

instance - URL of the default instance XML file. It can be empty.

envelope – it is calculated from the instance file URL, if CDR doesn't send envelope parameter in request URL

file_id – if there is no XML file yet in the envelope, then CDR sends the name of the new file eg. file.xml

instance_id - envelope URL + file_id

web-feedback - shows whether there are any feedback available in repository

form - the name of the XForm with the folder name under public dir. Eg: xfomrs/xform.xhtml

If the client application sends additional parameters through request URL to WebQ, then all these parameters are passed into the Chiba's context and they are available on webforms.

The request URL sent by CDR with the additional parameters looks like this:

http://webq.eionet.europa.eu/WebQMenu?language=En&envelope=http://cdrtest.eionet.europa.eu/ee/eea/colrzmhia/envrzmhng&schema=http://biodiversity.eionet.europa.eu/schemas/bernconvention/derogations.xsd&country=EE&add=true&file_id=derogations.xml

There are 2 ways how to use these parameters on webforms.

Using context parameters in XPath The parameters are available in XPath statements through the following construction: “chiba:context('country')”. This refers to the country parameter sent by request URL and stored in Chiba's context. Since the parameters are read-only, it's not possible to refer them in “ref” or “nodeset” attributes directly. It's only possible to get the value, when calculating some instance elements or displaying them on webform.

Example1 - displays the country parameter on webform:<f:output value="chiba:context('country')">

<f:label>Country:</f:label></f:output>Example2 - stores the country parameter value in default instance element, if it is not filled already. This event happens when the webform is loaded.<f:action ev:event="xforms-ready">

<f:setvalue ref="/derogations/@country" value="if(string-length(/derogations/@country) > 0,/derogations/@country,chiba:context('country'))" />

</f:action>


Example3 – uses context parameter in calculate attribute.

<f:bind id="b-country-name" nodeset="country_name" calculate="if(chiba:context('country')='EE','Estonia','Some other country')"/>

Parameterizing instance URIsWith the help of context properties, URIs can be dynamically reading parameters from Chiba's context. For example in your form you might write something like:

<f:instance src=”http://myhost/path?param1={$key1}&param2={$key2}” />

Of course this is not a valid URI and would throw an MalformedURIException if used with the Connector directly. So before the URI is resolved, all expressions enclosed in curly brackets are substituted with the values from the Context. If we assume 'key1' to be 'value1' and 'key2' to be 'value2' for the above example the resulting URI would be

<f:instance src=”http://myhost/path?param1=value1&param2=value2” />

The same scheme is available also in other XForms elements where the URIs are resolved. Eg. in <f:submission action="{$envelope} ... "/>, <f:load resource="{$envelope} ... "/>

>

3.3.4. How to store the instance file into several XML filesIt is possible to store the instance file into several xml files in the same action. You should send several submissions from the same action to achieve this. Each submission have a response and it's possible to catch the submission results with ev:event="xforms-submit-done" and ev:event="xforms-submit-error" events.

For example, if you want to store the default instance file with “restrict from public view” flag and generate the public view of the default instance with confidential data stripped out at the same time, then use the following constructions:

The following example sends save_confidential submission at first, using restricted=true parameter, that flags the file to be restricted from public view.

The next step is to send save_public submission. This submission stores the instance data into file called questionnaire_public.xml, after the data is converted into suitable format with public.xsl.<xf:model>

<xf:instance id="default" src="{$instance}"/>  <f:submission id="save_confidential" action="{$base_uri}WebQServlet?mode=save&instance_id={$instance_id}&restricted=true" method="post" replace="instance" encoding="UTF-8" instance="saveresult" validate="false">


http://instanceURL/

<f:message ev:event="xforms-submit-done" ref="instance('saveresult')/message" /> <f:message ev:event="xforms-submit-error">Error on saving data!</f:message> </f:submission>  <f:submission id="save_public" action="{$base_uri}WebQServlet?mode=savexml&instance_id={$instance_id}&file_name=questionnaire_public.xml&xsl=public.xsl&title=Generated%20automatically&restricted=false" method="post" replace="instance" encoding="UTF-8" instance="saveresult" validate="false">

 <f:message ev:event="xforms-submit-error">Error on saving public file!</f:message> </f:submission>

...

</f:model><body>...

<f:trigger id="tr_save_confidential"> <f:label>Save</f:label> <f:hint>Saves the current status of the confidential file into the CDR envelope, without moving away from the web form</f:hint> <f:action ev:event="DOMActivate"> <f:send submission="save_confidential" name="xforms-submit"/> <f:send submission="save_public" name="xforms-submit"/> </f:action> </f:trigger>...</body>

3.4. WebForms limitations

Before implementing webforms for the new dataflow, user should be aware about some limitations when using webforms.

The main limitation about using webforms is the amount of data processed on a form. If the size of the resulting XML file is several MegaBytes, then it is definitely not a case of using webforms. The webforms are more suitable for questionnaire type of dataflows, where the resulting XML file contains the simple answers for the given questions. It is rather easy to implement pagination and dependent questions on webforms and it is possible to use rich-text formatting in the answers. If the dataflow contains a table-like structure ant the table contains more than some hundreds rows, then it is not suggested to use webforms because of performance issues. In that case the special spreadsheet software can be used for reporting data eg. MS Excel, OpenOffice Calc, MS Access.

Another limitation is that it is not possible to implement complex navigation flow between the webforms. The navigation between the webforms is implemented at CDR side and it means that only one XML file can be created/edited on one web form.

Web forms does not auto-save the data into CDR envelope. The XML file is only saved, when the save action is submitted. Web forms author should take care about the saving events as needed. Usually there is “Save” button on the page.

3.5. XForms references

http://www.w3.org/TR/xforms/ - XForms 1.0 W3C Recommendation

http://www.xml.com/pub/a/2001/09/05/xforms.html - What are XForms? By Micah Dubinko

http://www.w3schools.com/xforms/default.asp - XForms Tutorial by w3schools

http://xformsinstitute.com/essentials/browse/book.php - XForms Essentials

http://chiba.sourceforge.net/ - Server-side XForms processor

http://www.formsplayer.com/ - Internet Explorer plug-in for viewing XForms

3.6. Add new WebForm to repository

If a new web form is successfully created, then it’s time to upload it into the repository and view the page in a web browser. User should have access rights and update privileges in the repository. Functions for data managers and administrators will become visible if they log in using the Login button on the left pane of WeForms repository.

There is ‘Add WebForm’ blue button on the right side of the work area both on the opening page and on the XML Schema web forms page. After clicking the button a new page with file upload possibilities is available. If the user came from the XML Schema page, then the first 2 fields are already filled. After filling in the properties of the web form click on the save button. The detailed description about the web form properties can be found from thenext chapter.

If upload went successfully, then the user is directed into the XML Schema web forms page. It’s possible to delete the web form by clicking at the red ‘x’ button at the end of the table row.


http://www.formsplayer.com/

http://chiba.sourceforge.net/

http://xformsinstitute.com/essentials/browse/book.php

http://www.w3schools.com/xforms/default.asp

http://www.xml.com/pub/a/2001/09/05/xforms.html

http://www.w3.org/TR/xforms/

Illustration 5: Add WebForm screenshot

3.7. WebForm properties

Edit web form page is very similar to the adding page. The difference is that the input fields are already filled with previously inserted data. WebForm has the following properties:

– XML Schema title – title of the XML Schema eg. “VOC Solvents direcrtive”

– WebForm title – title of the selected web form eg. “VOC Solvents direcrtive Form 1”

– WebForm file – the web form file uploaded into the repository. The file name should be unique in the repository. If a new file is uploaded into repository, then a local copy from the original is stored in backup folder and the new file gets the same file name as original.

– Set as default – one XML schema can have several web forms assigned, but only one of them can be default. Default web form is opened when user selects to edit data with web forms on CDR envelope page. If the form does not have default property, then they can opened from the default web form or they are inserted only for testing purposes.

– AJAX off – the checkbox allows to turn the Javascript feature off on the forms. It is useful to turn AJAX off, when the Javascript causes serious performance issues on the form. If the form does not use AJAX, then all the server requests are synchronous – SUBMIT sends the form to the server and the client has to wait for the response before continuing to fill the form.

– Description – detailed information about the web form (optional).


It’s possible to test the inserted web form on the edit page. The testing functionality has been described already under the read-functionality chapters.

Illustration 6: Edit WebForm properties screenshot

3.8. WebForms file history

WebForms repository keeps the backups of all XForms and XML files. When uploading a new file to repository a local copy is made from the original file. The backup file is stored in the “backup” directory under the xforms directory. The backup file name starts with the “bup_ID” predicate where the ID is the unique database identifier of XForms file. The long number in the file name represents the number of milliseconds counted from 1970 to the time when the backup was made. The file name, timestamp and user name is stored in the database table. Old backups can be purged on the Configuration page.


Illustration 7: Webforms file history

3.9. Add images and styles to WebForms

The user may want to use additional CSS stylesheets and images in web forms. For those purposes it’s possible to upload stylesheets and images into the repository. There are ‘Styles’ and ‘Images’ buttons under the administration menu in the left side. The page mirrors one of the file directories from the system. The directory is available over the Internet. ‘Add style’ and ‘Add image’ buttons allow file uploading into these directories. ‘x’ button at the end of each row deletes the file from the system. The main table of the file repository page displays the file name, link to the source and last modified time.

CSS Stylesheets will be stored into /styles directory and images will be stored into /images directory. The web forms files are stored under /xforms directory under webapps. It means that, if the user wants to use uploaded images or stylesheets, then these files can be referenced relatively as follows:

<img src=”../images/image_name.gif”/>

<link rel="stylesheet" type="text/css" href="../styles/stylesheet_name.css"/>


Illustration 8: CSS Stylesheet files repository screenshot

3.10.XML Files management

Since XForms may use several “helper” XML files when rendering the form, then the WebForms Service offers possibility to store the remote XML files locally to lessen the internet traffic. The locally stored XML files can be code-lists, translations for labels, instance files etc.

3.10.1.Add an XML file

The Administrator of WebForms Service may upload a new XML file.

In order to upload an XML file the user must be logged in as administrator.

If you have administrator privileges, then the following steps must be followed:

STEP 1 – Login

If you are not already logged in, then log in.

STEP 2 – Click on “XML Files” button on the navigation bar.

Arrive at the Uploaded XML files section. The user may view the list of existing uploaded XML files.


llustration 9: Uploaded XML Files screen shot

STEP 3 – Click on “Add XML File” button

Clicking on the “Add XML File” button will take the user on the create XML file menu.

STEP 4 – Fill-in required values.

In order for the XML file to be successfully created, all fields must be properly filled-in. Namely, the Administrator must browse to the file of the XML File to be uploaded and then specify a description for it. The file will get the URL of the converter site plus /xmlfile/ plus filename. File name is an unique field in the system. It means that two different XML files can't have the same name.


llustration 10: XML File addition screen shot

STEP 5 – Finalize upload.

After filling-in all required values the administrator must press the “Upload” button in order for the new XML file to be successfully created.

So, in summary:

Step Add new XML File1 Login2 Click on “XML Files” icon3 Click on “Add XML File” button4 Fill-in required values5 Finalize upload

3.10.2.Delete XML File

In order to delete an XML file the user must be logged in as Administrator.

If the user has administrator privileges, then the following steps must be followed:

STEP 1 – Login


STEP 2 – Click on “XML File” button on the navigation bar.


Arriving at the Uploaded XML files section, the user may view the list of existing file (llustration 11: Delete XML file confirmation prompt).

STEP 3 – Click the (Delete XML file) icon.

You may select which XML file to delete by clicking the delete XML file icon. This icon is located at the leftmost column of the files list

STEP 4 – Confirm XML file's Deletion

For safety reasons, the user receives a confirmation prompt for the delete XML file action. If the user confirms, then the file is deleted from the database.

llustration 11: Delete XML file confirmation prompt

So, in summary:

Step Delete an XML File1 Login2 Click on “XML Files” icon3 Click on “Delete XML file” button4 Confirm XML file deletion

3.10.3.Edit XML file

In order to edit a XML file you must be logged in as Administrator.

When uploading a new XML file into repository, then the old file will be stored as a backup in the system. The backups of XML files are stored exactly the same way as for xforms: #3.5.WebForms file history|outline

If the user has administrator privileges, then the following steps must be followed:

STEP 1 – Login


STEP 2 – Click on “XML Files” button on the navigation bar.


Arriving at the XML files section, the user may view the list of uploaded schemas (llustration 12: Edit XML file page screen shot).

STEP 3 – Click on the edit XML file icon for an entry on the list

By clicking on the edit XML file icon “ ” the user arrives at the edit XML file dialogue.

llustration 12: Edit XML file page screen shot

STEP 4 – Edit XML file

The Administrator is only able to change the description for an uploaded XML schema. It's not possible to upload a new XML file here. Use Delete/Add XML file functionality for changing the content of XML file.

STEP 5 – Update XML Files

By pressing the “OK” button, the user accepts the changes on the Description field. The cancel button will call off any changes in case the user decides not to perform the edit operation.

So, in summary:

Step Edit Schema1 Login2 Click on “XML Files” button3 Click on the edit XML file icon for an entry on the list4 Edit XML File


5 Update XML file

3.11.Hosts management

WebForms service is tightly integrated with Data Repository (DR). Users in Data Repository can edit XML files via WebForms service. Saving XML files in Data Repository requires authentication information. Since WebForms service and Data Repository are different applications, the authentication information can be exchanged in 2 different ways:

1. If DR and WebForms service run on the same domain, then Basic Authentication information is sent automatically through user's web browser from CDR to WebFroms service. In that case the applications should have the URLs as following: http://cdr.eionet.europa.eu and http://cdr.eionet.europa.eu/webq/

2. If DR and WebForms service run on different domains, then the authentication info should be stored in WebFroms service Hosts area. In that case WebForms can provide services for more than one DR.

Webforms service uses the stored user account credentials for saving XML file into DR envelope only if user entets into WebForm page through the WebQEdit or WebQMenu links on DR envelope page.

New hosts can be added after clicking “Add new host” button. Host's credentials can be edited when clicking on the Host URL link.

llustration 13: Hosts management screen-shot

3.11.1.Add new host The following properties should be fill in for successfully adding a new host:

• Host URL – Data Repostory URL eg. Http://cdr.eionet.europa.eu


http://cdr.eionet.europa.eu/

http://cdr.eionet.europa.eu/webq/

http://cdr.eionet.europa.eu/

• Host name – Data Repository name

• User name – user name that has privileges to save XML files into DR's envelope

• Password – user account password

llustration 14: Add new host credentials screen-shot

3.12.Purge backups history

WebForms service stores the history of all uploaded XForms and XML files. The backup files are stored in the “backup” directory under the “xforms” and “xml” directories. Backup filenames are generated to be bup_<ID>_<timestamp>.xhtml, where ID is the database identifier of xml or xforms and timestamp is the number of seconds since 1970. The data about the backup files is stored also in database table called T_BACKUP.

Old backup files can be purged on the system configuration page. Select “Configure“ from left hand menu and it opens the backup files purge page. The administrator can set the number of days to keep the files and click “Purge” button. The action deletes all files and database rows where the backup timestamp is smaller than the timestamp of the date that is today - inserted days.


llustration 15: Purge backup files


4. External system features

4.1. Integrations with CDR (for CDR admins)

The main client of WebForms Service is CDR. These applications communicate with each other over HTTP protocol. This chapter lists all the methods they have to call for filling, opening and saving XML files with WebForms.

There are 2 ways for opening WebForms from CDR envelope – “Deliver with WebForms” and “Edit with WebForms”. These are actually web pages, where the users can make their selections of delivering files and the page checks the user's browser ability to use JavaScript.

4.1.1. Query Web Forms

For knowing which dataflows can be reported with WebForms, CDR is calling “WebQService.getXForm()” method using XML-RPC. The method returns all the available XForms in WebForms repository. Now CDR knows where to show the links to WebQ service. The detailed description of XML-RPC method can be found from chapter 4.3. XML-RPC Methods

4.1.2.Deliver with WebForms

“Deliver with WebForms” page is like a menu, where all the files from the envelope and corresponding web forms are displayed. User can select the XML file and start to edit it or to start to fill out a new form. If there is only one action available in the menu and browser has Javascript turned on, then the user is automatically redirected to the webform. In most of the cases ordinary users don't see this page unless Javascript is turned off or they can do several selections – eg. edit more than one XML file.

To call “Deliver with WebForms” page from CDR envelope, then there should be a link to http://webq.eionet.europa.eu/WebQMenu with the following parameters:

– envelope (required) – URL of the CDR envelope

– schema (optional) – displays only the links to XML files with the given XML Schema

– language (optional) – default language code used on the web form in case the web form is multilingual and the language is available.

– JavaScript (optional) – boolean (true/false). Client browser is able to use Javascript or not. If not specified, the WebQMenu page detects the Javascript ability automatically.

– add (optional) – boolean (true /false). If the value is true, then web page displays the links for starting to fill out a new file.

– file_id (optional) – file name for the new file stored in the envelope. If not specified and new file is stored in the envelope, then CDR generates a name for the new file.

It's possible to send also custom parameters that can be used on web forms.

Example of WebQMenu request URL:


http://webq.eionet.europa.eu/WebQMenu

http://webq.eionet.europa.eu/WebQMenu?language=En&envelope=http://cdrtest.eionet.europa.eu/ee/eea/colrzmhia/envrzmhng

llustration 16: Deliver with WebForms screenshot

4.1.3.Edit with WebForms

“Edit with WebForms” page is quite similar to the menu page, but allowing only one file to be edited. The selection of the file has been done already in the envelope. If a web form is available for the given XML file and user's browser has Javascript turned on, then the user is automatically redirected to the webform. In most of the cases ordinary users don't see this page unless Javascript is turned off.

To call “Edit with WebForms” page from CDR envelope, then there should be a link to http://webq.eionet.europa.eu/WebQEdit with the following parameters:

– instance (required) – URL of the XML file stored in the CDR envelope

– schema (required) – XML Schema of the instance file. The parameter value is used for searching available web forms stored in the repository.

– instance_title (optional) – title of the XML file.

– language (optional) – default language code used on the web form in case the web form is multilingual and the language is available.

– JavaScript (optional) – boolean (true/false). Client browser is able to use Javascript or not. If not specified, the WebQMenu page detects the Javascript ability automatically.

It's possible to send also custom parameters that can be used on web forms.

Example of WebQEdit request URL:


http://webq.eionet.europa.eu/WebQEdit

http://cdrtest.eionet.europa.eu/webq/WebQEdit?language=En&schema=http%3A//air-climate.eionet.europa.eu/schemas/AirQualityQuestionnaire/AirQualityQuestionnaire-form2.xsd&instance=http%3A//cdrtest.eionet.europa.eu/ee/eu/aqq/envszrq7q/aqq_form2.xml&instance_title=Delimination%20of%20zones%20and%20agglomerations

llustration 17: Edit XML file with WebForms screenshot

4.1.4.Create new file with WebForms

If there is no XML file stored in the envelope yet, then CDR should call WebQMenu page with the following required parameters:

– envelope (required) – URL of the CDR envelope

– schema (required) – XML Schema for the new XML file. The parameter value is used for searching available web forms stored in the repository.

– add (required) = true

– file_id (optional) – file name for the new file stored in the envelope. If not specified and new file is stored in the envelope, then CDR generates a name for the new file.

If the web form is available for the given type of XML file and Javascript is turned on, then the empty web form is opened automatically. A new XML file will be stored in the envelope, when user pushes Save button on the web form.

It is possible to send also custom parameters that can be used on web forms.

The request URL for creating a new XML file sent by CDR looks like this:

http://webq.eionet.europa.eu/WebQMenu?envelope=http://cdrtest.eionet.europa.eu/ee/eea/colrzmhia/envrzmhng&schema=http://biodiversity.eionet.europa.eu/schemas/bernconvention/derogations.xsd&add=true&file_id=derogations.xml


4.2. Integrations with Data Dictionary

If user (Data definer) wants to create a new WebForm for a dataflow table, then he/she can get some help from Data Dictionary. With data definer rights, it’s possible to generate WebForms from Data Dictionary with data defined in DD. DD is downloading the XForm template from XForms repository, pareses it, adds field definitions to the XForms and returns the file to the user. The exact steps, how the system creates the XForms are following:

1. The XForm template should be stored in the WebForms repository and related with the Schema: http://dd.eionet.eu.int

2. User calls DD servlet http://dd.eionet.eu.int/GetXForm?id=2551

3. DD is calling getXFormTemplate servlet with HTTP GET from WebQ (http://cdr-ewn.eionet.eu.int/webq/GetXFormTemplate).

4. WebQ is searching the template from the repository and returns it to the DD

5. DD is parsing the template and adding data instance reference, bindings, controls and modifying buttons. After that it returns the result to user.

6. User modifies the XForm, because probably it doesn’t look very nice and uploads the new XForm to the repository. It’s possible to test the form also in the repository. Now the WebForm is operational.

WebForms service is using DD XML instance file each time the XForm is used with an empty instance file. The instance file reference has been placed into the XForm by DD and it seems like: http://dd.eionet.eu.int/GetXmlInstance?id=2551 . If the user opens XForm with already filled XML file, then the DD instance is not used.

The automatic versioning of XForms is not implemented yet. If something is changed in DD, then these changes should be made manually in the XForm. This task can be one of the future developments.

4.3. XML-RPC Methods

Information of WEBQ can be retrieved by using XML-RPC The XML-RCP and SOAP router URL is http://cdr.eionet.europa.eu/webq/RpcRouter and the service is called WebQService.

At the moment there are these methods available:

getXForms(xmlSchema)Name: getXForms(xmlSchema)Parameters: ARRAY

Return type: STRUCT

Description: This method finds all the available web forms for specified XML Schemas.

Detailed description: This method finds all the available web forms for specified XML Schemas. If no parameter has passed, then all the web-forms will be returned with


http://dd.eionet.eu.int/GetXmlInstance?id=2551

http://cdr-ewn.eionet.eu.int/webq/GetXFormTemplate

http://dd.eionet.eu.int/GetXForm?id=2551

http://dd.eionet.eu.int/

corresponding XML Schemas. CDR is calling that function for knowing, whether the dataflows have web forms available or not.

The parameter of the method is an array with XML Schema URLs. And it returns a STRUCT that contains the the following fields:

key - XML Schema URLvalue - default web form name

Example: getXForm([“http://dd.eionet.europa.eu/GetSchema?id=TBL2551”]) returns the following result:

{'http://dd.eionet.eu.int/GetSchema?id=TBL2551': 'Instance2551.xml'}


webforms service user manual

Documents