4.9  Agents

Agents are what trigger the work of syncing and sorting your bookmarks when changes are detected.

       Topics on this Page

4.9.1  Controls for Agents

Smarky and Synkmark use Agents under the hood to perform their syncing, and you control them in Preferences > Syncing.

Markster does not support syncing nor Agents.

In BookMacster, you control Agents in a document’s Settings > Agents tab.

All Agents have Commands and Triggers, as described below, but in the Simple view, you don’t see them.  Checking boxes ON will create one or two Agents, pre-configured to do what most people want.

By default, the Simple Agents subtab is displayed.  This tab is gives enough detail to configure BookMacster agents for keeping bookmarks in a single browser sorted, or sync multiple browsers.  Users who desire more (or less) may use the Advanced Agents subtab.

Note that the settings in this tab are not kept in the .bkmslf document.  Instead, they are Local Settings.

4.9.2  Advanced Agents

In the Settings > Agents > Advanced tab of a Bookmarkshelf, you can create customized Agents.  Agents are a feature provided by Mac OS X which dispatch a BookMacster Worker process to do some work on your Bookmarkshelf whenever certain triggers occur.

The conditions which trigger Agents to spring into action are called, well, Triggers, and the work that they do is defined by a sequence of Commands.

In the Advanced view, note that the Triggers and Commands shown in the two lower tables are those of the Agent which is selected in the upper table.  To add an item, click the nearby button.

The order of Triggers does not make any difference, but of course the order of Command execution is significant.  To reorder commands, either drag and drop, or select a command and type ⌘↑ or ⌘↓.

Deactivating or Removing Agents

If you would like to temporarily deactivate an Agent, un-check the box in its Active column.  To remove an Agent permanently, select it and click the button next in the top table in the Settings > Agents tab.

Triggers

Triggers are events which cause the Commands of a BookMacster Agent to execute.

Triggers have a trigger type and an optional detail.  For example, the scheduled trigger type is triggered every day or every week at a certain time.  Its detail is the scheduled time and days.  The available trigger types are explained in subsequent sections on this page.

The necessary trigger(s) are created for you automatically when you check one of the boxes in the Simple tab of Settings > Agents.  To see what trigger(s) were created, or to modify triggers, click the Advanced tab.

If an Agent has more than one trigger, there is no significance to the order of the triggers.

Trigger Types

I log in to my Mac Trigger Type

This trigger will run commands when you log into your Macintosh User Account.  Besides being handy for people who like to start their day in sync, this trigger is recommended if your Bookmarkshelf document file might be updated while you are logged out.  ChronoAgent, for example, can do this, and it is conceivable that other processes could update a .bkmslf file before Mac OS X has loaded the *Other Mac updates this file” trigger. This trigger has an option; choose one of the following…

Bookmarks Changed Trigger Type

The Bookmarks Changed trigger is available only if one of your Import or Export Clients is the Safari, Firefox, or one of the (Google) Chrome bookmarks on your Mac account.  The reason is that only these browsers are capable of notificy BookMacster when their bookmarks change.  For other locally-installed browser apps, use the Browser Quit trigger (see below) instead.  For web-based browser apps (Delicious, Pinboard, Diigo, Google Bookmarks), this trigger does not function because none of these services push their changes.

Other Mac updates this file Trigger Type

This trigger is activated whenever a Online File Syncing Service (or, actually, any other app) updates the Bookmarkshelf file.  Note that when setting Commands for such a trigger, it is not necessary to “reload” or “reopen” the Bookmarkshelf, even if it is already open, because Bookmacster does that automatically, presenting the new content.  Typically, with this trigger you will only execute one Command, which is to Export – this is the trigger that is set when you activate the Simple Agent to Export Changes from Other Macs to Clients.

New bookmark is landed from browser Trigger Type

