One or more custom tasks can be defined in the
<tasks> block. Individual tasks are defined in
<task> child blocks. The base
<task> class represents an extension-based workflow
task that serves as a template from which ACT creates real instances.
In each task definition, you must include the attributes
name and version. The following
figure maps the task DataSquares to the Workbench UI.
Child blocks are used to specify callbacks, inputs and outputs, properties, parameters, context menus, and remote execution. The basic structure of a task definition follows:
<tasks> <task name="" caption="" icon="" version="1" enableGenericTransfer=""> <callbacks> <IsVisible></IsVisible> <IsValid></IsValid> <GetValue></GetValue> <SetValue></SetValue> <OnShow></OnShow> <OnHide></OnHide> <OnInit></OnInit> <OnAdd></OnAdd> <OnRemove></OnRemove> <OnDuplicate></OnDuplicate> <OnActivate></OnActivate> <OnCancel></OnCancel> <OnApply></OnApply> <Value2String></Value2String> <String2Value></String2Value> <OnValidate></OnValidate> <OnMigrate></OnMigrate> </callbacks> <contextmenus> <entry name="" caption="" icon="" priority="" type=""> <callbacks> <onclick></onclick> </callbacks> </entry> </contextmenus> <propertygroup name="" caption=""> <property name="" caption="" control="" default="" options="" readonly="" needupdate="" visible="" persistent="" isparameter="" keytype="" valuetype="" elementtype=""/> </propertygroup> <property name="" caption="" control="" default="" readonly="" needupdate="" visible="" persistent="" isparameter="" keytype="" valuetype="" elementtype=""> <callbacks> <IsVisible></IsVisible> <IsValid></IsValid> <GetValue></GetValue> <SetValue></SetValue> <OnShow></OnShow> <OnHide></OnHide> <OnInit></OnInit> <OnAdd></OnAdd> <OnRemove></OnRemove> <OnDuplicate></OnDuplicate> <OnActivate></OnActivate> <OnCancel></OnCancel> <OnApply></OnApply> <Value2String></Value2String> <String2Value></String2Value> <OnValidate></OnValidate> <OnMigrate></OnMigrate> </callbacks> <property/> <parameters> <parameter name="" caption="" usage="" control="" version="1"/> </parameters> <inputs> <input/> <input type="" count="" format=""/> </inputs> <outputs> <output type="" format=""/> </outputs> <rsmjob name="" deletefiles="" version="1"> <inputfile id="1" name=""/> <outputfile id="1" name=""/> <program> <platform name="" path=""/> <argument name="" value="" separator=""/> </program> <callbacks> <oncreatejobinput></oncreatejobinput> <onjobstatus></onjobstatus> <onjobcancellation></onjobcancellation> <onjobreconnect></onjobreconnect> </callbacks> </rsmjob> </task> </tasks>
All attributes set on ACT-defined tasks are persisted and resumed within a project.
...
task = ExtAPI.DataModel.Tasks[0]
task.SetAttributeValue('MyAttribute', 'MyValue')
Save(FilePath=’...’, Overwrite=True)
Reset()
Open(FilePath=’...’)
task = ExtAPI.DataModel.Tasks[0]
task.GetAttributeValue('MyAttribute')ACT provides you with a method of transferring data within the
Project Schematic. All tasks contain a general transfer
object of type GeneralTransfer. This object contains one
property, TransferData, of type
Dictionary<string, object>. When the type is
fully created for each task, ACT automatically exposes the type as an output by
default. If you do not want to engage in all transfer possibilities enabled
through the general transfer, you can declare this at the task level:
<workflow name="MyWorkflow" context="Project" version="1">
<tasks>
<task name="MyTask" ... enableGenericTransfer="False">
...
</task>
...
</tasks>
</workflow>Once a general transfer-enabled task exists in the schematic, the transfer
data can be accessed to push and pull data within the data
store. A simple property TransferData is
exposed off of the task argument of all task callbacks or tasks retrieved from
ExtAPI or as a callback argument:
def producer_update(task):
data = task.TransferDataOnce obtained, the dictionary TransferData acts like
any other dictionary within ACT. You can both set and retrieve values through
string keys, and you can perform other collection-based
calls such as Add() and Remove().
The custom IDictionary is coded in such a way that if you
try to access a non-existent key, such as when setting a new value, it
automatically adds the key and allows the set to take place.
task.TransferData["Test"] = "Sample text"
One the consumer side, you can easily access the transfer data:
def consumer_update(task):
container = task.InternalObject
upstreamData = container.GetInputDataByType(
InputType="GeneralTransfer")
for upstreamDataEntity in upstreamData:
task = ACT.GetTaskForContainer(
upstreamDataEntity.Container)
data = task.TransferData["Test"]The transfer data approach eliminates dependency on file and file path transfers. However, if desired, you can still opt to pass file paths via the new transfer data. No further actions or implementations are required to fulfill the basic framework transfer connections.
Note: Downstream processing might require additional actions implemented via ACT workflow callbacks.
In some circumstances, you might want to interrogate a task's source tasks.
For example, this can ease the access of transfer data from upstream sources.
The property SourceTasks is available on all objects of
the type UserTask:
def myTaskUpdate(task):
sources = task.SourceTasks
for sourceTask in sources:
data = sourceTask.TransferData[“Test”]Tasks can filter or block their source connections by implementing a
task-level callback canconsumedata.
XML Definition File:
<task name="Consumer"...>
<callbacks>
<canconsumedata>taskCanUse</canconsumedata>
...
</callbacks>
...
</task>IronPython Script:
def taskCanUse(task, sourceTask):
if sourceTask.Name == “Foo”:
return True
else:
return FalseFor a list of pre-installed tasks that support general data transfer, see Appendix E: Pre-Installed Custom Workflow Support.
Custom solver-based systems also support general data transfer.
The properties InputData and
OutputData are exposed on the object
UserTask. Additionally,
UserTask exposes a property
TargetTasks that returns all downstream tasks that
consume (hold a connection to) the current task.
| Class | Member |
|---|---|
|
|
|
|
| |
|
|
An example follows.
import System
def consumer_update(task):
upstreamData = task.InputData["MyData"]
fileRef = None
upstreamDataCount = upstreamData.Count
if upstreamDataCount > 0:
fileRef = upstreamData[0]
task.UnregisterFile(fileRef)
task.RegisterFile(fileRef.Location)
def producer_update(task):
extensionDir = task.Extension.InstallDir
activeDir = task.ActiveDirectory
filePath = System.IO.Path.Combine(extensionDir, "Sample_Materials.xml")
activeFilePath = System.IO.Path.Combine(activeDir,
"Sample_Materials.xml")
task.UnregisterFile(activeFilePath)
if System.IO.File.Exists(activeFilePath) == False:
System.IO.File.Copy(filePath, activeFilePath)
fileRef = task.RegisterFile(activeFilePath)
myData = task.OutputData["MyData"][0]
myData.TransferFile = fileRef
def mesh_update(task):
upstreamData = task.InputData["MeshingMesh"]
meshFileRef = None
upstreamDataCount = upstreamData.Count
if upstreamDataCount > 0:
meshFileRef = upstreamData[0]
meshOutput = task.OutputData["SimulationGeneratedMesh"][0]
meshOutput.TransferFile = meshFileRef

