Getting Started with ThingWorx > Importing and Exporting in ThingWorx
Importing and Exporting in ThingWorx
Importing and Exporting Data, Entities, and Extensions
There are multiple options for importing and exporting data and entities in ThingWorx. Depending on your starting point, importing an extension that contains data and entities into ThingWorx might be the first step in your journey. The information in streams, value streams, data tables, blogs, and wikis (row entries, blog posts, wiki pages) is considered data. Extensions can only be imported. While the Import/Export menu can only be used by administrator users, data and entities can be imported and exported manually by non-administrators. See Manually Exporting and Importing.
For smaller imports and exports, you can import using From File and export using To File since you are importing or exporting specific files. For larger imports and exports, you can import From Thingworx Storage and export To Thingworx Storage. They allow you to import or export all entities and data asynchronously from or to the ThingworxStorage/exports folder.
* 
Exports can contain sensitive information that should be properly protected. Any time a system export, filtered export, or single entity export occurs, the exported file should be encrypted and stored in a sensitive location. The export should not be shared with any untrusted parties, and once the import is confirmed to be successful into the target system, the export should either be securely deleted or securely stored in a long term storage solution. See Passwords for more information.
For more information on all import and export options available in ThingWorx, see the tables below.
Import
Importing entities that have been exported from a newer version of ThingWorx is not supported.
Option
Description
Supported Formats
Additional Information
From File
Imports a single file of entities or data from a selected local file (not asynchronous) or from a file repository.
XML, JSON, and binary
• For entities, if the Use default Persistence Provider option is selected, imported entities without a valid persistence provider will use the system-defined default persistence provider.
• For entities, if the Include Subsystems option is selected, the associated subsystem configurations are imported with the entities.
• For entities, if the Overwrite Property Values option is selected, the property values that currently exist on an entity will be overwritten by any property values for that entity that exist in the import. If unchecked, any property values in the import will be ignored.
From Thingworx Storage
Imports entities and data (optional) asynchronously from a selected (server-side) file located in the ThingworxStorage/exports folder on the server.
JSON and binary
* 
From Thingworx Storage automatically selects the correct file format when importing.
• If the Include data option is selected, data is imported in addition to the entities. The files must be located in ThingworxStorage/exports. ThingWorx automatically pairs the entity and data files.
* 
Each data file has an associated import.log file created upon import. The same data cannot be imported unless this file is deleted.
• If the Use default Persistence Provider option is selected, any imported entities that do not have a valid associated persistence provider will use the system-defined default persistence provider. Specifically,
◦ If the imported entity has a valid persistence provider established, ThingWorx will import it with that persistence provider.
◦ If the imported entity does not have a valid persistence provider established, ThingWorx will use the default persistence provider.
• If the Include Subsystems option is selected, all configured subsystem settings will be overwritten upon import.
• If the Overwrite collection permissions and organizations setting is selected, the collection permissions and organizations in the import file will overwrite the settings on the server. The default behavior merges the collection permissions and organizations from the imported file into what is already defined on the server.
• For entities, if the Overwrite Property Values option is selected, the property values that currently exist on an entity will be overwritten by any property values for that entity that exist in the import. If unchecked, any property values in the import will be ignored.
* 
In the following scenario, importing from Thingworx Storage will fail, and the import must be done as a two-step process if the following conditions are met:
1. A tag is added to one or more data entries and the vocabulary isn't dynamic.
2. That tag is subsequently deleted from the vocabulary.
3. Entities and data are exported to Thingworx Storage.
In this scenario, importing from Thingworx Storage with data will fail because ThingWorx imports the vocabulary and then fails when importing the data because the tag does not exist and cannot be added to a non-dynamic vocabulary. To enable the data import in this scenario, one of the following steps must be taken:
• Add the missing tag to the vocabulary on the original ThingWorx server and re-export to Thingworx Storage.
• Make the vocabulary dynamic on the original ThingWorx server and re-export to Thingworx Storage.
• Import only the entities to the new ThingWorx server, add the missing tag(s) to the appropriate vocabulary, and then import the data using the Import From File option.
Source Control Entities
Imports ThingWorx entities from a source control folder in a FileRepository thing in ThingworxStorage or a source control folder in a Source Control Repository thing. For more information on these repositories, see Thing Templates.
XML
• If the Use default Persistence Provider option is selected, imported entities without a valid persistence provider will use the system-defined default persistence provider.
• If the Include Subsystems option is selected, the associated subsystem configurations are imported with the entities.
• For entities, if the Overwrite Property Values option is selected, the property values that currently exist on an entity will be overwritten by any property values for that entity that exist in the import. If unchecked, any property values in the import will be ignored.
• If an error occurs, no entities in the folder will be imported. Files that fail to parse as XML or ThingWorx files are skipped. Errors are recorded in the Application log.
Extension
Imports an extension zip file.
.zip
Export
Option
Description
Format
Additional Information
To File—Collection of Entities
• Can synchronously export entities from specified entity collections (application keys, dashboards, mashups, media entities, etc.), with model tags, by project, or by date (determined by the “last modified date” time stamp on the file).
• If a repository is not specified, entities are exported locally.
Binary and XML
• If a file repository is not specified, the file will be exported locally in Downloads folder.
• If Export Matching Model Tags is selected, only entities that contain all the Tags specified in the Tags field are exported. If Export Matching Model Tags is not selected, entities that contain any of the Tags specified in the Tags field are exported.
To File—Collection of Data
• Can synchronously export data from specified collections (blogs, data tables, streams, value streams, or wikis), with model tags, or by date (determined by the data’s recorded timestamp).
Binary
• If a repository is not specified, a folder named SystemRespository will be automatically created at the following location: ThingworxStorage\repository\SystemRespository.
• If Export Matching Model Tags is selected, only entities that contain all the tags specified in the Tags field are exported. If Export Matching Model Tags is not selected, entities that contain any of the tags specified in the Tags field are exported.
To File—Single Entity
Can export a single entity to a selected local destination (synchronous).
Binary or XML
If a repository is not specified, the entity is downloaded locally.
To File—Single Data
Can export single data to a selected local destination (synchronous).
Binary
• If Export Matching Model Tags is selected, only entities that contain all the tags specified in the Tags field are exported. If Export Matching Model Tags is not selected, entities that contain any of the tags specified in the Tags field are exported.
To Thingworx Storage
Exports all entities and data (optional) asynchronously to the server (in the ThingworxStorage/exports folder).
Binary
• There is no size limit when exporting to the ThingworxStorage folder.
• The export is broken into folders by date, entity/data type, and data type name. For example, C:\ThingworxStorage\exports\20150625140545\Blogs\AcmeVendingEquiptmentBlog\data-0.twx
• The size of the exported files can be configured in the Export Import Subsystem.
• An accompanying checksum (chk) file is added for each data and entity file.
Source Control Entities
Exports ThingWorx entities by collection, model tags, project, start and end dates. The specified entities can be directed to a FileRepository or SourceControlRepository thing. When entities are exported, a file structure is created at the destination that resembles the way a source control system manages its artifacts. If you want to move or copy exported files to another location, you can export the file structure as a zip file.
* 
When exporting entities via source control, sensitive information such as password hashes or application key IDs associated with the entity are not exported. Importing the source control export back into the system will cause the loss of any sensitive information associated with the entity.
XML
• The following options are available when specifying the export of the entities:
◦ Collections— All, Application Keys, Dashboards, Data Shapes, Data Tags, Directory Services, Extension Packages, Localization Tables, Logs, Mashups, Media, Menus, Model Tags, Networks, Organizations,Persistence Providers, Projects, Resources, Script Function Libraries, State Definitions, Style Definitions, Style Themes,Subsystems, Thing Groups, Thing Packages, Things, Thing Shapes, Thing Templates, Users, User Groups.
◦ Project — Specify the project to use for export. When exporting entities, all entities that have the selected project applied will be exported.
◦ Tags—Use the magic picker to export by model tags.
◦ Export Matching Model Tags — If selected, only entities that contain all the tags specified in the Tags field are exported. If Export Matching Model Tags is not selected, entities that contain any of the tags specified in the Tags field are exported.
◦ Start Date—Use the start date to limit the content of exported entities based on the time stamp recorded with your entities. Start date exports entities time-stamped after the start date.
◦ End Date—Use the end date to limit the content of exported entities based on the time stamp as recorded with your data entries. End date exports entities time-stamped before the specified end date. If the end date is blank, the current date and time is used.
◦ Repository—Specify a repository for the export.
◦ Path—Specify the location of the export.
◦ Export to Zip File—Places the exported entities into a zip folder in the specified location. A file name must be provided.
Export from the More menu
XML
Universal Export
This option is useful when migrating data from one system to another, when each system uses unique encryption keys. For example, it is useful when migrating a pre-production system to a production system. In this situation, encrypted sensitive information such as properties of the base type PASSWORD, exported from one system cannot be imported to the other.
Available only for administrator users and only for exporting entities, this option allows entities to be exported from one ThingWorx server for subsequent import into another. Note that data associated with entities is NOT exported with them.
* 
When this Universal Export option is selected, sensitive information is exported in plain text. For ThingWorx Flows, however, sensitive information is not exported at all and must be re-entered via the ThingWorx Flow UI after import on the target system. A security warning appears when this option is selected. Ensure that the exported file is safeguarded in an appropriate way.
See the topic, Password Base type.
Binary or XML
This option is available within the Export UI when the following conditions are true:
• Export Option is "To File" or "To Thingworx Storage"
• Export Type is "Collection of Entities" or "Single Entity
• The user is a member of the Admin group
If a non-admin user calls the Export service directory with the universal option enabled, the server will prevent the user from performing the export.
Was this helpful?