====== Vortex Integration via Webservices ======

Integrating the Vortex with other systems is relatively straightforward. The preferred way of integration is via the built in webservice API, or an extension thereof. Using the webservice API or extending it involves a few configuration steps described below. All of the configuration and extensions are done within the Database Instance.

===== Setting up a Vortex Webservice =====

To setup a webservice you first need a working Database Instance with a valid configuration file //config.xml//.\\
In the configuration file you'll need to add a webservice node where all the webservices for this database instance are defined.

<code xml>
  <webservices>
    <mywebservice id="my_webservice" relpath="mywebservice/" config="config.xml" />
  </webservices>
</code>

This configuration adds the webservice //mywebservice// with ID //my_webservice//. The source for this webservice will be in the database instance home directory under ///webservices/mywebservice/// and the configuration file will be ///webservices/mywebservice/config.xml//

==== Webservice configuration file ====
The webservice configuration file, in this case ///webservices/mywebservice/config.xml// might look like
<code xml>
<?xml version="1.0" encoding="utf-8"?>
<webservice file="server.php" name="My test webservice" handler="my_webservice_class" stdhandler="false">
  <cache enabled="true" />
  <database id="MyDatabaseInstance" />
  <user username="user" password="pass" />
  <logger relativepath="" />
  <wsdl uri="mywebservice.wsdl" />
  <xsd uri="mywebservice.xsd" />
</webservice>
</code>

This webservice does not use the standard Vortex API but implements a handler class which gets all the webservice calls. If the webservice should use the built in API without extending it, the config file would be
<code xml>
<?xml version="1.0" encoding="utf-8"?>
<webservice name="My test webservice" stdhandler="true">
  <cache enabled="true" />
  <database id="MyDatabaseInstance" />
  <user username="user" password="pass" />
  <logger relativepath="" />
  <stdhandler enableget="true" enableset="true" function="function" name="name" />
</webservice>
</code>

and in the last case where the webservice should extend the built in API
<code xml>
<?xml version="1.0" encoding="utf-8"?>
<webservice file="server.php" name="My test webservice" handler="my_webservice_class" stdhandler="false">
  <cache enabled="true" />
  <database id="MyDatabaseInstance" />
  <user username="user" password="pass" />  
  <logger relativepath="" />
  <stdhandler enableget="true" enableset="true" function="function" name="name" />
  <wsdl uri="mywebservice.wsdl" />
  <xsd uri="mywebservice.xsd" />
</webservice>
</code>

==== Configuration description ====
^Tagname^Attribute^Values^Description^
|webservice|file|*|The PHP file containing the handler class for the webservice|
|:::|name|*|Plaintext description of the webservice|
|:::|handler|*|The classname of the webservice handler class|
|:::|stdhandler|true/false|Wether to use the built in webservice API|
|cache|enabled|true/false|Wether to enable caching of the WSDL files for this webservice. Disable this during development and testing.|
|database|id|*|The ID of the Database Instance this webservice is connected to.|
|logger|relativepath|*|Relative path for the logging, if you want webservice logging on a different location from normal logging|
|stdhandler|enableget|true/false|Wether to enable the getDataFromTable API method|
|:::|enableset|true/false|Wether to enable the setDataToTable API method|
|:::|function|*|The name of the function element in the API XML|
|:::|name|*|The name of the attribute in the function element describing the function name|
|user|username|*|The user to run the webservice as
|:::|password|*|The password to authenticate the user
|wsdl|uri|*|The URI or relative path of the WSDL file to publish for this webservice|
|xsd|uri|*|The URI or relative path of the XSD file to publish for this webservice|

===== The inner workings of the Webservice =====

==== Calling a Vortex Webservice ====

To call a function published by a Vortex Webservice, you'll need to use the published WSDL file. To access the WSDL use the URI
<code>
http://path.to.server/?vortex_ws=[webserviceid]
</code>
The [webserviceid] is the //id// you assigned the webservice in the Database Instance configuration file.
If the webservice is using the built in API, the method //API// will be published. Otherwise this will show the custom WSDL file as pointed to from the webservice configuration file.

==== The built in API ====

The built in //API// method will take an XML String as input and will give an XML String as output. The format of the input is
<code xml>
<VortexAPI>
  <function name="[function_name]">
    <other_xml_passed_to_the_function />
  </function>
</VortexAPI>
</code>

Calling the //API// method will first check the handler class (from the webservice configuration file) for a method matching the [function_name]. If none exists, it will check the internal webservice handler for such a method. Upon finding a matching method, this will be executed with the <function - element and all subelements passed as the argument in the form of a DOMDocument.

In other words it is possible to override the internal webservice methods //getDataFromTable// and //setDataToTable// by implementing methods with those names in the handler class.

==== Internal webservice methods ====

If a handler class is not supplied or if the standard API is extended, there are two functions in the //API// implemented in the Vortex. Those are //getDataFromTable// and //setDataToTable//.

