# Example simple string replacement macro
The following example walks you through the process of using macros, from defining the macro in a template, to creating a Lambda function for the macro, and then to using the macro in a template.
In this example, we create a simple macro that inserts the specified string in place of the specified target content in the processed template. And then we'll use it to insert a blank `WaitHandleCondition` in the specified location in the processed template.
## Creating a macro
Before using a macro, we first have to complete two things: create the Lambda function that performs the desired template processing, and then make that Lambda function available to CloudFormation by creating a macro definition.
The following sample template contains the definition for our example macro. To make the macro available in a specific AWS account, create a stack from the template. The macro definition specifies the macro name, a brief description, and references the ARN of the Lambda function that CloudFormation invokes when this macro is used in a template. (We haven't included a `LogGroupName` or `LogRoleARN` property for error logging.)
In this example, assume that the stack created from this template is named `JavaMacroFunc`. Because the macro `Name` property is set to the stack name, the resulting macro is named `JavaMacroFunc` as well.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Macro:
Type: AWS::CloudFormation::Macro
Properties:
Name: !Sub '${AWS::StackName}'
Description: Adds a blank WaitConditionHandle named WaitHandle
FunctionName: 'arn:aws:lambda:us-east-1:012345678910:function:JavaMacroFunc'
```
## Using the macro
To use our macro, we include it in a template using the `Fn::Transform` intrinsic function.
When we create a stack using the template below, CloudFormation calls our example macro. The underlying Lambda function replaces one specified string with another specified string. In this case, the result is a blank `AWS::CloudFormation::WaitConditionHandle` is inserted into the processed template.
```
Parameters:
ExampleParameter:
Type: String
Default: 'SampleMacro'
Resources:
2a:
Fn::Transform:
Name: "JavaMacroFunc"
Parameters:
replacement: 'AWS::CloudFormation::WaitConditionHandle'
target: '$$REPLACEMENT$$'
Type: '$$REPLACEMENT$$'
```
+ The macro to invoke is specified as `JavaMacroFunc`, which is from the previous macro definition example.
+ The macro is passed two parameters, `target` and `replacement`, which represent the target string and its desired replacement value.
+ The macro can operate on the contents of the `Type` node because `Type` is a sibling of the `Fn::Transform` function referencing the macro.
+ The resulting `AWS::CloudFormation::WaitConditionHandle` is named `2a`.
+ The template also contains a template parameter, `ExampleParameter`, which the macro also has access to (but doesn't use in this case).
## Lambda input data
When CloudFormation processes our example template during stack creation, it passes the following event mapping to the Lambda function referenced in the `JavaMacroFunc` macro definition.
+ `region` : `us-east-1`
+ `accountId` : `012345678910`
+ `fragment` :
```
{
"Type": "$$REPLACEMENT$$"
}
```
+ `transformId` : `012345678910::JavaMacroFunc`
+ `params` :
```
{
"replacement": "AWS::CloudFormation::WaitConditionHandle",
"target": "$$REPLACEMENT$$"
}
```
+ `requestId` : `5dba79b5-f117-4de0-9ce4-d40363bfb6ab`
+ `templateParameterValues` :
```
{
"ExampleParameter": "SampleMacro"
}
```
`fragment` contains JSON representing the template fragment that the macro can process. This fragment consists of the siblings of the `Fn::Transform` function call, but not the function call itself. Also, `params` contains JSON representing the macro parameters. In this case, replacement and target. Similarly, `templateParameterValues` contains JSON representing the parameters specified for the template as a whole.
## Lambda function code
Following is the actual code for the Lambda function underlying the `JavaMacroFunc` example macro. It iterates over the template fragment included in the response (be it in string, list, or map format), looking for the specified target string. If it finds the specified target string, the Lambda function replaces the target string with the specified replacement string. If not, the function leaves the template fragment unchanged. Then, the function returns a map of the expected properties, discussed in detail below, to CloudFormation.
```
package com.macroexample.lambda.demo;
import java.util.List;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.Map;
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
public class LambdaFunctionHandler implements RequestHandler, Map> {
private static final String REPLACEMENT = "replacement";
private static final String TARGET = "target";
private static final String PARAMS = "params";
private static final String FRAGMENT = "fragment";
private static final String REQUESTID = "requestId";
private static final String STATUS = "status";
private static final String SUCCESS = "SUCCESS";
private static final String FAILURE = "FAILURE";
@Override
public Map handleRequest(Map event, Context context) {
// TODO: implement your handler
final Map responseMap = new HashMap();
responseMap.put(REQUESTID, event.get(REQUESTID));
responseMap.put(STATUS, FAILURE);
try {
if (!event.containsKey(PARAMS)) {
throw new RuntimeException("Params are required");
}
final Map params = (Map) event.get(PARAMS);
if (!params.containsKey(REPLACEMENT) || !params.containsKey(TARGET)) {
throw new RuntimeException("replacement or target under Params are required");
}
final String replacement = (String) params.get(REPLACEMENT);
final String target = (String) params.get(TARGET);
final Object fragment = event.getOrDefault(FRAGMENT, new HashMap());
final Object retFragment;
if (fragment instanceof String) {
retFragment = iterateAndReplace(replacement, target, (String) fragment);
} else if (fragment instanceof List) {
retFragment = iterateAndReplace(replacement, target, (List