Browse a Repository

The identifiers fetch action provides information that can be used to browse a repository. It retrieves a list of documents that are present in the repository and generates an identifier for each document.

Action Description Method to override
/action=fetch&fetchaction=Identifiers Retrieve a list of documents that are present in the repository. identifiers

Enable the Action

To enable the identifiers fetch action, update the features() function on the connector so that it returns Features::identifiers.

   Features::feature_type MyConnector::features()
   {
     return Features::synchronize_from_ids|Features::identifiers /*...*/;
   }

Declare the Types of Identifiers

Before implementing the action, you must specify the types of identifier that the connector can return. For example, a connector that retrieves information from a file system might return identifiers that represent folders and identifiers that represent files.

Add the types in a header file (in the namespace of the connector), for example:

   struct id
   {
      static const autonomy::cppsdk::connector::IdentifierType Folder;
      static const autonomy::cppsdk::connector::IdentifierType File;
   };

Then, in a cpp file such as connector.cpp, define the types:

   const IdentifierType id::Folder("Folder", IdentifierAttribute::container);
   const IdentifierType id::File("File", IdentifierAttribute::document);

In the main connector class, implement the identifierTypes() function so that it returns each IdentifierType that is known to the connector:

   IdentifierTypes MyConnector::identifierTypes()
   {
      return IdentifierTypes{
        id::Folder,
        id::File
      };
   }

You can verify the identifier types you have declared by running /action=GetStatus, which returns the list of IdentifierTypes and attributes.

Implement the Identifiers Action

To implement the identifiers action, override the identifiers method.

When you implement the action, you can choose whether your users must set the parameter ParentIdentifiers in the identifiers action request.

The parameter ParentIdentifiers accepts a comma-separated list of identifiers. The action should return identifiers for items that exist below the parent identifiers in the repository. For example, the user might specify an identifier for a folder and would expect the action to return identifiers for folders and files contained within that folder. Alternatively, the user might specify the root of the repository by including the special identifier ROOT. The following sample code demonstrates how to implement the identifiers action and handle these cases.

   void MyConnector::identifiers(const IdentifiersTask& task)
   {
      // Check whether we are expanding provided Parent identifiers.
      // If no Parent Identifiers are provided (when task.usingParentIdentifiers() == false),
      //  the implementation may choose to return Identifiers using some other criteria.
      if (task.usingParentIdentifiers())
      {
        // The special Identifier "ROOT" is used to request the top level
        // Identifiers in the repository. The task.parentIdentifierIsRoot()
        // returns true if this special Identifier is present in the request.
        if (task.parentIdentifierIsRoot())
        {
          // Create the root identifier and set the IdentifierType.
          document::Identifier identifier = task.docInfoBuilder().createIdentifier("/Root");
          identifier.setIdentifierType(id::Folder);

          // Add root Identifiers.
          // The parameters are the Identifier, and a name for display purposes.
          task.addIdentifier(identifier, "RootReference");
        }

        // Loop over all parent Identifiers (excluding ROOT)
        for (ParentIdentifier parentIdentifier = task.nextParent();
          parentIdentifier;
          parentIdentifier = task.nextParent())
        {
          // Check the parent IdentifierType is a container that can be expanded
          if (parentIdentifier->identifierType() == id::Folder)
          {
            try
            {
              // Retrieve the children (may throw) and for each add the identifier.
          
              // Create the child identifier and set the IdentifierType.
              document::Identifier identifier = task.docInfoBuilder().createIdentifier("/Root/Child");
              identifier.setIdentifierType(id::File);

              // Add child identifier
              // This call is the same structure as the root Identifier call except
              // for the additional first argument being the parent Identifier.
              task.addIdentifier(parentIdentifier, identifier, "ChildReference");
            }
            catch (const std::exception& ex)
            {
              task.addError(parentIdentifier, ex.what());
            }
          }
        }
      }
   }