Import, Export, and Clone

Applications and their resources can be imported, exported from, or cloned into other Organizations.

Importing and Exporting allows users to share their applications with users outside of their organization easily. All of the export files are human-readable, which makes it easy to use things like Git to independently version control your Losant Applications.

You can:

• Create a new application from an import
• Import into an existing application
• Export an existing application
• Clone an existing application

Importing An Application

You can import a previously exported application by using the “Import” button on your Organization overview page and uploading the export zip.

If the application is small, you’ll be immediately redirected to the new application’s overview page. If the application is large, you’ll receive an email when the import is complete.

Resource IDs

Since IDs within Losant are globally unique, all resources in an imported application will have different IDs than the original application. The import process will take care of re-creating any relationships between resources using their newly generated ID.

Disabled Resources

Application Workflows and Integrations are automatically disabled for imported applications. This is to ensure unexpected logic is not executed until you’re ready.

Integrations can be enabled on the specific properties page for each integration. You can quickly enable all workflows on the workflows overview page:

Application Import Throttling

Application imports are limited to 1 request per 60 seconds per owner (i.e. per personal Sandbox or per organization). If multiple import requests are received within a 60-second window for a given owner, a 429 status code is returned with a message that indicates how much longer the throttle is in effect.

Import Into an Existing Application

When importing an export bundle into an existing application, there are a few properties to set for the import request.

Request Dry Run

We recommend you test your exported bundle by requesting a dry run before proceeding with the import. To do so, select an application export bundle, configure your settings, then click the “Request Dry Run Report” button. Depending on the size of the bundle and your import settings, the CSV report may be generated instantly, otherwise, a download link will be sent to the email address and/or callback URL provided. The CSV lists which resources from the bundle would be created and for each resource, details whether the resource conflicts with an existing resource in the existing application. In the case of a conflict, the ID of the existing resource is listed as well as the anticipated result based on the selected conflict behavior.

Bundle Source

You can import a previously exported application into an existing application by uploading the export zip (up to 10MB) within the Application Import/Export Settings:

To upload files larger than 10MB, click on the “Import from a URL” button. Then, enter a URL from which the bundle should be pulled or click the folder icon to browse your Application Files. Importing from a URL is an asynchronous request and can take some time to complete. You will receive an email when the process has finished.

Resource Selection

By default all resources in the import bundle are uploaded. Optionally you may choose to import only specified resource types.

There are some potential ramifications and errors to consider if you choose to import only specified resources.

• If you import resources that reference other resources that are not imported, there is a high likelihood that the import will error. For example, if device recipes are uploaded and one or more recipes reference a parent device but devices are not uploaded a validation error is thrown.
• For versioned experience resources, only the develop version of specified resources are imported when the resources are explicitly selected.
• To import all versions of experience resources other than those from the “develop” version, you must select Experience Versions. This will import all resources from all other versions, as well as each version’s configuration settings.

Conflict Behavior

Conflict behavior describes what should happen in the case of conflicting resources during the import process. There are four available conflict behaviors:

• Keep both resources whenever possible: (Default) The import process attempts to keep both the existing resource and the resource from the bundle.
• Overwrite the existing resource with the imported resource: The import process replaces existing resources with resources from the bundle in the case of a conflict.
• Keep the existing resource and ignore the imported resource: The import process retains the existing resources and ignores conflicting resources in the import bundle.
• Error the import request if any resources conflict: The import process errors and no resources from the import bundle are added to the application.

How Are Conflicts Determined?

The exact parameters that determine a conflict for the import process vary by resource type. Resources match by their “name” property unless otherwise noted below.

• Devices: Name and device class
• Integrations: Name and integration type
• Non-Experience Workflows: Name and flow class
• Non-Experience Workflow Versions: Name, flow class, and version
• Experience Workflows: Name, flow class, and version (develop only, see below note for versioned experience workflows)
• Experience Endpoints: Method, route, and version (develop only, see below note for versioned experience workflows)
• Experience Views: Name, type, and version (develop only, see below note for versioned experience workflows)
• Experience Versions: Version name
• Experience Users: Email address
• Experience Groups: Name and parent group
• Files: Name and directory
• Application Globals: Key
• Data Table Rows: Data table ID and row ID

