# Stub

This action inserts a stub, a link to a document in another repository.

An application might use a connector to insert a stub when a document is moved to another repository or is deleted. The stub can point to the new location, or in the case where the document has been deleted, explain why the document is missing.

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 section of the connector's configuration file that contains settings to use for inserting the stub. | Yes
`StubXML` | Provides information about how to insert the stub. The value of this parameter must be URL-encoded XML:
    <StubXML>
        <stub>
            <reference>reference</reference>
            <section>configsection</section>
            <property name="propname" value="propvalue"/>
            <!-- ... -->
            <metadata name="name" value="value"/>
            <!-- ... -->
            <xmlmetadata>
              <name>value</name>
            </xmlmetadata>
            <target>
                <group>AUTN_GROUP</group>
                <identifier>AUTN_IDENTIFIER</identifier>
                <uri>URI</uri>
            </target>
            <stub_id>ANY_STRING</stub_id>
        </stub>
        <!-- ... -->
    </StubXML>
- - `<stub>` is the outer element containing a single stub operation to be performed. You can include multiple `<stub>` elements. `<reference>` and `<property>` are used to construct an identifier for the stub that is inserted into the repository. The `<reference>` and `<property>` elements are optional, and the usage of these elements depends on the repository. The usage of these elements is the same as for the `insert` action. `<section>`. The name of the task section (in the configuration file) to use to insert the stub. The default value is specified by the `ConfigSection` action parameter, but if you specify a different value in the XML, the value in the XML takes priority. `<metadata>` If the repository requires additional metadata to be set when creating a document (that are not used to locate the document) then additional metadata can be provided with this element. Usually the `<property>` element is used for metadata that identifies the location where the stub is inserted. The usage of this element is the same as for the `insert` action. `<xmlmetadata>` can be used instead of `<metadata>` to provide metadata as structured XML rather than a name and value for a single field. The usage of this element is the same as for the `insert` action. `<target>` contains the details of where the document is now located. `<group>` contains the name of the connector group, recognized by a Distributed Connector, that can access the current location of the document. You can omit this information, but the Distributed Connector will then need to query IDOL to find the relevant connector group. `<identifier>` specifies the identifier of the document in the destination repository. `<uri>` The URI of the document in the destination repository, or a URI that will redirect to the document. This URI overrides the `StubTargetUri` parameter, if that is set in the connector's configuration file. The URI can contain placeholders (see StubTargetUri). In the following example [`AUTN_IDENTIFIER:ID`] is replaced by the identifier property named "ID" instead of the full identifier.
        http://host/url?group=[AUTN_GROUP]&identifier_id=[AUTN_IDENTIFIER:ID]
`<stub_id>` is optional and can contain any string that you want to use as an identifier for this stub request. The response to the `stub` fetch action reports which stubs 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

    http://localhost:1234/action=Fetch&FetchAction=Stub
                                      &ConfigSection=MyTask
                                      &StubXML=...(url-encoded XML)...

## 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.

    <action>
      <status>Finished</status>
      <queued_time>2014-Dec-12 10:39:02</queued_time>
      <time_in_queue>0</time_in_queue>
      <process_start_time>2014-Dec-12 10:39:02</process_start_time>
      <time_processing>0</time_processing>
      <process_end_time>2014-Dec-12 10:39:02</process_end_time>
      <documentcounts>
        ...
      </documentcounts>
      <fetchaction>STUB</fetchaction>
      <identifiers>
        <identifier>[SUCCESS_IDENTIFIER1]</identifier>
        <identifier stub_id="STUB_ID2">[SUCCESS_IDENTIFIER2]</identifier>
        <failed message="an error">STUB_ID3</failed>
      </identifiers>
      <token>MTAuMi4xMDUuMzQ6MTIzNDpGRVRDSDotMTc4NTQ1MTYwOQ==</token>
    </action>

For failed documents, the `<failed>` element contains the value of `stub_id`, if this was specified in the `StubXML` provided in the action. If a `stub_id` was not provided, the element contains the identifier that was constructed for the stub.

_FT_HTML5_bannerTitle.htm