Creation and Deletion of Ghost Entities
About Ghost Entities
• Ghost entities are in-memory representations of entities that failed to be created due to an error.
• Ghost entities only persist until the next ThingWorx restart.
• Failed entities are not committed to the database.
• Generally, ghost entities are the result of improper exception handling in a service that calls a Create<Entity> service programmatically (for example, CreateUser or CreateThing).
• If an exception is thrown during a custom ThingWorx service's execution, any entities that were created do not get committed to the database.
• When a ghost entity exists, entities of the same type (Thing, User, Group, etc) and name cannot be created.
• Ghost entities are not searchable using the spotlight search in Composer.
• Ghost entities can only be found through the use of specific ThingWorx services.
• Ghost entities cannot be interacted with via Composer, except through a few specific ThingWorx services.
Ghost Entities Example
Ghost entities are entities within ThingWorx that exist in the platform’s memory, but not in the database. They do not appear in Composer, but if you attempt to create a new entity with the same name and type, Composer displays an error that the entity already exists. Once the platform is restarted, the ghost entities disappear.
Ghost entities are created when entities are created in a service, and the service throws an exception. When the exception occurs, the database transaction that saved the entities rolls back, but the entities are not removed from the platform’s memory. The following is an example service that may create a ghost entity:
var params = {
name: "GhostThing" /* STRING */,
description: "Ghost" /* STRING */,
thingTemplateName: "GenericThing" /* THINGTEMPLATENAME */
};
Resources["EntityServices"].CreateThing(params); var makeError;
makeError.notThere = 1
name: "GhostThing" /* STRING */,
description: "Ghost" /* STRING */,
thingTemplateName: "GenericThing" /* THINGTEMPLATENAME */
};
Resources["EntityServices"].CreateThing(params); var makeError;
makeError.notThere = 1
In the above example, an exception occurs and the transaction that created GhostThing rolls back because the last line refers to a property in ‘makeError’ that does not exist. However, the GhostThing still exists in the memory, and an error occurs if you attempt to create a new entity named “GhostThing,” because the platform thinks it already exists.
 |
GhostThing will not appear in Composer.
|
To prevent ghost entities from being created, place a try/catch statement around code that has the potential to throw an exception, and recover from anything that may have been created. The code above can be updated as follows to prevent the creation of the ghost entity:
try {
let params = {
name: "GhostThing" /* STRING */,
description: "Ghost" /* STRING */,
thingTemplateName: "GenericThing" /* THINGTEMPLATENAME */
};
Resources["EntityServices"].CreateThing(params);
var makeError;
makeError.notThere = 1;
} catch (err) {
let params = {
name: "GhostThing" /* THINGNAME */
};
Resources["EntityServices"].DeleteThing(params);
}
let params = {
name: "GhostThing" /* STRING */,
description: "Ghost" /* STRING */,
thingTemplateName: "GenericThing" /* THINGTEMPLATENAME */
};
Resources["EntityServices"].CreateThing(params);
var makeError;
makeError.notThere = 1;
} catch (err) {
let params = {
name: "GhostThing" /* THINGNAME */
};
Resources["EntityServices"].DeleteThing(params);
}
Ghost Entity Services
The following services are available in the Platform Subsystem to deal with ghost entities:
|
|
DeleteGhostEntities and GetGhostEntities are subject to the MaxSearchItems limit set in platform-settings.properties.
|
• DeleteGhostEntities - Deletes all entities that have not been persisted. Set the deleteGhostEntitiesInAllInstances parameter to false to delete ghost entities in the current ThingWorx instance or set to true to delete ghost entities across all instances.
• GetGhostEntities - Returns a list of ghost entity names that have not been persisted in the current ThingWorx instance. To identify the entities, the endpoint performs a spotlight search and selects entities that don't have an ID.