Skip to main content

Fredhopper Deployment Agent API

Rumyana Grigorova
  • Updated

    This document provides detailed information about how to setup, configure and start a Fredhopper Deployment Agent, as well as how to use its command line client or directly its REST API.

    Starting the Agent

    The agent can be started from the command line using these commands:

    $ bin/deployment-agent [arguments]

    The agent logs into data-directory/log/agent.log.

    Arguments

    -d, --directory Data directory Required
    -i, --address IP address to bind the agent Default is to bind to all local addresses
    -p, --port Port on which agent listens Default is 8177
    -f, --foreground Run in foreground Log to the console as well, and react to keypresses on the console
    -v, --version Show version information  
    -h, --help Show a summary of the available command line arguments  

    Running the Client

    $ bin/deployment-agent-client [global options] [command] [command arguments]

    See the sections about global options and commands below.

    Global Options

    Typical global client options

    --location A URL pointing to the agent Default is http://localhost:8177
    -O, --output Name of the output file Default is console
    --type MIME type to request Default is text/plain, unless noted otherwise in the command description
    -v, --version Show version information  

    Commands

    Optional arguments come before the required arguments, for example:

    $ deployment-agent-client install --name 'Installation1' fredhopper-releases/FAS6_2_3.zip

    Installations and Instances

    • create-installation URL

    Install a distribution archive. Required Arguments: URL of the distribution, Optional Arguments: --name <name>

    Alias: install

    • remove-installation [--force] name

    Uninstall a distribution. If '--force' is given instances will be stopped and removed, otherwise uninstall fails if instances still exist.

    Alias: uninstall

    • describe-installation name

    Get the configuration settings of the named installation.

    • rename-installation [--force] originalName newName

    Rename an installation, if '--force' is given instances' processes will be stopped before removal, otherwise removal fails if processes are still running.

    • create-instance name installation-name

    Create a new instance

    Alias: create

    • remove-instance [--force] name

    Remove an instance, if '--force' is given processes will be stopped before removal, otherwise removal fails if processes are still running.

    Alias: remove

    • describe-instance name

    Get the configuration settings of the named instance.

    • rename-instance [--force] originalName newName

    Rename an instance, if '--force' is given processes will be stopped before removal, otherwise removal fails if processes are still running.

    Controling Processes

    • invoke [-Dname=value...] instance process verb

    Invoke a verb of a process of an instance.

    File Management

    • get path

    Get a file from the server. Optional arguments: --instance <name>, --installation <name> to select source.

    • put URI location

    Put a file onto the server. Optional arguments: --instance <name>, --installation <name> to select target.

    • delete path

    Delete a file on the server. Optional arguments: --instance <name>, --installation <name> to select target.

    Discovery

    • list-instances [--installation installation-name]

    Show all available instances. If a particular installation is specified with the argument <installation-name> then list only its instances.

    • list-installations

    Show all available installations

    • list-processes instance

    Show all available processes for the instance.

    • list-verbs instance process

    Show all available verbs for the particular process.

    • environment

    Show the environment as seen by the daemon. This will be given to newly started processes.

    • info

    Show general information about the agent like version properties, base installations directory and base instances directory.

    Role Management

    • add-role instance role-definition-URL

    Add a role defined by the role XML at the URL into the instance.

    • remove-role instance role-name

    Remove the named role from the instance.

    • get-role instance role-name

    Get the role definition XML for the named role from the instance.

    • list-roles instance

    List all available roles of the given instance.

    • invoke-command [--role role-name] [-Dname=value...] instance command-name

    Invoke the command <command-name> for the given role on the instance. If no role is given, the default role will be used if available.

    Importing/Exporting of Instance Configuration and Data

    • export-capture [-c] [-i] [-l] [-x] [-s] instance

    Export a capture from the named instance. Use the -O switch to define the output file name. Use any of the options to specify what should be included in the capture: -c - config data; -i - indices; -l - log files; -x - processed XML; -s - stack traces of processes.

    Alias: create-capture

    • import-capture instance [sourceURI]

    Import a capture from the named URI or standard input into the named instance.

    Monitoring

    • get-jmx instanceName processName objectName attributeName

    Get a JMX-exposed value from the process

    • set-jmx instanceName processName objectName attributeName [value]

    Set a JMX exposed value. If <<value>> is not given it will be taken from the standard input

    • list-jmx instanceName processName

    List available JMX object names

    • list-jmx instanceName processName objectName

    List available JMX attribute names.

    URL Patterns and Responses

    • ROOT

    GET: Show daemon settings (text/plain)

    • ROOT/environment

    GET: Show daemon environment (text/plain, key=value pairs, # marks comments)

    • ROOT/log

    GET: show all logs of the agent, ROOT/log/agent.log is the latest one

    • ROOT/monitor

    GET: show available monitoring groups

    • ROOT/monitor/{group}

    GET: show available monitoring values in the group

    • ROOT/monitor/{group}/{value}

    GET: get a monitoring value, POST: set a value

    • ROOT/instance

    GET: List available instances (text/plain)

    • ROOT/installation

    GET: List available installations (text/plain)

    • ROOT/instance/{name}

    GET: Describe instance configuration (text/plain), PUT: create instance, POST: rename instance, DELETE: remove instance

    • ROOT/installation/{name}

    GET: Describe installation configuration (text/plain), PUT: create installation, POST: rename installation, DELETE: remove instance

    • ROOT/instance/{name}/universes

    GET: Get a list of configured universes (text/plain, one universe per line)

    • ROOT/instance/{name}/browse/{path}

    GET: download file from instance, PUT: upload file for instance, DELETE: remove file

    • ROOT/installation/{name}/browse/{path}

    GET: download file from installation, PUT: upload file for installation, DELETE: remove file

    • ROOT/instance/{name}/process

    GET text/plain: show all available processes

    • ROOT/instance/{name}/process/{process}

    GET text/plain: get process name

    • ROOT/instance/{name}/process/{process}/verb

    GET text/plain: list process verbs, one per line

    • ROOT/instance/{name}/process/{process}/verb/{verb}

    GET (properties as query parameters)/POST (text/plain Properties): invoke verb of process with properties

    • ROOT/instance/{name}/process/{process}/monitor

    GET: show available monitoring groups

    • ROOT/instance/{name}/process/{process}/monitor/{group}

    GET: show available monitoring values in the group

    • ROOT/instance/{name}/process/{process}/monitor/{group}/{value}

    GET: get a monitoring value, POST: set a value

    • ROOT/installation/{name}/preset/{presetname}

    GET text/plain: get properties defined by a named preset

    • ROOT/installation/{name}/presets

    GET text/plain: list all known presets of an installation

    • ROOT/instance/{name}/preset

    GET text/plain: get the instance preset

    • ROOT/instance/{name}/preset?name={settingname}

    GET text/plain: get the value of the setting from the preset, POST text/plain: set the value of the setting, DELETE: remove the setting from the preset.

    • ROOT/instance/{name}/role/add

    PUT text/xml: add the role from the XML definition

    • ROOT/instance/{name}/role/{role}

    GET text/xml: get the role definition, DELETE: remove the role

    • ROOT/instance/{name}/role/{role}/{command}

    GET (properties as query parameters)/POST (text/plain Properties): execute the command of the role with properties

    • ROOT/instance/{name}/{command}

    GET (properties as query parameters)/POST (text/plain Properties): execute the command of the default role if a default role is available with properties.

    • ROOT/instance/{name}/capture

    GET (application/x-fredhopper-export+zip or application/zip): export a capture, POST (application/x-fredhopper-export+zip or application/zip): import a capture.

     

    Support for Suggest Service

    The Fredhopper Suggest service can be installed and used in the deployment agent using the standard create-installation, create-instance, import-capture, and invoke commands.

    After creating the suggest instance you should import a capture containing your configuration and suggest indices. The capture has the following structure:

    capture.zip

    • config
      • suggest configuration
    • data
      • suggest
        • suggest data files goes here ...

    The suggest service can then be started, and will by default answer requests on port 8380.

    For more information see Suggest Reference.

    Related articles

    Comments

    0 comments

    Article is closed for comments.