addToken
Add custom token as placeholder for dynamic information
Description
addToken(
adds a single, custom token to the process model. The token is resolved at task runtime by
using the token resolution function, pm,token,resolutionFunction)resolutionFunction, which provides
the information to replace the token with its actual value.
Tokens serve as placeholders for dynamic information like filenames and paths. For
example, you can use the built-in token $TIMESTAMP$ to represent the
current date and time in filenames and paths. 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.
Before you add a custom token, you can check if a built-in token for that functionality
already exists in the support package. The support package provides built-in tokens for
common dynamic filenames and paths such as $TIMESTAMP$,
$ITERATIONARTIFACT$, and $PROJECTROOT$ as shown in
Dynamically Resolve Paths with Tokens.
addToken(
adds the tokens specified in the pm,tokenDictionary)tokenDictionary to the process model.
You can use this syntax to define a preset dictionary of tokens and add multiple tokens into
the process model in a single step.
Examples
Suppose you want the task Collect Model Maintainability Metrics to generate reports into different subfolders based on the username of the current user. Since the current username can change, you can add a custom token that acts as a placeholder for the username in the path and then the task can resolve the tokenized path when the task runs. If you want to create a custom token that uses information about the current task or task iteration artifact, see Define Custom Token That Uses Task Iteration Information instead.
Open the Process Advisor example project. The model AHRS_Voter opens with the Process Advisor pane to the left of the Simulink® canvas.
processAdvisorExampleStart
In Process Advisor, open the process model by clicking the Edit process model button 
.
Inside the process model, add a custom token to the process model object, pm, by using the addToken function. This example creates a new token, "$USER:USERNAME$", that resolves to the username of the current user by getting the 'USERNAME' environment variable. This example token does not require information about the task iteration artifact, so the input argument is specified as ~.
addToken(pm,"$USER:USERNAME$",@(~)getenv('USERNAME'));
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 organizes reports
into folders by using tokens in the ReportPath property. By
default, the task generates reports in the path
$DEFAULTOUTPUTDIR$/$ITERATIONARTIFACT$/metrics, which the task
resolves for each task iteration.
To organize the reports by user, customize the ReportPath
property of the task to include a username by using the custom token
$USER:USERNAME$.
mmMetricTask = pm.addTask(padv.builtin.task.CollectMetrics());
mmMetricTask.ReportPath = fullfile(mmMetricTask.ReportPath,"$USER:USERNAME$");To see how the Collect Model Maintainability Metrics task resolves the
tokenized ReportPath property value, you can inspect the use of the
resolvePath method inside the task definition file. Inside the
run method, the task resolves the ReportPath
property by using the resolvePath method and assigns the resolved path
as the output directory for the generated
report.
open padv.builtin.task.CollectMetricsresolvePath method inside the run and
dryRun methods in the task definition file.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 go into a subfolder with the username of the current user, as shown in this example build log with the example username myusername.
... ## 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/myusername/AHRS_Voter_ModelMaintainability.pdf ...
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 create a custom token resolution function that identifies the project that owns the current task iteration artifact and use 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.CollectMetricsIn 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 ...
When you want to specify multiple dynamic placeholders for a process model, you can define a dictionary of custom tokens and add the dictionary to the process model. Instead of adding tokens individually, you can add a collection of tokens to the process model by using the dictionary syntax. For this example, suppose you want to add tokens for the current MATLAB version, system architecture, and the number of physical cores on your machine for use in tokenized names and paths in the process model.
Open the Process Advisor example project. The model
AHRS_Voter opens with the Process Advisor pane to the
left of the Simulink
canvas.
processAdvisorExampleStart
In Process Advisor, open the process model by clicking the
Edit process model button .
Inside the process model, define a dictionary of custom tokens. Each dictionary
entry is a key-value pair of the token and its token resolution function. In this
example, the token resolution function handles use the MATLAB functions version, computer, and maxNumCompThreads.
dCustomTokens = dictionary; dCustomTokens("$MATLAB:VERSION$") = @(~)version('-release'); dCustomTokens("$SYSTEM:ARCH$") = @(~)computer('arch'); dCustomTokens("$SYSTEM:NUM_CORES$") = @(~)string(maxNumCompThreads);
Inside the process model, add the dictionary of custom tokens to the process model
object, pm, by using the addToken
function.
addToken(pm,dCustomTokens);
Define a tokenized folder path that includes the custom tokens as placeholders. For
this example, update the ReportPath property of the
Collect Model Maintainability Metrics task to include the
MATLAB and system information. The task resolves the
ReportPath property at task runtime to include the actual
values.
mmMetricTask = pm.addTask(padv.builtin.task.CollectMetrics()); mmMetricTask.ReportPath = fullfile("$DEFAULTOUTPUTDIR$","R"+"$MATLAB:VERSION$",... "$SYSTEM:ARCH$","$SYSTEM:NUM_CORES$"+"core",... "$ITERATIONARTIFACT$","metrics");
To see how the Collect Model Maintainability Metrics task
resolves the tokenized ReportPath property value, you can inspect
the use of the resolvePath method inside the task definition file.
Inside the run method, the task resolves the
ReportPath property by using the resolvePath
method and assigns the resolved path as the output directory for the generated
report.
open padv.builtin.task.CollectMetricsIn 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 task generates the reports for each model into a folder hierarchy based on the current MATLAB version, system architecture, and the number of physical cores on the machine. This example build log shows the folder hierarchy for a process run using MATLAB R2025a on a 64-bit Windows® machine with 4 cores.
... ## 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/R2025a/win64/4core/AHRS_Voter/metrics/AHRS_Voter_ModelMaintainability.pdf ...
