Developing File Output Connectors

Jadu Central allows developers to create file output connectors. Connectors provide the mechanism to process and send user submitted data to remote locations for processing external to the Jadu platform.

When developing your own connectors, you must extend the Jadu_XForms2_Connector_Adapter_Abstract class, found in /path/to/jadu/xforms2/Connector/Adapter/. As the developer, you provide implementations for the protected function _prepare and public function send. Abstract.php also provides a logError function for writing out any error messages to the log file if you choose to implement this into your own connectors.

Creating a custom connector

Connectors can be one or more scripts as required but at least one script must include and extend the Connector Abstract class referred to above for your specific version. This class contains abstract methods _prepare and send. When a user successfully completes and submits their form, the send method is called, passing through an array of file paths. At least one file is always passed through, this is either an XML or CSV file depending upon the settings configured during the design of the form within the Jadu Control Center.

Basic Structure

<?php
/**
* Example Connector is a class to handle the
* encryption and storage and transmission of
* form data.
*
* @package custom
* @copyright All Contents (c) 2015 Jadu Ltd.
* @author Jadu Ltd.
*/

require_once("xforms2/Connector/Adapter/Abstract.php");
//<< ANY OTHER INCLUDES REQUIRED >>

class JaduXFormsConnectorExample extends Jadu_XForms2_Connector_Adapter_Abstract
{
    /**
    * {@link XFormsForm} identifier
    * @access private
    * @var integer
    */
    private $_formID;
    /**
    * The web reference given to the end user
    * @access private
    * @var integer
    */
    private $_webRefNumber;
    /**
    * The sequence id of the completed form
    * @access private
    * @var string
    */
    private $_sequenceID;
    /**
    * System generated filename, made up of _formID,
    * _webRefNumber, _sequenceID
    * @access private
    * @var string
    */
    private $_filename;
    /**
    * Constructor creates a new instance and sets default values
    *
    * @param integer $formID The {@link XFormsForm} identifier
    * @param integer $webRefNumber The web reference given
    * to the end user
    * @param string $sequenceID The sequence id of the completed form
    */
    public function __construct($formID, $webRefNumber, $sequenceID)
    {
    $this->_formID = $formID;
    $this->_webRefNumber = $webRefNumber;
    $this->_sequenceID = $sequenceID;
    $this->_filename = 'xform_' . $_formID . $webRefNumber .
    $sequenceID.'.zip';
    }
    /**
    * Function to send prepare and send data
    * @param array[]string $data Array of file paths for sending
    * @param array[string]string $settings Key/Value
    * array where the key is the property
    * @return integer Error code 0 = success, 1 = No data given, 2 = Files
    * not found,
    * 3 = Error zipping, 4 = Error Encoding, 5 = DB Error, 6 = Unknown
    * error
    */
    final public function send($data, $settings)
    {
    //<< CUSTOM LOGIC HERE >>
    }
    /**
    * This function prepares the data for transmission
    *
    * @param array[]string $data
    * @return mixed filename of the prepared data on success or Error code
    * 1 = No data given,
    * 2 = Files not found, 3 = Error zipping, 4 = Error Encoding, 5 = DB
    * Error
    */
    protected function _prepare($data)
    {
    //<< CUSTOM LOGIC HERE >>
    }
}```

As long as your class follows the base structure shown above, you will be able to register your connector for use within
Jadu Central.

### Required functions

These methods should be implemented to the following standards described below:

____construct()__

The constructor takes the form ID, the user’s web reference number and the sequence ID as its arguments. The
`$formID` identifies which specific XForm the user has completed. The `$webRefNumber` is the number provided to the end
user once they have completed the form. The `$sequenceID` is the incremental number of times that this particular form
has been submitted. These details can be used within your class to assist in identifying any files that are created.

__send()__
    
Your connector may require specific settings to be passed to it, along with the array of file paths. `$data` is an array
of file paths, which contains either an XML or CSV file along with paths to additional files that the user uploaded when
completing the form. `$settings` is an array of key / value pairs, where the key is the setting property name.
The send function must conform with the return values expected as follows:

| Return Code | Reason |
|:---|:---|
|0 | Success |
|1 | No data given |
|2 | A file was not found when processing |
|3 | Error in zipping the result as may be implemented by your connector |
|4 | Error in encoding or encrypting the resulting data as implemented by your connector |
|5 | Some form of Database error |
|6 | Unknown error occurred |
    
__prepare()__

You may need to prepare the data before it is ready to be sent, for example you may require the data to be encrypted
ready for transmission. The prepare method should process the data to the point that it is ready to be sent. The 
`$data`	parameter contains a string of data to be prepared.
    
### Registering the connector

You must register your connector with XForms Professional before it can be applied to any forms. This is done by adding
records into the appropriate database tables that provide structure to XForms Professional Connectors. This can be done
through your preferred DBMS interface. For reference, the connector database schema is as follows:

![Database Schema for File Output Connectors](../assets/connector_schema.jpg)

_File output connector database schema_

##### Step 1 - Adding the Connector

You must provide a name for your Connector. The name will display within the Jadu Control Center and is what form
administrators will use to identify the connector when choosing it as part of the File Output action setup. Create
a new record in the database table JaduXFormsConnectorTypes giving a title, the path to your custom connector class file
and finally the name of the class within it.

```sql
INSERT INTO JaduXFormsConnectorTypes (
`title`,
`classFile`,
`class`
) VALUES (
'Example Connector',
'custom/ExampleConnector.php',
'ExampleConnector');

