ConnectorLib C++ 25.2
ConnectorLib C++ SDK Programming Guide

# 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:(Undefined variable: ACIServer.ACIPort)/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>

Copyright 2025 Open Text
Version 25.2 | Last updated April 2025

Send documentation feedback

Close

Send documentation feedback

To send feedback using your default email client, open an email window.

Otherwise, send your feedback and the information below to MFI-swpdl.idoldocsfeedback@opentext.com.

We appreciate your feedback!

Product: Knowledge Discovery ConnectorLib C++ 25.2

Topic Title: Insert