Skip to content

Mediator API / mediator.pl

Background

Mediator is an API containing a number of administrative tasks that can be triggered via a REST API, or via the command line.

Command line usage

mediator.pl is used to trigger administrative actions, either locally or on a remote Funnelback server:

mediator.pl TaskToRun[@host[:port]] arg1=value1 ... argN=valueN

Where:

TaskToRun

Name of the task / action to run.

host

Optional host where the task should be run (fully-qualified hostname). If not set the task is run locally.

port

Optional port to use to contact the remote host.

argN=valueN

Arguments specific to the taskThe list of available tasks can be obtained by running:

mediator.pl --list-tasks

For the remote invocation to work the remote and local server must share the same server_secret in $SEARCH_HOME/conf/global.cfg. Special care must be taken when changing the server secret, see the server_secret page for details.

Examples

Obtain the list of collections on the local server (--verbose is required there to get the return value of the task, which is the collection list):

mediator.pl --verbose ListCollections

Obtain the list of collections from a remote server:

mediator.pl --verbose ListCollections@server.domain.com

Push the complete intranet collection from the local server to a remote host:

mediator.pl PushCollection collection=intranet host=server.domain.com

Push the complete intranet collection from the server1 host to the server2 host (The task will be invoked on server1, and server1 will push its intranet collection to server2):

mediator.pl PushCollection@server1.domain.com collection=intranet host=server2.domain.com

REST API endpoint

The mediator tasks can also be triggered through a REST endpoint, available at https://FUNNELBACK-SERVER/search/admin/mediator/ . This URL returns a list of all available tasks and their parameters. To call a specific task, use

https://FUNNELBACK-SERVER/search/admin/mediator/Task?param1=value1... 

The example below uses the REST endpoint to push the 'intranet' collection to the server.domain.com remote host:

https://FUNNELBACK-SERVER/search/admin/mediator/PushCollection?collection=intranet&host=server.domain.com

This endpoint requires authentication, and the user must have the sec.service.mediator permission.

The output format is XML by default, but JSON is also available since v13.2. To choose an output format:

  • Either suffix the REST call with .json or .xml: mediator/PushCollection.json?collection=...
  • Set the appropriate Accept: ... header in the HTTP request: Accept: text/xml or Accept: application/json

Mediator tasks

Task: AllCollectionsConfiguration

Get the configurations of all collections on the server

Arguments:

No arguments

Task: ArchiveLogs

Archive the queries and clicks logs of a collection

Arguments:

  • collection (String) : (Required) Identifier of a collection
  • view ([live|offline]) : Which view to archive (offline or live)

Task: ClearLocks

Clear the update locks and status of a collection

Arguments:

  • collection (String) : (Required) Identifier of a collection

Task: GetConfiguration

Get the configuration of a collection

Arguments:

  • collection (String) : (Required) Identifier of a collection

Task: GetFunnelbackVersion

Get the version of Funnelback

Arguments:

No arguments

Task: GetIndexTime

Get the last time an index was updated (based on the index_time file)

Arguments:

  • collection (String) : (Required) Identifier of a collection
  • view ([live|offline]) : Which view to get the time from (offline or live)

Task: GetProgress

Get the current update progress of a collection

Arguments:

  • collection (String) : (Required) Identifier of a collection

Task: ListCollections

Get the list of all existing collection IDs

No arguments

Task: PullLogs

Pull queries and clicks logs of a collection from a remote server

Arguments:

  • collection (String) : (Required) Identifier of a collection
  • host (String) : (Required) Hostname of the target to pull from
  • port (int) : Port of the remote target WebDAV service
  • recursive (boolean) : Should the pull be recursive (default=true), if set folders will replace files in local.

Task: PushCollection

Push a complete collection (configuration + data) to a remote server

Arguments:

  • collection (String) : (Required) Identifier of a collection
  • host (String) : (Required) Hostname of the target to push to
  • delete (boolean) : Whether to delete remote files that don't exist locally
  • mediatorPort (int) : Port of the mediator service (Admin UI port)
  • mediatorProtocol ([http|https]) : Protocol of the mediator service (Admin UI protocol)
  • pushType ([COMPLETE_COLLECTION|QP|ADMIN|ADMIN_AND_QP]) : Describes what is to be pushed, Defaults to QP
  • smart (boolean) : Whether to send only files that have changed based on their filesize
  • webdavPort (int) : Port of the remote target WebDAV service

Task: PushConfigFile

