Managing Context and Equipment Permissions
A user’s role (for example, Maintenance Manager or Maintenance Engineer) determines the areas of the ThingWorx Apps user interface that the user can access. Permissions determine the contexts and equipment which a user or user group can see and edit in the areas of ThingWorx Apps that are context-aware. The combination of a user’s role and their permissions determines what they can view and edit in the areas of ThingWorx Apps to which they have access.
 |
Administrators and users with the Controls Engineer role can always view and edit all contexts and equipment, regardless of permission settings.
|
The following areas of ThingWorx Apps are impacted by context and equipment permissions:
• In Asset Advisor, Production KPIs, and Alert Monitoring, users need at least read (Read) permission on a context to view the context, and read (Read) permission on particular equipment to see that equipment within the context. Write (Write) permission automatically includes read (Read) permission.)
• On the Equipment tab of Configuration and Setup, users must have Write permission on a context to view and create equipment in the context, and Write permission on particular equipment to view, edit, or delete the equipment. The user who creates a piece of equipment automatically has Write permission on that piece of equipment.
• When configuring an individual piece of equipment from the Equipment tab of Configuration and Setup, and adding related child equipment from the Equipment Structure page, only equipment to which the current user has Write permission is included in the list of equipment available to be added as child equipment.
• On the Alerts tab of Configuration and Setup, users can view and select all equipment in all contexts, but must have Write permission on particular equipment to create, edit, or delete alerts on that equipment.
Administrators and Controls Engineers manage permissions using services provided on the context manager thing (PTC.SCA.SCO.ContextManager) in ThingWorx Composer. These services are used to grant read (Read), write (Write), or none (None) permissions to users and user groups on individual contexts or pieces of equipment, on all equipment in the equipment structure of a context, or on a specified piece of equipment and all of its children in the equipment structure of a context. This allows you to tailor a user’s access to the specific contexts and equipment which are applicable to them.
The user groups provided with ThingWorx Apps are Controls Engineer, Maintenance Manager, Maintenance Engineer, and Production Manager, which map to the user roles with those names, and FactoryUser, which includes the four previously mentioned user groups and the Administrator user.
 |
