Import and Export

Applications and their resources can be exported, shared, and imported 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:

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.

Application Import

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:

Enable Toggle

Import Into an Existing Application

You can import a previously exported application into an existing application by uploading the export zip within the Application Import/Export Settings:

Partial Application Export

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 “Application Info” link.

Application Export

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

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 Result

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

Exported Application Contents

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.

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.