padv.util.TokenStringsResolver

Access information about current task iteration and token information

expand all in page

    Description

    A padv.util.TokenStringsResolver object represents a resolver that can resolve tokenized strings. For your custom tokens, you can use the resolver object to access information about the current task iteration and token information.

    The resolvePath method of padv.Task uses the resolver to handle dynamic information in paths. Tokens act as placeholders for dynamic information, which tasks can resolve at task runtime. For example, you can use the built-in token $TIMESTAMP$ to represent the current date and time in filenames and paths.

    Creation

    You do not need to create this object directly. During task runtime, the padv.util.TokenStringsResolver object is available to provide information about the current task iteration artifact and general token information.

    When you add a custom token by using the addToken function, you can pass the padv.util.TokenStringsResolver object to your token resolution function by using the anonymous function syntax @(obj)anonymous_function(obj). The argument obj represents padv.util.TokenStringsResolver object that is available at task runtime. Inside the resolution function definition, you can use the padv.util.TokenStringsResolver object functions like getIterationArtifact get information about the current task iteration artifact.

    To resolve your tokenized strings, use the resolvePath method of padv.Task. The built-in tasks automatically resolve tokenized task properties such as OutputDirectory, ReportPath, and ReportName by using the resolvePath method inside the run and dryRun methods of the task definition.

    Object Functions

    Object FunctionDescription
    getIterationArtifact

    Returns the current task iteration artifact at task runtime

    getIterationArtifact(resolver)

    getTokens

    Returns the list of acceptable tokens

    getTokens(resolver)

    The built-in tokens are:

    TokenDescription
    $INPUTARTIFACT$Input artifact for task
    $ITERATIONARTIFACT$Current artifact that the task is acting on
    $PWD$Current working directory
    $TIMESTAMP$Current date and time in the format 'yyyy_mm_dd_HH_MM_ss'
    $PROJECTROOT$Root folder of project
    $TASKNAME$Task name or title
    $DEFAULTOUTPUTDIR$Default output directory for the process model
    $ROOTITERATIONARTIFACT$Root-level artifact for the iteration artifact

    To add custom tokens to the process model, use addToken.

    getTokenMap

    Returns the mapping of tokens to their resolution functions

    getTokenMap(resolver)

    Examples

    collapse all

    In a project with multiple referenced projects, you might need to identify which project each artifact belongs to when generating filenames and paths. You can use a custom token as a placeholder for the project name in the report name, allowing the task to resolve the tokenized path during task execution. You can create a custom token resolution function that identifies the project that owns the current task iteration artifact by accessing the padv.util.TokenStringsResolver object at task runtime and uses that project name as a prefix for the generated report name. For this example, you update the Collect Model Maintainability Metrics task to generate reports with names that include the owning project name as a prefix. If you want to create a custom task that does not require information about the current task or artifact, see Define Basic Custom Token instead.

    Open the Process Advisor example project that uses referenced projects. The model AHRS_Voter opens with the Process Advisor pane to the left of the Simulink® canvas.

    processAdvisorProjectReferenceExampleStart

    In Process Advisor, open the process model by clicking the Edit process model button .

    Inside the process model, add a new, custom token to the process model object, pm, by using the addToken function. This example creates a new token, "$ARTIFACT:OWNING_PROJECT$", that uses the custom function resolveProjectName to return the name of the project that owns the current task iteration artifact. This example token requires information about the current task iteration artifact, so the function handle specifies an input argument obj.

    addToken(pm,"$ARTIFACT:OWNING_PROJECT$",@(obj)resolveProjectName(obj));

    In the project, create a MATLAB® function resolveProjectName.m with the following content. The function accepts a padv.util.TokenStringsResolver object as an input to get information about the current task iteration artifact and the project that owns that artifact. The function returns the name of the owning project, which is the resolved project name for the current task iteration artifact.

    function owningProject = resolveProjectName(obj)
    arguments
        obj padv.util.TokenStringsResolver
    end

    iterationArtifact = obj.getIterationArtifact();
    if isempty(iterationArtifact)
        owningProject="";
        return
    end
    artifactAddress = iterationArtifact.ArtifactAddress;
    owningProject = artifactAddress.getOwningProject();

end

    The built-in tasks automatically resolve tokenized names and paths for commonly tokenized properties such as OutputDirectory, ReportPath, and ReportName. For example, the Collect Model Maintainability Metrics task customizes report names by using tokens the ReportName property. By default, the task generates reports with the name pattern $ITERATIONARTIFACT$_ModelMaintainability, which the task resolves for each task iteration to generate a unique report name.

    In the process model, prefix the report name with the project name by updating the ReportName property of the task to use the custom token $ARTIFACT:OWNING_PROJECT$.

    mmMetricTask = pm.addTask(padv.builtin.task.CollectMetrics());
mmMetricTask.ReportName = "$ARTIFACT:OWNING_PROJECT$"+"_"+mmMetricTask.ReportName;

    To see how the Collect Model Maintainability Metrics task resolves the tokenized ReportName property value, you can inspect the use of the resolvePath method inside the task definition file. Inside the run and dryRun methods, the task resolves the ReportName property by using the resolvePath method and assigns the resolved path as the output directory for the generated report.

    open padv.builtin.task.CollectMetrics

    In Process Advisor, refresh task information by clicking the Refresh Tasks button in the warning banner.

    Dry run the Collect Model Maintainability Metrics task by pointing to the task, opening the options menu (...), and then clicking Dry Run Task. Dry runs allow you to quickly generate representative task outputs without actually running the task.

    The reports for each model have the prefix ProcessAdvisorExample_.

    ...
## Task: Collect Model Maintainability Metrics
#### Input Artifacts:
####      02_Models/AHRS_Voter/specification/AHRS_Voter.slx
#### Dependent Artifacts:
####      02_Models/AHRS_Voter/specification/data/DD_AHRS_Voter.sldd
####      02_Models/common/specification/data/csSingleInstance.sldd
####      02_Models/common/specification/data_types/bus_types.sldd
####      processmodel.m
#### Output Artifacts:
####      PA_Results/AHRS_Voter/metrics/ProcessAdvisorExample_AHRS_Voter_ModelMaintainability.pdf
...

    See Also

    | |