Push a collection config file to a remote server

Arguments:

  • collection (String) : (Required) Identifier of a collection
  • filePath (String) : (Required) Path of the file to push, relative to the collection or profile configuration folder
  • host (String) : (Required) Hostname of the target to push to
  • port (int) : Port of the remote target WebDAV service
  • profile (String) : Which profile to push (_default, _default_preview, or a custom one). If not set the file will be taken from the collection config directory.

Task: PushInstantUpdate

Push instant update changes to a remote server

Arguments:

  • collection (String) : (Required) Identifier of a collection
  • host (String) : (Required) Hostname of the target to push to
  • delete (boolean) : Whether to delete remote files that don't exist locally
  • mediatorPort (int) : Port of the mediator service (Admin UI port)
  • mediatorProtocol ([http|https]) : Protocol of the mediator service (Admin UI protocol)
  • port (int) : Port of the remote target WebDAV service

Task: PushLogs

Push queries and clicks logs of a collection to a remote server

Arguments:

  • collection (String) : (Required) Identifier of a collection
  • host (String) : (Required) Hostname of the target to push to
  • port (int) : Port of the remote target WebDAV service

Task: PushView

Push a view of the index and data of a collection to a remote server

Arguments:

  • collection (String) : (Required) Identifier of a collection
  • host (String) : (Required) Hostname of the target to push to
  • view ([live|offline]) : (Required) Which view to push (offline or live)
  • delete (boolean) : Whether to delete remote files that don't exist locally
  • port (int) : Port of the remote target WebDAV service
  • pushAll (boolean) : Whether to push ALL folders in the view, in addition to the one required to serve queries
  • remoteView ([live|offline]) : Which remote view to write in (offline or live). Defaults to the value of view
  • smart (boolean) : Whether to send only file that have changed based on their filesize

Task: RecordStatistics

Record the given statistics

Arguments:

  • collection (String) : (Required) Identifier of a collection
  • phase ([pre_gather_command|gather|post_gather_command|pre_instant_gather_command|instant_gather|post_instant_gather_command|pre_convert_command|convert|post_convert_command|pre_instant_convert_command|instant_convert|post_instant_convert_command|pre_index_command|index|post_index_command|pre_instant_index_command|instant_index|post_instant_index_command|pre_report_command|report|post_report_command|pre_swap_command|swap|post_swap_command|pre_meta_dependencies_command|meta_dependencies|post_meta_dependencies_command|pre_archive_command|archive|post_archive_command|pre_delete_prefix_command|delete_prefix|post_delete_prefix_command|pre_delete_list_command|delete_list|post_delete_list_command|pre_vacuum_command|vacuum|post_vacuum_command|pre_update_command|update|post_update_command|recommender|post_update_tasks]) : (Required) Update phase (e.g. pre_crawl, index etc.)
  • updateStartTime (String) : (Required) Start time for overall update
  • endTime (String) : End time for operation
  • exitCode (String) : Exit code for operation
  • startTime (String) : Start time for operation
  • updateType (String) : Update type (e.g. incremental, refresh etc.)

Task: SetupViews

Setup the offline and live views (symlinks) for a collection

Arguments:

  • collection (String) : (Required) Identifier of a collection
  • liveFolder ([one|two]) : (Required) Which folder to assign to the live view (offline will be set accordingly)
  • collectionRoot (File) : A pre configured collection root for testing

Task: StartFilecopySlave

Start a filecopy slave process

Arguments:

  • collection (String) : (Required) Identifier of a collection

Task: StopUpdate

Stop a currently running update

Arguments:

  • collection (String) : (Required) Identifier of a collection

Task: SwapInstantUpdate

Moves instant update files from the instant update temporary directory into the live index

Arguments:

  • collection (String) : (Required) Identifier of a collection
  • timeOutMS (int) : Timeout in milliseconds for waiting to acquire the index lock. High query volume may prevent acquiring this lock

Task: SwapViews

Swap the offline and live view for a collection

Arguments:

  • collection (String) : (Required) Identifier of a collection
  • force (boolean) : Whether to ignore the changeover conditions

Task: ValidateExternalMetadata

Validate per-profile external_metadata.cfg files and concatenate them into the collection configuration folder

Arguments:

  • collection (String) : (Required) Identifier of a collection
  • errorThreshold (float) : Maximum error threshold before failing
  • mode ([check|concatenate]) : Mode of operation, check or concatenate

See also

top

Funnelback logo
v15.24.0