Quick start guide for preparing the X-Road XForms complex service Version 2.0

Transcription

1 Quick start guide for preparing the X-Road XForms complex service Version 2.0

2 1. Table of contents 1. Table of contents Introduction XForms History Advantages and disadvantages XForms function and what does it consist of XForms model XForms user interface Container XPath Let us get to know the code Example 1 Welcome Example 2 Hello World Example 3 Selection list Example 4 Input form Necessary XForms elements of the X-Road service Necessary XForms elements of the X-Road service Model Necessary XForms elements of the X-Road service User interface Simple services in MISP Complex services in MISP Adding a complex collection Ways to develop the service Service development Link for switching to the other service Changing the button logic Result...26 Annex I complex service XForms...27 Annex II Persons list query Xforms...32 Annex III Person details query XForms

3 2. Introduction The aim of this guide is to give a brief overview of how to create a complex service from two simple services. The service can be used in MISP2. We will look at some simpler XForms forms and the important XForms elements of the simple service beforehand to get to know the semantics of the language. The guide is meant for developers who are developing the X-Road service in the MISP2 application. MISP2 uses an X-Road request presentation based on XForms technology. XForms is a form description language, an offspring of HTML forms in XHTML

4 3. XForms XForms is a text-formatting language used to collect input data from web forms. XForms uses XML for data definition and HTML or XHTML for data display. XForms separates the logic of data from its presentation. This way, the data is defined on its own, independently from the user s activity. 3.1 History XForms 1.0 (Third Edition) was released on 29 October The original XForms specification became an official W3C Recommendation on 14 October The version 1.1, which introduced a number of improvements, reached the same status on 20 October The latest XForms version is 2.0 (as at 25 September 2017) 3.2 Advantages and disadvantages Advantages of XForms Model-View-Controller (MVC) architecture Declarative programming easier to learn, maintain, debug The user interface has many options for solving complex issues (e.g. dates, numbers, and ranges) Compatibility with other XML standards (CSS, CML, Schema, XPath) Less Javascript Localization Disadvantages of XForms Low browser support Slow with large forms o Large = fields Few supporting materials 3.3 XForms function and what does it consist of The goal of XForms is to collect data in forms. In order to use XForms, the XForms elements have to be declared with the namespace xmlns:xforms=" XForms framework is divided into two parts: XForms model XForms user interface 4

5 3.3.1 XForms model XForms model is used for describe data. The data template is an XML document. <xforms:model> <xforms:instance xmlns=""> <person> <fname/> <lname/> </person> <xforms:submission id="form1" action="submit.asp" method="get"/> </xforms:model> In the example above, we define inside the <instance> element our XML template for data to be collected and in the <submission> element, we describe how to submit the data. Inside the Submission, we establish the request identifier (id="form1"), the URL to where we submit data (action="submit.asp") and the method that we use to submit data (method="get"). If our XML template looks initally like this: <person> <fname/> <lname/> </person> Then after collecting data it could look like this: <person> <fname>john</fname> <lname>smith</lname> </person> XForms user interface XForms user interface is used to display and input data. The user interface elements of XForms are called controls (input controls). <xforms:input ref="fname"> <xforms:label>first Name</xforms:label> </xforms:input> <xforms:input ref="lname"> <xforms:label>last Name</xforms:label> </xforms:input> <xforms:submit submission="form1"> <xforms:label>submit</xforms:label> </xforms:submit> Here, we use two <input> elements to collect input data. Attributes ref= fname and ref= lname point to the <fname/> and <lname/> elements of our data structure. In the <Submit> control, the submission= form1 attribute refers to the <submission> element in the XForms model. A submit element is usually displayed as a button. With XForms, every input control has a required <label> element. 5

6 3.3.3 Container As the XForms document does not exist, we have to move it inside another XML document, e.g. XHTML. <html xmlns=" xmlns:xforms=" <head> <xforms:model> <xforms:instance xmlns=""> <person> <fname/> <lname/> </person> <xforms:submission id="form1" action="submit.asp" method="get"/> </xforms:model> </head> <body> <xforms:input ref="fname"> <xforms:label>first Name</xforms:label> </xforms:input> <xforms:input ref="lname"> <xforms:label>last Name</xforms:label> </xforms:input> <xforms:submit submission="form1"> <xforms:label>submit</xforms:label> </xforms:submit> </body> </html> Visually it looks like this: Figure1 XForms example Additional information about the XForms model and the user interface controls can be found on:

7 3.4 XPath XPath is a W3C standard syntax for defining parts of XML documents. XPath uses path expressions to identify nodes in an XML document. This XPath expression: /person/fname addresses the fname node in the XML document: <person> <fname>hege</fname> <lname>refsnes</lname> </person> Additional information about XPath functions can be found on the following link: Let us get to know the code Example 1 Welcome <?xml version="1.0" encoding="utf-8"?> <html xmlns=" xmlns:xforms=" <head> <xforms:model> <xforms:instance xmlns=""> <person xmlns=""> <givenname /> </person> </xforms:model> </head> <body> <h1>hello</h1> <p> <xforms:input ref="/person/givenname" incremental="true"> <xforms:label xml:lang="et">sisestage oma nimi: </xforms:label> <xforms:label xml:lang="en">enter your name: </xforms:label> </xforms:input> </p> <p> <xforms:output value="if (normalize-space(/person/givenname) = '') then '' else concat('hello ', /person/givenname, '!')" /> </p> </body> </html> Form overview: The file begins with an XML declaration that can be excluded. 7

