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 WEGnology 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 WEGnology 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:

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:

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 Result

The export result files are human-readable in YAML format, which makes it easy to independently version control your WEGnology 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 ~wnology-<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 theWEGnology 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.

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.

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

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.

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.