All permissions-related services on the context manager thing (PTC.SCA.SCO.ContextManager) have the ContextPermissions category tag. Filter the list of services to display only permissions-related services by selecting ContextPermissions from the Choose category drop-down list next to the services search field.
|
High-level Process Flow
The following high-level steps are a recommended approach to managing permissions for a context and its equipment.
1. Create the context with the appropriate equipment relationship definitions.
2. Use the services to grant permissions on that context to the users and user groups that you want to see the context.
3. Add equipment to the context, either through import or by allowing users to create new equipment.
4. Once equipment has been added, use the services to grant and propagate appropriate permissions for that equipment to your users and user groups.
5. When any new equipment is added to the context, grant and propagate permissions on that new equipment as needed.
Services for Granting Permissions
The following services are available to grant permissions to users or user groups. Using these services to grant permissions has the following results:
• Granting Read sets the read (Read) permission to true and write (Write) permission to false.
• Granting Write sets both the read (Read) and write (Write) permissions to true.
• Granting None sets both the read (Read) and write (Write) permissions to false.
The permission type values (Read, Write, and None) and entity type values (Context and Equipment) in these services are case-sensitive.
• GrantUserGroupPermissionsOnEntities—Grants the specified user groups the specified permission (Read, Write, or None) to the specified entities. Context and equipment entities can both be specified for the same execution of the service. When adding entities to the entities infotable, provide the following information:
◦ Name—The name of the context or equipment thing as it appears in ThingWorx Composer.
◦ Type—Enter the entity type, Context or Equipment.
• GrantUserPermissionsOnEntities—Grants the specified users the specified permission (Read, Write, or None) to the specified entities. Context and equipment entities can both be specified for the same execution of the service. When adding entities to the entities infotable, provide the following information:
◦ Name—The name of the context or equipment thing as it appears in ThingWorx Composer.
◦ Type—Enter the entity type, Context or Equipment.
• GrantPermissionsOnEntities—Utility service used by the previously listed services. Not intended for standalone use.
Services for Propagating Permissions
The following services are available to grant permissions on a specific entity (piece of equipment) and propagate that permission to all of its children within the equipment structure for a context.
The permission type values (Read, Write, and None) in these services are case-sensitive.
• PropagateUserGroupPermissionsOnEntities—Grants the specified user groups the specified permission (Read, Write, or None) on entities (equipment) in the specified context.
◦ If the entityName parameter is left empty, then the specified permission is granted to the specified user groups on all equipment in the specified context.
◦ If an entity is specified for the entityName parameter, then the specified permission is granted to the specified user groups on that entity in the specified context, and is propagated to all children of the specified entity in the equipment structure.
• PropagateUserPermissionsOnEntities—Grants the specified users the specified permission (Read, Write, or None) on entities (equipment) in the specified context.
◦ If the entityName parameter is left empty, then the specified permission is granted to the specified users on all equipment in the specified context.
◦ If an entity is specified for the entityName parameter, then the specified permission is granted to the specified users on that entity in the specified context, and is propagated to all children of the specified entity in the equipment structure.
• PropagatePermissionsOnEntities—Utility service used by the previously listed services. Not intended for standalone use.
Services for Viewing Permission Settings
The following services are available to view the current permission settings.
The permission type values (Read, Write, and None) in these services are case-sensitive.
• GetContextPermissionByUser—Returns a list of contexts to which the specified user has permission, along with the permission type (Read or Write).
• GetContextPermissionByUserGroup—Returns a list of contexts to which the specified user group has permission, along with the permission type (Read or Write).
• GetContextsByUserAndPermission—Returns a list of contexts for which the specified user has the specified permission (Read or Write), along with the details for each context.
• GetEntityPermissionsByUserGroupOnContext—Returns a list of the entities (equipment) to which the specified user group has permission in the specified context, along with the permission type (Read or Write) for each entity.
• GetEntityPermissionsByUserOnContext—Returns a list of all entities (equipment) to which the specified user has permission in the specified context, along with the permission type (Read or Write).
• GetPermissionsByContext—For the specified context, returns a list of all entities (equipment) in the context; for each entity, an infotable shows the permission that each user and user group has for the entity (Read, Write, or None).
• GetContextPermission and GetEntityPermissionsOnContext—Utility services used by the previously listed services. Not intended for standalone use.
Best Practices for Permissions
Keep in mind the following when granting and propagating permissions:
• Permissions granted to a user group are inherited by the users who belong to the group. This allows you manage permissions at a user group level, by adding and removing users to and from the user group as needed.
• The most recent permission granted for a user or user group on a context or a piece of equipment is the current permission setting for that user or user group on that context or piece of equipment. For example:
◦ If User1 is granted read (Read) permission to all equipment within Context4, and subsequently granted write (Write) permission to Line3 and all of its children in Context4, then within Context4, User1 has write (Write) permission to Line3 and all of its children, and read (Read) permission to all other equipment.
◦ If User1 is granted write (Write) permission to Line3 and all its children in Context4, and subsequently granted read (Read) permission to all equipment in Context4, then within Context4, User1 has read (Read) permission for all equipment.
• Granting the none (None) permission to a user group takes precedence over any read (Read) or write (Write) permission explicitly granted to a user in the group. Granting the none (None) permission to a user takes precedence over any read (Read) or write (Write) permission granted to a user group to which the user belongs.
• Granting read (Read) permission to a user group results in users in the group effectively having only read (Read) permission, even when a user in the group is explicitly granted write (Write) permission. The false setting for the write (Write) permission on the user group from granting the read (Read) permission is inherited by the users in the user group. To allow some users in the user group to have write (Write) permission, grant write (Write) permission to the user group, and grant read (Read) permission to individual users.
• Write (Write) permission is automatically granted to the user who creates a new piece of equipment on the Equipment tab of Configuration and Setup. No other user or user group has read (Read) or write (Write) permission on that piece of equipment until the permission is granted to them. (Administrators and Controls Engineers can always see all contexts and equipment, regardless of permission settings).
• The Import and Export Equipment action is limited by the permissions granted to the current user who is performing the action.
◦ Exporting includes only those contexts and the equipment within those contexts on which the current user has at least Read permission.
◦ When importing, the current user must have write (Write) permission on the contexts into which equipment is being imported. For each piece of equipment listed in the spreadsheet, the current user must also be granted permission in both the Property Read and Property Write columns, either explicitly or as a member of a user group.
For more information, see Importing Equipment Information.
• To remove a user’s or user group’s permission on certain contexts or equipment, grant them the none (None) permission for that context or equipment.