Mac Developer Library

Developer

Automator Framework Reference AMAction Class Reference

Options
Deployment Target:

On This Page
Language:

AMAction

Inheritance


Conforms To


Import Statement


Swift

import Automator

Objective-C

@import Automator;

Availability


Available in OS X v10.4 and later.

AMAction is an abstract class that defines the interface and general characteristics of Automator actions. Automator is an Apple application that allows users to construct and execute workflows consisting of a sequence of discrete modules called actions. An action performs a specific task, such as copying a file or cropping an image, and passes its output to Automator to give to the next action in the workflow. Actions are currently implemented as loadable bundles owned by objects of the AMBundleAction class, a subclass of AMAction.

The critically important method declared by AMAction is runWithInput:error:. When Automator executes a workflow, it sends this message to each action object in the workflow (in workflow sequence), in most cases passing in the output of the previous action as input. The action object performs its task in this method and ends by returning an output object for the next action in the workflow.

Subclassing Notes

Subclassing AMAction is not recommended. For most situations requiring an enhancement to the Automator framework, it is sufficient to subclass AMBundleAction.

  • definition - definition (OS X v10.4)

    Returns the definition of the receiver.

    Deprecation Statement

    Removed for performance reasons. There is no replacement.

    Declaration

    Objective-C

    - (NSMutableDictionary *)definition

    Return Value

    A mutable dictionary containing the current parameters of the action as well as other information.

    Discussion

    If your action has non-persistent data, it may override this method to append that data to the definition supplied by the superclass and return it.

    Special Considerations

    This method was removed to allow for performance improvements in the underlying implementation. There is no replacement.

    Import Statement

    Objective-C

    @import Automator;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

  • Initializes the receiver with the specified definition.

    Declaration

    Swift

    init!(definition dict: [NSObject : AnyObject]!, fromArchive archived: Bool)

    Objective-C

    - (instancetype)initWithDefinition:(NSDictionary *)dict fromArchive:(BOOL)archived

    Parameters

    dict

    Describes the action, including any custom definition properties.

    archived

    If the receiver is being unarchived, YEStrue, otherwise NOfalse.

    Return Value

    The initialized action.

    Discussion

    This is the primary initializer for all Automator classes. The Automator application sends this message to instances of AMAction both when it loads actions bundles and when it unarchives them.

    The AMAction object being instantiated should perform whatever initializations are necessary after invoking super’s implementation of this method. It can then examine the values in dict, particularly if the receiver had been archived with custom definition properties.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.4 and later.

  • Loads an Automator action from a file URL.

    Declaration

    Swift

    init!(contentsOfURL fileURL: NSURL!, error outError: NSErrorPointer)

    Objective-C

    - (instancetype)initWithContentsOfURL:(NSURL *)fileURL error:(NSError **)outError

    Parameters

    fileURL

    URL that specifies the location of an action file.

    outError

    If no action is found or if an error occurs in initializing or running it, upon return contains an instance of NSError that describes the problem. For keys and error constants used with action errors, see Automator Constants Reference.

    Return Value

    The initialized action.

    Discussion

    This method is typically invoked by applications that use the AMWorkflow class to embed Automator workflows. It is used to allow creation of actions for a workflow.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.5 and later.

  • Examines the parameters and other configuration information specified in the passed dictionary and adds its own information to it if appropriate.

    Declaration

    Swift

    func writeToDictionary(_ dictionary: NSMutableDictionary!)

    Objective-C

    - (void)writeToDictionary:(NSMutableDictionary *)dictionary

    Parameters

    dictionary

    Possibly contains parameter and other configuration information about the receiver.

    Discussion

    Automator sends this message to an action object prior to archiving it. In its implementation of this method, the action object should first invoke the superclass implementation.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.4 and later.

  • Sent by the receiver to itself when it has finished running asynchronously.

    Declaration

    Objective-C

    - (void)didFinishRunningWithError:(NSDictionary *)errorInfo

    Parameters

    errorInfo

    If an error occurred during asynchronous running of the action, upon return contains an instance of NSError that describes the problem.

    Discussion

    An action that overrides runAsynchronouslyWithInput: should invoke didFinishRunningWithError: on completion, so that Automator can resume running the workflow that the action is part of.

    Special Considerations

    This method is deprecated. Use finishRunningWithError: instead.

    Import Statement

    Objective-C

    @import Automator;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.5.

  • Causes the action to stop running and return an error, which, in turn, causes the workflow to stop.

    Declaration

    Swift

    func finishRunningWithError(_ error: NSError!)

    Objective-C

    - (void)finishRunningWithError:(NSError *)error

    Parameters

    error

    The error to be returned to Automator.

    Discussion

    This method is intended to be called by any action that overrides runAsynchronouslyWithInput: in order to make asynchronous calls. Note that when finishRunningWithError: is invoked, it immediately calls willFinishRunning.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.7 and later.

  • Resets the receiver to its initial state.

    Declaration

    Swift

    func reset()

    Objective-C

    - (void)reset

    Discussion

    Resetting causes the action to release its output generated from the current execution of the workflow.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.4 and later.

    See Also

    – stop

  • Causes Automator to wait for notification that the receiver has completed execution, which allows the receiver to perform an asynchronous operation.

    Declaration

    Swift

    func runAsynchronouslyWithInput(_ input: AnyObject!)

    Objective-C

    - (void)runAsynchronouslyWithInput:(id)input

    Parameters

    input

    The input for the action. Should contain one or more objects compatible with one of the types specified in the action’s AMAccepts property.

    Discussion

    This method is intended to be overridden only by actions that need to make asynchronous calls. After runAsynchronouslyWithInput: is invoked, Automator does not continue until the action invokes finishRunningWithError:. So in your override of this method, you can make an asynchronous call, wait to be notified of its completion, then invoke finishRunningWithError: to signal to Automator that the action has completed.

    For actions that do not need to make asynchronous calls, the preferred method is runWithInput:fromAction:error:.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.5 and later.

  • Requests the receiver to perform its task using the specified input.

    Declaration

    Swift

    func runWithInput(_ input: AnyObject!, error error: NSErrorPointer) -> AnyObject!

    Objective-C

    - (id)runWithInput:(id)input error:(NSError **)error

    Parameters

    input

    The input for the receiving action. Should contain one or more objects compatible with one of the types specified in the action’s AMAccepts property.

    error

    If an error occurs, the action returns an NSError object in this parameter. For actions running AppleScript code, the following keys may be specified in the userInfo property of NSError, and they will be honored.

    • OSAScriptErrorNumber (a string constant) — The value for this key is an instance of NSNumber whose integer value indicates an error code. See the header file MacErrors.h in the Carbon Core framework for a list of valid error codes, particularly the section on OSA errors.

    • OSAScriptErrorMessage (a string constant) —The value for this key is an instance of NSString describing the error.

    Return Value

    An NSArray object containing one or more objects of a data type compatible with a type specified in the receiving action’s AMProvides property. If the receiver does not modify the data passed in input, it should return it unchanged. If the receiver does not have any data to provide, it should return an empty NSArray object.

    Discussion

    The input and output objects for actions are usually instances of NSArray. If the receiver encounters problems, it should return by indirection an NSError object that describes the error.

    This method is intended to be overridden.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.7 and later.

  • Requests the receiver to perform its task using the specified input from the specified action.

    Declaration

    Objective-C

    - (id)runWithInput:(id)input fromAction:(AMAction *)anAction error:(NSDictionary **)errorInfo

    Parameters

    input

    The input for the receiving action. Should contain one or more objects compatible with one of the types specified in the action’s AMAccepts property.

    By default, actions can only accept and provide the following types. However, by overriding this method, you can change the types your action can use:

    • Objective-C actions: Accepts and provides types must inherit from com.apple.cocoa.string, com.apple.cocoa.path, com.apple.cocoa.url, or, starting in OS X version 10.5 (v10.5), com.apple.cocoa.data.

    • Shell script actions: Accepts and provides types must inherit from com.apple.cocoa.string or, starting in OS X v10.5, com.apple.cocoa.data.

    • AppleScript actions: Accepts and provides types must inherit from com.apple.applescript.object.

    anAction

    The action from which the input object was obtained.

    errorInfo

    If an error occurs, the action returns an error dictionary in this parameter. The keys and values for this dictionary are:

    • OSAScriptErrorNumber (a string constant) — The value for this key is an instance of NSNumber whose integer value indicates an error code. See the header file MacErrors.h in the Carbon Core framework for a list of valid error codes, particularly the section on OSA errors.

    • OSAScriptErrorMessage (a string constant) —The value for this key is an instance of NSString describing the error.

    For an example of how to create such a dictionary, see “Implementing runWithInput:fromAction:error:” in “Implementing an Objective-C Action" in Automator Programming Guide.

    Return Value

    An object containing one or more objects of a data type compatible with a type specified in the receiving action’s AMProvides property. If the receiver does not modify the data passed in input, it should return it unchanged.

    Discussion

    The input and output objects for actions are usually instances of NSArray. If the receiver encounters problems, it should return by indirection an error dictionary that describes the error.

    This method is intended to be overridden. AppleScript actions, however, usually will not need to override this method because the same functionality is provided by an AppleScript script.

    Import Statement

    Objective-C

    @import Automator;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.4.

  • Stops the receiver from running.

    Declaration

    Swift

    func stop()

    Objective-C

    - (void)stop

    Discussion

    The output acquired by the action during execution of the current workflow is still accessible to Automator.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.4 and later.

    See Also

    – reset

  • Invoked by Automator when the receiver has essentially completed its run phase.

    Declaration

    Swift

    func willFinishRunning()

    Objective-C

    - (void)willFinishRunning

    Discussion

    This method is intended to be overridden only by actions that need to make asynchronous calls. An action can use this method to perform cleanup operations, such as closing windows and deallocating memory.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.5 and later.

  • Invoked when the window of the Automator workflow to which the receiver belongs becomes the main window. This allows the receiver to synchronize its information with settings in another application.

    Declaration

    Swift

    func activated()

    Objective-C

    - (void)activated

    Discussion

    Be sure to invoke the superclass implementation of this method as the last thing in your implementation.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.4 and later.

    See Also

    – opened

  • Invoked when the receiver is first added to a workflow, allowing it to initialize its user interface.

    Declaration

    Swift

    func opened()

    Objective-C

    - (void)opened

    Discussion

    You should perform all initializations of an action’s user interface in this method and not in awakeFromNib. Be sure to invoke the superclass implementation of this method as the final step of your implementation.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.4 and later.

    See Also

    – activated

  • Displays a message in Automator’s log area. Note that this message is visible to the user.

    Declaration

    Objective-C

    - (void)logMessageWithLevel:(AMLogLevel)level format:(NSString *)format, ...

    Parameters

    level

    The level of logging to perform. Options include AMLogLevelDebug, AMLogLevelInfo, AMLogLevelWarn, and AMLogLevelError.

    format

    A format string. See Formatting String Objects for examples of how to use this method, and String Format Specifiers for a list of format specifiers.

    ...

    A comma-separated list of arguments to substitute into format.

    Discussion

    Use this method if you wish to provide feedback to the user in Automator’s log area as your action runs.

    Import Statement

    Objective-C

    @import Automator;

    Availability

    Available in OS X v10.7 and later.

  • Requests the receiver to update its user interface from its stored parameters, which have changed.

    Declaration

    Swift

    func parametersUpdated()

    Objective-C

    - (void)parametersUpdated

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.4 and later.

  • Requests the receiver to update its stored set of parameters from the settings in the action’s user interface.

    Declaration

    Swift

    func updateParameters()

    Objective-C

    - (void)updateParameters

    Discussion

    This message is sent just before an action is saved, copied, or run. Preferably, an action’s settings should not solely reside in the controls of its view, but if they do, the action can fetch and save them in this method.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.4 and later.

  • Invoked by Automator when the receiving action is removed from a workflow, allowing it to perform cleanup operations.

    Declaration

    Swift

    func closed()

    Objective-C

    - (void)closed

    Discussion

    This method is intended to be overridden, so that your action can perform its specific cleanup operations.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.5 and later.

  • A Boolean value that indicates whether the action acts upon its input or the input is ignored. (read-only)

    Declaration

    Swift

    var ignoresInput: Bool { get }

    Objective-C

    @property(readonly) BOOL ignoresInput

    Discussion

    YEStrue if the action acts upon its input, otherwise NOfalse.

    Many actions act upon their input, but an action may merely pass on its input or, rarely, ignore it.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.5 and later.

  • name name Property

    The name of the action. (read-only)

    Declaration

    Swift

    var name: String! { get }

    Objective-C

    @property(readonly, strong) NSString *name

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.5 and later.

  • output output Property

    The action’s output.

    Declaration

    Swift

    var output: AnyObject!

    Objective-C

    @property(strong) id output

    Return Value

    The receiving action’s output, or nil if called before the action is run.

    Discussion

    nil if called before the action is run.

    This method is used in conjunction with the AMWorkflow class, which allows access to the actions in a workflow. Within a workflow, for example, you might iteratively inspect the output of each action. Or, on completion of a workflow, you might examine the output of the last action, to determine the output of the workflow.

    This parameter can also be used when running an action asynchronously. Call setOutput to specify the output the action produces.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.5 and later.

  • A float value between 0 and 1, which indicates how far along the action is while processing.

    Declaration

    Swift

    var progressValue: CGFloat

    Objective-C

    @property CGFloat progressValue

    Discussion

    Setting this value causes Automator’s action progress indicator (displayed as a workflow runs) to update in order to provide the user with an indication of progress.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.6 and later.

  • The type of input, in UTI format, of the input received by the action.

    Declaration

    Swift

    var selectedInputType: String!

    Objective-C

    @property(strong) NSString *selectedInputType

    Discussion

    Getting this value provides the type of input the action is configured to accept. For example, your action may have the ability to accept files and folders, or documents, depending on how it’s configured and what action precedes it in the workflow.

    The input types the action supports are specified in the action’s info.plist file. By default, this property defaults to first input type in the info.plist file.

    Through its interface, the action can could be configured to allow the user to specify the type of input the action should accept. For example, an Address Book action may allow the user to configure whether the action accepts people or groups. In cases like this, set this property value to explicitly indicate the input type the action accepts. Setting this value to accurately reflect the appropriate type of input helps Automator determine whether the input the action receives is compatible, or can be made compatible, with the action.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.6 and later.

  • The type of output, in UTI format, of the output to be produced by the action.

    Declaration

    Swift

    var selectedOutputType: String!

    Objective-C

    @property(strong) NSString *selectedOutputType

    Discussion

    Getting this value provides the type of output the action is configured to produce. For example, your action may have the ability to output files and folders, or documents, depending on how it’s configured or what it encounters while processing.

    The output types the action supports are specified in the action’s info.plist file. By default, this property defaults to the first output type in the info.plist file.

    Set this value to explicitly specify the output type the action produces. Setting this value to accurately reflect the appropriate output helps Automator determine whether the output is compatible, or can be made compatible, with the next action in the workflow.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.6 and later.

  • stopped stopped Property

    Indicates whether the user clicked the stop button on the parent workflow. (read-only)

    Declaration

    Swift

    var stopped: Bool { get }

    Objective-C

    @property(getter=isStopped, readonly) BOOL stopped

    Discussion

    Returns YEStrue if the user clicked the stop button, or NOfalse if the workflow is still running. This property should be referenced during lengthy action processes, such as a loop, in order to determine whether to exit the operation and stop the action.

    Import Statement

    Objective-C

    @import Automator;

    Swift

    import Automator

    Availability

    Available in OS X v10.10 and later.