Access Modifiers
Access Modifiers is a new construct introduced in ThingWorx 9.5 to allow developers to identify those artifacts (entities and their characteristics) that are protected from external use and those that can be consumed by end users for further customization or development including, extension, referencing, and reuse. It is also possible to have entities opened for external use with some of the characteristics being protected.
The protected artifacts would not be allowed to be accessed through runtime checks when the access comes up for use. Most formally defined relationships are validated at authoring time. However, usage within code blocks of services and Mashups will only be verified at runtime. The runtime checks cannot be completely error-free and are to be treated as an assistance in avoiding improper use. The declaration of access modifier remains the source of truth, and developers should abide by not using the concerned protected artifacts in violation of the declared access modifiers. Such protected artifacts may be changed or removed, and any violating dependent usage could start failing at any future time without notice.
An access modifier specifies the scope of accessibility for entities and characteristics.
In ThingWorx 9.5.0, the access modifier is supported for the following entities and characteristics:
|
Entities
|
Characteristics
|
||||
|---|---|---|---|---|---|
|
• Things
• Thing Templates
• Thing Shape
• Thing Groups
• Data Shapes
• Networks
• Industrial Connections
• Integration Connectors
• Schedulers
• Timers
• Dashboards
• Menus
• Media
• Style Definitions
• Style Themes
• State Definitions
• Data Table
• Streams
• Value Streams
• Blogs
• Wikis
|
• Property
• Service
• Configuration Table
|
The following entities do not support the access modifier:
|
• Project
• Model Tag
• Notification
• Data Tag
• Persistent Provider
• User Groups
• Users
• Organizations
• Application Keys
• Directory Services
• Authenticators
• Mashup
• Mashup Template
• Master
• Gadget
• Localization Tables
|
Access Modifiers are classified into the following:
• NONE—Absence of scope is treated as a public scope and can be applied to an entity or characteristics. Everyone can access entities or characteristics with public scope.
◦ Entities with the NONE scope can be accessed by everyone.
◦ Characteristic with the NONE scope inherits the access modifier from the entity it belongs to.
• PRIVATE — This scope can be applied to an entity or characteristics and can only be accessed within the project.
• RESTRICTED — This scope can be applied to an entity or characteristics. It acts as a private scope adding those projects with the namespace and it’s child hierarchy to the accessible list. For example, RESTRICTED[ptc.dpm.jobOrder] is accessible to all entities from ptc.dpm.jobOrder namespace and children namespaces but is private for all other entities.
 |