8 Then follows an <html> tag with the namespaces used in the file. <head> content differs from regular HTML code, as we define the model (<xforms:model>) where we can create our XForms data structure (<xforms:instance>) whose content is an XML object. <body> section shows both the HTML code and the XForms user interface controls. It begins with a heading, which is inside a regular <h1> tag, as the default namespace of the file is the XHTML namespace. Inside the <p> tag you can see the <xforms:input> control, which we can use to set the value of the respective XML node (XPath) determined in the ref attribute. Attribute incremental= true determines the automatic update of a value. <xforms:label> is similar to the HTML <label> element, which can be used to display explanatory text in front of the input. In the second paragraph, we will display, using an output, a <xforms:output> control, whose value attribute is also XPath. A condition has been added that if the XPath value is empty or the input is blank, the response will not be displayed. Otherwise, Hello {input}! will be displayed. Figure2 Hello Example 2 Hello World <?xml version="1.0" encoding="utf-8"?> <html xmlns=" xmlns:xforms=" xmlns:events=" <head> <xforms:model> <xforms:instance xmlns=""> <data xmlns="" /> </xforms:model> </head> <body> <h1>hello World</h1> <p> <xforms:trigger> <xforms:label xml:lang="et">nupp</xforms:label> <xforms:label xml:lang="en">button</xforms:label> <xforms:hint xml:lang="et">seda nuppu vajutades ilmub teade.</xforms:hint> <xforms:hint xml:lang="en">a message will be displayed when clicking this button.</xforms:hint> <xforms:message level="modal" events:event="domactivate">hello World!</xforms:message> </xforms:trigger> </p> </body> </html> 8

9 Form overview: In comparison to the previous form, we notice one difference a new namespace events has been added. With Event commands we can control the form s activity regarding the trigger time of a command. In the <body> tag, we create a new button by using the <xforms:trigger> control, in which we add three controls. o <xforms:label> we give the button text. o <xforms:hint> while hovering over the button with the cursor, an explanatory text will appear. o <xforms:message> a message that will be displayed after clicking the button. Attribute level= modal gives the message an appearance (the value is the same by default), events:event= DOMActivate triggers the command. If needed, the button can be replaced with a link, which can be done by adding appearance= minimal attribute to the <xforms:trigger> control. Figure3 Hello World 9

10 3.5.3 Example 3 Selection list <?xml version="1.0" encoding="utf-8"?> <html xmlns=" xmlns:xforms=" <head> <xforms:model> <xforms:instance xmlns=""> <data> <selectedelement /> </data> </xforms:model> </head> <body> <h1>selection</h1> <p> <xforms:select1 ref="selectedelement"> <xforms:label xml:lang="et">valikuloend:</xforms:label> <xforms:label xml:lang="en">selection:</xforms:label> <xforms:item> <xforms:label xml:lang="et">esimene</xforms:label> <xforms:label xml:lang="en">first</xforms:label> <xforms:value>first</xforms:value> </xforms:item> <xforms:item> <xforms:label xml:lang="et">teine</xforms:label> <xforms:label xml:lang="en">second</xforms:label> <xforms:value>second</xforms:value> </xforms:item> <xforms:item> <xforms:label xml:lang="et">kolmas</xforms:label> <xforms:label xml:lang="en">third</xforms:label> <xforms:value>third</xforms:value> </xforms:item> <xforms:item> <xforms:label xml:lang="et">neljas</xforms:label> <xforms:label xml:lang="en">fourth</xforms:label> <xforms:value>fourth</xforms:value> </xforms:item> <xforms:item> <xforms:label xml:lang="et">viies</xforms:label> <xforms:label xml:lang="en">fifth</xforms:label> <xforms:value>fifth</xforms:value> </xforms:item> </xforms:select1> </p> <p> <xforms:output value="selectedelement"> <xforms:label xml:lang="et">valitud: </xforms:label> <xforms:label xml:lang="en">selected: </xforms:label> </p> </body> </html> Form overview: Inside the <head> part, we create a data structure, in which we keep the value currently selected in the selection list. Inside the <body> tag, we create a selection list, <xforms:select1> control, to which we add the ref= selectedelement attribute this saves the selected value of the element. Inside 10

11 the selection list, we define the options, using <xforms:item> control, in which we define its displayed name (<xforms:label>) and value (<xforms:value>). It should be noted that inside the <xforms:output> output, the response is not displayed after the first loading of the form but only after we have made a choice. Figure4 Selection list Example 4 Input form <?xml version="1.0" encoding="utf-8"?> <html xmlns=" xmlns:xforms=" xmlns:events=" <head> <xforms:model> <xforms:instance id="personal-data" xmlns=""> <people> <person> <firstname /> <lastname /> <birthdate /> <contactinfo> <phone /> < /> </contactinfo> </person> </people> <xforms:bind nodeset="instance('personal-data')"> <xforms:bind nodeset="person"> <xforms:bind nodeset="firstname" type="xforms:string" /> <xforms:bind nodeset="lastname" type="xforms:string" /> <xforms:bind nodeset="birthdate" type="xforms:date" /> <xforms:bind nodeset="contactinfo"> <xforms:bind nodeset="phone" type="xforms:integer" /> <xforms:bind nodeset=" " type="xforms:string" /> </xforms:model> <style>.input-w150 input {width:150px!important;}.input-50 input {width:50px!important;} </style> </head> <body> <h1>insertion</h1> <p> <xforms:repeat nodeset="instance('personal-data')/person[position() > 1]" 11

