Scheduled Analysis Execution
- Last UpdatedNov 18, 2025
- 4 minute read
- PI System
- AF SDK 2024 R2
- Developer
A scheduled AFAnalysis will be scheduled to execute by PI Analysis Service. An AFAnalysisRule that supports state passing can be executed manually or can be executed by the analysis service. Analysis rules that support state passing do not hold information pertaining to their context (e.g. target AFElement or input AFAttribute) or their runtime state (e.g. an in-progress AFEventFrame), rather this information is held in a state object instance that implements IAFAnalysisRuleState. Calling an AFAnalysisRule using state passing provides several benefits:
- Memory reduction: a single analysis rule instance can be used to evaluate different contexts (e.g. the analysis rule on an AFAnalysisTemplate can be used to evaluate all derived AFAnalysis instances).
- Richer configuration and diagnostic information from the analysis rule.
- Control over output: the analysis rule will deposit its output values in the state object and let the caller determine what to do with them. This enables ad-hoc calculations and high-performance scenarios where bulk-writes are necessary.
- State management: the caller can discard the state (for ad-hoc calculation) or change the time stamp and run the analysis again to run a stateful analysis.
Execution Steps
Verify that the analysis rule supports state passing
An analysis rule that supports state passing will return a value of AFAnalysisRuleSupportedBehaviors with the SupportsStatePassing flag set. If this flag is not set, another execution method must be used.
Get the analysis rule configuration
The configuration information for an analysis rule is available by calling AFAnalysisRuleGetConfiguration. To specify the context (e.g. to configure an AFAnalysisTemplateAnalysisRule against a target AFElement), call AFAnalysisRuleGetConfiguration(AFObject), passing the target context. The returned AFAnalysisRuleConfiguration instance contains the Inputs and Outputs collections along with any configuration errors. If the AFAnalysisRuleConfigurationIsValid property returns false, there are configuration errors that prevent the analysis rule from being run.
Construct a state object
An AFAnalysisRuleState object can be constructed using the AFAnalysisRuleStateAFAnalysisRuleState(AFAnalysisRuleConfiguration) constructor. This instance can be used for repeated evaluations of the same context.
Set the time stamp
To set the execution time and populate input values, call the AFAnalysisRuleStateSetExecutionTimeAndPopulateInputs(AFTime) method.
Run the analysis rule
To run the analysis rule, pass the state object to the AFAnalysisRuleRun(IAFAnalysisRuleState) method. The analysis rule will populate the outputs of the state object with values that correspond to the Outputs collection of the AFAnalysisRuleConfiguration. These can be consumed by the caller as desired.
To run the next time stamp, repeat from step 4.
Queueing Calculations in the Analysis Service
A scheduled analysis can also be queued for calculation in the analysis service. Call the QueueCalculation(IEnumerableAFAnalysis, AFTimeRange, AFAnalysisServiceCalculationMode) method with one or more analyses and a desired calculation time range. Use AFAnalysisServiceCalculationMode to specify what to do with existing data in the analysis output time range. Supported modes are FillDataGaps, DeleteExistingData, and DeleteExistingDataCalculateDependents that will result in filling gaps in existing data, deleting existing data before writing new calculated data, or the latter with also queuing dependent analyses, respectively. FillDataGaps is not supported for analyses that output Event Frames.
To check if calculations can be queued at the time, use CanQueueCalculation(String). If the functionality is not available (e.g. the analysis service is not running), the method will return 'false' along with the reason.
Monitoring Analyses Execution in the Analysis Service
You can monitor the scheduled analyses execution in PI Analysis Service by querying the service and calling QueryRuntimeInformation(String, String) or one of its overloads with a filtering criteria and desired return fields. This allows you to monitor the health of running analyses and also gather general statistics of analysis executions. For example, it allows you to develop an application that monitors the health of PI Analysis Service by periodically polling the service with a query that returns analyses with higher-than-specified lag or certain evaluation errors. The information can be used to alert the end users, so they can take appropriate actions.
For specific examples, see QueryRuntimeInformation(String, String) method and RuntimeInformationFields property.