Guides and Sample Code

Developer

Mac Automation Scripting Guide

On This Page

Making a Systemwide Service

In OS X, services let you access functionality in one app from within another app. An app that provides a service advertises the operations it can perform on a particular type of data. Services are triggered from the Application Name > Services menu, or from contextual menus that appear when you Control-click on text, files, and other kinds of data. When you’re manipulating a particular type of data, related services becomes available. For example, Mail provides a service that creates a new email from selected text.

Making a Script Available as a Service

A script can be made available as a service by embedding it in an Automator service workflow.

To create a service workflow that runs a script
  1. Launch Automator, found in /Applications/.

  2. Create a new Automator document.

  3. When prompted, choose a document type of Service and click Choose.

    image: ../Art/automator_template_window_servicesselected_2x.png
  4. At the top of the Automator document, configure the service.

    image: ../Art/automator_workflow_document_serviceoptions_2x.png

    If the service will process a specific type of data, such as text, files, or images, select the appropriate type. Otherwise, select “no input.”

    If the service will be available within the context of a specific app only, select the appropriate app. Otherwise, select “any application.”

    If the service will replace selected text with processed text, select the “Output replaces selected text” checkbox.

  5. Type run in the search field above the action library pane to filter the action library.

    A list of actions for running AppleScripts, JavaScripts, UNIX shell scripts, and more are displayed.

    image: ../Art/automator_runscriptactions_2x.png
  6. Drag an action, such as Run AppleScript or Run JavaScript, to the workflow area.

    An interface for the action appears.

    image: ../Art/automator_workflow_runapplescriptaction_2x.png
  7. Write the script code and add it to the action. If the action contains additional configuration options, adjust them as needed.

    For AppleScripts and JavaScripts, use the action’s run handler template to process input data when the service runs, such as text or files. For workflows that replace selected text with processed text, be sure your workflow results in a text value. See Example Service Workflow Scripts.

    image: ../Art/automator_runapplexcript_textprocessingserviceexample_2x.png
  8. Save the Automator document.

    When prompted, enter a name for the service.

    image: ../Art/automator_saveservice_dialog_2x.png

Example Service Workflow Scripts

Listing 40-1 and Listing 40-2 provide example code that can be pasted into the Run AppleScript and Run JavaScript Automator actions to convert selected text to uppercase.

APPLESCRIPT

Open in Script Editor

Listing 40-1AppleScript: Example of an Automator service script that converts selected text to uppercase
  1. on run {input, parameters}
  2. set input to changeCaseOfText(input as string, "upper")
  3. return input
  4. end run
  5. on changeCaseOfText(theText, theCaseToSwitchTo)
  6. if theCaseToSwitchTo contains "lower" then
  7. set theComparisonCharacters to "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
  8. set theSourceCharacters to "abcdefghijklmnopqrstuvwxyz"
  9. else if theCaseToSwitchTo contains "upper" then
  10. set theComparisonCharacters to "abcdefghijklmnopqrstuvwxyz"
  11. set theSourceCharacters to "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
  12. else
  13. return theText
  14. end if
  15. set theAlteredText to ""
  16. repeat with aCharacter in theText
  17. set theOffset to offset of aCharacter in theComparisonCharacters
  18. if theOffset is not 0 then
  19. set theAlteredText to (theAlteredText & character theOffset of theSourceCharacters) as string
  20. else
  21. set theAlteredText to (theAlteredText & aCharacter) as string
  22. end if
  23. end repeat
  24. return theAlteredText
  25. end changeCaseOfText

JAVASCRIPT

Open in Script Editor

Listing 40-2JavaScript: Example of an Automator service script that converts selected text to uppercase
  1. function run(input, parameters) {
  2. var selectedText = input[0]
  3. return selectedText.toUpperCase()
  4. }

Triggering Service Workflows

Saved Automator service workflows automatically appear in services menus throughout the system at the appropriate time. For example, text processing workflows become available when you select text in an app. To run a service, select Application Name > Services > Service Workflow Name from the menu bar, or select Services > Service Workflow Name from a contextual menu.