12 id="repeat-list"> <xforms:output ref="firstname"> <xforms:label xml:lang="et">eesnimi</xforms:label> <xforms:label xml:lang="en">first name</xforms:label> <xforms:output ref="lastname"> <xforms:label xml:lang="et">perekonnanimi</xforms:label> <xforms:label xml:lang="en">last name</xforms:label> <xforms:output ref="birthdate"> <xforms:label xml:lang="et">sünniaeg</xforms:label> <xforms:label xml:lang="en">date of birth</xforms:label> <xforms:output ref="contactinfo/phone"> <xforms:label xml:lang="et">telefon</xforms:label> <xforms:label xml:lang="en">telephone</xforms:label> <xforms:output ref="contactinfo/ "> <xforms:label xml:lang="et"> </xforms:label> <xforms:label xml:lang="en"> </xforms:label> </xforms:repeat> <xforms:group ref="instance('personal-data')/person" appearance="compact"> <xforms:input ref="firstname" class="input-w150"> <xforms:label xml:lang="et">eesnimi</xforms:label> <xforms:label xml:lang="en">first name</xforms:label> </xforms:input> <xforms:input ref="lastname" class="input-w150"> <xforms:label xml:lang="et">perekonnanimi</xforms:label> <xforms:label xml:lang="en">last name</xforms:label> </xforms:input> <xforms:input ref="birthdate" class="input-w50"> <xforms:label xml:lang="et">sünniaeg</xforms:label> <xforms:label xml:lang="en">date of birth</xforms:label> </xforms:input> <xforms:input ref="contactinfo/phone" class="input-w150"> <xforms:label xml:lang="et">telefon</xforms:label> <xforms:label xml:lang="en">telephone</xforms:label> </xforms:input> <xforms:input ref="contactinfo/ " class="input-w150"> <xforms:label xml:lang="et"> </xforms:label> <xforms:label xml:lang="en"> </xforms:label> </xforms:input> <xforms:group ref="instance('personal-data')"> <xforms:trigger> <xforms:label xml:lang="et">lisa</xforms:label> <xforms:label xml:lang="en">insert</xforms:label> <xforms:action events:event="domactivate"> <xforms:insert nodeset="person[last()]" at="last()" position="after" /> <xforms:setvalue ref="instance('personaldata')/person[last()]/firstname" value="instance('personal-data')/person/firstname" /> <xforms:setvalue ref="instance('personaldata')/person[last()]/lastname" value="instance('personal-data')/person/lastname" /> <xforms:setvalue ref="instance('personaldata')/person[last()]/birthdate" value="instance('personal-data')/person/birthdate" /> <xforms:setvalue ref="instance('personaldata')/person[last()]/contactinfo/phone" value="instance('personaldata')/person/contactinfo/phone" /> <xforms:setvalue ref="instance('personaldata')/person[last()]/contactinfo/ " value="instance('personaldata')/person/contactinfo/ " /> </xforms:action> </xforms:trigger> <xforms:trigger ref=".[count(person) > 1]"> 12

13 <xforms:label xml:lang="et">kustuta</xforms:label> <xforms:label xml:lang="en">delete</xforms:label> <xforms:action events:event="domactivate"> <xforms:delete nodeset="person[last()]" at="last()"/> </xforms:action> </xforms:trigger> </p> </body> </html> Form overview: Inside <xforms:model>, we once again create our data structure, but in addition, we will define our validation rules. It should be noted that the validation rules will be applied only during the (<xforms:submission>) data submission, which we will not do here. You only need to add type= xforms:date to the date for the calender to appear next to that field. In addition, you can see the <style> tag inside the<head> tag. You can also change the style on the XForms forms by using the <style> tag. With this example, we will only change the width of the table s columns. More information about the XForms styling can be found here: here: Inside the <body>, we can see the control <xforms:repeat>, which can be used to go through all the data in the list. Using the nodeset attribute, we determine which list we put in the cycle; in addition, a condition has been set inside the square brackets that we skip the first element (instance('personal-data')/person) (we will use it for the template data). Inside the cycle we will, however, write the data on the display by using <xforms:output> control. This is followed by <xforms:group>, which we use to group our input fields into one table. Attribute appearance= compact gives our table a horizontal formation. We use the <xforms:trigger> control to create the buttons to add and delete rows. Inside it, we have to add control <xforms:action events:event= DOMActivate >, which gives our button the command to do something when the button is clicked. <xforms:insert> control can be used to add data to the list; it is necessary to select three attributes. With Nodeset, we determine the list to which we add data. Attribute at is an index which we use to determine a target; in this case, the last object on the list. Position determines where the data is added to relative to the target. To set the value of the new object, we use the <xforms:setvalue> command with whose ref attribute we set the location where the value is saved, and we use value to set value. As we use the first object of the list as a template, it is therefore a value and the last object of the list is where we save. Last, we create a new button and give it an ability with the <xforms:delete> control to delete the object at the end of the list. 13

14 Figure 5 Input form 14

15 4. Necessary XForms elements of the X-Road service When you generate an XForms description for the X-Road service via the MISP application, the form will get certain elements via which the data is being exchanged between the input, output, and user interface request controls. To explain the code, we use Persons List query s XForms (aktorstest-db01.persondetails.v1) Necessary XForms elements of the X-Road service Model Inside the <xforms:model> tag, which is inside <xhtml:head>, data structures (<xforms:instance>), validation rules (<xforms:bind>) and queries (<xforms:submission>) are defined. <xforms:instance> data structure, which in the case of X-Road service is XML SOAP. Output data structure is provisional, because in case of a successful request submission, the data structure will be replaced with request responses. In addition to the input and output of services, provisional data structures and classificators can also be created. <xforms:instance id="personlist.input"> <SOAP-ENV:Envelope> <SOAP-ENV:Header> <xrd:protocolversion>4.0</xrd:protocolversion> <xrd:id/> <xrd:userid>ee</xrd:userid> <xrd:service iden:objecttype="service"> <iden:xroadinstance>ee-dev</iden:xroadinstance> <iden:memberclass>com</iden:memberclass> <iden:membercode> </iden:membercode> <iden:subsystemcode>aktorstest-db01</iden:subsystemcode> <iden:servicecode>personlist</iden:servicecode> <iden:serviceversion>v1</iden:serviceversion> </xrd:service> <xrd:client iden:objecttype="subsystem"> <iden:xroadinstance>ee-dev</iden:xroadinstance> <iden:memberclass/> <iden:membercode/> <iden:subsystemcode/> </xrd:client> </SOAP-ENV:Header> <SOAP-ENV:Body> <ns5:personlist xmlns:ns5=" <request> <givenname/> <surname/> </request> </ns5:personlist> </SOAP-ENV:Body> </SOAP-ENV:Envelope> <xforms:instance id="personlist.output"> <dummy/> 15

