# Insert

This action inserts a document or documents into a 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 containing all the properties to determine how and where to add each document, all the metadata, and optionally, a file to insert for each document. Some connectors require a file. The data must be provided in XML format as below:
    <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. `insert`. The `insert` tag can be omitted if a single document is being inserted. `reference`, `property`, `metadata`, `xmlmetadata`. The usage of these tags depends on the connector used. 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. `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
`SecurityInfo` | An IDOL security info string. Set this parameter to impersonate the specified user. To impersonate another user you must set DocumentSecurityType and SecurityInfoKeys. | No
`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. The XML is then URL encoded and used in the `Insert` action.

       http://localhost:1234/action=Fetch&FetchAction=Insert&ConfigSection=DIR1
                                &InsertXML=%3CinsertXML%3E%3Cinsert%3E%3Creference%3EC%3A%5CAutonomy%5C
                                 FileSystemConnectorCFS%5Cdir1%5Cnewfile.txt%3C%2Freference%3E%3Cfile%3
                                 E%3Ctype%3Econtent%3C%2Ftype%3E%3Ccontent%3EVGhpcyBpcyBteSBmaWxl%3C%2F
                                 content%3E%3C%2Ffile%3E%3Cinsert_id%3E012345%3C%2Finsert_id
                                 %3E%3C%2Finsert%3E%3C%2FinsertXML%3E

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>

_FT_HTML5_bannerTitle.htm