docs(ssm): document how to use valueFromLookup for specific value formats

packages/@aws-cdk/aws-ssm/README.md

@@ -34,6 +34,56 @@ your CDK app by using `ssm.StringParameter.fromStringParameterAttributes`:
 
 [using SSM parameter](test/integ.parameter-store-string.lit.ts)
 
+### Lookup existing parameters
+
+You can also use an existing parameter by looking up the parameter from the AWS environment.
+This method uses AWS API calls to lookup the value from SSM during synthesis.
+
+```ts
+const stringValue = ssm.StringParameter.valueFromLookup(stack, '/My/Public/Parameter');
+```
+
+When using `valueFromLookup` an initial value of 'dummy-value-for-${parameterName}'
+(`dummy-value-for-/My/Public/Parameter` in the above example)
+is returned prior to the lookup being performed. This can lead to errors if you are using this
+value in places that require a certain format. For example if you have stored the ARN for a SNS
+topic in a SSM Parameter which you want to lookup and provide to `Topic.fromTopicArn()`
+
+```ts
+const arnLookup = ssm.StringParameter.valueFromLookup(this, '/my/topic/arn');
+sns.Topic.fromTopicArn(this, 'Topic', arnLookup);
+```
+
+Initially `arnLookup` will be equal to `dummy-value-for-/my/topic/arn` which will cause
+`Topic.fromTopicArn` to throw an error indicating that the value is not in `arn` format.
+
+For these use cases you need to handle the `dummy-value` in your code. For example:
+
+```ts
+const arnLookup = ssm.StringParameter.valueFromLookup(this, '/my/topic/arn');
+let arnLookupValue: string;
+if (arnLookup.includes('dummy-value')) {
+	arnLookupValue = this.formatArn({
+	service: 'sns',
+	resource: 'topic',
+	resourceName: arnLookup,
+	});
+
+} else {
+	arnLookupValue = arnLookup;
+}
+
+sns.Topic.fromTopicArn(this, 'Topic', arnLookupValue);
+```
+
+Alternatively, if the property supports tokens you can convert the parameter value into a token
+to be resolved _after_ the lookup has been completed.
+
+```ts
+const arnLookup = ssm.StringParameter.valueFromLookup(this, '/my/role/arn');
+iam.Role.fromRoleArn(this, 'role', Lazy.string({ produce: () => arnLookup }));
+```
+
 ## Creating new SSM Parameters in your CDK app
 
 You can create either `ssm.StringParameter` or `ssm.StringListParameter`s in
@@ -57,3 +107,4 @@ new ssm.StringParameter(this, 'Parameter', {
 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.
+

packages/@aws-cdk/aws-ssm/rosetta/default.ts-fixture

@@ -1,7 +1,9 @@
 // Fixture with packages imported, but nothing else
 import { Construct } from 'constructs';
-import { Stack } from '@aws-cdk/core';
+import { Stack, Lazy } from '@aws-cdk/core';
 import * as ssm from '@aws-cdk/aws-ssm';
+import * as sns from '@aws-cdk/aws-sns';
+import * as iam from '@aws-cdk/aws-iam';
 
 class Fixture extends Stack {
   constructor(scope: Construct, id: string) {