Insert

Inserts a document or documents into the data repository.

Type: Asynchronous

Parameter Name Description Required
Config A base-64 encoded configuration. The configuration parameters that are set override the same parameters in the connector's configuration file. No
ConfigSection The name of the task section in the connector's configuration file to use to insert the documents. Yes
failedDirectory The directory in which the action reports failures. No
InsertXML

XML that describes how and where to add each document, all the metadata, and optionally, a file to insert for each document. Some connectors require a file.

You must provide the data in XML format, as follows:

<InsertXML>
  <insert>
    <reference>reference</reference>
    <section>configsection</section>
    <property name="propname" value="propvalue"/>
    <!-- ... -->
    <metadata name="fieldname" value="fieldvalue"/>
    <!-- ... -->
    <xmlmetadata>
      <fieldname>fieldvalue</fieldname>
    </xmlmetadata>
    <file>
      <type>type</type>
      <displayname>filename</displayname>
      <content>content</content>
    </file>
    <insert_id>012345</insert_id>
  </insert>
  <!-- ... -->
</InsertXML>

Most of the tags are optional. You can omit the insert tag if you are inserting a single document.

  • reference, property, metadata, xmlmetadata. The usage of these tags depends on the connector. For more information about using the insert fetch action, refer to Administration Guide for your connector. xmlmetadata is an alternative to metadata that you can use to provide metadata as structured XML, rather than providing the name and value for a single field at a time.
  • section. The name of the task section (in the configuration file) to use to insert the document. The default value is specified by the ConfigSection action parameter, but if you specify a different value in the InsertXML, the value in the InsertXML takes priority.
  • file. Specifies information about the file to insert. If you include the <file> element, you must include at least <content>.

    • type. The type element specifies the type of data included in the following <content> element. Use one of the following values:

      • file - The content element contains a file name. The file is not owned by the connector, so the connector does not delete it after the action succeeds.
      • tempfile - The content element contains a file name. The file is owned by the connector and is deleted after the action succeeds.
      • content - The content element contains the body of the file base64 encoded.
      • drecontent - The content element contains the document DRECONTENT.
      • dataid - The file has been previously sent to the connector's DataPort with the dataid set in the content element.
    • displayname - used for logging and when writing the data to a temporary file.
  • insert_id. This tag is optional and specifies a unique ID for the document. The response to the insert fetch action reports which documents were successfully inserted by returning the specified IDs.
Yes
Override_Config_Parameters

Any other action parameters that you set override settings in the connector's configuration file. For example:

/action=fetch&fetchaction=...
&[Section]Parameter=Value

where [Section] (optional) is the name of a configuration file section, Parameter is the name of a configuration parameter, and Value is the parameter value.

No

Example

This example shows how to use a File System Connector to insert a file with the reference C:\Autonomy\FileSystemConnectorCFS\dir1\newfile.txt and the content This is my file into a file system.

  1. Construct the InsertXML:
    <insertXML>
      <insert>
        <reference>C:\Autonomy\FileSystemConnectorCFS\dir1\newfile.txt</reference>
        <file>
          <type>content</type>
          <content>VGhpcyBpcyBteSBmaWxl</content>
        </file>
        <insert_id>012345</insert_id>
      </insert>
    </insertXML>

    NOTE: The content This is my file is base64 encoded.

  2. Send the Insert action. For example, if you save the XML in a file named my.xml, you could use the command-line utility curl to send the action as follows:

    curl http://localhost:7134/action=Fetch --data-urlencode FetchAction=Insert --data-urlencode ConfigSection=MyTask --data-urlencode InsertXML@my.xml

For more information about using the insert fetch action, refer to Administration Guide for your connector.

Response

As this is an asynchronous action, you receive a token in response to the request. A sample response to the action (as retrieved using the queueinfo action) appears below.

This response shows that the action has completed and that one document has been inserted, and gives the identifier of the new document.

<action>
  <status>Finished</status>
  <queued_time>2013-Dec-12 10:39:02</queued_time>
  <time_in_queue>0</time_in_queue>
  <process_start_time>2013-Dec-12 10:39:02</process_start_time>
  <time_processing>0</time_processing>
  <process_end_time>2013-Dec-12 10:39:02</process_end_time>
  <documentcounts>
    <documentcount
      added="0"          collected="0"       deleted="0"
      errors="0"         holds="0"           ingestadded="0"
      ingestdeleted="0"  ingestfailed="0"    ingestupdated="0"
      inserted="1"       releasedholds="0"   seen="0"
      task="DIR1"        unchanged="0"       updated="0"/>
  </documentcounts>
  <fetchaction>INSERT</fetchaction>
  <identifiers>
    <identifier insert_id="012345">
       PGlkIHM9IkRJUjEiIHI9IkM6XEF1dG9ub215XEZpbGVTeXN0ZW1Db25uZWN0b3JDRlNcZGlyMVxuZXdmaWxlLnR4dCIvPg==
    </identifier>
  </identifiers>
  <token>MTAuMi4xMDUuMzQ6MTIzNDpGRVRDSDotMTc4NTQ1MTYwOQ==</token>
</action>

If a document cannot be inserted successfully, the insert_id specified in the action appears between <failed> tags and a message explains the reason for the failure. If an insert_id was not specified, the document identifier appears between the <failed> tags. For example:

<tasks>
   <failed message="Connector does not support insertion of metadata only">012345</failed>
</tasks>