Task Functions

In programming, functions allow the structuring of programs in segments of code to enable performance of individual tasks. A function has input and output, and contains instructions used to create the output from its input (that is, performs a calculation on the input and returns an output). The same holds true for task functions in Automate. Each task function performs an operation and optionally returns a value. The output value can be private, or it can be made public and stored in a variable to be called upon by as many steps as required by the task.

Task functions are created and managed through a drop-down interface accessible from the Steps Panel of Task Builder.

NOTE: Task Functions are supplemental features aimed for advanced users. You can build tasks without the use of Task Functions and may choose to use these features at your own pace.

Scope & Accessibility

The power of task functions comes from their ability to provide variable modularity and protection and their capability to arrange a collection of task steps into a logical structure. This is accomplished through two distinct yet complimentary standards; scope and accessibility. Scope and accessibility are primary building blocks that allows you to construct a solid foundation and enable a rich object-oriented approach to tasks. They provide distinct capabilities and serve different but complimentary roles necessary to distinguish the benefits of task functions.

Scope

A scope in any programming is a region of the program where a defined variable can have its existence and beyond that variable can not be accessed. In Automate, scope limits a task function's visibility within a task. Without proper scoping, some of the primary advantages of function-oriented design would not be possible, including information-protection, modularity, maintainability and recursion. Scoping helps take large, unruly tasks and enforce logical restrictions to their structure to provide greater readability and maintainability. Scoping also helps avoid unintentional and confusing data changes leading to easier debugging as well as construction of cleaner and more reliable tasks.

Accessibility

Accessibility provides the fundamentals of information-protection, encapsulation and interfacing, all of which are essential for an object-oriented approach to a language. It makes tasks more portable, manageable and documentable by providing outside access only to those parts of the task that are meant to be used, while providing the user full flexibility of functions. Task functions exist at the root of a task structure, thus, their scope is to the entire task. However, their accessibility, which defines whether or not the function is accessible and visible to an external task, can be defined in the following manners:

  • Public - Visible and accessible to external tasks.

  • Private - Not visible or accessible to external tasks. Access is limited to the containing type.

The ability to set task functions as public or private give developers greater control over how a task is used by another task.

Sub-tasks

Sub-tasks are task files that are executed within another task by using the Task - Start sub-task activity. In this situation, the parent task’s (i.e. the task executing the Start sub-task step) basic functions, extended functions, public task functions, public task variables, and any local variables (not marked as private), created up to point where the Start sub-task step is encountered, are accessible to the sub-task. All other variables and functions are not accessible to the sub-task. Conversely, because the Start sub-task action is a synchronous operation, the sub-task’s public functions and public task variables are not accessible from the parent task. This is fully backward compatible with previous versions of Automate, since in the past there was only one “function” (what is now called “main”), no task variables, and all (local) variables and extended functions were considered public.

When you define a task function, you can optionally define one or more named, typed values that the function receives as input (known as argument parameters). You can declare arguments as optional and set a default value for any argument - so if the argument is not present, the default value will be used. You can also define a type of value that the function will pass back to the task as output upon completion (known as return type).

Function argument parameters and return values are extremely flexible in Automate. You can define anything from a simple utility function with a single unnamed parameter to a complex function with expressive parameter names and different parameter options. You can provide default values to simplify function calls and can be passed as in-out parameters, which modify a passed variable once the function has completed its execution.

Creating & Defining Task Functions

When you define a task function, you can optionally define one or more named, typed values that the function receives as input (known as argument parameters). You can declare arguments as optional and set a default value for any argument - so if the argument is not present, the default value will be used. You can also define a type of value that the function will pass back to the task as output upon completion (known as return type).

Function argument parameters and return values are extremely flexible in Automate. You can define anything from a simple utility function with a single unnamed parameter to a complex function with expressive parameter names and different parameter options. You can provide default values to simplify function calls and can be passed as in-out parameters, which modify a passed variable once the function has completed its execution.

To Create and Define a New Task Function

  1. From Task Builder's Steps panel, select Functions.
  2. Click the Add new function button. This expands the UI panel to display available function properties.

 

  1. Enter a function name, select a return type and specify whether the function is public or private (see the Function Properties table below for more details).
  2. To add argument parameters, click the Add new parameter button. A dialog appears that allows you to enter function parameters.

  1. Enter the required information and click the Save Changes button upon completion (see the Argument Parameters table below for more details). Perform steps 3-4 To add additional parameters. To edit or remove an existing parameter, select it from the list and click the Edit or Remove button.

To Modify an Existing Task Function

  1. From the Task Builder's Steps panel, click the drop-down button to expand the list of existing task functions/events.

  2. Select the task function you wish to modify, then click the (View Function Properties) button.

  3. Perform the appropriate modifications.

To Delete an Existing Task Function

  1. From the Task Builder's Steps panel, click the drop-down button that displays existing task functions/events.

  2. Select the function you wish to delete.

  3. Click the (Remove Task Function) button. This will permanently delete the task function.

Function Parameters

The following table describes the parameters available during task function creation/modification.

Property Type Description
Name Text The identifier by which the function can be called. This parameter defaults to the name NewFunction but can be modified to a name that better identifies the function.
Return type Text (options) The return value type. The available options are:
  • Nothing - No value (nothing) will be returned.
  • Variable - The return value will be in the form of a variable.
  • Array - The return value will be in the form of an array.
  • Dataset - The return value will be in the form of a dataset.
Function is private Yes/No If selected, the function becomes private.

Argument Parameters

The following table describes the parameters available during task function creation/modification.

Property Type Description
Name Text The identifier by which the function can be called. This parameter defaults to the name NewFunction but can be modified to a name that better identifies the function.
Type Text (options) The return value type. The available options are:
  • Nothing - There will be no return value.
  • Variable - The return value will be in the form of a variable.
  • Array - The return value will be in the form of an array.
  • Dataset - The return value will be in the form of a dataset.
Is Optional TRUE/FALSE Specifies whether the parameter is optional (TRUE) or required (FALSE). Any call must provide arguments for all required parameters, but can omit arguments for optional parameters. Each optional parameter has a default value as part of its definition. If no argument is sent for that parameter, the default value is used. When you define a complicated function, you will often want to set this to optional (TRUE) for flexibility.
Default value Text The function's default value (if any).
Description Text An optional description to enter about the parameter.

Calling Task Functions

A function doesn't do anything until it is called. Every function has a function name which may describe the procedure that the function performs. To use a function, you “call” that function with its name and pass it input values (known as arguments) that match the types of the function’s parameters. If you are calling a function with no parameters, an empty pair of parentheses is required.

The Task - Call function activity calls a function defined in the task. If the function returns a result, you can specify the name of the variable in which to place the value. This activity is mainly used to pass control to a subroutine; after the subroutine is executed, control returns to the next instruction in main task.

In addition, the Variable - Return activity can be used to exit the current function and return task execution to the calling function. A return value can also be specified to the caller. This activity immediately ends execution of the current function and returns its argument as the value of the function call.