16 <xforms:bind> validation rules controlled during request submissions. Here we bind our input and output data (nodeset) into certain data types (type). It is also possible to use other attributes in addition to data types. o relevant condition; if it is met, that part will be displayed in your form o required required, data field has to have a value o readonly read-only, the data field value can not be changed o constraint constraint, for setting minimum/maximum value o calculate calculation <xforms:bind nodeset="instance('personlist.input')/soap-env:body"> <xforms:bind nodeset="tns:personlist"> <xforms:bind nodeset="request"> <xforms:bind nodeset="givenname" type="xforms:string"/> <xforms:bind nodeset="surname" type="xforms:string"/> <xforms:bind nodeset="instance('personlist.output')/soap-env:body"> <xforms:bind nodeset="tns:personlistresponse"> <xforms:bind nodeset="response"> <xforms:bind nodeset="faultcode" type="xforms:string"/> <xforms:bind nodeset="faultstring" type="xforms:string"/> <xforms:bind nodeset="person"> <xforms:bind nodeset="givenname" type="xforms:string"/> <xforms:bind nodeset="surname" type="xforms:string"/> <xforms:bind nodeset="ssn" type="xforms:string"/> <xforms:submission> requests. Inside the submission, it is possible to determine the request input data, output data, how they are formatted, and error message processing. o action address where we submit our request. This is not taken into account in the MISP portal, but instead a certain address is used, which is determined by an administrator. o mediatype we determine that our request is application/soap+xml type. o encoding encoding o ref input data o method HTTP method used to transmit the request. o replace we determine what will be done with the output data; in this case, we save them inside instance. o instance Instances where the output data is saved. o <xforms:toggle> determines which (<xforms:case>) view we display after a successful request (xforms-submit-done). o <xforms:message> a message that is displayed after an unsuccessful request. level= modal attribute gives our message an appearance and with the events:event= xforms-submit-error attribute we make sure that it is displayed only if the request is unsuccessful. <xforms:submission id="personlist.submission" action=" mediatype="application/soap+xml; charset=utf-8; action=" 16

17 encoding="utf-8" ref="instance('personlist.input')" method="post" replace="instance" instance="personlist.output"> <xforms:setvalue ref="instance('temp')/relevant" value="false()" events:event="xforms-submit"/> <xforms:setvalue ref="instance('personlist.input')/soap-env:header/*:id" value="digest(string(random()), 'SHA-1', 'hex')" events:event="xforms-submit"/> <xforms:toggle case="personlist.response" events:event="xforms-submitdone"/> <xforms:setvalue ref="instance('temp')/relevant" value="true()" events:event="xforms-submit-done"/> <xforms:setvalue ref="instance('temp')/relevant" value="true()" events:event="xforms-submit-error"/> <xforms:message level="modal" events:event="xforms-submit-error"> <xforms:output xml:lang="et" value="if (event('error-type') = 'submission-in-progress') then 'Üks päring juba käib!' else if (event('error-type') = 'no-data') then 'Pole andmeid, mida saata!' else if (event('error-type') = 'validation-error') then 'Valideerimise viga!' else if (event('error-type') = 'parse-error') then 'Viga vastuse töötlemisel!' else if (event('error-type') = 'resource-error') then 'Päringu vastus ei ole XML!' 'Sihtkoha viga!' else 'Sisemine viga!'"/> <xforms:output xml:lang="en" else if (event('error-type') = 'target-error') then value="if (event('error-type') = 'submission-in-progress') then 'Submission already started!' else if (event('error-type') = 'no-data') then 'No data to submit!' else if (event('error-type') = 'validation-error') then 'Validation error!' else if (event('error-type') = 'parse-error') then 'Error parsing response!' else if (event('error-type') = 'resource-error') then 'Response is not XML!' else if (event('error-type') = 'target-error') then 'Target error!' else 'Internal error!'"/> </xforms:message> </xforms:submission> The <xforms:dispatch> targetid attribute (case id as input) determines which view will be displayed upon first loading. <xforms:dispatch targetid="personlist.request" name="xforms-select" events:event="xforms-ready"/> 17

18 4.1.2 Necessary XForms elements of the X-Road service User interface User interface controls of XForms are inside the <xhtml:body> tag. The previously mentioned views can be determined with<xforms:case> tags that are inside <xforms:switch>. <xforms:switch> <xforms:case id="personlist.request">... </xforms:case> <xforms:case id="personlist.response">... </xforms:case> </xforms:switch> <xforms:group> control can group and optimise elements by using ref attribute whose value is XPath. <xforms:group ref="instance('personlist.input')/soap-env:body"> <xforms:group ref="tns:personlist"> <xforms:group ref="request">... With <xforms:input> we create a field for submitting data. We use ref attribute to determine where the submitted data will be saved. We use <xforms:label> control to display explanatory text in front of the input field. We use xml:lang attribute to define texts with different languages. <xforms:group ref="instance('personlist.input')/soap-env:body"> <xforms:group ref="tns:personlist"> <xforms:group ref="request"> <xforms:input ref="givenname"> <xforms:label xml:lang="en">given name</xforms:label> <xforms:label xml:lang="et">eesnimi</xforms:label> </xforms:input>... We use <xforms:output> control to display data. <xforms:output ref="givenname"> <xforms:label xml:lang="en">given name</xforms:label> <xforms:label xml:lang="et">eesnimi</xforms:label> 18

