Importing Entities in 9.2+
Due to improvements made to ThingWorx permissions and security model, substantial changes were made to the way in which permissions are stored in ThingWorx 9.2.0 and later. These improvements affect the process of importing entities from older releases into ThingWorx 9.2.0 and later. Prior to Thingworx 9.2.0, it was possible to import entities with permissions using principals (users, user groups, organizations, and organization units) that were not yet imported into the platform; principals could be imported later. In 9.2.0 and later, entities with permissions that have references to principals not currently in the platform, or not part of the same import file, will lose the permissions assigned to them.
Specifically, importing entities from older releases into Thingworx 9.2.0 and later may cause failures due to the following missing principal scenarios:
• Deleted principals that are still present in the permissions JSON that is persisted with the entity.
• Entities imported with valid principals that are not currently in the system but will get imported later.
To avoid these failures, you must first import all the users, user groups, and organizations (Principals.xml) referred to in your entities export, and then import the entities (Entities.xml). This ensures that the users, user groups, organization units, and organizations exist in the platform before importing entities that reference these principals in their permissions. The principals.xml file is obtained by combining the user, user group, and organization exports into a single file.
 |
If you mistakenly import the Entities.xml before importing the Principals.xml, you can re-import Entities.xml after importing Principals.xml to apply the permissions to the entities.
|
Combining Entities and Principals in the Same XML File
You can also combine the entities and the principals in the same import file. The order does not need to be maintained within the same import file, as the platform will import the principals before importing any other entities. For example, the following AllEntities.xml will work in 9.2.0 and later:
//AllEntities.xml
<Entities build="latest" majorVersion="0" minorVersion="0"
revision="0" schemaVersion="940">
<Things>
<Thing effectiveThingPackage="ConfiguredThing" enabled="true" homeMashup=""
identifier="" lastModifiedDate="2017-04-10T14:15:07.346-04:00" name="TestThing-WithPermissions"
projectName="" published="false" tags=""
thingTemplate="GenericThing" valueStream="">
<Owner name="Administrator" type="User" />
<avatar />
<DesignTimePermissions>
<Create />
<Read />
<Update />
<Delete />
<Metadata />
</DesignTimePermissions>
<RunTimePermissions>
<Permissions resourceName="*">
<PropertyRead />
<PropertyWrite />
<ServiceInvoke>
<Principal isPermitted="true" name="New-TestUser"
type="User" />
</ServiceInvoke>
<EventInvoke />
<EventSubscribe />
</Permissions>
</RunTimePermissions>
<VisibilityPermissions>
<Visibility>
<Principal isPermitted="true" name="New-TestOrg"
type="Organization" />
</Visibility>
</VisibilityPermissions>
<ConfigurationTables />
<ConfigurationChanges />
</Thing>
</Things>
<Users>
<User description="" documentationContent="" enabled="true" name="New-TestUser" projectName="" tags="">
<avatar />
<DesignTimePermissions>
<Create />
<Read />
<Update />
<Delete />
<Metadata />
</DesignTimePermissions>
<RunTimePermissions />
<VisibilityPermissions />
</User>
</Users>
<Organizations>
<Organization description="Organization for Visibility Permissios tests"
name="New-SystemOrg" projectName="" tags="">
<avatar />
<DesignTimePermissions>
<Create />
<Read />
<Update />
<Delete />
<Metadata />
</DesignTimePermissions>
<RunTimePermissions />
<VisibilityPermissions>
<Visibility />
</VisibilityPermissions>
<ConfigurationTables />
<loginImage />
<Connections>
<Connection from="" to="New-SystemOrgUnit" />
</Connections>
<OrganizationalUnits>
<OrganizationalUnit description="top of the food chain"
name="New-SystemOrgUnit">
<Members>
<Members>
<Member name="System" type="User" />
</Members>
</Members>
</OrganizationalUnit>
</OrganizationalUnits>
</Organization>
<Organization name="New-TestOrg" projectName="" tags="">
<avatar />
<DesignTimePermissions>
<Create />
<Read />
<Update />
<Delete />
<Metadata />
</DesignTimePermissions>
<RunTimePermissions />
<VisibilityPermissions>
<Visibility />
</VisibilityPermissions>
<ConfigurationTables />
<loginImage />
<Connections>
<Connection from="" to="New-TestOrgUnit" />
</Connections>
<OrganizationalUnits>
<OrganizationalUnit description=""
name="New-TestOrgUnit">
<Members>
<Members>
<Member name="New-TestUser" type="User" />
</Members>
</Members>
</OrganizationalUnit>
</OrganizationalUnits>
<ConfigurationChanges>
</ConfigurationChanges>
</Organization>
</Organizations>
<Menus />
<Resources />
<DataTags />
<ThingShapes />
<Subsystems />
</Entities>
<Entities build="latest" majorVersion="0" minorVersion="0"
revision="0" schemaVersion="940">
<Things>
<Thing effectiveThingPackage="ConfiguredThing" enabled="true" homeMashup=""
identifier="" lastModifiedDate="2017-04-10T14:15:07.346-04:00" name="TestThing-WithPermissions"
projectName="" published="false" tags=""
thingTemplate="GenericThing" valueStream="">
<Owner name="Administrator" type="User" />
<avatar />
<DesignTimePermissions>
<Create />
<Read />
<Update />
<Delete />
<Metadata />
</DesignTimePermissions>
<RunTimePermissions>
<Permissions resourceName="*">
<PropertyRead />
<PropertyWrite />
<ServiceInvoke>
<Principal isPermitted="true" name="New-TestUser"
type="User" />
</ServiceInvoke>
<EventInvoke />
<EventSubscribe />
</Permissions>
</RunTimePermissions>
<VisibilityPermissions>
<Visibility>
<Principal isPermitted="true" name="New-TestOrg"
type="Organization" />
</Visibility>
</VisibilityPermissions>
<ConfigurationTables />
<ConfigurationChanges />
</Thing>
</Things>
<Users>
<User description="" documentationContent="" enabled="true" name="New-TestUser" projectName="" tags="">
<avatar />
<DesignTimePermissions>
<Create />
<Read />
<Update />
<Delete />
<Metadata />
</DesignTimePermissions>
<RunTimePermissions />
<VisibilityPermissions />
</User>
</Users>
<Organizations>
<Organization description="Organization for Visibility Permissios tests"
name="New-SystemOrg" projectName="" tags="">
<avatar />
<DesignTimePermissions>
<Create />
<Read />
<Update />
<Delete />
<Metadata />
</DesignTimePermissions>
<RunTimePermissions />
<VisibilityPermissions>
<Visibility />
</VisibilityPermissions>
<ConfigurationTables />
<loginImage />
<Connections>
<Connection from="" to="New-SystemOrgUnit" />
</Connections>
<OrganizationalUnits>
<OrganizationalUnit description="top of the food chain"
name="New-SystemOrgUnit">
<Members>
<Members>
<Member name="System" type="User" />
</Members>
</Members>
</OrganizationalUnit>
</OrganizationalUnits>
</Organization>
<Organization name="New-TestOrg" projectName="" tags="">
<avatar />
<DesignTimePermissions>
<Create />
<Read />
<Update />
<Delete />
<Metadata />
</DesignTimePermissions>
<RunTimePermissions />
<VisibilityPermissions>
<Visibility />
</VisibilityPermissions>
<ConfigurationTables />
<loginImage />
<Connections>
<Connection from="" to="New-TestOrgUnit" />
</Connections>
<OrganizationalUnits>
<OrganizationalUnit description=""
name="New-TestOrgUnit">
<Members>
<Members>
<Member name="New-TestUser" type="User" />
</Members>
</Members>
</OrganizationalUnit>
</OrganizationalUnits>
<ConfigurationChanges>
</ConfigurationChanges>
</Organization>
</Organizations>
<Menus />
<Resources />
<DataTags />
<ThingShapes />
<Subsystems />
</Entities>
Missing Principal Errors
Entities exported from the platform on versions prior to 9.2.0 may contain principals (users, user groups, organizations, and organization units) that are no longer present in the platform. When these entities are imported, there may be “missing principal” warning messages in the Security Log. As an administrator, examine the logs and ensure that the missing principals are indeed deleted principals and that no legitimate permissions are being ignored or skipped.
|
|
The administrator must examine the logs and add legitimate permissions that got skipped or ignored because of the missing principal.
|
|
|
Even if the deleted principal with deny, allow, or inherited access shows up in the warning log message, the user, user group, and organization permissions are removed. Whenever a user, user group, or organization is recreated on the platform, the permissions will be assigned per the collection permission (unless otherwise specified). Ensure that the deny, allow, and inherited permissions are manually assigned whenever the user, user group, or organization is added to the system.
|