In ThingWorx 9.5.0, only one namespace (+children, which is implicit) can be added for Restricted scope.
|
• Internal —This scope can be applied only to characteristics; such characteristic is accessible only within that entity.
|
|
Scope assignments are persisted for entity and characteristics.
Scope can be applied for all the supported entities irrespective of their project type. If namespace is not assigned to a project then only None or Private scopes can be applied on the entities, and None, Private, or Internal on characteristics.
|
|
|
All entities and characteristics will have NONE (absent) scope after migrating to ThingWorx 9.5.
|
• Characteristics level cannot have a broader scope. For example, if the entity has scope as PRIVATE, the characteristics cannot have NONE as scope.
• For the objects associated with an entity has NONE scope, then the scope for objects in the RESTRICTED list allowed at the characteristic level must be broader, equal, or narrower. And for entities with other scopes, the scope for objects in the RESTRICTED list allowed at the characteristics level must be equal or narrow.
Requirements for Creating Scope
A scope must include only Capital letters.
Configuring a Default Scope for Building Block Projects
A default scope can be configured on building block type of projects. When creating a new entity, this configuration is used as default assignment for scope.
The default scope of a project can be updated at runtime through the Composer or a REST call. New entities being created in this project will inherit this scope. Scope of existing entities is not affected by the change of this configuration. The scope of an entity can be changed at runtime.
|
|
This configuration only applies to scope setting when using Composer for creating entities
|
Setting an Access Modifier on an Entity or Characteristics
An access modifier can be assigned to an entity or characteristics in the following ways:
• By selecting the scope from the Scope list on the General Information tab in the Composer.
• By using Java Annotations
• By XML or Extension import.
• By executing the SetAccessModifier service under the EntityServices resource. This service can be used to set an access modifier on multiple entities and characteristics in bulk.
|
|
In ThingWorx 9.5.0, setting an access modifier from the create services call in EntityServices resource is not supported. For example, create services like CreateThing, CreateThingShape, CreateNetwork, etc., do not accept access modifier as an argument.
|
|
|
While creating an entity, access modifiers are not logged in Audit logs.
|
|
|
Access Modifiers can be added to characteristics via java annotations. But to add Access Modifiers on the entity level we do not have annotations support. we can add the Access Modifiers at the entity level through XML import.
|
Viewing an Access Modifier Set on an Entity or Characteristics
By executing the GetAspects service under EntityServices resources, you can view the access modifier that is set on any entity or characteristics.
Filtering Entities via Access Modifiers
Entities can be filtered based on Scope by using 
in Composer.
in Composer.
Logging Access Modifiers
If a user creates, updates, or deletes the access modifiers set on an entity or characteristics, then the audits are maintained in the Audit Log.
For information, see Audit Subsystem.
| | Modifications to an entity or characteristic by another entity, member, or service calls are not audited. |
Moving Entities from One Project to Another Project
When you move an entity across projects, the scope of the entity, properties, services, and configuration tables remain unchanged if the source entity or characteristic has a None or Private scope.
| | A namespace that is the same or broader than the target project's namespace is a valid namespace. A namespace that is not the same or narrower than the target project's namespace is an invalid namespace. |
Listed below are the different scenarios that occur while moving entities with Restricted scope from one namespace to another:
• Scenario 1
If the entity has a valid namespace, then there is no change in scope.
For example, when an entity with scope RESTRICTED [dpm.sco.jobOrder] is moved to a project with namespace (dpm.sco.jobOrder.scp.jobOrder12), the scope of the entity remains the same.
• Scenario 2
If the entity has an invalid namespace and the target project does not have a default scope, then the scope of the entity changes to private.
For example:
◦ When a Thing with scope RESTRICTED[dpm.sco.jobOrder.scp.jobOrder12] is moved to a project with namespace (abc.xyz.pqr), the scope of the Thing changes to PRIVATE[abc.xyz.pqr].
• Scenario 3
If the entity has an invalid namespace and the target project has a default scope Restricted with exmptList, then the scope of the entity changes to the default scope of the target project.
For example:
◦ When a Thing with scope RESTRICTED[dpm.sco.jobOrder.scp.jobOrder12] is moved to a project with default scope RESTRICTED[abc.xyz.pqr], the scope of the Thing changes to RESTRICTED[abc.xyz.pqr].
◦ When a Thing with scope RESTRICTED[dpm.sco.jobOrder.scp.jobOrder12] is moved to a project with default scope RESTRICTED[dpm.sco.jobOrder], the scope of the Thing changes to RESTRICTED[dpm.sco.jobOrder.scp.jobOrder12].
• Scenario 4
If the entity has an invalid namespace and target project’s default scope is private, then the scope of the entity changes to the default scope of the target project.
For example:
◦ When a Thing with scope RESTRICTED[dpm.sco.jobOrder.scp.jobOrder12] is moved to a project with default scope PRIVATE[dpm.sco.jobOrder], the scope of the Thing changes to PRIVATE[dpm.sco.jobOrder].
◦ When a Thing with scope RESTRICTED[dpm.sco.jobOrder.scp.jobOrder12] is moved to a project with default scope PRIVATE[abc.xyz.pqr], the scope of the Thing changes to PRIVATE[abc.xyz.pqr].
• Scenario 5
If the entity has an invalid namespace and target project does not have a namespace, then the scope of the entity changes to Private.
For example, when a Thing with scope RESTRICTED [dpm.sco.jobOrder.scp.jobOrder12] is moved to a project with no namespace, the scope of the Thing changes to PRIVATE.
| | If the RESTRICTED changes at entity level and the characteristics RESTRICTED is invalid, the characteristics scope changes to Inherited. |
| | Moving entities is logged as Debug in the Application Log. |
Limitations with Access Modifiers
Following are the limitations with the Access Modifiers.
• Inherited characteristics will not show in the Me/Entities section while creating a new service or editing an existing service.
• Private properties of another project are visible while creating property bindings.
• Mashups do not have access modifiers.
• If your entity name has any special character and the access modifier checks are not being performed during runtime, follow the steps below:
1. Encode the name to Base64 format.
2. Add a suffix in the format, encodedname/b64.
3. Pass this value as twx-referrer-entity while using REST APIs.
• If any entity name has the characters apart from those mentioned in validation.properties file, the access modifier checks will not be performed during runtime. You can add characters to the file by configuring the validation.properties file. Add or modify the values for Validator.HTTPHeaderValue. For more information, see Configuring ESAPI Validator Settings.