External Adapter Configuration File

The framework defines the structure of the external adapter configuration file (cnxml) file that contains the adapter properties.

The external adapter configuration file is an XML file that contains the properties and commands used by Event Stream Processor to start and stop the external adapter and to optionally run schema discovery, as well as other information that allows the external adapter to be configured from Studio.

The example below shows a cnxml file that uses four of the utilities shipped with Event Stream Processor (esp_convert, esp_upload, esp_client, and esp_discxmlfiles) to fully define a functional external adapter that supports browsing a directory of files, the creation of a source stream, and data loading. This sample configuration file, simplified_xml_input_plugin.cnxml, can be found in the $ESP_HOME/lib/adapters directory. The directory is included in the standard Event Stream Processor distribution package.

In the example, long lines of script below have been split for readability and to avoid formatting issues. If you are using this to create your own external adapter configuration file, ensure that all command properties are on a single line, regardless of length.

<?xml version="1.0" encoding="UTF-8"?>

<Adapter type="input" external="true"
  id="simplified_xml_input_plugin"
  label="Simplified external XML file input plugin Adapter"
  descr="Example of uploading an XML file through a simple external Adapter"
>
  <Library file="simple_ext" type="binary"/>

  <!-- 
     The special section contains the special internal parameters
     which are prefixed with "x_". Although these are parameters,
     the framwork requires them to be defined using the <Internal
     .../> element. They are hidden from the user in ESP Studio.
  -->
  <Special>
    <Internal id="x_initialOnly" 
      label="Does Initial Loading Only" 
      descr="Do initial loading, or the continuous loading"
      type="boolean"
      default="true"
    />
    <Internal id="x_addParamFile" 
      label="Add Parameter File" 
      type="boolean"
      default="false"
    />
    <Internal id="x_killRetryPeriod" 
      label="Period to repeat the stop command until the process exits" 
      type="int"
      default="1"
    />

    <!-- 
	Convert a file of xml record to ESP Binary format using esp_convert;
        pipe into the esp_upload program, naming the upload connection:
	$platformStream.$platformConnection
    -->
    <Internal id="x_unixCmdExec" 
      label="Execute Command" 
      type="string"
      default="$ESP_HOME/bin/esp_convert -p $platformCommandPort &lt;&quot;$directory/$filename&quot; | $ESP_HOME/bin/esp_upload -m $platformStream.$platformConnection -p $platformCommandPort"
    />
    <Internal id="x_winCmdExec" 
      label="Execute Command" 
      type="string"
      default="$+/{$ESP_HOME/bin/esp_convert} -p $platformCommandPort &lt;&quot;$directory/$filename&quot; | $+/{$ESP_HOME/bin/esp_upload} -m $platformStream.$platformConnection -p $platformCommandPort"
    />

    <!-- 
        use the esp_client command to stop an existing esp_upload connection named:
        $platformStream.$platformConnection
    -->
    <Internal id="x_unixCmdStop" 
      label="Stop Command" 
      type="string"
      default="$ESP_HOME/bin/esp_client -p $platformCommandPort 'kill every {$platformStream.$platformConnection}' &lt;/dev/null"
    />
    <Internal id="x_winCmdStop" 
      label="Stop Command" 
      type="string"
      default="$+/{$ESP_HOME/bin/esp_client} -p $platformCommandPort &quot;kill every {$platformStream.$platformConnection}&quot; &lt;nul"
    />

    <!--
	Use the esp_discxmlfiles command to do data discovery. 
	The command below will have '-o "<temp file>"' added to it. It 
	will write the discovered data in this file.
     -->
    <Internal id="x_unixCmdDisc" 
      label="Discovery Command" 
      type="string"
      default="$ESP_HOME/bin/esp_discxmlfiles -d &quot;$directory&quot;"
    />
    <Internal id="x_winCmdDisc" 
      label="Discovery Command" 
      type="string"
      default="$+/{$ESP_HOME/bin/esp_discxmlfiles} -d &quot;$+/{$directory}&quot;"
    />
  </Special>

  <Section>

    <!-- 
        Any parameter defined here, is visible in the ESP Studio, and may 
	be configured by the user at runtime in the data location explorer. 
	These are defined according to the $ESP_HOME/etc/Adapter.xsd 
	schema.
    -->

    <Parameter id="filename" 
      label="File" 
      descr="File to upload"
      type="tables"
      use="required"
    />
    <Parameter id="directory" 
      label="path to file" 
      descr="directory to search"
      type="directory"
      use="required"
    />
    <Parameter id="propertyset" 
      label="propertyset" 
      descr="to look up properties in project configuration"
      type="string"
      use="advanced"
      default=""/>  	
  </Section>
</Adapter>