Contents x
    Script Hooks: External Scripting with Event Handlers
    • 24 Oct 2023
    • 3 Minutes to read
    • Print
    • Dark
      Light
    • PDF
    Contents

    Script Hooks: External Scripting with Event Handlers

    • Updated on 24 Oct 2023
    • 3 Minutes to read
    • Print
    • Dark
      Light
    • PDF
    Article summary

    Hooks

    Overview

    Retrospect administrators can use Retrospect’s external scripting to hook into Retrospect’s events. These hooks can be used to integrate with monitoring systems, quiesce databases and other services before a backup starts or alert the administrator to unusual error conditions. Script hooks can also be used as web hooks, triggering events on services such as Slack or IFTTT.

    Retrospect triggers these events by calling a file named "RetroEventHandler". This file can be any script type known to the operating system (As examples for Windows, BAT or VBScript. For Mac, bash or ruby). They can even be compiled programs. For each event, Retrospect sends the name of the event followed by information specific for the event. Retrospect looks in the following locations:

    • Retrospect for Windows: C:\ProgramData\Retrospect and C:\Program Files\Retrospect
    • Retrospect for Mac: /Library/Application Support/Retrospect
    • Retrospect Client for Windows: C:\Program Files\Retrospect\Retrospect Client
    • Retrospect Client for Mac: /Library/Application Support/Retrospect Client/retroeventhandler
    • Retrospect Client for Linux: /etc/retroeventhandler

    Note that you do not need to restart the application for Retrospect to recognize the script hooks file. Also note that for Retrospect for Windows, script hooks are only supported for scripted executions, not immediate executions.

    Events

    Retrospect has fifteen events that can be handled by scripts. Retrospect client software has two of these events. Below are the event names and descriptions of when they are triggered.

    • StartApp occurs when Retrospect is opening, including when it is autolaunching.
    • EndApp occurs when Retrospect quits.
    • StartBackupServer occurs when Proactive Backup is about to start.
    • StopBackupServer occurs when Proactive Backup is stopped.
    • StartScript occurs when a script is about to start.
    • EndScript occurs when a script is finished.
    • StartSource occurs when a source is about to be accessed for the first time. This event is present in both the Retrospect application and Retrospect client software.
    • EndSource occurs when a source has finished being accessed. This event is present in both the Retrospect application and Retrospect client software.
    • MediaRequest occurs when Retrospect is about to request media, and again every five minutes while the media request window is open.
    • TimedOutMediaRequest occurs when Retrospect has requested media and it has waited longer than the time specified in the preferences.
    • ScriptCheckFailed occurs when Retrospect quits after running a script and there is a scheduled script set to run outside the look ahead time and the script check fails.
    • NextExec occurs when Retrospect quits after running a script and there is a scheduled script set to run outside the look ahead time and the script check passes.
    • SchedStop occurs when a script is running and about to stop because its allowed time of execution has expired.
    • PasswordEntry occurs after someone enters a password.
    • FatalBackupError occurs when a fatal backup error occurs.
    • AnomalyAlert occurs when an anomaly detection has been triggered.

    $interventionFile can be used in the launch script to stop the backup under certain conditions. For instance, you can stop it if you detect an anomaly.

    For specific information about each event, examine one of the example scripts available on our website.

    Example scripts

    The following example scripts are available on our website: "Retrospect_External_Scripts.zip".

    email notifier

    Windows specific batch file to illustrate emailing each event. (Old)

    ifttt

    Mac (Bash) and Windows (VBScript) example scripts that trigger an IFTTT Maker event

    lotus_domino

    Older Windows example script for quiescing a Lotus Domino server before backup and restarting it after the backup is complete. (Old)

    quitexchange_bat

    Example for pausing Microsoft’s Exchange server before backup and restarting it after backup is complete.

    quitoutlook vb

    Visual Basic application that would quit Microsoft Outlook before backup and restarting it after backup is complete. (Old)

    quitoutlook vbs

    Visual Basic script that would quit Microsoft Outlook before backup and restarting it after backup is complete. (Old)

    sample bat

    Windows Batch Script example. This triggers a dialog for each event.

    sample vb

    Visual Basic application example.

    sample vbs

    Visual Basic script example. As above, it triggers a dialog for each event.

    sample_c

    Windows command line application example. As above, it triggers a dialog for each event.

    sample_rb

    Event handler written in the Ruby language. This logs each event to a file.

    sample_sh

    Event handler written in the bash script language. This logs each event to a file.

    slack

    Mac (Bash) and Windows (VBScript) example scripts that send a Slack message.

    vcb

    Windows batch file to quiesce VMware VCB servers. (Old)

    Some of the Windows examples use custom command-line applications to do their work:

    In addition, we have a Knowledge base article that demonstrates using a retroeventhandler to back up SharePoint Team Services.

    ask

    Displays a dialog

    controlservices

    Starts or stops a Windows service

    mailsndr

    Command-line interface for sending email via smtp.

    Last Update: February 15, 2022

    Was this article helpful?
    What's Next