From 0247013e828b0bcb6c3a7ed8804b970a2bb99650 Mon Sep 17 00:00:00 2001
From: GZ <yuanhaoz@amazon.com>
Date: Wed, 26 Jun 2024 15:13:26 -0700
Subject: [PATCH] chore(ssm): update simple name description and documentation
 (#30653)

### Issue # (if applicable)

Closes #28778.

### Reason for this change

There are issues with SSM `StringParameter` where the parameter ARN would have missing `/` or duplicate `/` depending on the setup of `simpleName` with unresolved tokens in the parameter name.

### Description of changes

Update README and docstring to explain to users when and how to correctly use `simpleName` parameter.

### Description of how you validated changes

No code changes made.

### Checklist
- [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
---
 packages/aws-cdk-lib/aws-ssm/README.md        | 30 ++++++++++++++++++-
 packages/aws-cdk-lib/aws-ssm/lib/parameter.ts | 12 +++++---
 2 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/packages/aws-cdk-lib/aws-ssm/README.md b/packages/aws-cdk-lib/aws-ssm/README.md
index e70e424f0573b..0f678c449c756 100644
--- a/packages/aws-cdk-lib/aws-ssm/README.md
+++ b/packages/aws-cdk-lib/aws-ssm/README.md
@@ -1,6 +1,5 @@
 # AWS Systems Manager Construct Library
 
-
 This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.
 
 ## Using existing SSM Parameters in your CDK app
@@ -143,3 +142,32 @@ When specifying an `allowedPattern`, the values provided as string literals
 are validated against the pattern and an exception is raised if a value
 provided does not comply.
 
+## Using Tokens in parameter name
+
+When using [CDK Tokens](https://docs.aws.amazon.com/cdk/v2/guide/tokens.html) in parameter name,
+you need to explicitly set the `simpleName` property. Setting `simpleName` to an incorrect boolean
+value may result in unexpected behaviours, such as having duplicate '/' in the parameter ARN
+or missing a '/' in the parameter ARN.
+
+`simpleName` is used to indicates whether the parameter name is a simple name. A parameter name
+without any '/' is considered a simple name, thus you should set `simpleName` to `true`.
+If the parameter name includes '/', set `simpleName` to `false`.
+
+```ts
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+
+const simpleParameter = new ssm.StringParameter(this, 'StringParameter', {
+  // the parameter name doesn't contain any '/'
+  parameterName: 'parameter',
+  stringValue: 'SOME_VALUE',
+  simpleName: true, // set `simpleName` to true
+});
+
+declare const func: lambda.IFunction;
+const nonSimpleParameter = new ssm.StringParameter(this, 'StringParameter', {
+  // the parameter name contains '/'
+  parameterName: `/${func.functionName}/my/app/param`,
+  stringValue: 'SOME_VALUE',
+  simpleName: false, // set `simpleName` to false
+});
+```
diff --git a/packages/aws-cdk-lib/aws-ssm/lib/parameter.ts b/packages/aws-cdk-lib/aws-ssm/lib/parameter.ts
index 1972b605665fc..f4087515bc724 100644
--- a/packages/aws-cdk-lib/aws-ssm/lib/parameter.ts
+++ b/packages/aws-cdk-lib/aws-ssm/lib/parameter.ts
@@ -99,8 +99,10 @@ export interface ParameterOptions {
   readonly parameterName?: string;
 
   /**
-   * Indicates if the parameter name is a simple name (i.e. does not include "/"
-   * separators).
+   * Indicates whether the parameter name is a simple name. A parameter name
+   * without any "/" is considered a simple name. If the parameter name includes
+   * "/", setting simpleName to true might cause unintended issues such
+   * as duplicate "/" in the resulting ARN.
    *
    * This is required only if `parameterName` is a token, which means we
    * are unable to detect if the name is simple or "path-like" for the purpose
@@ -337,8 +339,10 @@ export interface CommonStringParameterAttributes {
   readonly parameterName: string;
 
   /**
-   * Indicates if the parameter name is a simple name (i.e. does not include "/"
-   * separators).
+   * Indicates whether the parameter name is a simple name. A parameter name
+   * without any "/" is considered a simple name. If the parameter name includes
+   * "/", setting simpleName to true might cause unintended issues such
+   * as duplicate "/" in the resulting ARN.
    *
    * This is required only if `parameterName` is a token, which means we
    * are unable to detect if the name is simple or "path-like" for the purpose