=== getDataFromTable ===

Fetches the TableRecords matching the given criteria from the database. The result is an XML description of the TableRecord object.

Syntax:
<code xml>
<vortexAPICall>
  <function name="getDataFromTable" table="myTable">
    <filter>
      <myRelation1.myRelatedField>some_value</myRelation1.myRelatedField>
      <myField3>test value</myField3>
    </filter>
    <include relation="[relationname]" />
    <limit>100</limit>
    <offset>10</offset>
    <orderby>myField1</orderby>
    <searchstring>[myField2="8"]|[myField2=15]</searchstring>
    <view>
      <field>myField1</field>
      <field>myField2</field>
      <field>myRelation1.myRelatedField</field>
    </view>
  </function>
</vortexAPICall>
</code>

Description of elements

==filter==
Contains the filter rules to apply to the search. Each subelement is on the form <fieldname>value</fieldname> where fieldname is the name of the field to match, and value is the value to match.\\
The subelement describing the rule can also have a couple of attributes describing how to match:
<code xml>
  <filter>
    <field1 operator="GREATER">5</field1>
    <field2 operator="LESSER" FilterOperator="OR">7</field2>
  </filter>
</code>

operator can have the values LIKE / IN / GREATER / EQUAL|GREATER / LESSER / EQUAL|LESSER / NOT|EQUAL  and matches if the field is LIKE, IN, GREATER, EQUAL or GREATER, LESSER, EQUAL or LESSER or NOT EQUAL to the value.\\
FilterOperator can have the values AND or OR, and controls if rules are ORed or ANDed togeather.

==include==
Tells the API to include records from the X-relation called [relationname]. The include element can contain all subelements and attributes from the //function// tag, i.e. //filter//, //view//, //limit// etc. The //table// attribute is not supported though.

==limit==
<code xml>
<limit>[numner]</limit>
</code>
Limits the result to [number] rows

==offset==
<code xml>
<offset>[number]</offset>
</code>
Offsets the beginning of the fetch [number] rows.

==orderby==
<code xml>
<orderby>[fieldname]</orderby>
</code>
Orders the resultset according to the field.

==searchstring==
Supply a searchstring to use when filtering data.

==view==
<code xml>
<view idview="[idview]" />
</code>

or 

<code xml>
<view>
  <field>field1</field>
  <field>field2</field>
</view>
</code>

If the attribute //idview// is supplied, the stored view with the given ID is loaded and used for the data. If not, a new view containing the fields supplied in the subelements is created and used.


=== setDataToTable ===

Sets data to a table in the database instance according to the supplied data.

Syntax:
<code xml>
<vortexAPICall>
  <function name="setDataToTable">
    <tablerecord uuid="myUUID">
      <field1>25</field1>
      <field2>test</field2>
    </tablerecord>
    <tablerecord table="myTable">
      <field1>25</field1>
      <field2>test</field2>   
    </tablerecord>
    <tablerecord table="myTable" id="85">
      <field1>25</field1>
      <field2>test</field2>
    </tablerecord>
  </function>
</vortexAPICall>
</code>

The subelements of the function call describes three tablerecords to store to the database. Tablerecords are identified by using the //uuid// attribute, or by using the //table// and //id// attribute. If a TableRecord can be identified either way, that TableRecord will be updated. If //id// is 0 or not supplied, a new TableRecord will be created in the supplied //table//. If //table// is not supplied and //uuid// does not match an existing TableRecord, an error is raised and the TableRecord is not stored in the database.

The //field// subelements to each TableRecord are the values that are set in the TableRecord.
<code xml>
<[fieldname]>[value]</[fieldname]>
</code>

If the fieldname does not exist in the TableRecord, the field is simply skipped, and the rest of the data is stored.

==== Extending the built in API ====

When extending the existing API, a handler class must be supplied in the webservice configuration file. This handler class is implemented in the file supplied in the configuration file. 

<code php>
class handler_class {
  private $xml;
  
  public function __construct( &$xml ) {
    $this->xml = &$xml;
  }
  
  public function testMethod() {
    echo $this->xml->saveXML();
  }
}
</code>

As you can see in the handler class, the entire XML with function tag and all, is passed to the class constructor as a PHP DOMDocument. After that, the function is called without arguments.

<code xml>
<vortexAPICall>
  <function name="testMethod">
    <test>1</test>
  </function>
</vortexAPICall>
</code>

will execute the method handler_class::testMethod which will echo 

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<vortexAPICall>
  <function name="testMethod">
    <test>1</test>
  </function>
</vortexAPICall>
</code>
</code>

==== Not using the built in API ====

If the built in API is not used, the methods in the handler class will be called as Webservice functions. For more information, see the [[http://se.php.net/manual/en/class.soapserver.php|PHP manual on SoapServer]].