The Results services are the central mechanism that transfers data from CM4D into the Results database.
- Results Sender - Processes the data events from CM4D, extracts the data from the databases and sends the data to Results Loader. In the case of a modified CAD image, a message is sent to the StreamCacheSmith service. This service requires a connection to the CM4D Site database and the Transport/Persistence database(s).
- Results Loader - Updates the Results database with minimum database locks. This service requires a connection to the CM4D Results database and the Transport/Persistence database(s).
- StreamCacheSmith - Converts 3D CAD images into the HOOPS streaming format used over the web by CM4D Peruse. The stream cache images are stored in the CM4D Site database and streamed to clients as-needed for rendering on the client-side HOOPS Viewer. This service requires a connection to the CM4D Results database and the Transport/Persistence database(s) and must be installed on the same machine as the HOOPS Communicator Server. Images transferred to the Results database cannot contain User Variables in the Image Path.
These services are installed using the ATS CM4D Results Services installer, which provides deployment flexibility to add service instances in larger organizations.
See the topic Results Transport for technical details on how these services can be distributed and monitored for optimal performance.
Deployment of Services
The Results services are typically installed on the same machine as CM4D Server, but the Results services are a separate installer from CM4D Server to allow one or more of the services to be distributed to additional servers. To support scalability for larger organizations the services can run on a single computer or multiple computers, and multiple instances of each service can be added and distributed throughout your network. The Results services can be deployed as Windows services (default install option) or as docker images.
Only ONE instance of each of the three Results Services is supported per server.
The Results Loader service can work without any connection to the Site database (e.g. in the cloud connected via a RabbitMQ queue). The connection is entered during the installation of the service.
The Results Sender service includes configuration options for specifying Managed DataSources and processing options.
ServiceControl Manager
Each installed instance of the Results Services on a machine must have a corresponding ServiceControl and Monitoring instance.
NServiceBus (used by CM4D Results and EventSmith services) provides powerful error handling and monitoring tools:
- ServiceControl - Collects data from endpoints (CM4D Services).
- ServicePulse - A web-based application to inspect failed messages and resubmit them and to monitor the availability and performance of endpoints.
- ServiceInsight - Supports auditing of message details but has a major performance impact.
At a minimum, it is strongly recommended to use ServiceControl and ServicePulse. You need to configure at least one instance of ServiceControl and Auditing and one Monitoring instance for the transport method chosen during the installation of the Results service.
The downloads and installation instructions for the NServiceBus applications can be found on the Particular Software website.
Basic Installation Options
If you simply want to install one instance of the Results services to run local to your CM4D Server, select the following options during installation:
- CM4D Database Options - Use .4ds File
- NServiceBus Transport Options - Site Database
- NServiceBus Persistence Options - Site Database
- ServiceControl Queues - Use default labels
Results Sender Configuration
The Results Sender service is configurable for optimal performance in a distributed system. The configurable options include:
Specify Managed DataSource
The Results Sender service processes the database changes in CM4D for export. Distributed installations with databases in different regions that are organized within a single Site may cause inefficiencies. For example, if a Results Sender service in Europe processes changes for a database in Asia.
A configuration option allows you to restrict a Results Sender instance to process only specified Managed Datasources. It is possible to configure a datasource via DataSource label or to specify a Site and include all Datasources in that Site.
The Results Sender appsettings.json file has a configuration setting ProcessDatasources that takes an array of definitions. See below for examples of possible configurations.
- All DataSources ["*/*"] - Include all DataSources in the Site using an asterisk in place of the Site and DataSource labels, separated by a forward slash (*/*). This is the default configuration if the parameter is empty or missing.
},
"AllowedHosts": "*",
"ProcessDatasources": ["*/*"]
}
- All DataSources in a Site ["Site/*"] - Include all DataSources in the specified Site.
},
"AllowedHosts": "*",
"ProcessDatasources": ["SiteA/*"]
}
- Multiple DataSources ["Site/DB","Site/DB"] - Include multiple specified DataSources. Each definition contains a Site label and a DataSource label separated by a forward slash (Site/DataSource). Additional Datasources can be specified by separating the Site/DB labels with a comma.
},
"AllowedHosts": "*",
"ProcessDatasources": ["SiteA/CM4DB1","SiteA/CM4DDB2","SiteB/CM4DDB3"]
}
Results Processing Options
The number of entries in the Results Command Queue table (used during processing Results from CM4D to the Results database) can become busy if you are moving a large amount of data. Customizing the processing configuration may improve overall performance.
Add or modify the following settings in the Results Sender appsettings.json file:
| Setting | Default Value | Description |
| MaxParallelProcessing | 10 | Maximum number of parallel Routines to be processed if the complete database is transferred. |
| JobBatchSize | 100 | Number of commands processed in each transaction. |
| ScanQueueIntervallWhenIdle | 1000 | Milliseconds between two table scans if no entry was processed. |
| ScanQueueIntervallWhenFound | 100 | Milliseconds between two table scans if entries have been processed. |
| RetryFailedAfter | 30 | Minutes to retry a command that did not complete (status 1). |
| RemoveProcessedAfter | 2880 | Minutes to delete commands that have been processed (status 2). |
},
"AllowedHosts": "*",
"MaxParallelProcessing": "10",
"JobBatchSize": "100",
"ScanQueueIntervallWhenIdle": "1000",
"ScanQueueIntervallWhenFound": "100",
"RetryFailedAfter": "30",
"RemoveProcessedAfter": "2880",
"ProcessDatasources": ["*/*"]
}
Troubleshooting Results Services
| Area | Issue | Checks | Solution(s) | Help Topics |
|
Results Loader Service |
Results Loader service does not start. Windows Event Viewer Description: The process was terminated due to an unhandled exception. Exception Info: System.Exception: The results database has pending migrations. Please run ResultsDatabaseMigrator to upgrade the database. |
Check that the Results Database does not have any pending schema updates. |
Run the Results Database Utility. Complete the migration on any pending schema changes. Once complete, try to start the service again. |
Results Database Utility |
See also: