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.

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.

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

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

The webservice configuration file, in this case /webservices/mywebservice/config.xml might look like

<?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>

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

<?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>

and in the last case where the webservice should extend the built in API

<?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>

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

http://path.to.server/?vortex_ws=[webserviceid]

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 method will take an XML String as input and will give an XML String as output. The format of the input is

<VortexAPI>
  <function name="[function_name]">
    <other_xml_passed_to_the_function />
  </function>
</VortexAPI>

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.

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.

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

Syntax:

<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>

Description of elements

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:

  <filter>
    <field1 operator="GREATER">5</field1>
    <field2 operator="LESSER" FilterOperator="OR">7</field2>
  </filter>

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.

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>[numner]</limit>

Limits the result to [number] rows

<offset>[number]</offset>

Offsets the beginning of the fetch [number] rows.

<orderby>[fieldname]</orderby>

Orders the resultset according to the field.

Supply a searchstring to use when filtering data.

<view idview="[idview]" />

or

<view>
  <field>field1</field>
  <field>field2</field>
</view>

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.

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

Syntax:

<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>

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.

<[fieldname]>[value]</[fieldname]>

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

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.

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

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.

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

will execute the method handler_class::testMethod which will echo

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

</code>

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 PHP manual on SoapServer.