Note for conflicting experience versions: If an experience version in an import bundle conflicts with an existing experience version, all of the resources within the version will follow the selected conflict behavior. If keeping existing resources, no resources of that version from the bundle will be imported. If overwriting existing resources, all existing resources will be removed and the resources from the bundle will be imported. The exception to this is for resources in the “develop” version, which conflict according to the above rules.

Note that these conflicts do not always align with what is strictly allowed in applications. For example, it is possible within an application to make two devices with the same name and the same class without issue and this is considered a conflict when a bundle is imported. Additionally, if a resource from the import bundle conflicts with multiple existing resources, the import will error (unless keeping both resources).

Notifications

You may provide an email address to send a notification when the import has succeeded. When uploading a small application bundle, files will be imported immediately and no email will be sent. Optionally, you can provide a URL that will receive a callback request when the import has completed.

Existing Application Import Throttling

Application import resource requests are limited to 1 request per 60 seconds per application. If multiple import resource requests are received within a 60-second window for a given application, a 429 status code is returned with a message that indicates how much longer the throttle is in effect.

Exporting An Application

You can only export an application if you are an Administrator for that application.

Exporting can be found under the “Export” tab under the “Import / Export” navigation.

Depending on the number of resources, exporting an application can take a while. For this reason, if your application is large, you will see an Email Address field on this export screen. If so, once the export is complete, you will receive a link to download a zip file.

If your application is small enough, you’ll be immediately prompted to download the export. In either case, the export will be a zip file. When you extract it, you’ll see a folder structure and YAML files that represent the resources that make up your application.

Resources That Will Never Be Exported

• Access Keys
• API Tokens
• Events
• Device State Data
• Experience Domains and Slugs
• Edge and Embedded Workflow Deployments

Optional Resources to Export

• Devices - Selecting this option will include all of your device configuration in the export. This does not include any device data nor any access keys tied to your devices.
• Data Table Rows - Selecting this option will include all of the rows stored within your Data Tables in the export. If unchecked, your export will still include all of your tables and their column configurations, just no content in the tables.
• Files - Selecting this option will include all of your files in the export. If unchecked, any references to your files (such as within experience views) will no longer work.

Export Throttling

Only one export of a given application may be in progress at a time. If additional export requests are received while there is one in progress, a 429 status code is returned and the request must be made again after the in-progress request completes.

Export Result

The export result files are human-readable in YAML format, which makes it easy to independently version control your Losant applications.

Editing the Export Result

You can also directly edit these files if you’d like to make changes manually. A common edit may be to replace actual devices and users with an example set, which can make imported applications a little cleaner.

All exported YAML files, except file resources, will always have two keys resourceType and resources. If you do not have any resources of a specific type, that file will not be exported.

All IDs are replaced with placeholder IDs, that will be in the format of ~losant-<resourceModelName>-<resourceName>-<number>~.

Single File Resources

The following are resources that will come in a single file, and by default the file name is the name of the resource type, e.g. device recipes will be in the deviceRecipe.yaml file.

Application Meta File

application.yaml - The resource type for this file is Application. The application meta file is very special. It is the only resource that can have only one resource in it’s resources list. It is also the only required file to exist for the zip to be importable.

This metafile will have a special field on it called filesPath. It is the relative path to the root directory for file resources. By default, this field will be ./files. If this field is removed, then files will not be imported.

Device Recipe Export

deviceRecipe.yaml - The resource type for this file is DeviceRecipe.

Device Export

device.yaml - The resource type for this file is DeviceGroupTree.

If you have System devices you will notice a special attribute labeled children which will contain that device’s children.

Integration Export

integration.yaml - The resource type for this file is Integration.

Webhook Export

webhook.yaml - The resource type for this file is Webhook.

Multiple File Resources

The following are resources that will be exported to multiple files for legibility because their metadata can be very large. The directory will be named after the resource type, and each metadata file will be named after the resource’s name.

If you combined these files into one giant file with the list of resources, they would still import correctly.

Dashboards Export

dashboard - The resource type in each of these files is Dashboard.

Workflows Export

workflows - The resource type in each of these files is Flow. This will only include edge and application workflows.

Workflow Versions Export

workflowVersions - The resource type in each of these files is FlowVersion. These will only include edge and application workflow versions.

File Resources with Metafiles

The following are resources that will be inside a directory with a metafile. These files have a special field called localFilename, which will point the metafile to the local resource.

