Setting Up Permissions and Visibility for the eMessage Connector
If you understand permissions and visibility in ThingWorx and understand why you need to set up security for your eMessage Connector, start with the procedures in this topic. If you would like some background information, read Security Background: ThingWorx Permissions for the eMessage Connector first.
This topic contains the following sections
Checklist for Security
Here is a checklist for setting up security for an eMessage Connector:
1. If you have not already done so, create security entities required when running services that grant visibility and permissions to the Connector. For step-by-step instructions, refer to Create Security Entities in ThingWorx for a Connector and for Remote Access. You will need to specify the organization and user group that you created when running the services.
2. In ThingWorx Composer, navigate to the eMessageServices Thing and run the following services to grant the visibility and permissions for the eMessage Connector:
a. GrantEMessageConnectorPermissions to set general visibility and permissions for the Connector, including visibility and permissions to/for the following entities:
▪ To the ConnectionServicesHub Thing for the Connector, for all the Thing Templates in the Axeda Compatibility Extension (ACE), and for the AxedaProtocolAdapter Thing.
▪ To the file repository that stores SCM packages so that the eMessage Connector can download packages from the ThingWorx Platform to the Axeda eMessage Agent devices.
▪ For the AxedaPollingTimer, set the runAsUser property to be the eMessage Connector non-admin user. Once this service has set the runAsUser property for the timer, the platform runs the timer as that user.
 |
