Creating the Extension for Integrating an External Application with Custom Data

The file DataSquares.xml follows.

<extension version="1" name="DataSquares">
    <guid shortid="DataSquares">69d0095b-e138-4841-a13a-de12238c83f2</guid>
    <script src="datasquares_complete.py" />
    <interface context="Project">
        <images>images</images>
    </interface>
    <workflow name="MyWorkflow" context="Project" version="1">
        <tasks>        
            <task name="DataSquares" caption="Data Squares" icon="dsquares_component" version="1">
                <callbacks>
                    <onupdate>update</onupdate>
                    <onstatus>status</onstatus>
                    <onreport>report</onreport>
                    <onreset>reset</onreset>
                </callbacks>
                <propertygroup name="Inputs">
                    <property name="Input" caption="Input" control="double" default="0.0" readonly="False" needupdate="true" visible="True" persistent="True" isparameter="True" />
                </propertygroup>
                <propertygroup name="Outputs">
                    <property name="Output" caption="Output" control="double" default="0.0" readonly="True" visible="True" persistent="True" isparameter="True" />
                </propertygroup>
                <inputs>
                    <input/>
                </inputs>
                <outputs/>
                <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%\Addins\ACT\extensions\DataSquares\ExampleAddinExternalSolver.exe" />
                        <platform name="Linux64" path="%AWP_ROOT171%/Addins/ACT/extensions/DataSquares/ExampleAddinExternalSolver.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>
        </tasks>
        <taskgroups>
            <taskgroup name="DataSquares" caption="Data Squares" icon="dsquares" category="ACT Custom Workflows" abbreviation="DSQRS" version="1">
                <includeTask name="DataSquares" caption="Data Squares"/>
            </taskgroup>
        </taskgroups>
    </workflow>
</extension>

This XML file performs the following actions:

  • References the script datasquares_complete.py.

  • Defines a single task in the element <tasks>. Within this element:

    • Defines the callback <onreport>, which is called when a project report is generated. This allows the task to access the report object and add its own task-specific reporting content.

    • Defines two property groups with the element <propertygroup>. Within the two property groups, <property> tags define the properties Input and Output.

    • Defines the inputs and outputs in the elements <inputs> and <outputs>. Note that an empty input is defined here, although this is not required.

    • Specifies via the element <rsmJob> that the task can be sent via RSM as a job for remote execution. To specify RSM support, you add the element <rsmJob> to the task in the existing XML extension definition file. In the RSM job specification:

      • Attributes specify the name and indicate the files to manage upon successful completion or cancellation of the job.

      • The tag <platform> specifies a supported platform.

      • The tag <argument> specifies the external application's command line parameters, including input and output file paths.

        When using referenced file paths, the same ID can be used across categories but not within categories. An input and an output can both have an ID of 1, but two inputs cannot have an ID of 1. During the execution, all input and output file names are transformed into fully qualified file paths.

      • The element <program> informs the extension about the task's executable, supported platforms, and corresponding command line arguments. Environment variables can be used for the executable path and previously defined arguments can be referenced by ID.

      • The callbacks invoke methods defined in the script to create the job, check job status, provide the capability to cancel the job, and access output files and results.

  • Defines a single task group in the element <taskgroups> that includes the task DataSquares

The following callbacks reference methods in the IronPython script. The first three callbacks invoke standard task actions. The subsequent callbacks invoke actions related to the RSM job specification.

<onupdate>

Invokes the method update. Called when the user updates the task.

<onstatus>

Invokes the method status. Called when the product (such as Workbench) asks the task for its current state.

<onreport>

Invokes the method report. Called when the user generates a project report. This allows the extension to access the report object and add their own task-specific reporting content.

<oncreatejobinput>

Invokes the method createJobInput. Called when the RSM job requires the generation of all specified input files. Must prepare and generate the input files specified for the RSM job.

As a method argument, ACT passes in the fully qualified input file paths. For this example, only one input file is generated. It contains the input value for the squares solver. ACT retrieves the first entry from the input file list, opens the file, writes the input value line, and closes the file. ACT requires no further action.

<onjobstatus>

Invokes the method getJobStatus. Must tell Workbench if the job has finished. Polled by Workbench several times during the RSM job execution to determine if the update execution has completed. ACT supplies the fully qualified output file list as a method argument.

For the example, True is returned when the presence of the solver's sole output file is detected. Otherwise, False is returned.

<onjobcancellation>

Invokes the method cancelJob. Called when the remote update is stopped before the job completes. Must conduct any clean-up actions required due to a user-initiated stoppage. ACT supplies the fully qualified lists of both input and output files as method arguments.

For this example, no other action is performed. Only file cleanup is required. Setting the method DeleteFiles to True automatically handles the file cleanup.

<onjobreconnect>

Invokes the method reconnectJob. Called when the job status reports a completed job. Must retrieve remotely solved information from output files and update the task's data, rendering it up-to-date.

For this example, the output file generated by the solver is read and the output property that is defined on the task is updated.

The next topic provides additional information about these methods.