# CfnInclude

Construct to import an existing CloudFormation template file into a CDK application.

All resources defined in the template file can be retrieved by calling the `getResource` method.
Any modifications made on the returned resource objects will be reflected in the resulting CDK template.

Extends: Construct › CfnElement › CfnInclude
Implements: IConstruct, IDependable

- Source: [`cloudformation-include/lib/cfn-include.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/cloudformation-include/lib/cfn-include.ts#L105)

## Example

```ts
const cfnTemplate = new cfn_inc.CfnInclude(this, 'Template', {
  templateFile: 'my-template.json',
});
```

## Initializer

```ts
new CfnInclude(scope: Construct, id: string, props: CfnIncludeProps)
```

## Construct Props

- `allowCyclicalReferences`: boolean — Specifies whether to allow cyclical references, effectively disregarding safeguards meant to avoid undeployable templates.

  **Default:** will throw an error on detecting any cyclical references

  This should only be set to true in the case of templates utilizing cloud transforms (e.g. SAM) that
  after processing the transform will no longer contain any circular references.

- `dehydratedResources`: string[] — Specifies a list of LogicalIDs for resources that will be included in the CDK Stack, but will not be parsed and converted to CDK types.

  **Default:** All resources are hydrated

  This allows you to use CFN templates
  that rely on Intrinsic placement that `cfn-include`
  would otherwise reject, such as non-primitive values in resource update policies.

- `loadNestedStacks`: { [key: string]: [CfnIncludeProps](/cdk/api/v2/docs/aws-cdk-lib.cloudformation_include.CfnIncludeProps.html) } — Specifies the template files that define nested stacks that should be included.

  **Default:** no nested stacks will be included

  If your template specifies a stack that isn't included here, it won't be created as a NestedStack
  resource, and it won't be accessible from the `CfnInclude.getNestedStack` method
  (but will still be accessible from the `CfnInclude.getResource` method).

  If you include a stack here with an ID that isn't in the template,
  or is in the template but is not a nested stack,
  template creation will fail and an error will be thrown.

- `parameters`: { [key: string]: any } — Specifies parameters to be replaced by the values in this mapping.

  **Default:** parameters will retain their original definitions

  Any parameters in the template that aren't specified here will be left unmodified.
  If you include a parameter here with an ID that isn't in the template,
  template creation will fail and an error will be thrown.

  If you are importing a parameter from a live stack, we cannot know the value of that
  parameter. You will need to supply a value for your parameters, else the default
  value will be used.

- `preserveLogicalIds`: boolean = true — Whether the resources should have the same logical IDs in the resulting CDK template as they did in the original CloudFormation template file.

  If you're vending a Construct using an existing CloudFormation template,
  make sure to pass this as `false`.

  **Note**: regardless of whether this option is true or false,
  the `CfnInclude.getResource` and related methods always uses the original logical ID of the resource/element,
  as specified in the template file.

- `templateFile`: string (required) — Path to the template file.

  Both JSON and YAML template formats are supported.

## Properties

- `creationStack`: string[]

- `logicalId`: string — The logical ID for this CloudFormation stack element.

  The logical ID of the element
  is calculated from the path of the resource node in the construct tree.

  To override this value, use `overrideLogicalId(newLogicalId)`.

- `node`: [Node](/cdk/api/v2/docs/constructs.Node.html) — The tree node.

- `stack`: [Stack](/cdk/api/v2/docs/aws-cdk-lib.Stack.html) — The stack in which this element is defined.

  CfnElements must be defined within a stack scope (directly or indirectly).

## Methods

- `getCondition(conditionName: string): CfnCondition` — Returns the CfnCondition object from the 'Conditions' section of the CloudFormation template with the given name.

  Any modifications performed on that object will be reflected in the resulting CDK template.

  If a Condition with the given name is not present in the template,
  throws an exception.

  **Parameters**

  - `conditionName` — the name of the Condition in the CloudFormation template file.

- `getHook(hookLogicalId: string): CfnHook` — Returns the CfnHook object from the 'Hooks' section of the included CloudFormation template with the given logical ID.

  Any modifications performed on the returned object will be reflected in the resulting CDK template.

  If a Hook with the given logical ID is not present in the template,
  an exception will be thrown.

  **Parameters**

  - `hookLogicalId` — the logical ID of the Hook in the included CloudFormation template's 'Hooks' section.

- `getMapping(mappingName: string): CfnMapping` — Returns the CfnMapping object from the 'Mappings' section of the included template.

  Any modifications performed on that object will be reflected in the resulting CDK template.

  If a Mapping with the given name is not present in the template,
  an exception will be thrown.

  **Parameters**

  - `mappingName` — the name of the Mapping in the template to retrieve.

- `getNestedStack(logicalId: string): IncludedNestedStack` — Returns a loaded NestedStack with name logicalId.

  For a nested stack to be returned by this method,
  it must be specified either in the `CfnIncludeProps.loadNestedStacks` property,
  or through the `loadNestedStack` method.

  **Parameters**

  - `logicalId` — the ID of the stack to retrieve, as it appears in the template.

- `getOutput(logicalId: string): CfnOutput` — Returns the CfnOutput object from the 'Outputs' section of the included template.

  Any modifications performed on that object will be reflected in the resulting CDK template.

  If an Output with the given name is not present in the template,
  throws an exception.

  **Parameters**

  - `logicalId` — the name of the output to retrieve.

- `getParameter(parameterName: string): CfnParameter` — Returns the CfnParameter object from the 'Parameters' section of the included template.

  Any modifications performed on that object will be reflected in the resulting CDK template.

  If a Parameter with the given name is not present in the template,
  throws an exception.

  **Parameters**

  - `parameterName` — the name of the parameter to retrieve.

- `getResource(logicalId: string): CfnResource` — Returns the low-level CfnResource from the template with the given logical ID.

  Any modifications performed on that resource will be reflected in the resulting CDK template.

  The returned object will be of the proper underlying class;
  you can always cast it to the correct type in your code:

      // assume the template contains an AWS::S3::Bucket with logical ID 'Bucket'
      const cfnBucket = cfnTemplate.getResource('Bucket') as s3.CfnBucket;
      // cfnBucket is of type s3.CfnBucket

  If the template does not contain a resource with the given logical ID,
  an exception will be thrown.

  **Parameters**

  - `logicalId` — the logical ID of the resource in the CloudFormation template file.

- `getRule(ruleName: string): CfnRule` — Returns the CfnRule object from the 'Rules' section of the CloudFormation template with the given name.

  Any modifications performed on that object will be reflected in the resulting CDK template.

  If a Rule with the given name is not present in the template,
  an exception will be thrown.

  **Parameters**

  - `ruleName` — the name of the Rule in the CloudFormation template.

- `isCfnElement(x: any): boolean` (static) — Returns `true` if a construct is a stack element (i.e. part of the synthesized cloudformation template).

  Uses duck-typing instead of `instanceof` to allow stack elements from different
  versions of this library to be included in the same stack.

  **Returns:** The construct as a stack element or undefined if it is not a stack element.

- `isConstruct(x: any): boolean` (static) — Checks if `x` is a construct.

  Use this method instead of `instanceof` to properly detect `Construct`
  instances, even when the construct library is symlinked.

  Explanation: in JavaScript, multiple copies of the `constructs` library on
  disk are seen as independent, completely different libraries. As a
  consequence, the class `Construct` in each copy of the `constructs` library
  is seen as a different class, and an instance of one class will not test as
  `instanceof` the other class. `npm install` will not create installations
  like this, but users may manually symlink construct libraries together or
  use a monorepo tool: in those cases, multiple copies of the `constructs`
  library can be accidentally installed, and `instanceof` will behave
  unpredictably. It is safest to avoid using `instanceof`, and using
  this type-testing method instead.

  **Parameters**

  - `x` — Any object.

  **Returns:** true if `x` is an object created from a class which extends `Construct`.

- `loadNestedStack(logicalId: string, nestedStackProps: CfnIncludeProps): IncludedNestedStack` — Includes a template for a child stack inside of this parent template.

  A child with this logical ID must exist in the template,
  and be of type AWS::CloudFormation::Stack.
  This is equivalent to specifying the value in the `CfnIncludeProps.loadNestedStacks`
  property on object construction.

  **Parameters**

  - `logicalId` — the ID of the stack to retrieve, as it appears in the template.
  - `nestedStackProps` — the properties of the included child Stack.

  **Returns:** the same `IncludedNestedStack` object that `getNestedStack` returns for this logical ID

- `overrideLogicalId(newLogicalId: string): void` — Overrides the auto-generated logical ID with a specific ID.

  **Parameters**

  - `newLogicalId` — The new logical ID to use for this stack element.

- `toString(): string` — Returns a string representation of this construct.

- `with(...mixins: IMixin[]): IConstruct` — Applies one or more mixins to this construct.

  Mixins are applied in order. The list of constructs is captured at the
  start of the call, so constructs added by a mixin will not be visited.
  Use multiple `with()` calls if subsequent mixins should apply to added
  constructs.