Whether you are running the Connector as a non-admin user or as Administrator, you must run this service for the AxedaPollingTimer to work. Otherwise, the ThingWorx SCM utility will not see the related device as available for a package deployment. This utility checks the value of the isReporting property to determine whether to display the name of a Thing as available for a deployment.
|
b. GrantFileDownloadPermissions for using the Copy service of the ThingWorx File Transfer Subsystem.
c. GrantFileDownloadPermissions for using the ThingWorx SCM Extension to download instruction-based packages to Axeda eMessage Agent devices.
d. GrantFileUploadPermissions for using the Copy service of the ThingWorx File Transfer Subsystem to upload files from Axeda eMessage Agent devices.
e. GrantRemoteAccessPermissionsGASFor(Thing|ThingTemplate) to enable end users to execute remote sessions to their eMessage Agent assets that connect to the eMessage Connector, To grant remote access permissions and visibility to a single eMessage asset, pass in the name of the Thing that represents that asset. To grant remote access permissions and visibility to a group of assets, such as all assets of a certain model, pass in the name of the ThingTemplate from which the Things representing those assets are derived. You must also specify the organization and user group to which you want to assign the permissions and visibility for remote sessions.
How to Run the Services that Grant Visibility and Permissions
To run the services that grant the entity visibilities and permissions:
1. Log in to ThingWorx Composer as an administrator user.
2. Navigate to the eMessageServices Thing.
3. Click Services.
4. Locate the GrantEMessageConnectorPermissions service. In the Execute column for the service, click 
. Then, follow these steps:
. Then, follow these steps:a. In the organization field, enter the name of the organization created in Creating Security Entities for a Connector.
b. In the userGroup field, enter the name of the user group created in Creating Security Entities for a Connector.
c. To run the service, click 
.
.d. After the service runs, click 
to close the window.
to close the window.5. Back in the Services page, locate the GrantFileUploadPermissions service, click . Then, follow these steps:
. Then, follow these steps:a. In the organization field, enter the name of the organization created in Creating Security Entities for a Connector.
b. In the userGroup field, enter the name of the user group created in Creating Security Entities for a Connector.
c. In the targetRepository field, enter the name of the file repository to be used to store agent-uploaded files.
d. To run the service click .
.e. After the service runs, click to close the window.
to close the window. | Running the GrantFileUploadPermissions service grants permissions to the eMessage Connector to handle both agent-initiated and platform-initiated file uploads (using the Copy service of the File Transfer Subsystem). The default target repository is the SystemRepository. If you specified a different repository for file uploads in the configuration file of the eMessage Connector, specify that repository name here. |
6. Back in the Services window, locate the GrantFileDownloadPermissions service. Then, follow these steps:
a. In the organization field, enter the name of the organization created in Creating Security Entities for a Connector.
b. In the userGroup field, enter the name of the user group created in Creating Security Entities for a Connector.
c. In the sourceRepository field, enter the name of the file repository from which agents will download files.
| | If your Download (source) and Upload (target) repositories are different, you must run the GrantFileDownloadPermissions service against your Upload (target) repository too. If you fail to do this, the smoke test will fail. It assumes the repository for Download (source) is the one specified as the Upload (target) repository. |
d. To run the service, click .
.e. After the service runs, click to close the window.
to close the window.f. Repeat step 6 for each file repository from which agents will download files.
g. Click to close the window.
to close the window.| | The next two steps are required if you plan to use the ThingWorx SCM Extension features. For downloading instruction-based packages from the ThingWorx Platform to Axeda eMessage agent devices, run the GrantFileDownloadPermissions, specifying the SCM File Repository as the source repository. Similarly, if your packages contain upload instructions, run the GrantFileUploadPermissions, specifying the SCM File Repository as the destination repository. The packages are stored in a File Repository that is separate from the repository used for uploading and downloading files. |
7. In the Services page for the Thing, locate the GrantFileDownloadPermissions service, click . Then, follow these steps:
. Then, follow these steps:a. In the organization field, enter the name of the organization created in Creating Security Entities for a Connector.
b. In the userGroup field, enter the name of the user group created in Creating Security Entities for a Connector.
c. In the sourceRepository field, enter the following file repository name: TW.RSM.Thing.FileRepository.
d. Click .
.e. After the service runs, click to close the window.
to close the window.8. In the Services page for the Thing, locate the GrantFileUploadPermissions service, click , and then:
, and then:a. In the organization field, enter the name of the organization created in Creating Security Entities for a Connector.
b. In the userGroup field, enter the name of the user group created in Creating Security Entities for a Connector.
c. In the targetRepository field, enter the following file repository name: TW.RSM.Thing.FileRepository.
d. To run the service, click .
.e. After the service runs, click to close the window.
to close the window.9. In the Services page for the RemoteAccessPermissionServices Thing, locate the GrantRemoteAccessPermissionsGAS service and click. Then follow these steps:
. Then follow these steps:a. In the organization field, enter the name of the organization that should be granted visibility and permissions to start, end, and get remote sessions.
b. In the userGroup field, enter the name of the user group that should be granted visibility and permissions to start, end, and get remote sessions.
c. To run the service, click .
.d. After the service runs, click to close the window.
to close the window.eMessage Connector Visibility and Permissions Requirements
The following table lists the entities and their visibility and permissions requirements that are granted by the GranteMessageConnectorPermissions service. This service applies specific permissions to the eMessage Connector User for ThingWorx functionality. In addition, this service invokes the ConnectionServicesHub.GrantConnectorPermissions to apply base Connector permissions.
Entity | Visibility | Permissions |
|---|---|---|
Permissions granted by ConnectionServicesHub.GrantConnectorPermissions | ||
PlatformSubsystem subsystem | Entity | ServiceInvoke for GetExtensionPackageList |
ConnectionServicesHub Thing | Entity | ServiceInvoke for the GetMetadata service EventInvoke for the following events: • AuthenticationError • ThingNotFoundError • UserError • ClearCacheEntry • ProtocolError • EdgeError • WritePropertyError • FileNotFoundError • InternalError |
FileTransferSubsystem subsystem | Entity | None |
ThingworxPersistenceProvider Persistence Provider | Entity | ServiceInvoke for GetVisibilityPermissions |
CollectionFunctions Resource | None | EventSubscribe permission for the Things collection |
Permissions granted by eMessageServices.GrantEMessageConnectorPermissions in addition to the permissions granted by ConnectionServicesHub.GrantConnectorPermissions | ||
eMessageServices Thing | Entity | ServiceInvoke for all services |
InfoTableFunctions Resource | Entity | ServiceInvoke for CreateInfoTableFromDataShape |
ThingShapes Collection | Collection | Create permission Update permission Read permission |
ThingTemplates Collection | Collection | Create permission Update permission. |
AxedaBaseModel Thing Template | Thing Template | ServiceInvoke for QueryImplementingThingsWithData |
Things Collection | Collection | Create permission Update permission EventSubscribe Run Time permission for the Things collection |
EntityServices Resource | Entity | ServiceInvoke for • AddShapeToThing • CreateThing • DeleteThing |
GenericThing Thing Template | None | PropertyRead instance permission PropertyWrite instance permission |
RemoteThing Thing Template | None | ServiceInvoke for • GetPropertySubscriptionss on template instances • UpdateSubscribedPropertyValues on all Things that implement the RemoteThingThing Template |
ConnectionServicesHub Thing | Entity | ServiceInvoke for all services EventInvoke for all events Read Design Time permissions on template instances |
Permissions applied if the ThingWorx Software Content Management (SCM) Extension is installed. | ||
FileRepository Thing Template | None | ServiceInvoke for GetConfigurationTable on template instances |
TW.RSM.SFW.SoftwareManager Thing | Entity | ServiceInvoke for • GetDeliveryTargets • UpdateDeliveryTargetState • CompleteDeliveryTarget PropertyRead permission |
TW.RSM.RemoteServices User Group | Entity | This service adds the user group of the eMessage Connector User to the TW.RSM.RemoteServices user group to enable use of SCM. |
TW.RSM.SFW.SoftwareManager.DeliveryTarget Thing | None | ServiceInvoke for QueryDataTableEntries |