Functions for use with Azure Blueprints
Important
On July 11, 2026, Blueprints (Preview) will be deprecated. Migrate your existing blueprint definitions and assignments to Template Specs and Deployment Stacks. Blueprint artifacts are to be converted to ARM JSON templates or Bicep files used to define deployment stacks. To learn how to author an artifact as an ARM resource, see:
Azure Blueprints provides functions making a blueprint definition more dynamic. These functions are for use with blueprint definitions and blueprint artifacts. An Azure Resource Manager Template (ARM template) artifact supports the full use of Resource Manager functions in addition to getting a dynamic value through a blueprint parameter.
The following functions are supported:
artifacts
artifacts(artifactName)
Returns an object of properties populated with that blueprint artifacts outputs.
Note
The artifacts() function can't be used from inside an ARM Template. The function can only be
used in the blueprint definition JSON or in the artifact JSON when managing the blueprint with
Azure PowerShell or REST API as part of
Blueprints-as-code.
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| artifactName | Yes | string | The name of a blueprint artifact. |
Return value
An object of output properties. The outputs properties are dependent on the type of blueprint artifact being referenced. All types follow the format:
{
"outputs": {collectionOfOutputProperties}
}
Policy assignment artifact
{
"outputs": {
"policyAssignmentId": "{resourceId-of-policy-assignment}",
"policyAssignmentName": "{name-of-policy-assignment}",
"policyDefinitionId": "{resourceId-of-policy-definition}",
}
}
ARM template artifact
The outputs properties of the returned object are defined within the ARM template and returned by the deployment.
Role assignment artifact
{
"outputs": {
"roleAssignmentId": "{resourceId-of-role-assignment}",
"roleDefinitionId": "{resourceId-of-role-definition}",
"principalId": "{principalId-role-is-being-assigned-to}",
}
}
Example
An ARM template artifact with the ID myTemplateArtifact containing the following sample output property:
{
"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
...
"outputs": {
"myArray": {
"type": "array",
"value": ["first", "second"]
},
"myString": {
"type": "string",
"value": "my string value"
},
"myObject": {
"type": "object",
"value": {
"myProperty": "my value",
"anotherProperty": true
}
}
}
}
Some examples of retrieving data from the myTemplateArtifact sample are:
| Expression | Type | Value |
|---|---|---|
[artifacts("myTemplateArtifact").outputs.myArray] |
Array | ["first", "second"] |
[artifacts("myTemplateArtifact").outputs.myArray[0]] |
String | "first" |
[artifacts("myTemplateArtifact").outputs.myString] |
String | "my string value" |
[artifacts("myTemplateArtifact").outputs.myObject] |
Object | { "myproperty": "my value", "anotherProperty": true } |
[artifacts("myTemplateArtifact").outputs.myObject.myProperty] |
String | "my value" |
[artifacts("myTemplateArtifact").outputs.myObject.anotherProperty] |
Bool | True |
concat
concat(string1, string2, string3, ...)
Combines multiple string values and returns the concatenated string.
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| string1 | Yes | string | The first value for concatenation. |
| additional arguments | No | string | Additional values in sequential order for concatenation |
Return value
A string of concatenated values.
Remarks
The Azure Blueprints function differs from the ARM template function in that it only works with strings.
Example
concat(parameters('organizationName'), '-vm')
parameters
parameters(parameterName)
Returns a blueprint parameter value. The specified parameter name must be defined in the blueprint definition or in blueprint artifacts.
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| parameterName | Yes | string | The name of the parameter to return. |
Return value
The value of the specified blueprint or blueprint artifact parameter.
Remarks
The Azure Blueprints function differs from the ARM template function in that it only works with blueprint parameters.
Example
Define parameter principalIds in the blueprint definition:
{
"type": "Microsoft.Blueprint/blueprints",
"properties": {
...
"parameters": {
"principalIds": {
"type": "array",
"metadata": {
"displayName": "Principal IDs",
"description": "This is a blueprint parameter that any artifact can reference. We'll display these descriptions for you in the info bubble. Supply principal IDs for the users,groups, or service principals for the Azure role assignment.",
"strongType": "PrincipalId"
}
}
},
...
}
}
Then use principalIds as the argument for parameters() in a blueprint artifact:
{
"type": "Microsoft.Blueprint/blueprints/artifacts",
"kind": "roleAssignment",
...
"properties": {
"roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635",
"principalIds": "[parameters('principalIds')]",
...
}
}
resourceGroup
resourceGroup()
Returns an object that represents the current resource group.
Return value
The returned object is in the following format:
{
"name": "{resourceGroupName}",
"location": "{resourceGroupLocation}",
}
Remarks
The Azure Blueprints function differs from the ARM template function. The resourceGroup() function
can't be used in a subscription level artifact or the blueprint definition. It can only be used in
blueprint artifacts that are part of a resource group artifact.
A common use of the resourceGroup() function is to create resources in the same location as the
resource group artifact.
Example
To use the resource group's location, set in either the blueprint definition or during assignment, as the location for another artifact, declare a resource group placeholder object in your blueprint definition. In this example, NetworkingPlaceholder is the name of the resource group placeholder.
{
"type": "Microsoft.Blueprint/blueprints",
"properties": {
...
"resourceGroups": {
"NetworkingPlaceholder": {
"location": "eastus"
}
}
}
}
Then use the resourceGroup() function in the context of a blueprint artifact that is targeting a
resource group placeholder object. In this example, the template artifact is deployed into the
NetworkingPlaceholder resource group and provides parameter resourceLocation dynamically
populated with the NetworkingPlaceholder resource group location to the template. The location of
the NetworkingPlaceholder resource group could have been statically defined on the blueprint
definition or dynamically defined during assignment. In either case, the template artifact is
provided that information as a parameter and uses it to deploy the resources to the correct
location.
{
"type": "Microsoft.Blueprint/blueprints/artifacts",
"kind": "template",
"properties": {
"template": {
...
},
"resourceGroup": "NetworkingPlaceholder",
...
"parameters": {
"resourceLocation": {
"value": "[resourceGroup().location]"
}
}
}
}
resourceGroups
resourceGroups(placeholderName)
Returns an object that represents the specified resource group artifact. Unlike resourceGroup(),
which requires context of the artifact, this function is used to get the properties of a specific
resource group placeholder when not in context of that resource group.
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| placeholderName | Yes | string | The placeholder name of the resource group artifact to return. |
Return value
The returned object is in the following format:
{
"name": "{resourceGroupName}",
"location": "{resourceGroupLocation}",
}
Example
To use the resource group's location, set in either the blueprint definition or during assignment, as the location for another artifact, declare a resource group placeholder object in your blueprint definition. In this example, NetworkingPlaceholder is the name of the resource group placeholder.
{
"type": "Microsoft.Blueprint/blueprints",
"properties": {
...
"resourceGroups": {
"NetworkingPlaceholder": {
"location": "eastus"
}
}
}
}
Then use the resourceGroups() function from the context of any blueprint artifact to get a
reference to the resource group placeholder object. In this example, the template artifact is
deployed outside the NetworkingPlaceholder resource group and provides parameter
artifactLocation dynamically populated with the NetworkingPlaceholder resource group location to
the template. The location of the NetworkingPlaceholder resource group could have been statically
defined on the blueprint definition or dynamically defined during assignment. In either case, the
template artifact is provided that information as a parameter and uses it to deploy the resources to
the correct location.
{
"kind": "template",
"properties": {
"template": {
...
},
...
"parameters": {
"artifactLocation": {
"value": "[resourceGroups('NetworkingPlaceholder').location]"
}
}
},
"type": "Microsoft.Blueprint/blueprints/artifacts",
"name": "myTemplate"
}
subscription
subscription()
Returns details about the subscription for the current blueprint assignment.
Return value
The returned object is in the following format:
{
"id": "/subscriptions/{subscriptionId}",
"subscriptionId": "{subscriptionId}",
"tenantId": "{tenantId}",
"displayName": "{name-of-subscription}"
}
Example
Use the subscription's display name and the concat() function to create a naming convention passed
as parameter resourceName to the template artifact.
{
"kind": "template",
"properties": {
"template": {
...
},
...
"parameters": {
"resourceName": {
"value": "[concat(subscription().displayName, '-vm')]"
}
}
},
"type": "Microsoft.Blueprint/blueprints/artifacts",
"name": "myTemplate"
}
Next steps
- Learn about the blueprint lifecycle.
- Understand how to use static and dynamic parameters.
- Learn to customize the blueprint sequencing order.
- Find out how to make use of blueprint resource locking.
- Learn how to update existing assignments.
- Resolve issues during the assignment of a blueprint with general troubleshooting.