The class UserTask includes APIs to facilitate easier
management of task-level files. The following APIs are available:
| Class | Member | Description |
|---|---|---|
|
|
|
Obtains the active design point directory for the task. |
|
|
A collection of all registered files associated with the task. | |
|
|
Registers and associates a file with the task. | |
|
|
Unregisters and disassociates a file from the task. | |
|
|
Unregisters and disassociates a file from the task. | |
|
|
Unregisters and disassociates a file from the task. | |
|
|
Unregisters and disassociates a file from the task. |
A sample implementation of task-level file management capabilities follows.
import System
def update(task):
activeDir = task.ActiveDirectory
installDir = task.Extension.InstallDir
srcImageFilePath = System.IO.Path.Combine(installDir,
System.IO.Path.Combine("images", "logo-ansys.jpg"))
destImageFilePath = System.IO.Path.Combine(activeDir, "logo-ansys.jpg")
task.UnregisterFile(destImageFilePath)
System.IO.File.Copy(srcImageFilePath, destImageFilePath)
task.RegisterFile(destImageFilePath)
ExtAPI.Log.WriteMessage('task "'+task.Name+'" Registered File Count =
'+str(task.RegisteredFiles.Count))Note: The UnRegister(...) members fully unregister the
files only if they have been associated with the task (through the
task.Register(...) members). Otherwise, the files
remain registered.
Callbacks to IronPython functions are specified in a
<callbacks> block. All callbacks receive, at
minimum, a task object as an argument. The following table lists the available
callbacks and their arguments.
| Callback | Arguments |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
*Definition of the callback <onedit>
automatically creates a default context menu for the
task.
**The callback <onstatus> invokes the method
status when the application asks the task for its
current state. For more information, see Accessing State-Handling APIs.
***The callback <onreport> invokes the method
report when you generate a project report. It allows
the task to access the report object and add its own task-specific reporting
content. For more information, see Accessing Project Reporting APIs.
In the event of task-level callback errors, exceptions are provided to the Workbench framework, allowing the framework to detect failures and correctly manage task states. Exception details are also reported to the Log.
If you specify the callback <onedit> in the XML
definition file, a default context menu option is
automatically created for the task. However, it is possible to define additional
GUI operations for each task.
Custom GUI operations are specified in the optional
<contextmenus> block. At minimum, the context
menu entry definition must include the attribute name.
When the optional attribute type is defined, it must be
set to ContextMenuEntry.
Each entry in the <contextmenus> block must have
a callback <onclick>, which receives a task object
as its argument.
The basic structure of the <contextmenus> block
follows.
<contextmenus> <entry name="" caption="" icon="" priority="" type=""> <callbacks> <onclick></onclick> </callbacks> </entry> </contextmenus>
Instead of using parameters to drive your simulation, you can work through the data model, simplifying data access by defining custom properties.
Properties can be defined in the optional
<propertygroup> block. At minimum, each
property group definition must include the attribute
name. The attribute caption is
used as the group category name in the Workbench Property
view if the child properties are visible.
Individual properties can be defined in the
<property> bock, which can be either a child to
a <propertygroup> block or a standalone definition
at the same level. At minimum, each property definition must include the
attributes name and control.
The basic structure of a property definition follows.
<propertygroup name="" caption=""> <property name="" caption="" control="" default="" readonly="" needupdate="" visible="" persistent="" isparameter="" keytype="" valuetype="" elementtype=""/> </propertygroup> <property name="" caption="" control="" default="" readonly="" needupdate="" visible="" persistent="" isparameter="" keytype="" valuetype="" elementtype=""/>
ACT supports the following property control types:
string/text
double
float
integer
DataReference
boolean
object
quantity
option/select
fileopen
folderopen
list
dictionary
DataContainerReference
Callbacks to IronPython functions can be specified in a task-level property definition. All property callbacks receive, at minimum, the entity (task) and property as arguments. Available property callbacks are listed and described.
IsVisibleYou can define the callback isvisible
on task-exposed properties. This callback can dynamically
control whether or not to display a property. You can key off of
any desired condition or other task property to determine the
property's visibility, returning True or
False as a result.
XML Definition File:
...
<task ...>
...
<property name="Input" caption="Input" control="double" .../>
<property name="HiddenString" caption="Test String"
control="string" ...>
<callbacks>
<isvisible>stringVisibilityCheck</isvisible>
</callbacks>
</property>
...
</task>
...IronPython Script:
def stringVisibilityCheck(entity, property):
inputVal = entity.Properties["Input"]
if inputVal.Value == 2.0:
return True
else:
return False
IsValidYou can define the callback isvalid on
task-exposed properties. This callback can dynamically control
whether or not a property is valid. You can key off of any
desired condition or other task property to determine the
property's validity, returning True or
False as a result.
XML Definition File:
...
<task ...>
...
<property name="Input" caption="Input" control="double"
default="0.0" readonly="False" needupdate="True"
visible="True" persistent="True"
isparameter="True">
<callbacks>
<isvalid>validityCheck</isvalid>
</callbacks>
</property>
...
</task>
...IronPython Script:
def validityCheck(entity, property):
if property.Value == 1.0:
return False
else:
return TrueIn the following figure, the property is valid.
In the following figure, the property is invalid.
GetValueYou can define the callback getvalue,
which is invoked when the user obtains a value either from the
command line, a script, or through the project itself.
SetValueYou can define the callback setvalue,
which is called when the user sets a value from either the
command line, a script, or through the project itself.
OnShowYou can define the callback onshow,
which is called when the Project page is
about to display the property.
OnHideYou can define the callback onhide,
which is called when the Project page is
about to hide the property.
OnInitYou can define the callback oninit,
which is called when the property is first created on the task
object.
**This is called at the same location as the callback
onadd.**
OnAddYou can define the callback onadd,
which is called when the property is first added on the task
object.
**This is called at the same location as the callback
oninit.**
OnRemoveYou can define the callback onremove,
which is called when the property is deleted from the task
object.
OnDuplicateYou can define the callback
onduplicate, which is called when the
property is duplicated to another task.
OnActivateYou can define the callback onactivate,
which is called when the property is activated in the user
interface.
**This is called at the same location as the callback
onshow.**
OnCancelYou can define the callback oncancel,
which is called when a property is deactivated.
**This is called at the same location as the callback
onhide.**
OnApplyYou can define the callback onapply,
which is called immediately after a property value change but
before it is actually processed.
Value2StringYou can define the callback
value2string, which is called when
the property ValueString is retrieved.
String2ValueYou can define the callback
string2value, which is called when
the property ValueString is set.
OnValidateYou can define the callback onValidate,
which is called during a property value change.
OnMigrateAs of 17.1, this callback is not supported.
You can get and set property values using standard ACT syntax, as defined
through SimEntity. At the task-level callbacks, the
provided task argument provides the entry point:
propA = task.Properties[“PropertyA”].Value task.Properties[“PropertyA”].Value = “Foo”
Access is available at the master ExtAPI level.
Assuming that only one task resides in the schematic:
task = ExtAPI.DataModel.Tasks[0] propA = task.Properties[“PropertyA”].Value task.Properties[“PropertyA”].Value = “Foo”
Property groups are treated the same as elsewhere in ACT:
task = ExtAPI.DataModel.Tasks[0] group1 = task.Properties[“GroupName”] supProp1 = group1.Properties[“SubPropertyA”] subProp1Val = subProp1.Value
When you must perform “advanced” schematic interactions, you
can access task.InternalObject to receive the
task’s underlying DataContainerReference. This
might be needed to execute Workbench-specific scripting commands. For more
information, see the Workbench Journaling and
Scripting Guide.
task = ExtAPI.DataModel.Tasks[0] container = task.InternalObject container.SendCommand(Language=”Python”, Command=”print ‘test’”)
Interaction with pre-installed tasks operates in the same way. For
example, if you create a Fluent analysis system in the schematic, you could
set the property RunParallel as follows:
task = ExtAPI.DataModel.Task[0] task.Properties[“RunParallel”].Value = True
All "set"-based actions performed via
Property.Value calls are recorded in the journal.
Using the last example with a Fluent system, the resulting journal would
contain the following code:
# encoding: utf-8 # Release 17.1 SetScriptVersion(Version=”17.1.21”) Reset() template1 = GetTemplate(TemplateName=”FLUENT”) system1 = template1.CreateSystem() setup1 = system1.GetFluentLauncherSettings() fluentLauncherSettings1.RunParallel = True
You can specify the controls fileopen and
folderopen on task properties. On task creation
and property display, a folder icon appears in the property value cell.
Selecting this icon displays a dialog box for selecting a file or folder.
File path and folder path access remains the same as if the property was
string-based.
XML Definition File:
<task ...>
...
<property name="Prop1" caption="File Path" control="fileopen"
.../>
<property name="Prop2" caption="Directory Path"
control="folderopen" .../>
...
</task>IronPython Script:
def update(task):
filePath = task.Properties["Prop1"].Value
dirPath = task.Properties["Prop2"].Value
For string-based task properties, specify text as
the control type.
...
<task ...>
...
<property name="StringTest" caption="String" control="text"...>
</property>
...
</task>
...For option-based task properties, specify the standard
select control type and use the
options attribute to provide the items to be
populated to the control.
...
<task ...>
...
<property name="ComboBoxTest" caption="My Prop" control="select"...>
...
<attributes options=”one,two,three” .../>
...
</task>
...In the XML definition file, you can specify default property values to be used in the Project Schematic.
...
<task ...>
...
<property name="MyProperty" caption=”My Property" control="text" default=”Foo”.../>
...
</task>
...You can integrate an external application with the Project Schematic by defining parameters that are created dynamically at initialization.
Parameters are defined in the optional
<parameters> block. At minimum, each
parameter definition must include the following attributes:
name, usage,
control, and
version.
The basic structure of a parameter definition follows.
<parameters> <parameter name="" caption="" usage="" control="" version="1"/> </parameters>
In a Workbench workflow, the Project Schematic connections serve as visual representations of data flow between tasks. These connections depend on input and output coordination. Workbench can establish connections only if an upstream (providing) task exposes outputs whose types also match the inputs for a downstream (consuming) task.
Inputs and outputs are defined in <input> and
<output> blocks.
You can use the attribute type to specify the data
type expected by the connection.
By default, ACT applies an unlimited count to the number of input specifications. You can specify a count according to your own requirements:
...
<task ...>
...
<inputs>
<input/>
<input format="" type="GeneralTransfer" count=2/>
</inputs>
...
</task>
...
Certain Workbench types require the use of both the attributes
type and format. For
example, a Mesh task that consumes a mesh and then
passes a mesh to another task group would use these attributes to specify
the mesh type and file format of the input and output files.
This example defines the inputs and outputs for a task within a Fluent
meshing workflow. The meshing-based type values and
FluentMesh format values instruct an upstream
mesh task to output the Fluent mesh file format (MSH).
... <task name="Mesher" caption="Mesher" icon="GenericMesh_cell" version="1"> <callbacks> <onupdate>update</onupdate> <onedit>edit</onedit> </callbacks> <inputs> <input format="FluentMesh" type="MeshingMesh" count="1"/> <input/> </inputs> <outputs> <output format="FluentMesh" type="SimulationGeneratedMesh"/> </outputs> </task> ...
For a list of supported transfer types and their corresponding transfer properties, see Appendix C: Data Transfer Types.
For a list of the data types and data transfer formats for each addin, see Appendix D: Addin Data Types and Data Transfer Formats.
ANSYS Remote Solve Manager (RSM) enables the remote execution of applications and processes. By leveraging high-performance clusters and efficient job scheduling, users submit jobs either as background solve tasks (local machine) or as true remote cluster and scheduler submissions. Workbench orchestrates the packaging, submission, tracking, and reintegration of job artifacts.
ACT enables you to leverage RSM capabilities, specifying the remote
execution of a task’s processes via an
<rsmJob> child block. This block allows you
to specify all relevant RSM-related information, including supported
platforms, input and output files, process arguments, and the callbacks
needed to execute the remote jobs.
This example shows the basic definition of a remote execution specification. It defines the name and version of the job, specifies that job files should be deleted after execution, and defines job input and output files and callbacks.
...
<task name="MyTask" caption="My Task" icon="my_task" version="1">
...
<rsmjob name="squares" deletefiles="True" version="1">
<inputfile id="1" name="input1.txt"/>
<outputfile id="1" name="output1.txt"/>
<program>
<platform name="Win64" path="%AWP_ROOT171%\path_to.exe"/>
<platform name="Linux64" path="%AWP_ROOT171%/path_to.exe"/>
<argument name="" value="inputFile:1" separator=""/>
<argument name="" value="outputFile:1" separator=""/>
</program>
<callbacks>
<oncreatejobinput>createJobInput</oncreatejobinput>
<onjobstatus>getJobStatus</onjobstatus>
<onjobcancellation>cancelJob</onjobcancellation>
<onjobreconnect>reconnectJob</onjobreconnect>
</callbacks>
</rsmjob>
</task>
...For a more detailed discussion of how to access RSM capabilities, see the example Custom, Lightweight, External Application Integration with Custom Data and Remote Job Execution.
From a task, you can access and manipulate objects above the task level, such as container-level commands, Workbench-level components or parameters, and the task-containing task group.
ACT provides the ability to invoke journaling and scripting-defined, container-level commands on a task. The following API is available:
| Class | Member | Description |
|---|---|---|
|
|
|
Invokes a schematic method defined on the task. |
The following code sample shows an implementation of the method
ExecuteCommand.
#assume the first task is a mechanical-based system task = ExtAPI.DataModel.Tasks[0] task.ExecuteCommand(“Edit”, [])
ACT enables you to access task-defined Workbench parameters directly from a task. The following API is available:
| Class | Member | Description |
|---|---|---|
|
|
|
Obtains the parameters defined on this task. |
The following code sample shows an implementation of the method
Parameters.
task = ExtAPI.DataModel.Tasks[0] myParameters = task.Parameters myParam = myParameters[0] myParamValue = myParam.Value
ACT enables you to access the Workbench-based component object directly from a task. The following API is available:
| Class | Member | Description |
|---|---|---|
|
|
|
Obtains the underlying Project Schematic component associated with this task. |
The following code sample shows an implementation of the method
Component.
#assume the first task is a mechanical-based system task = ExtAPI.DataModel.Tasks[0] myTaskComponent = task.Component
ACT enables you to access specific taskgroup
instances that have been created within the Project
Schematic. Because a task is owned by
a TaskGroup, you can access the owning
TaskGroup directly from a new
Task. The following APIs are available:
| Class | Member | Description |
|---|---|---|
|
|
|
Obtains the task’s task group owner. |
|
|
|
The list of all task groups currently within the schematic. |
|
|
|
The list of all tasks owned by this task group. |
|
|
The task group name. | |
|
|
The task group display name. | |
|
|
The task group toolbox category. | |
|
|
The task group abbreviation. | |
|
|
Indicates whether the task group falls under the Parameter Set bar, operating only on parameter and design point data. | |
|
|
(System data reference) |
