Import and Export APL Documents

Export an APL document to create a JSON file with the document and data sources. You can import a previously-exported document to create a new document.

The following sections describe how to export and import full APL documents. You can also import animations in Lottie format. For details about Lottie, see Import a Lottie Animation.

Export an APL document to JSON

Exporting a document from the developer console combines the document, data, and sources in a single JSON file with top-level document, datasources, and sources properties.

{
  "document": {},
  "datasources": {
    "dataSourceName": {}
  },
  "sources": {
    "sourceName": {}
  }
}

If you make changes to this file outside of the authoring tool, you can re-import the file later as a new APL document.

To export a document

  1. In the developer console, open the skill that the document was saved with.
  2. In the left-hand navigation, click Multimodal Responses.
  3. Click either Audio or Visual to see the list of existing documents.
  4. Find the document in the list and click Download.

You can also export the document while editing the document in the authoring tool. In the upper-right corner, click the Export Code button (Export Code button ).

Use the exported document in your skill code

After you export an APL document as a JSON file, you can copy the JSON into your skill code and return the document in the RenderDocument directive.

For details about RenderDocument, see the following:

Instead of exporting the JSON and copying it into your code, you can provide a link to the document saved in the developer console when you return RenderDocument. Linking to the response instead of embedding the JSON in your code simplifies the code and lets a skill designer work on the response in the developer console independently of the code.

Use the Integrate with Skill option in the developer console to get a code example that shows how to return RenderDocument with a link to the document.

For details, see the following:

Import an APL document from a JSON file (visual response)

When you import an existing APL document from a JSON file, the authoring tool creates a new document based on the file.

To import an APL document for a visual response from a JSON file

  1. In the developer console, open the skill for which you want to import the document.
  2. In the left-hand navigation, click Multimodal Responses.
  3. Click Create with authoring tool.
  4. Click Upload, then either drag your JSON file to the dialog box, or Browse to find the JSON file on your computer.
  5. Click Upload.

Format for importing an APL document

The JSON file to upload must have the following structure:

{
  "document": {},
  "datasources": {
    "dataSourceName": {}
  },
  "sources": {
    "sourceName": {}
  }
}
Property Type Description Required
document Object Contains the JSON for the APL document Yes
datasources Map of data source objects Map of data sources to test with the document. No
sources Map of source objects Applies when the document type is APL. Map of APL for audio documents to test with the APL for audio transformer. For details about how you use sources, see Test the APL and APL for audio integration. No

For example, the following JSON file imports a document without any data sources or sources.

{
  "document": {
    "type": "APL",
    "version": "2023.1",
    "theme": "dark",
    "import": [],
    "resources": [],
    "styles": {},
    "layouts": {},
    "mainTemplate": {
      "parameters": [
        "payload"
      ],
      "items": [
      ]
    }
  }
}

This example illustrates a file with both document and datasources properties.

{
  "document": {
    "type": "APL",
    "version": "2023.1",
    "theme": "dark",
    "import": [
      {
        "name": "alexa-layouts",
        "version": "1.7.0"
      }
    ],
    "mainTemplate": {
      "parameters": [
        "payload"
      ],
      "item": [
        {
          "type": "AlexaHeadline",
          "id": "PlantHeadline",
          "primaryText": "${payload.headlineTemplateData.properties.textContent.primaryText.text}",
          "headerBackButton": false,
          "headerAttributionImage": "${payload.headlineTemplateData.properties.logoUrl}",
          "headerAttributionPrimacy": true,
          "footerHintText": "${payload.headlineTemplateData.properties.hintText}",
          "backgroundImageSource": "${payload.headlineTemplateData.properties.backgroundImage.sources[0].url}",
          "backgroundColorOverlay": false,
          "speech": "${payload.headlineTemplateData.properties.welcomeSpeech}"
        }
      ]
    },
    "onMount": [
      {
        "type": "SpeakItem",
        "componentId": "PlantHeadline"
      }
    ]
  },
  "datasources": {
    "headlineTemplateData": {
      "type": "object",
      "objectId": "headlineSample",
      "properties": {
        "backgroundImage": {
          "contentDescription": null,
          "smallSourceUrl": null,
          "largeSourceUrl": null,
          "sources": [
            {
              "url": "https://d2o906d8ln7ui1.cloudfront.net/images/templates_v3/headline/HeadlineBackground_Dark.png",
              "size": "large"
            }
          ]
        },
        "textContent": {
          "primaryText": {
            "type": "PlainText",
            "text": "Welcome to The Daily Plant Facts"
          }
        },
        "logoUrl": "https://d2o906d8ln7ui1.cloudfront.net/images/templates_v3/logo/logo-modern-botanical-white.png",
        "hintText": "Try, \"Alexa, what is the plant fact of the day?\"",
        "welcomeSpeechSSML": "<speak><amazon:emotion name='excited' intensity='medium'>Welcome to The Daily Plant Facts</amazon:emotion></speak>"
      },
      "transformers": [
        {
          "inputPath": "welcomeSpeechSSML",
          "transformer": "ssmlToSpeech",
          "outputName": "welcomeSpeech"
        }
      ]
    }
  },
  "sources": {}
}

This example shows a document with a data source and sources for testing with an APL for audio document.

Alternatively, you can also paste or create your data source directly in the authoring tool.

Synchronize documents with APL Ninja

APL Ninja is an independent social platform for Alexa developers developed by Alexander Martin. You can use features in this platform to synchronize APL documents between the developer console and APL Ninja.

To learn how to synchronize your documents, see the SMAPI Integration page in APL Ninja.

Last updated: May 19, 2021