Work with templates that reference external files

You can use external files with your AWS Serverless Application Model (AWS SAM) templates to reuse repeated code and organize your projects. For example, you may have multiple Amazon API Gateway REST API resources that are described by an OpenAPI specification. Instead of replicating the OpenAPI specification code in your template, you can create one external file and reference it for each of your resources.

AWS Application Composer supports the following external file use cases:

• API Gateway REST API resources defined by external OpenAPI specification files.

• AWS Step Functions state machine resources defined by external state machine definition files.

To learn more about configuring external files for supported resources, see the following:

• DefinitionBody for AWS::Serverless::Api.

• DefinitionUri for AWS::Serverless::StateMachine.

Note

To reference external files with Application Composer from the Application Composer console, you must use Application Composer in local sync mode. For more information, see Local sync mode.

Create an external file reference

You can create an external file reference from the resource properties panel of supported resources.

To create an external file reference

1. From an API Gateway or Step Functions enhanced component card, select Details to bring up the resource properties panel.

2. Locate and select the Use external file option.

3. Specify the relative path to the external file. This is the path from your template.yaml file to the external file.

   For example, to reference the api-spec.yaml external file from the following project’s structure, specify ./api-spec.yaml as your relative path.

   demo
   ├── api-spec.yaml
   ├── src
   │ └── Function
   │ ├── index.js
   │ └── package.json
   └── template.yaml

   Note

   If the external file and its specified path does not exist, Application Composer will create it.

4. Save your changes.

Load a project that contains an external file reference

Application Composer from the Application Composer console

When you load a project, the following occurs:

• If your browser supports the File System Access API, Application Composer will prompt you to connect to the root folder of your project. Application Composer will open your project in local sync mode to support your external file.

• If the referenced external file is not supported, you will receive an error message. For more information about error messages, see Troubleshooting.

Application Composer from the Toolkit for VS Code

When you access Application Composer from a template, Application Composer will automatically detect your external file. If the referenced external file is not supported, you will receive an error message. For more information about error messages, see Troubleshooting.

Best practices

For Application Composer from the Application Composer console, use Application Composer with a local IDE

When you use Application Composer with a local IDE in local sync mode, you can use your local IDE to view and modify external files. Content from supported external files that are referenced on your template will automatically update in the Application Composer canvas. To learn more, see Using Application Composer with your local IDE.

Keep external files within your project’s parent directory

You can create subdirectories within your project’s parent directory to organize your external files. Application Composer can’t access external files that are stored in a directory outside of your project’s parent directory.

Deploy your application using the AWS SAM CLI

When deploying your application to the AWS Cloud, local external files need to first be uploaded to an accessible location, such as Amazon Simple Storage Service (Amazon S3). You can use the AWS SAM CLI to automatically facilitate this process. To learn more, see Upload local files at deployment in the AWS Serverless Application Model Developer Guide.

Examples

Reference an OpenAPI specification external file

In this example, we use Application Composer from the console to reference an external OpenAPI specification file that defines our API Gateway REST API.

First, we create a new project from the Application Composer home page.

Next, we activate local sync by selecting Activate local sync from the Menu. We create a new folder named demo, allow the prompt to view files, and select Activate. When prompted, we select Save changes.

Next, we drag an Amazon API Gateway card onto the canvas. We select Details to bring up the Resource properties panel.

From the Resource properties panel, we configure the following and save.

• Select the Use external file for api definition option.

• Input ./api-spec.yaml as the relative path to external file

This creates the following directory on our local machine:

demo
└── api-spec.yaml

Now, we can configure the external file on our local machine. Using our IDE, we open the api-spec.yaml located in our project folder. We replace its contents with the following:

openapi: '3.0'
info: {}
paths:
  /:
    get:
      responses: {}
    post:
      x-amazon-apigateway-integration:
        credentials:
          Fn::GetAtt:
            - ApiQueuesendmessageRole
            - Arn
        httpMethod: POST
        type: aws
        uri:
          Fn::Sub: arn:${AWS::Partition}:apigateway:${AWS::Region}:sqs:path/${AWS::AccountId}/${Queue.QueueName}
        requestParameters:
          integration.request.header.Content-Type: '''application/x-www-form-urlencoded'''
        requestTemplates:
          application/json: Action=SendMessage&MessageBody={"data":$input.body}
        responses:
          default:
            statusCode: 200
      responses:
        '200':
          description: 200 response

In the Application Composer Template view, we can see that Application Composer has automatically updated our template to reference the external file.

Create an application using the AWS SAM CLI and load it in Application Composer

In this example, we use the AWS SAM CLI to create an application that references an external file for its state machine definition. We then load our project in Application Composer with our external file properly referenced.

First, we use the AWS SAM CLI sam init command to initialize a new application named demo. During the interactive flow, we select the Multi-step workflow quick start template.

$ sam init

...

Which template source would you like to use?
        1 - AWS Quick Start Templates
        2 - Custom Template Location
Choice: 1

Choose an AWS Quick Start application template
        1 - Hello World Example
        2 - Multi-step workflow
        3 - Serverless API
        4 - Scheduled task
        ...
Template: 2

Which runtime would you like to use?
        1 - dotnet6
        2 - dotnetcore3.1
        ...
        15 - python3.7
        16 - python3.10
        17 - ruby2.7
Runtime: 16

Based on your selections, the only Package type available is Zip.
We will proceed to selecting the Package type as Zip.

Based on your selections, the only dependency manager available is pip.
We will proceed copying the template using pip.

Would you like to enable X-Ray tracing on the function(s) in your application?  [y/N]: ENTER

Would you like to enable monitoring using CloudWatch Application Insights?
For more info, please view https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-application-insights.html [y/N]: ENTER

Project name [sam-app]: demo

    -----------------------
    Generating application:
    -----------------------
    Name: demo
    Runtime: python3.10
    Architectures: x86_64
    Dependency Manager: pip
    Application Template: step-functions-sample-app
    Output Directory: .
    Configuration file: demo/samconfig.toml
    
    Next steps can be found in the README file at demo/README.md

...

This application references an external file for the state machine definition.

...
Resources:
  StockTradingStateMachine:
    Type: AWS::Serverless::StateMachine
    Properties:
      DefinitionUri: statemachine/stock_trader.asl.json
...

The external file is located in the statemachine subdirectory of our application.

demo
├── README.md
├── __init__.py
├── functions
│   ├── __init__.py
│   ├── stock_buyer
│   ├── stock_checker
│   └── stock_seller
├── samconfig.toml
├── statemachine
│   └── stock_trader.asl.json
├── template.yaml
└── tests

Next, we load our application in Application Composer from the console. From the Application Composer home page, we select Load a CloudFormation template.

We select our demo project folder and allow the prompt to view files. We select our template.yaml file and select Create. When prompted, we select Save changes.

Application Composer automatically detects the external state machine definition file and loads it. We select our StockTradingStateMachine resource and choose Details to show the Resource properties panel. Here, we can see that Application Composer has automatically connected to our external state machine definition file.

Any changes made to the state machine definition file will be automatically reflected in Application Composer.