AMWorkflow Class Reference

Inherits from
NSObject
Conforms to
NSCopying
NSObject (NSObject)
Framework
/System/Library/Frameworks/Automator.framework
Availability
Available in OS X v10.5 and later.
Declared in
AMWorkflow.h
Companion guides
Automator Programming Guide
Automator Framework Reference
Related sample code

Overview

The AMWorkflow class lets you use an Automator workflow in your application. You can display a workflow with an instance of AMWorkflowView and control its operation with an instance of AMWorkflowController.

A workflow consists of one or more actions (discrete tasks), which together can perform complex automation tasks. Your application can use workflows to package its own features and to take advantage of features provided by other applications. You create actions with Xcode, while you create workflows with the Automator application.

You can load and run a workflow with minimal overhead by using the AMWorkflow class method runWorkflowAtURL:withInput:error:. However, in situations where you need greater control, such as the ability to start and stop the workflow, you can use an instance of the AMWorkflowController class instead. In that case, you’ll have to create and initialize both a workflow and a workflow controller object.

In either case, the workflow is run in a separate process so that any actions it contains are executed in a separate memory space. That helps to insulate your application from crashes, memory leaks, or exceptions that might occur from running the actions in the workflow.

Tasks

Running a Specified Workflow

Creating and Initializing a Workflow

Saving Changes to a Workflow

Getting Information About the Workflow

Manipulating the Workflow’s Actions

Class Methods

runWorkflowAtURL:withInput:error:

Loads and runs the specified workflow file.

+ (id)runWorkflowAtURL:(NSURL *)fileURL withInput:(id)input error:(NSError **)error
Parameters
fileURL

URL that specifies the location of a workflow file.

input

Specifies the input for the first action in the workflow. Pass nil if the first action doesn’t need input.

error

If no workflow is found or if an error occurs in initializing or running it, upon return contains an instance of NSError that describes the problem.

Return Value

On error, returns nil. Otherwise, returns the output of the last action in the workflow. Your application may need to convert the data to a desired type.

Discussion

Use this method to run a workflow without the overhead of performing a separate allocation, setting up a workflow controller, and so on. However, in situations where you need greater control, such as the ability to start and stop the workflow, use an instance of the AMWorkflowController class instead.

The workflow is run in a separate process so that any actions it contains are executed in a separate memory space. This helps to insulate the application from crashes, memory leaks, or exceptions that might occur from running the actions in the workflow.

Availability
  • Available in OS X v10.5 and later.
Declared In
AMWorkflow.h

Instance Methods

addAction:

Adds the specified action at the end of the receiving workflow.

- (void)addAction:(AMAction *)action
Parameters
action

The action to add.

Discussion

The workflow retains the action but does not copy it.

Availability
  • Available in OS X v10.5 and later.
Declared In
AMWorkflow.h

initWithContentsOfURL:error:

Creates and initializes a workflow based on the contents of the specified file.

- (id)initWithContentsOfURL:(NSURL *)fileURL error:(NSError **)outError
Parameters
fileURL

URL that specifies the location of a workflow file.

outError

If the workflow file can’t be found, or if an error occurs in initializing the workflow, upon return contains an instance of NSError that describes the problem.

Return Value

The initialized workflow object. On error, returns nil.

Availability
  • Available in OS X v10.5 and later.
Declared In
AMWorkflow.h

insertAction:atIndex:

Inserts the specified action at the specified position of the receiving workflow.

- (void)insertAction:(AMAction *)action atIndex:(NSUInteger)index
Parameters
action

The action to insert.

index

The position in the receiver at which to insert the action. If the position is invalid, this method does nothing.

Discussion

The workflow retains the action but does not copy it.

Availability
  • Available in OS X v10.5 and later.
Declared In
AMWorkflow.h

moveActionAtIndex:toIndex:

Moves the action from the specified start position to the specified end position in the receiving workflow.

- (void)moveActionAtIndex:(NSUInteger)startIndex toIndex:(NSUInteger)endIndex
Parameters
startIndex

The start position of the action to move.

endIndex

The end position for the action that is moved.

Discussion

If either index is invalid, this method does nothing.

Availability
  • Available in OS X v10.5 and later.
Declared In
AMWorkflow.h

removeAction:

Removes the specified action from the receiver.

- (void)removeAction:(AMAction *)action
Parameters
action

The action to be removed.

Discussion

The action receives an AMAction closed message before being released.

Availability
  • Available in OS X v10.5 and later.
Declared In
AMWorkflow.h

setValue:forVariableWithName:

Sets the value of the workflow variable with the specified name.

- (BOOL)setValue:(id)value forVariableWithName:(NSString *)variableName
Parameters
value

The value to set for the named variable.

variableName

The name of a variable to set the value for.

Return Value

YES if variableName was found and its value set; otherwise NO.

Discussion

This method does nothing if the variable specified by variableName is not found.

Availability
  • Available in OS X v10.5 and later.
Declared In
AMWorkflow.h

valueForVariableWithName:

Returns the value of the workflow variable with the specified name.

- (id)valueForVariableWithName:(NSString *)variableName
Parameters
variableName

The variable name.

Return Value

The value for the variable. Returns nil if no variable is found with the specified name.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
AMWorkflow.h

writeToURL:error:

Writes the workflow to the specified file.

- (BOOL)writeToURL:(NSURL *)fileURL error:(NSError **)outError
Parameters
fileURL

URL that specifies the file location to write the workflow to.

outError

If the workflow file can’t be written, upon return contains an instance of NSError that describes the problem.

Return Value

YES if the workflow was successfully written; otherwise NO.

Discussion

You might want to save the workflow, for example, because you have made changes to a variable it contains.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
AMWorkflow.h


© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-10-26)

Did this document help you? Yes It's good, but... Not helpful...