Implement Custom Fetch Actions

You can implement custom fetch actions in a ConnectorLib C++ connector.

Action Description Method to override
action=Fetch&FetchAction=MyAction Perform custom fetch actions on a repository. customFetch

First add the custom_fetch feature to the list of supported features returned by the features function on ConnectorBase:

       Features::feature_type MyConnector::features() 
       { 
          return Features::synchronize|Features::collect|Features::custom_fetch;
       } 

To implement a custom fetch action, override the customFetch method on the ConnectorBase interface.

The customFetch method is passed the name of the fetch action that was called in the request. The name is always in upper case, because action names are case-insensitive. You can use the customFetch method to handle as many fetch action names as necessary, however the action names SYNCHRONIZE, COLLECT, HOLD, and so on, are reserved by the connector for the standard fetch actions.

The customFetch method is also passed a CustomFetchTask object. The CustomFetchTask object provides access to a request object which provides all of the action parameters. You can access action parameters using task.request().getParameter(parameterName).

Other resources, including a collection of identifiers and an ingester, are available through the CustomFetchTask object. You can use these in your implementation of the custom fetch action.

The customFetch method can run many times for a single request; each time it is passed a different CustomFetchTask instance. The number of times that the customFetch method runs is determined as follows:

  • The customFetch method runs for each distinct configuration file section name embedded in the identifiers (provided by the identifiers or identifiersXML action parameters) or included in the request (using the configsection or tasksections parameters). The configsection parameter accepts a single name. The tasksections parameter accepts a comma-separated list of names.
  • If no configuration file sections are provided by identifiers or by the configsection or tasksections parameters, then the customFetch method runs one time for each task listed in the [FetchTasks] section of the configuration file.
  • If no fetch tasks are configured in the connector's configuration file, the customFetch method does not run and the following warning is written to the connector's logs:

    WARNING: Custom fetch action is not associated with any task configuration sections, no tasks will be executed

Your code must use the parameters from the request to perform the action and populate the action response. Use the method response.setValue(elementName, value) to set the value of XML elements in the response.

You can add attributes and nested elements to the action response using XPath-like expressions with element indexes. For example:

       Response.setValue("document[0]/metadata[7]/@name", "MyField");

Your implementation of the customFetch method should return false only if the fetch action name is not supported. In all other cases, return true. If another failure occurs then throw an exception from the customFetch method, giving the reason for the failure.

The following sample code shows how a custom fetch action might be implemented for a basic connector. This example provides action=fetch&FetchAction=count, and counts the files below a list of paths:

      bool MyConnector::customFetch(const std::string& action, const CustomFetchTask& task) 
      { 
         if (action == "COUNT") 
         { 
            auto paths = task.taskConfig().getCollection("DirectoryPathCSVs"); 

            std::size_t count = 0; 
            for (const std::string& path : paths) 
            { 
                // Count files below path 
            } 
            task.response().setValue("file_count", count); 
           
            return true; 
         }  

         return false; 
      }