19 <xforms:repeat> control is used to display data that is located in the list. We use nodeset attribute to set XPath value. We can set its control an id value with Id attribute. <xforms:repeat nodeset="person" id="personlist_output_tns_personlistresponse_response_person"> <xforms:output ref="givenname"> <xforms:label xml:lang="en">given name</xforms:label> <xforms:label xml:lang="et">eesnimi</xforms:label>... </xforms:repeat> We use <xforms:submit> control to create a button for data submission. Request (submission) that we submit is specified in the submission attribute. <xforms:submit submission="personlist.submission"> <xforms:label xml:lang="et">esita päring</xforms:label> <xforms:label xml:lang="en">submit</xforms:label> </xforms:submit> We create a button by using <xforms:trigger> control. We can give the button functionality with events:event= DOMActivate attribute that has to be inside an action type control. As an example we will use <xforms:toggle> control by clicking on the button, we change the view. By giving the case attribute one view (case) id, we can display the respective view. <xforms:trigger> <xforms:label xml:lang="et">uuesti</xforms:label> <xforms:label xml:lang="en">again</xforms:label> <xforms:toggle events:event="domactivate" case="personlist.request"/> </xforms:trigger> 19

20 5. Simple services in MISP2 When creating a new complex service, we use two simple services (aktorstest database, WSDL: The first shows as an output a person s list that contains social security numbers and names (aktorstest-db01.personlist.v1) The other uses a social security number as an input and shows more specific information about the person (aktorstest-db01.persondetails.v1) Let us assume that the simple service forms have already been generated (using either wsdl2xforms command-line script or the standard form generating functionality of the MISP2 application). Complex service development idea is based on realising a switch from one service to another: how to use the output (or part of the output) of the first service as the input of the other. The goal of the developer of a new complex service is to find the places in the XForms descriptions where you have to add these commands to realize the switch. This is described by the following scheme: 20

21 6. Complex services in MISP2 6.1 Adding a complex collection In order to begin creating a new complex service in the MIPS2 application, it is necessary to add a new complex collection. This can be done by a user in the role of a portal administrator or a service administrator under the Menu option Services : On the complex collection management page, you must enter the complex collection name and a description, and click the Save button. Once the complex collection is saved, it must be visible in the complex collection list: By clicking on the complex collection name, we can look at the list of complex services in that database. The list is empty in the case of a new complex collection: 21

22 The button Add new leads to the page with the metadata of the new complex service where you can enter a systematic name, description, and XForms URL of the new service. XForms URL is useful when the XForms description of the service is already created and it can be loaded from the entered URL. Systematic name must be in the format servicename.vx, where X is the version number. Once the new service is saved, it will appear in the service list of the complex collection: 6.2 Ways to develop the service When clicking on the service name, a screen form will appear with the description of the XForms service. This is one way how to develop the service form. The other way is to use your favorite text editor and afterwards, by using XForms URL, load the given description into the application. 6.3 Service development Let us copy the XForms description of the first simple service (aktorstest-db01.personlist.v1) into the form of the new complex service aktorstest-complex.person-complex. The resulting document will look like a regular document with an XML/HTML markup, which contains <xforms:model> and other XForms-specific elements. 22

23 Figure 6 XForms description in a text editor Brief overview of the file: The file begins with an XML declaration. Then follows a <xhtml:html> tag. Next to that tag, all the prefixes of the namespaces used in the file are declared. <xhtml:head> section begins as usual with a <xhtml:title> tag that determines the title of the form. This has been generated based on the service <xtee:title> tag that is included in the WSDL file. The title is followed by <xforms:model> where three main things are defined: Data structures, (<xforms:instance>), validation rules (<xforms:bind>), requests (<xforms:submission>). <xhtml:body> section also begins with a title, which in this case is included inside a <xhtml:h1> tag. This is also generated based on <xtee:title>. Then follows a brief service 23

24 description inside a <xhtml:h1> tag. <xforms:switch> marks the beginning of the request forms. Now, if we save the service form without changing it, we get a regular simple service. In order to get a complex service, you have to copy the following elements from the XForms of the service aktorstest.persondetails.v1: <xforms:instance> (excluding temp with an id, because it is already there) <xforms:bind> <xforms:submission> o All of the aforementioned must be copied under the XForms <xforms:model> of the service aktorstest-complex.isikuandmed.v1. The order is not important. <xforms:case id="persondetails.response"> This goes under the XForms <xforms:switch> of the service. Hence, we get an XForms description that contains content elements necessary for activating the two services. 6.4 Link for switching to the other service Now, a trigger (or, in other words, a button) has to be created under the <xforms:repeat nodeset="person"> element, which could be used to activate the next service from the input of the first one. This has to be created under the element: <xforms:case id="personlist.response">. Before that, you can change the <xforms:repeat nodeset="person"> generated id value that will be hereafter used in the trigger description. In this example, it is person_index(<xforms:repeat nodeset="person" id="person_index">). Trigger code: <xforms:trigger appearance="minimal"> <xforms:label xml:lang="et">detailid</xforms:label> <xforms:label xml:lang="en">details</xforms:label> <xforms:action events:event="domactivate"> <xforms:setvalue ref="instance('persondetails.input')/soap- ENV:Body/tns:personDetails/request/ssn" value="context()/ssn"/> <xforms:send submission="persondetails.submission"/> </xforms:action> </xforms:trigger> Trigger subparts: appearance="minimal" determines that the trigger appears as a link, not a button 24

25 <xforms:label> determines the text shown in the user interface. Two texts have been defined: for Estonian (xml:lang= et ) and English (xml:lang= en ) language. <xforms:setvalue> assigns persondetails service to the SOAP-message input (persondetails.input), a value to the ssn field from this row (meaning the filed that the user selects), from the ssn field (or, in other words, the value of the value attribute) with a button clicking event (event DOMActivate). <xforms:send> sends a SOAP-request, using the xforms:submission 6.5 Changing the button logic It would be good to go back from the response of the second service to the previous list. For this, we change the Back button under <xforms:case id="persondetails.response"> in a way that it would direct back to the previous <xforms:case>. Then we change the trigger under the <xforms:group class= actions > element as follows: For the <xforms:toggle> case attribute we set the value personlist.response We change <xforms:label> texts respectively. The result is the following code: <xforms:group class="actions"> <xforms:trigger> <xforms:label xml:lang="et">tagasi</xforms:label> <xforms:label xml:lang="en">back</xforms:label> <xforms:toggle events:event="domactivate" case="personlist.response"/> </xforms:trigger> 25

26 6.6 Result The result is a complex service which can be used to look at the persons list with names found (form 2) by entering a person s name (form 1) and moving on from there via a link named Details to form 3, where the details of the chosen person are shown. 26

27 Annex I complex service XForms <?xml version="1.0" encoding="utf-8"?> <xhtml:html xmlns:xhtml=" xmlns:xforms=" xmlns:xxforms=" xmlns:events=" xmlns:xsd=" xmlns:xsi=" xmlns:soap-env=" xmlns:soap-enc=" xmlns:xtee=" xmlns:xrd=" xmlns:iden=" xmlns:tns=" <xhtml:head> <xhtml:title xml:lang="en">persons List query</xhtml:title> <xhtml:title xml:lang="et">isikute nimekirja päring</xhtml:title> <xforms:model> <xforms:instance id="personlist.input"> <SOAP-ENV:Envelope> <SOAP-ENV:Header> <xrd:protocolversion>4.0</xrd:protocolversion> <xrd:id/> <xrd:userid>ee</xrd:userid> <xrd:service iden:objecttype="service"> <iden:xroadinstance>ee-dev</iden:xroadinstance> <iden:memberclass>com</iden:memberclass> <iden:membercode> </iden:membercode> <iden:subsystemcode>aktorstest-db01</iden:subsystemcode> <iden:servicecode>personlist</iden:servicecode> <iden:serviceversion>v1</iden:serviceversion> </xrd:service> <xrd:client iden:objecttype="subsystem"> <iden:xroadinstance>ee-dev</iden:xroadinstance> <iden:memberclass/> <iden:membercode/> <iden:subsystemcode/> </xrd:client> </SOAP-ENV:Header> <SOAP-ENV:Body> <ns5:personlist xmlns:ns5=" <request> <givenname/> <surname/> </request> </ns5:personlist> </SOAP-ENV:Body> </SOAP-ENV:Envelope> <xforms:instance id="personlist.output"> <dummy/> <xforms:bind nodeset="instance('personlist.input')/soap-env:body"> <xforms:bind nodeset="tns:personlist"> <xforms:bind nodeset="request"> <xforms:bind nodeset="givenname" type="xforms:string"/> <xforms:bind nodeset="surname" type="xforms:string"/> <xforms:bind nodeset="instance('personlist.output')/soap-env:body"> <xforms:bind nodeset="tns:personlistresponse"> <xforms:bind nodeset="response"> <xforms:bind nodeset="faultcode" type="xforms:string"/> <xforms:bind nodeset="faultstring" type="xforms:string"/> <xforms:bind nodeset="person"> <xforms:bind nodeset="givenname" type="xforms:string"/> <xforms:bind nodeset="surname" type="xforms:string"/> <xforms:bind nodeset="ssn" type="xforms:string"/> <xforms:submission id="personlist.submission" action=" mediatype="application/soap+xml; charset=utf-8; action=" encoding="utf-8" ref="instance('personlist.input')" method="post" replace="instance" 27

28 instance="personlist.output"> <xforms:setvalue ref="instance('temp')/relevant" value="false()" events:event="xforms-submit"/> <xforms:setvalue ref="instance('personlist.input')/soap-env:header/*:id" value="digest(string(random()), 'SHA-1', 'hex')" events:event="xforms-submit"/> <xforms:toggle case="personlist.response" events:event="xforms-submit-done"/> <xforms:setvalue ref="instance('temp')/relevant" value="true()" events:event="xforms-submit-done"/> <xforms:setvalue ref="instance('temp')/relevant" value="true()" events:event="xforms-submit-error"/> <xforms:message level="modal" events:event="xforms-submit-error"> <xforms:output xml:lang="et" value="if (event('error-type') = 'submission-in-progress') then 'Üks päring juba käib!' else if (event('error-type') = 'no-data') then 'Pole andmeid, mida saata!' else if (event('error-type') = 'validation-error') then 'Valideerimise viga!' else if (event('error-type') = 'parse-error') then 'Viga vastuse töötlemisel!' else if (event('error-type') = 'resource-error') then 'Päringu vastus ei ole XML!' else if (event('error-type') = 'target-error') then 'Sihtkoha viga!' else 'Sisemine viga!'"/> <xforms:output xml:lang="en" value="if (event('error-type') = 'submission-in-progress') then 'Submission already started!' else if (event('error-type') = 'no-data') then 'No data to submit!' else if (event('errortype') = 'validation-error') then 'Validation error!' else if (event('error-type') = 'parse-error') then 'Error parsing response!' else if (event('error-type') = 'resource-error') then 'Response is not XML!' else if (event('error-type') = 'target-error') then 'Target error!' else 'Internal error!'"/> </xforms:message> </xforms:submission> <xforms:instance id="temp"> <temp> <relevant xsi:type="boolean">true</relevant> <ssn/> </temp> <xforms:instance id="variables"> <variables> <ssn/> </variables> <xforms:dispatch targetid="personlist.request" name="xforms-select" events:event="xforms-ready"/> <!-- persondetails service starts --> <xforms:instance id="persondetails.input"> <SOAP-ENV:Envelope> <SOAP-ENV:Header> <xrd:protocolversion>4.0</xrd:protocolversion> <xrd:id/> <xrd:userid>ee</xrd:userid> <xrd:service iden:objecttype="service"> <iden:xroadinstance>ee-dev</iden:xroadinstance> <iden:memberclass>com</iden:memberclass> <iden:membercode> </iden:membercode> <iden:subsystemcode>aktorstest-db01</iden:subsystemcode> <iden:servicecode>persondetails</iden:servicecode> <iden:serviceversion>v1</iden:serviceversion> </xrd:service> <xrd:client iden:objecttype="subsystem"> <iden:xroadinstance>ee-dev</iden:xroadinstance> <iden:memberclass/> <iden:membercode/> <iden:subsystemcode/> </xrd:client> </SOAP-ENV:Header> <SOAP-ENV:Body> <ns5:persondetails xmlns:ns5=" <request> <ssn/> </request> </ns5:persondetails> </SOAP-ENV:Body> </SOAP-ENV:Envelope> <xforms:instance id="persondetails.output"> <dummy/> <xforms:bind nodeset="instance('persondetails.input')/soap-env:body"> <xforms:bind nodeset="tns:persondetails"> <xforms:bind nodeset="request"> <xforms:bind nodeset="ssn" type="xforms:string"/> 28

29 <xforms:bind nodeset="instance('persondetails.output')/soap-env:body"> <xforms:bind nodeset="tns:persondetailsresponse"> <xforms:bind nodeset="response"> <xforms:bind nodeset="faultcode" type="xforms:string"/> <xforms:bind nodeset="faultstring" type="xforms:string"/> <xforms:bind nodeset="persondetailinfo"> <xforms:bind nodeset="givenname" type="xforms:string"/> <xforms:bind nodeset="surname" type="xforms:string"/> <xforms:bind nodeset="ssn" type="xforms:string"/> <xforms:bind nodeset="username" type="xforms:string"/> <xforms:bind nodeset="created" type="xforms:date"/> <xforms:submission id="persondetails.submission" action=" mediatype="application/soap+xml; charset=utf-8; action=" encoding="utf-8" ref="instance('persondetails.input')" method="post" replace="instance" instance="persondetails.output"> <xforms:setvalue ref="instance('temp')/relevant" value="false()" events:event="xforms-submit"/> <xforms:setvalue ref="instance('persondetails.input')/soap-env:header/*:id" value="digest(string(random()), 'SHA-1', 'hex')" events:event="xforms-submit"/> <xforms:toggle case="persondetails.response" events:event="xforms-submit-done"/> <xforms:setvalue ref="instance('temp')/relevant" value="true()" events:event="xforms-submit-done"/> <xforms:setvalue ref="instance('temp')/relevant" value="true()" events:event="xforms-submit-error"/> <xforms:message level="modal" events:event="xforms-submit-error"> <xforms:output xml:lang="et" value="if (event('error-type') = 'submission-in-progress') then 'Üks päring juba käib!' else if (event('error-type') = 'no-data') then 'Pole andmeid, mida saata!' else if (event('error-type') = 'validation-error') then 'Valideerimise viga!' else if (event('error-type') = 'parse-error') then 'Viga vastuse töötlemisel!' else if (event('error-type') = 'resource-error') then 'Päringu vastus ei ole XML!' else if (event('error-type') = 'target-error') then 'Sihtkoha viga!' else 'Sisemine viga!'"/> <xforms:output xml:lang="en" value="if (event('error-type') = 'submission-in-progress') then 'Submission already started!' else if (event('error-type') = 'no-data') then 'No data to submit!' else if (event('errortype') = 'validation-error') then 'Validation error!' else if (event('error-type') = 'parse-error') then 'Error parsing response!' else if (event('error-type') = 'resource-error') then 'Response is not XML!' else if (event('error-type') = 'target-error') then 'Target error!' else 'Internal error!'"/> </xforms:message> </xforms:submission> </xforms:model> </xhtml:head> <xhtml:body> <xhtml:h1 xml:lang="en">persons List query</xhtml:h1> <xforms:group class="help" xml:lang="en">the service returns list of persons filtered by name <xhtml:h1 xml:lang="et">isikute nimekirja päring</xhtml:h1> <xforms:group class="help" xml:lang="et">teenus tagastab isikute nimekirja mis otsitakse nime järgi <xforms:switch> <xforms:case id="personlist.request"> <xforms:group ref="instance('personlist.input')/soap-env:body"> <xforms:group ref="tns:personlist"> <xforms:group ref="request"> <xforms:input ref="givenname"> <xforms:label xml:lang="en">given name</xforms:label> <xforms:label xml:lang="et">eesnimi</xforms:label> </xforms:input> <xforms:input ref="surname"> <xforms:label xml:lang="en">surname</xforms:label> <xforms:label xml:lang="et">perenimi</xforms:label> <xforms:help>perekonnanimi v teine nimi</xforms:help> </xforms:input> <xforms:group class="actions"> <xforms:submit submission="personlist.submission"> <xforms:label xml:lang="et">esita päring</xforms:label> <xforms:label xml:lang="en">submit</xforms:label> </xforms:submit> </xforms:case> <xforms:case id="personlist.response"> 29

30 <xforms:group ref="instance('personlist.output')/soap-env:header" class="serviceid"> <xforms:output ref="xrd:id"> <xforms:label xml:lang="et">päringu id</xforms:label> <xforms:label xml:lang="en">query id</xforms:label> <xforms:group ref="instance('personlist.output')/soap-env:body"> <xforms:group ref="tns:personlistresponse"> <xforms:group ref="response"> <xforms:output ref="faultcode"/> <xforms:output ref="faultstring"/> <xforms:repeat nodeset="person" id="person_index"> <xforms:output ref="givenname"> <xforms:label xml:lang="en">given name</xforms:label> <xforms:label xml:lang="et">eesnimi</xforms:label> <xforms:output ref="surname"> <xforms:label xml:lang="en">surname</xforms:label> <xforms:label xml:lang="et">perenimi</xforms:label> <xforms:output ref="ssn"> <xforms:label xml:lang="en">ssn</xforms:label> <xforms:label xml:lang="et">isikukood</xforms:label> <xforms:trigger appearance="minimal"> <xforms:label xml:lang="et">detailid</xforms:label> <xforms:label xml:lang="en">details</xforms:label> <xforms:action events:event="domactivate"> <xforms:setvalue ref="instance('persondetails.input')/soap- ENV:Body/tns:personDetails/request/ssn" value="context()/ssn"/> <xforms:send submission="persondetails.submission"/> </xforms:action> </xforms:trigger> </xforms:repeat> <xforms:group ref="instance('personlist.output')/soap- ENV:Body/tns:personListResponse[not(response/*)]" class="info"> <xhtml:span xml:lang="et">andmeid ei tulnud.</xhtml:span> <xhtml:span xml:lang="en">service returned no data.</xhtml:span> <xforms:group ref="instance('personlist.output')/soap-env:body/soap-env:fault" class="fault"> <xforms:output ref="faultstring"/> <xforms:group class="actions"> <xforms:trigger> <xforms:label xml:lang="et">uuesti</xforms:label> <xforms:label xml:lang="en">again</xforms:label> <xforms:toggle events:event="domactivate" case="personlist.request"/> </xforms:trigger> </xforms:case> <xforms:case id="persondetails.response"> <xforms:group ref="instance('persondetails.output')/soap-env:header" class="serviceid"> <xforms:output ref="xrd:id"> <xforms:label xml:lang="et">päringu id</xforms:label> <xforms:label xml:lang="en">query id</xforms:label> <xforms:group ref="instance('persondetails.output')/soap-env:body"> <xforms:group ref="tns:persondetailsresponse"> <xforms:group ref="response"> <xforms:output ref="faultcode"/> <xforms:output ref="faultstring"/> <xforms:group ref="persondetailinfo"> <xforms:output ref="givenname"> <xforms:label xml:lang="en">given name</xforms:label> <xforms:label xml:lang="et">eesnimi</xforms:label> <xforms:output ref="surname"> <xforms:label xml:lang="en">surname</xforms:label> <xforms:label xml:lang="et">perenimi</xforms:label> <xforms:output ref="ssn"> <xforms:label xml:lang="en">personal ID code</xforms:label> <xforms:label xml:lang="et">isikukood</xforms:label> <xforms:output ref="username"> <xforms:label xml:lang="en">username</xforms:label> <xforms:label xml:lang="et">kasutajanimi</xforms:label> 30

31 <xforms:output ref="created"> <xforms:label xml:lang="en">entry created</xforms:label> <xforms:label xml:lang="et">sissekanne loodud</xforms:label> <xforms:group ref="instance('persondetails.output')/soap- ENV:Body/tns:personDetailsResponse[not(response/*)]" class="info"> <xhtml:span xml:lang="et">andmeid ei tulnud.</xhtml:span> <xhtml:span xml:lang="en">service returned no data.</xhtml:span> <xforms:group ref="instance('persondetails.output')/soap-env:body/soap-env:fault" class="fault"> <xforms:output ref="faultstring"/> <xforms:group class="actions"> <xforms:trigger> <xforms:label xml:lang="et">tagasi</xforms:label> <xforms:label xml:lang="en">back</xforms:label> <xforms:toggle events:event="domactivate" case="personlist.response"/> </xforms:trigger> </xforms:case> </xforms:switch> </xhtml:body> </xhtml:html> 31

32 Annex II Persons list query Xforms <?xml version="1.0" encoding="utf-8"?> <xhtml:html xmlns:xhtml=" xmlns:xforms=" xmlns:xxforms=" xmlns:events=" xmlns:xsd=" xmlns:xsi=" xmlns:soap-env=" xmlns:soap-enc=" xmlns:xtee=" xmlns:xrd=" xmlns:iden=" xmlns:tns=" <xhtml:head> <xhtml:title xml:lang="en">persons List query</xhtml:title> <xhtml:title xml:lang="et">isikute nimekirja päring</xhtml:title> <xforms:model> <xforms:instance id="personlist.input"> <SOAP-ENV:Envelope> <SOAP-ENV:Header> <xrd:protocolversion>4.0</xrd:protocolversion> <xrd:id/> <xrd:userid>ee</xrd:userid> <xrd:service iden:objecttype="service"> <iden:xroadinstance>ee-dev</iden:xroadinstance> <iden:memberclass>com</iden:memberclass> <iden:membercode> </iden:membercode> <iden:subsystemcode>aktorstest-db01</iden:subsystemcode> <iden:servicecode>personlist</iden:servicecode> <iden:serviceversion>v1</iden:serviceversion> </xrd:service> <xrd:client iden:objecttype="subsystem"> <iden:xroadinstance>ee-dev</iden:xroadinstance> <iden:memberclass/> <iden:membercode/> <iden:subsystemcode/> </xrd:client> </SOAP-ENV:Header> <SOAP-ENV:Body> <ns5:personlist xmlns:ns5=" <request> <givenname/> <surname/> </request> </ns5:personlist> </SOAP-ENV:Body> </SOAP-ENV:Envelope> <xforms:instance id="personlist.output"> <dummy/> <xforms:bind nodeset="instance('personlist.input')/soap-env:body"> <xforms:bind nodeset="tns:personlist"> <xforms:bind nodeset="request"> <xforms:bind nodeset="givenname" type="xforms:string"/> <xforms:bind nodeset="surname" type="xforms:string"/> <xforms:bind nodeset="instance('personlist.output')/soap-env:body"> <xforms:bind nodeset="tns:personlistresponse"> <xforms:bind nodeset="response"> <xforms:bind nodeset="faultcode" type="xforms:string"/> <xforms:bind nodeset="faultstring" type="xforms:string"/> <xforms:bind nodeset="person"> <xforms:bind nodeset="givenname" type="xforms:string"/> <xforms:bind nodeset="surname" type="xforms:string"/> <xforms:bind nodeset="ssn" type="xforms:string"/> <xforms:submission id="personlist.submission" action=" mediatype="application/soap+xml; charset=utf-8; action=" encoding="utf-8" ref="instance('personlist.input')" method="post" replace="instance" 32