Using the GetWhereUsed Service

ThingWorx Model Definition in Composer > Relationships > Using the GetWhereUsed Service

The GetWhereUsed service allows you to view an entity's relationships in ThingWorx. You can determine where an entity or its characteristics, such as a service or property, are used in ThingWorx. This can be useful if you need to make changes to entities, and need to know what effects your changes will have elsewhere in your model. This functionality is also available in the entity view in Composer, see Referenced By for more information.

The GetWhereUsed service is available in ThingWorx 9.3 and later.

Parameters

Parameter	Base Type	Description
query	JSON	Filters the results.
charType	STRING	Filters results for all usages of an entities characteristics. Possible inputs are ALL, Property, Service/Event, and LocalizationToken.
charName	STRING	Filters results to all usages of a specific characteristic on an entity.

Query Filter Example

Using the filter below for GetWhereUsed returns only mashups with the name MashupA.

{"filters":

{

"type": "And",

"filters": [

{

"type": "EQ",

"fieldName": "entityName",

"value": "MashupA"

}]}}

GetWhereUsed Results for Entity Types

The following table outlines the results that are returned when using the optional charType and/or charName parameters. N/A indicates the input is empty. System objects are not part of the results for GetWhereUsed.

For rows that mention "ALL or Service/Event," selecting either of these inputs for charType will result in the same output because that entity only has Service/Event characteristics.

Entity Type	charType	charName	Result
All entity types	n/a	n/a	Reference to usages of that specific entity.
Authenticator	ALL or Service/Event	n/a	Reference to all usages of the characteristics on that authenticator entity.
Authenticator	ALL or Service/Event	ServiceName	Reference to all usages of the characteristic with the name ServiceName on that authenticator entity.
DirectoryService	ALL or Service/Event	n/a	Reference to all usages of the characteristics on that DirectoryService entity.
DirectoryService	ALL or Service/Event	ServiceName	Reference to all usages of the characteristic with the name ServiceName on that DirectoryService entity.
LocalizationTable	n/a	n/a	Reference to usages of the localization table.
LocalizationTable	ALL or LocalizationToken	n/a	Reference to usages of all tokens on the localization table.
LocalizationTable	ALL or LocalizationToken	TokenName	Reference to all usages of the specific token TokenName on the localization table.
NotificationDefinition	ALL or Service/Event	n/a	Reference to all usages of the characteristics on that NotificationDefinition entity.
NotificationDefinition	ALL or Service/Event	ServiceName	Reference to all usages of the characteristic with the name ServiceName on that NotificationDefinition entity.
Project	ALL or Service/Event	n/a	Reference to all usages of the characteristics on that project entity.
Project	ALL or Service/Event	ServiceName	Reference to all usages of the characteristic with the name ServiceName on that project entity.
Subsystem	ALL or Service/Event	n/a	Reference to all usages of the characteristics on that subsystem entity.
Subsystem	ALL or Service/Event	ServiceName	Reference to all usages of the characteristic with the name ServiceName on that subsystem entity.
Thing	ALL	n/a	Reference to all usages of characteristics on that Thing entity.
Thing	ALL	ServiceName	Reference to all usages of the characteristic with the name ServiceName on that Thing entity.
Thing	Property	n/a	Reference to all usages of properties on that Thing entity.
Thing	Service/Event	n/a	Reference to all usages of services and events on that Thing entity.
ThingGroup	ALL or Service/Event	n/a	Reference to all usages of the characteristics on that ThingGroup entity.
ThingGroup	ALL or Service/Event	ServiceName	Reference to all usages of the characteristic with the name ServiceName on that ThingGroup entity.
ThingShape	ALL	n/a	Reference to all usages of characteristics on that ThingShape entity.
ThingShape	ALL	ServiceName	Reference to all usages of the characteristic with the name ServiceName on that ThingShape entity.
ThingShape	Property	n/a	Reference to all usages of properties on that ThingShape entity.
ThingShape	Service/Event	n/a	Reference to all usages of services and events on that ThingShape entity.
ThingTemplate	ALL	n/a	Reference to all usages of characteristics on that ThingTemplate entity.
ThingTemplate	ALL	ServiceName	Reference to all usages of the characteristic with the name ServiceName on that ThingTemplate entity.
ThingTemplate	Property	n/a	Reference to all usages of properties on that ThingTemplate entity.
ThingTemplate	Service/Event	n/a	Reference to all usages of services and events on that ThingTemplate entity.

The following entity types do not have characteristics and do not require inputs because they can only return references to direct usages of themselves.

• ApplicationKey

• Dashboard

• DataShape

• DataTagVocabulary

• Mashup

• MediaEntity

• Menu

• ModelTagVocabulary

• Network

• Organization

• StateDefinition

• StyleDefinition

• StyleTheme

• User

• User Groups

Result Behavior

It may seem like there are duplicate rows in the result set. In the images below, the GetWhereUsed service has been run on ThingA twice: once with no additional inputs (first image) and once with characteristicType as All (second image). A similar row is underlined in red in both results, where the columns share information with the exception of the Characteristic Type and Characteristic Name columns. Although the rows contain overlapping information, they are separate references. For ThingB to use the property name from ThingA, it must also use ThingA. Therefore, in the first image, the underlined row is a reference to ThingA that is used by ThingB. In the second image, the underlined row is a reference to the ThingA’s property name that is used by Thing B.

Permissions

A non-administrator user can run the GetWhereUsed service but may not be able to view all results if they don't have permissions to view certain entities or characteristics. In this case, an administrator user can view the Security log, which displays the first 50 entities that the non-administrator user is unable to view, and change permissions accordingly.

Was this helpful?