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 authoring tool 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
- In the developer console, open the skill that the document was saved with.
-
In the left-hand navigation, click Multimodal Responses.
The authoring tool opens in a new window or tab, and displays the Audio filter.
- Click either Audio or Visual to see the list of existing documents.
- Find the document in the list and click Download.
You can also export the document while editing the document. In the upper-right corner, click the 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:
- Visual response: Alexa.Presentation.APL Interface Reference.
- Audio response: Alexa.Presentation.APLA Interface Reference.
Instead of exporting the JSON and copying it into your code, you can provide a link to the document saved in the authoring tool 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 authoring tool independently of the code. For details, see the following:
- Visual response: Link to an APL document saved in the authoring tool (Alexa.Presentation.APL).
- Audio response: Link to an APLA document saved in the authoring tool (Alexa.Presentation.APLA).
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
- In the developer console, open the skill for which you want to import the document.
- In the left-hand navigation, click Multimodal Responses.
- Click Visual.
- Click Create Visual Response.
- Click Upload, then either drag your JSON file to the dialog box, or Browse to find the JSON file on your computer.
- 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": "2022.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": "2022.1",
"theme": "dark",
"import": [
{
"name": "alexa-layouts",
"version": "1.5.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.