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.

Here is the structure of a cnxml file:

<Adapter> 
	type = Can be input or output
	external = True
	id = Required to be unique to the adapter
	label = The adapter's name in Studio
	descr = Description of adapter functionalities

<Library>
	file = simple_ext (Always use this for custom external adapters)
	type = Binary

<Special>
	<Internal>
		**These values are not configurable from Studio. simple_ext has a function that parses this cnxml file and looks up the internal fields to find particular commands and their default values**
	id = The ids listed in the example below are the only valid id fields because simple_ext parses and tries to find the function that is being called.
	label = Description of function
	type = String
	default = This is the command that simple_ext executes. For example, if you are using x_unixCmdExec, it calls esp_convert with targets you specify followed by an upload.

<Section>
	<Parameter>
	**These parameter values are visible (except for id) and configurable in Studio.** 
	     id = The property id that you can reference to in <Internal> command calls with $(id's name). This is what you reference when writing an adapter in CCL.
		label = The property name which appears in Studio.
		descr = Description of adapter property.
		type = The property datatype.
		use = Whether the property is required, optional, or advanced. In Studio, required properties appear in red and advanced ones appear on a separate tab.
		default = Default value to use, if you do not set a value for the property.

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 framework 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 you can 
	configure it 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>