Stub

This action uses an appropriate connector to insert 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.

/action=Fetch&FetchAction=Stub
            &AUTN_GROUP=ConnectorGroup
            [&Config=Base64_Config]
             &ConfigSection=Section_Name
             &StubXML=Stub_XML
            [&Overriding_Config_Parameters=...]

Type: Asynchronous

Parameter Name Description Required
AUTN_GROUP The connector group to send the action to. Yes
Config An optional Base64 encoded configuration file. If this parameter is set, then the encoded configuration options are used instead of the options in the connector configuration file. No
ConfigSection The section of the connector's configuration file that contains settings to use for inserting the stub. No
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]"/>
        <!-- ... -->
        <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 connector's 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.
  • <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 because the stub can refer to a Distributed Connector that can query IDOL to find the 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:

      [AUTN_GROUP] The name of a connector group recognized by a Distributed Connector.
      [AUTN_IDENTIFIER] The full stub identifier.
      [AUTN_IDENTIFIER_R] The reference from the stub identifier.
      [AUTN_IDENTIFIER_S] The source (configuration file section) from the stub identifier.
      [AUTN_IDENTIFIER:XYZ] The value of a single identifier property, XYZ.

      To indicate that the value of the placeholder should be URL encoded, insert a % character before the name, for example [%AUTN_IDENTIFIER].

      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
Overriding_Config_Parameters Any other action parameters that you set override settings in the connector's configuration file. No

Example

http://localhost:1234/action=Fetch&FetchAction=Stub
                                  &AUTN_GROUP=FileSystemConnectors
                                  &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.