padv.builtin.query.GetDependentArtifacts Class

Namespace: padv.builtin.query
Superclasses: padv.Query

Query for getting dependent artifacts

Description

The padv.builtin.query.GetDependentArtifacts class provides a query that can return the dependent artifacts for a specific artifact. A dependent artifact is an artifact that a given artifact depends on. For example, the dependent artifacts for a model include the data dictionaries and library files that the model references.

You can use this query in your process model to find artifacts for your task to use as inputs. But typically, you use the GetDependentArtifacts query as the InputDependencyQuery for a task to find additional artifact dependencies for your task inputs, since those additional artifacts can also impact whether the task results are up-to-date. For example, if you specify a model as an input to a task and you use GetDependentArtifacts as the InputDependencyQuery, the build system can find the related artifacts that the model depends on, such as data dictionaries and other artifact dependencies. Then, you can view those dependent artifacts in the list of Dependencies in the I/O column in Process Advisor as shown in Find Related Artifact Dependencies for Task Inputs. For more information, see Overview of Process Model.

The padv.builtin.query.GetDependentArtifacts class is a handle class.

Creation

Description

query = padv.builtin.query.GetDependentArtifacts() creates a query for finding the dependent artifacts for a specific artifact. Typically, you use this query inside your process model or task definition to find the dependent artifacts for a task input.

query = padv.builtin.query.GetDependentArtifacts(IncludeRequirementLinkFiles=true) creates a query for finding the dependent artifacts for a specific artifact and includes any requirement link files associated with the specified artifact as dependent artifacts.

Properties

IncludeRequirementLinkFiles — Include requirement link files in set of dependent artifacts

false (0) (default) | true (1)

Include requirement link files in set of dependent artifacts, specified as a numeric or logical true (1) or false (0).

Data Types: logical

Title — Query title

"Get dependent artifacts for a given artifact" (default) | string | character vector

Query title, specified as a string or a character vector.

Example: "Find related artifacts"

Data Types: char | string

DefaultArtifactType — Default artifact type returned by query

"padv_dep_artifacts" (default) | ...

Default artifact type returned by the query, specified as one or more of the values in this table. To specify multiple values, use an array.

Category	Artifact Type	Description
MATLAB®	"m_class"	MATLAB class
	"m_file"	MATLAB file
	"m_func"	MATLAB function
	"m_method"	MATLAB class method
	"m_property"	MATLAB class property
Model Advisor	"ma_config_file"	Model Advisor configuration file
	"ma_justification_file"	Model Advisor justification file
Model Finder	"mf_database"	Model Finder database file
Process Advisor	"padv_dep_artifacts"	Related artifacts that current artifact depends on
	"padv_output_file"	Process Advisor output file
Project	"project"	Current project file
Requirements	"mwreq_file"	Requirement file (since R2024b)
	"mwreq_item"	Requirement (since R2024b)
	"sl_req"	Requirement (for R2024a and earlier)
	"sl_req_file"	Requirement file (for R2024a and earlier)
	"sl_req_table"	Requirements Table
Stateflow®	"sf_chart"	Stateflow chart
	"sf_graphical_fcn"	Stateflow graphical function
	"sf_group"	Stateflow group
	"sf_state"	Stateflow state
	"sf_state_transition_chart"	Stateflow state transition chart
	"sf_truth_table"	Stateflow truth table
Simulink®	"sl_block_diagram"	Block diagram
	"sl_data_dictionary_file"	Data dictionary file
	"sl_embedded_matlab_fcn"	MATLAB function
	"sl_block_diagram"	Block diagram
	"sl_library_file"	Library file
	"sl_model_file"	Simulink model file
	"sl_protected_model_file"	Protected Simulink model file
	"sl_subsystem"	Subsystem
	"sl_subsystem_file"	Subsystem file
System Composer™	"zc_block_diagram"	System Composer architecture
	"zc_component"	System Composer architecture component
	"zc_file"	System Composer architecture file
Tests	"harness_info_file"	Harness info file
	"sl_harness_block_diagram"	Harness block diagram
	"sl_harness_file"	Test harness file
	"sl_test_case"	Simulink Test™ case
	"sl_test_case_result"	Simulink Test case result
	"sl_test_file"	Simulink Test file
	"sl_test_iteration"	Simulink Test iteration
	"sl_test_iteration_result"	Simulink Test iteration result
	"sl_test_report_file"	Simulink Test result report
	"sl_test_result_file"	Simulink Test result file
	"sl_test_resultset"	Simulink Test result set
	"sl_test_seq"	Test Sequence
	"sl_test_suite"	Simulink Test suite
	"sl_test_suite_result"	Simulink Test suite result

Example: "padv_dep_artifacts"

Example: ["padv_dep_artifacts" "other_file"]

Parent — Initial query that runs before iteration query

padv.Query | Name of padv.Query object

Initial query that runs before iteration query, specified as either a padv.Query object or the Name of a padv.Query object. When you specify an iteration query for a task, the parent query is the initial query that the build system runs before running the specified iteration query.

For information on how to improve Process Advisor load times by sharing query instances across your process model, see Best Practices for Process Model Authoring.

Example: sharedQuery

Example: "FindMyInitialArtifacts"

Name — Unique identifier for query

