Edit

Functions for use with Azure Blueprints

  • Article

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