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

Only one import per owner (i.e. per personal Sandbox or per organization) may be in progress at a time. If additional import 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.

Import Into an Existing Application

Resources can also be imported into an existing application from a few different sources. Doing so allows for the sharing of proofs of concept and custom user templates, and the process also enables the management of an IoT application development lifecycle.

Import Request Settings

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 testing your import request first with a “dry run” before proceeding with the import. To do so, configure your request settings as described below, then click the “Request Dry Run Report” button. The result CSV, as well as any errors that would prevent an actual import, will then appear in the import request log and be delivered to your email and/or callback URL when the check is complete. (Depending on the size of the import source, this can take anywhere from a few seconds to several minutes.)

The CSV lists which resources from the bundle will 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.

If the selected conflict behavior is either “Replace” or “Retain”, and an existing application resource does conflict with an imported resource, and the existing resource has an export hash from a previous import that matches the export hash for the resource to be imported, then that indicates the configuration of the two resources is exactly the same and the import will have no impact on that particular resource.

The dry run CSV headers include the following:

• resourceType: The type of resource to import.
• resourceFingerprintFormat: The string format of the fingerprint used to find existing resource conflicts.
• importingResourceFingerprint: The fingerprint based on the YAML, and built with the fields shown in the fingerprint format. This fingerprint is unique per resource type.
• importingResourceId: The ID from the YAML file.
• existingResourceId: A matching existing resource ID from the importing application.
• importResult: The resulting import behavior at the time of import (create, error, retain, replace, no change) based on the selected conflict behavior and the results of the conflicts. For example, if the import is including Experience Views and the selected conflict behavior is replace, if a view with the same fingerprint is not found within the application, the result will be create.
• importResultComments: This field includes extra information about the resources at the time of import. If the import result is error, then this field can include the error message. For Data Tables, if the import is including data table rows, there will be some information on how many rows will be created, updated, conflict or error. For any non-develop-version experience resources (Experience Endpoints, Experience Views, and Experience Workflows), this field will contain information as to how these resources are created.

Import Source

The import source can be provided one of three ways:

1. Choose a source application: Choose any application that you have at least collaborate permissions for. The application can come from your sandbox or any organization.
2. Upload a .zip file: Select this option to upload a previously generated export bundle (up to 10MB) from your local file system.
3. Import from a URL: Provide a public URL to an export bundle. For example, if you wish to import .zip file larger than 10MB, you may upload the file to Application Files and then provide its URL through this method.

Resource Selection

By default all resources from the source 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 imported resources reference other resources that are not imported (are missing from the import source) and do not match against an existing resource by fingerprint, 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. Note: Losant recommends only importing the “develop” version and then creating a new experience version to serve to your users after thorough testing. Overwriting of experience versions could lead to unintended consequences without being verified first.

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

Finally, provide either or both of the following …

• Email Address: The result of the operation - a dry run report or an import request - will be provided to the address provided once it is completed. This value defaults to the address of the user making the import request.
• Callback URL: On completion, a POST request will be made to the provided URL. A link to the dry run report (if applicable) and other information relevant to the request will be available in the request body. The URL must be publicly available (such as a Losant webhook).

Import Request Log

A log of recent import requests is also available on the import request form. Each log item includes settings from the request, including:

• Who made the request and when.
• Settings applied to the request, including the bundle source, conflict behavior, selected resource types, and notifications.
• Whether the request succeeded, and why it failed if so.
• A link to the dry run report, if applicable and still available. (The report is no longer available 7 days after completion.)

From the log, any previous request’s settings can be copied to a new import request. Doing so will overwrite the import form’s settings with the settings applied to the selected log item, after which you may review the settings, make any adjustments, and submit a new request.

There are a few caveats to consider:

• If copying a request that used another application as the import source, the selected application will not be applied to the new request if the user does not have collaborator permissions for that application.

• Requests that use a .zip file as the import source will provide the bundle as an import URL for a new request, but only if …

  • The user who made the original import request is setting up the new request, and
  • A link to the originally uploaded file is still available, which it will only be for 7 days after the request was made.
• Requests that use an import URL as the source will only copy the URL to the new request if the user who made the original import request is setting up the new request.
• The email address from a previous request will never replace the value of the “Email Address” field in the form, which defaults to the address of the current user.

Existing Application Import Throttling

Only one application import resource request may be in progress at a time. If additional application import resources 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.

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.

Exporting an application takes time. When making the request, you must provide either an Email Address or a Callback URL (or both) for where to deliver the export .zip file when the process is complete. The link provided in the email and/or callback body expires after 7 days.

Resources That Will Never Be Exported

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

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, command history, and connection history
• Experience Domains and Slugs
• Edge and Embedded Workflow deployments
• Job execution history (for Notebooks, Resource Jobs, and application imports)
• Service Credentials
• Workflow storage values and execution metrics

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

Only one application clone request for a given owner (i.e. per personal Sandbox or per organization) may be in progress at a time. If additional clone 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.

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.