"padv.builtin.query.GetDependentArtifacts" (default) | string

Unique identifier for query, specified as a string.

Example: "FindDependentArtifacts"

Data Types: string

ShowFileExtension — Show file extensions for returned artifacts

0 (false) | 1 (true)

Show file extensions in the Alias property of returned artifacts, specified as a numeric or logical 1 (true) or 0 (false). The Alias property controls the display name for the artifact in the Tasks column in Process Advisor.

By default, queries strip file extensions from the Alias property of each task iteration artifact. To show file extensions for all artifacts in the Tasks column, select the project setting Show file extensions. To keep file extensions in the results for a specific query, specify the query property ShowFileExtension as true.

Example: true

Data Types: logical

SortArtifacts — Setting for automatically sorting artifacts by address

true or 1 (default) | false or 0

Setting for automatically sorting artifacts by address, specified as a numeric or logical 1 (true) or 0 (false). When a query returns artifacts, the artifacts should be in a consistent order. By default, the build system sorts artifacts by the artifact address.

Alternatively, you can sort artifacts in a different order by overriding the internal sortArtifacts method in a subclass that defines a custom sort behavior. For an example, see Sort Artifacts in Specific Order.

The build system automatically calls the sortArtifacts method when using the process model. The sortArtifacts method expects two input arguments: a padv.Query object and a list of padv.Artifact objects returned by the run method. The sortArtifacts method should return a list of sorted padv.Artifact objects.

Example: SortArtifacts = false

Data Types: logical

FunctionHandle — Handle to function that function-based query runs

function_handle

Handle to the function that a function-based query runs, specified as a function_handle.

If you define your query functionality inside a function and you or the build system call run on the query, the query runs the function specified by the function_handle.

The built-in queries are defined inside classes and do not use the FunctionHandle.

Example: FunctionHandle = @FunctionForQuery

Data Types: function_handle

Methods

Specialized Public Methods

This class overrides the following inherited methods.

run

Run query to find the artifacts that meet the criteria specified by the query. The query returns a padv.Artifact object or an array of padv.Artifact objects that represent those artifacts. Note You do not need to manually invoke this method inside your process model. The build system automatically invokes the run method when necessary. The run method inside this built-in query runs on a query object obj and returns artifacts artifacts that are associated with the artifact iterationArtifact. If you inherit from this built-in query, make sure to use the same method signature inside your custom query: function artifacts = run(obj,iterationArtifact) ... end

Examples

Find Related Artifact Dependencies for Task Inputs

Suppose that you have a task that uses models as task inputs. You can automatically find the related artifacts that the model depends on, such as data dictionaries, by specifying GetDependentArtifacts as the input dependency query for the task.

The built-in tasks typically use GetDependentArtifacts as the input dependency query. For example, the built-in task GenerateSimulinkWebView uses the GetDependentArtifacts query to find the data dictionaries and libraries that the models in the project depend on. The build system runs the InputDependencyQuery on each task input to find additional dependencies that can impact if task results are up-to-date.

In Process Advisor, the Tasks column shows the artifacts that the task iterates over. When you point to task results in the I/O column, you can see the task inputs and input dependencies.

Suppose that you define a custom task, MyCustomTask, inside a class file. You define when the task runs and the task inputs and dependencies by setting the task properties:

• IterationQuery — Determines how often the task runs by finding the artifacts that the task iterates over. For example, the task can find and iterate over the models in the project.

• InputQueries — Finds inputs for the task. For example, the task can find the current task iteration artifact and use that artifact as a task input.

• InputDependencyQuery — Finds additional dependencies related to the task inputs. For example, the task can find additional, related artifacts that the models in the project depend on.

Inside the class definition file, you can specify:

classdef MyCustomTask < padv.Task
    methods
        function obj = MyCustomTask(options)
            arguments
                options.Name = "MyCustomTask";
                options.IterationQuery = "padv.builtin.query.FindModels";
                options.InputQueries = "padv.builtin.query.GetIterationArtifact";
                % For each input, find dependencies that impact if the
                % task results are up-to-date
                options.InputDependencyQuery = padv.builtin.query.GetDependentArtifacts;
            end
            
            [e-mail](options.Name,...
                IterationQuery=options.IterationQuery,...
                InputQueries=options.InputQueries,...
                InputDependencyQuery=options.InputDependencyQuery);
        end
        function taskResult = run(obj,input)
            taskResult = padv.TaskResult;
            taskResult.Status = padv.TaskStatus.Pass;
        end
    end
end

When you specify InputQueries as padv.builtin.query.GetIterationArtifact, that allows the task to use the artifacts returned by IterationQuery as inputs to the task.

The build system runs the IterationQuery to determine which artifacts to run the task for. The build system then creates a task iteration, runs additional queries the task needs, runs the task, and saves the task results. For each task iteration, the build system runs the InputQueries to find the inputs for that specific task iteration. For each input, the build system runs the InputDependencyQuery to find additional dependencies that can impact if task results are up-to-date.

In this example custom task, the input dependency query finds the artifact dependencies for each model in the project. For information on custom tasks, see Create Custom Tasks.

Capabilities and Limitations

This table identifies functionality that is supported by the query.

Functionality	Supported?
Input query for task	Yes.
Iteration query for task	No.