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.