Help Center

Menu

Mediator API / mediator.pl

This feature is not available in the Squiz DXP.

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: GetFunnelbackVersion

Get the version of Funnelback

Arguments:

No arguments

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

  • mediatorProtocol ([http|https]) : Protocol of the mediator service

  • 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 file size

  • 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

  • mediatorProtocol ([http|https]) : Protocol of the mediator service

  • 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: 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: 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