This trigger is activated following each [landing of a new bookmark to BookMacster directly.  The export is delayed in case you want to edit the newly-landed bookmark in the Inspector panel.  If the Inspector is not displayed when the new bookmark is landed, the export occurs immediately.  If the Inspector is being displayed, the export occurs when you close the Inspector panel, or until you do not edit anything for 30 seconds, whichever comes first.

(Because this trigger can only occur when BookMacster is running, it does not require a launchd Agent like the other trigger types, but is really just a switch inside BookMacster.)

Browser Quit Trigger Type

The Browser Quit trigger is only available if one or more of your Import or Export Clients is that of a local browser app with bookmarks on your Mac account.  This trigger is actually “as soon as possible” for browsers that do not allow BookMacster or its Worker to edit their bookmarks while they are running.  (For Safari, you can get a sooner trigger by using the Bookmarks Changed trigger, see above.)

Scheduled Trigger Type

This trigger allows you to schedule an action to be performed daily or weekly at a specified time.  The time must be entered in the right-hand column using the 24-hour clock system.

Commands

Commands is a sequence of instructions which an Agent gives to a worker to perform the task you desire.  A command is typically something that you could do manually yourself by clicking an item in the main menu.  Often, they have the same name and do the same thing.  Some commands are Import, Sort, Export, Save Document, etc.

Note that there is no Open or Open Document command because this is implied.  Commands are attributes of an Agent which are in turn attributes of a particular Bookmarkshelf document that must be opened in order for the commands to be performed.

Some commands have a detail associated with them.  For example, the Export commands have a detail setting which specifies what to do if the export cannot be executed because a web browser app is running (abort, quit the web browser app, or force quit the web browser app).

The necessary command(s) are created for you automatically when you check one of the boxes in the Simple tab of Settings > Agents.  To see what command(s) were created, or to modify commands, click the Advanced tab.

In the Advanced view, you can move a command within the sequence by selecting it and typing ⌘↑ or ⌘↓, or by drag and drop.

The Revert command is now superfluous in most cases, because current versions of BookMacster are constantly watching open .bkmslf files and immediately read in any changes they see, and of course Workers must always load the Bookmarkshelf file from the disk when they begin because they are transient creatures.  This command is kept for compatibility.

Options for Import and Export Commands

When you select an Import or Export command, the next detail column offers a popup menu in which you select what to do if a web browser which is involved is running, and will not allow BookMacster to read or write its bookmarks as required.

Cancel.  The commands (sorting, whatever) will not be performed.  The Agent will try to run the commands again at the next scheduled time.

Quit.  The browser will be asked to Quit.  Normally, it will quit.  But there are many circumstances under which a browser could refuse to quit.  One example is if you have set in the browser’s preferences an option to “ask you” if windows or tabs should be closed.  It will display a dialog.  Another example, unexpected, is if the browser has recently been launched and is displaying a “Update is available, do you want me to install it now” message.  Finally, if you start to enter data into a web form, most browsers will display a dialog warning you that the data you have entered will be lost.  In any of these cases, if you are not there to dismiss the dialog, the browser will refuse to quit.

Force Quit.  In this case the browser will be asked to Quit, and if it refuses, BookMacster will “kill” it without regard to what dialogs are being displayed.

If BookMacster quits or force-quits a browser, it will automatically re-launch the browser for you after it is done.  Most browsers nowadays have a preference setting to restore your previous windows and tabs, loading all of the web pages currently being displayed.  Thus, with such a preference setting enabled, the Quit option is a good choice if your Agent is scheduled to run when you are not normally at your computer.  When you return, the job will have run and your browser will be displaying the same web pages as it was before the job started.

4.9.3  Agents are Lazy

In order to not slow down your Mac and your internet connection with frivolous processing, BookMacster and Online File Syncing Services such as Dropbox are designed to coalesce changes and sync lazily.  Changes from one Client to another on a local Mac may take up 9 minutes, and changes to Clients on another Mac may take up to 12 minutes to appear.  (Usually, those times are only 5 and 8 minutes, but there is an additional wait after BookMacster has synced, which you come into play if you make some changes, BookMacster syncs, and then you make more changes.)

This works fine as long as you only work on one Mac at a time.  If you feel you know what you’re doing and want syncing to be faster, you can change the value in Preferences > Syncing > Minutes to wait before importing changes from web browsers.  When set to the minimum value of 0-1, syncing should occur within 2 minutes on the local Mac and 5 minutes to your other Macs.  The latter time depends greatly on your Online File Syncing Service, Dropbox™ or whatever you’re using.

4.9.4  Agents Use launchd

Most of BookMacster’s Agents are implemented by one or more  launchd agents, a facility provided by Mac OS X.  BookMacster’s launchd agent files are in the directory

   ~/Library/LaunchAgents/

The launchd agent files are either trigger files, or a special quit watch file.

A trigger file implements a single Trigger in a single Agent, and has a name of the form

   com.sheepsystems.BookMacster.XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.YYY.ZZZ.plist

The part with all the XXXs is the unique identifier of the Bookmarkshelf on whose behalf it acts.  The YYY is three decimal digits saying which agent in the Bookmarkshelf this launchd agent is acting for, and the ZZZ is similarly three decimal digits saying which trigger it implements.  The YYY and ZZZ begin with 000 for the first agent or trigger in the table, 001 for the second, etc.

The special quit watch file has a name of the form

   com.sheepsystems.BookMacster.QuatchRunner.plist

This special file is installed whenever you save a Bookmarkshelf whose Agents contain one or more triggers that are of the browser  quit trigger type.  Its job is to keep running a little process which watches for browser apps to quit (because, unfortunately, launchd does not provide this service).  The process it keeps running is an instance of BookMacster-Quatch which is included in the BookMacster application package.

4.9.5  Workers

Agents, however, do not do any actual work.  When one of its triggers occurs, an Agent triggers an invisible Worker process.  Technically, the Worker is a running instance of the BookMacster-Worker helper tool which is included in the BookMacster application package.  It typically runs for ten seconds or so and then terminates itself, when the work is done.

First, the worker does several checks to make sure that BookMacster has not caused the trigger by an export, that another Worker is not already running, that the relevant Agent has not just been created within the last few seconds, that a Online File Syncing Service is not in the process of writing the file, etc.  If all the tests pass, then the Worker determines what to do as follows…

• If BookMacster is the active application and the Bookmarkshelf which the Worker needs is open and has unsaved changes, the syncing is skipped.  The pending changes will be imported the next time that a syncing is triggered.

• If BookMacster is running, and the Agent’s Bookmarkshelf is open, the Worker sends an AppleScript message to BookMacster, instructing BookMacster to perform the Commands.  If the bottom of the Bookmarkshelf is visible on the screen when this happens, you may notice the progress being indicated in the Status Bar.  If your use case is for BookMacster to sync bookmarks, we recommend leaving BookMacster quit in order to avoid this annoyance, except when you want to do bookmarks housekeeping.  Before beginnning your housekeeping, click the Syncing button to temporarily pause syncing.

• If BookMacster is not running, or if BookMacster is running but the Agent’s Bookmarkshelf is not open, then the Worker opens the Bookmarkshelf and silently performs the Commands itself.  If a Worker finds that a browser is running and you have set it to Force Quit if necessary, it will first try a normal Quit and Force Quit only if the normal Quit fails.  In either case, after reading or writing bookmarks, the Worker will re-launch any browser that has been Quit or Force Quit.

In all cases, the Worker process terminates itself when the work is done.

Testing and Troubleshooting Aids

If syncing is not performing as you expect, it is sometimes helpful to be alerted when actions occur, or watch what is happening as it happens.

Sound Effects

In the application menu click Preferences, then the Syncing tab and finally the Sound Effects… button which will show some checkboxes.

Real-Time Log

To see Workers in action, in even more detail, in the application menu click Logs and view the Logs tab.  Periodically hit the round Refresh button at the top of Logs to get new entries from Workers.

Workers have Your File System Permissions

Worker operations spawned by Agents will fail if you do not have permission to access the required data.  For example, when you import or export bookmarks on another Macintosh User Account manually in BookMacster, BookMacster requires you to enter an administrator password.  However, your Worker does not know the password, so the operation will fail.  (Note: Other applications have solved similar problems by setting the setuid bit and ownership to root on their tool, but this is a security risk and so BookMacster does not do this.)

4.9.6  Clean-Up of Orphaned Agents

BookMacster remembers the documents in which you have set Agents.  Each time you launch BookMacster, in the background, it runs through each of these and makes sure that they exist, are not in your Trash, and have not been replaced by a Online File Syncing Service update.   If any of these tests fail, BookMacster removes any of their Agents.  The same thing happens if an Agent cannot find its document when it tries to run.

Also, when the last Bookmarkshelf() which had an Agent with a browser quit trigger type is saved without such a trigger, the quit watch file is removed and the BookMacster-Quatch process is terminated.  In other words, BookMacster-Quatch only runs if one or more Bookmarkshelves need it.