Each of these will be placed in a directory named by the resource type. Inside the resource type directory, each file will be named by the name of the resource.

Notebooks Export

Notebooks - The resource type for these metafiles is Notebook. The notebook executable will be included in the export.

Data Tables Export

Data Tables - The resource type for these metafiles is DataTable. The data tables are optionally exported with their CSV of data.

Files Export Result

File resources themselves are very special in an export, because they do not need to contain any metafiles.

By default, they will be placed under a directory named files and the application metafile will contain a field called filesPath. This field tells the import where to look for the files resources, if any. If this field is not present or left blank, no files will be imported.

The files resources inside of the files directory will reflect the same paths as seen in theLosant Files UI. Empty directories will not be included in the export.

Experience Resources

All experience resources and versions of those resources will be placed in the directory called experience. Inside this directory there will be the following:

Experience Users

users.yaml - The resource type is ExperienceUsers, and it is a list of all the users.

Experience Groups

groups.yaml - The resource type is ExperienceGroupTree. All of the groups will be defined under resources, but they will have a special field called children. Children will be a list of all the group’s children. This keeps the nested group structure that can be seen in the Experience Group UI.

Versioned Experience Resources

All directories inside of the experience directory are named by the experience version name e.g. /export-application/experiences/develop. Inside of each of those directories will be the following resources:

Experience Endpoints

endpoints.yaml - This single file of all the endpoints for this particular version. The resource type is ExperienceEndpoint.

Experience Version

version.yaml - This is the meta data about the specific version. The resource type is ExperienceVersion.

Experience Layouts

layouts - This is a directory that will have a layouts.yaml metafile and each layout will have a handlebars file named by the name of the layout. In the layouts.yaml file, each resource will have a localFilename field, connecting the handlebars template to the layout meta data. The resource type for these files is ExperienceView.

Experience Pages

pages - This is a directory that will have a pages.yaml metafile and each page will have a handlebars file. In the pages.yaml file, each resource will have a localFilename field connecting the handlebars template to the page meta data. The resource type for these files is ExperienceView.

Experience Components

components - This is a directory that will have a components.yaml metafile and each page will have a handlebars file named by the name of the component. In the components.yaml file, each resource will have a localFilename field, connecting the handlebars template to the component meta data. The resource type for these files is ExperienceView.

Experience Workflows

workflows - This is a directory of all your Experience Workflows. Inside this directory will be a file for each workflow that is associated with this Experience Version. Each file will be named by the workflow name. The storage type for these files is ExperienceFlowVersion.

Cloning an Application

If you want to make a near-identical copy of an application, you can clone it. To do so:

1. Open the Import / Export screen.
2. Select Clone.
3. Choose an owner of the application from one of the available options in the drop-down menu. By default this is the organization or Sandbox that currently owns the source application, but this can be changed to any other organization where you have administrator access (or your own Sandbox).

4. Optional. Choose whether to clone the following by selecting the checkbox:

   • Clone devices—Copies all of your device data to the new application. Does not include any device data or access keys tied to your devices.
   • Clone data (rows) within data tables—Copies all the data stored within your data tables. If unchecked, your new application will still include all of your tables and column configurations.
   • Clone application files—Copies all of your files to the new application. If unchecked, links to your files will stop working.
5. Click Clone Application.

Cloned applications are still subject to account resource limits, and you are unable to clone an application if the result of the operation causes any of your resources to go over their allowed limits.

The following will not be cloned into the new application:

• Access keys
• API tokens
• Events
• Device state data
• Experience domains and slugs
• Edge workflow deployments

The following will be cloned but in a disabled state:

• Workflows
• Integrations

All other application resources, archive configuration settings, and global values are cloned into the new application.

Depending on the size of your cloned application, it may take some time for the process to complete, in which case you will receive an email at the address of your choosing, configured in the dialog, when your new application is ready.

Clone Throttling

Application clone limits are limited to 1 request per 60 seconds per owner (i.e. per personal Sandbox and per organization). If multiple import requests are received within a 60-second window for a given owner, a 429 status code is returned with a message that indicates how much longer the throttle is in effect.

Troubleshooting

Here are some common problems that may occur:

Opening Zip Files

If you are using a Windows computer, and you are having trouble unzipping an export, it could be due to your Application File path names.

The Windows OS will only allow 250 characters for the entire path inside the zip file. You may have to use a more powerful zip library such as UnZip.