Step 2 - Adding new Connector fields

Your connector may require specific fields when it is configured. XForms Professional provides some common fields as standard (hostname, port, username, password, timeout and directory). If you require any additional fields for your own connectors, then you should add an entry to the JaduXFormsConnectorFields database table. Title is the name of the field that will display when setting up connectors. The validation field should contain a regular expression for input validation. The encrypt field is a boolean 0 or 1 flag to specify that the value entered for this value should be encrypted within the database as it holds sensitive information, and subsequently will not be displayed on screen. The searchable field declares the field as searchable by form administrators from within the Control Center interface.

INSERT INTO JaduXFormsConnectorFields (
`title` ,
`validation` ,
`encrypt` ,
`searchable`
) VALUES (
'destinationID',
'',
'0',
'1');

Step 3 - Mapping new fields to your Connector

You now need to map the fields that your connector type requires. In JaduXFormsConnectorTypeSettings, create a new record for each field. Here you can define the position (order of the fields), required status (is field entry mandatory) and a default value if appropriate.

INSERT INTO JaduXFormsConnectorTypeSettings (
`connectorTypeID` ,
`fieldID` ,
`required` ,
`position` ,
`defaultValue`
) VALUES (
'1',
'1',
'1',
'1',
'');

Step 3 - Connector configuration

Finally, because Jadu uses database caching, the cache needs to be cleared. Using the cacheBash.php maintenance script (detailed in chapter X), clear the following tables: //TODO Update Chapter info

JaduXFormsConnectorFields,

JaduXFormsConnectorTypes,

JaduXFormsConnectorTypeSettings

Now log-in to your Jadu Central installation, and go to the Forms > Connector page (assuming you have the relevant access privileges to this area of the system) and click on “Create New Connection” to setup an instance of your new connector type.

Any new fields that you created in step 2 and mapped in step 3 to your connectors type will then appear within the “Connector”. You should now be able to use your connector when setting up File Output actions on forms.

Creating a custom connector​

Basic Structure​

Step 2 - Adding new Connector fields​

Step 3 - Mapping new fields to your Connector​

Step 3 - Connector configuration​

Creating a custom connector

Basic Structure

Step 2 - Adding new Connector fields

Step 3 - Mapping new fields to your Connector

Step 3 - Connector configuration