Functions for use with Azure Blueprints

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
• concat
• parameters
• resourceGroup
• resourceGroups
• subscription

artifacts

artifacts(artifactName)

Returns an object of properties populated with that blueprint artifacts outputs.

Parameters

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:

concat

concat(string1, string2, string3, ...)

Combines multiple string values and returns the concatenated string.

Parameters

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

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

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.