Event State Transitions
JMService uses event states to track the progress of an event, such as New, Unassigned, Assigned, Restored, and Complete. Configure the available states, the actions that change them, and the allowed transitions in the TE state tables. Use APP = 'TE' for JMService events in each table that contains an APP column.
This section covers JMService events. For switching and safety state transitions and state transition callback configuration, refer to the corresponding switching and safety documentation.
An event's type and state serve different purposes. The type identifies the event's condition status, such as Probable Service Outage or Planned Outage. The state identifies its progress through the configured workflow. Several event types can share one set of transitions by belonging to the same status group.
Event state configuration includes:
• Status groups and their event types.
• Valid states and their state bit values.
• Actions and the transitions they trigger.
• Rules that select an initial state.
• Terminal states that identify the end of the event workflow.
Configuration Tables
Note: Configure TE_STATUS_GROUPS_ST, TE_STATUSES_ST, and TE_VALID_STATES_ST in the project SQL files. JMService reads the corresponding runtime tables, TE_STATUS_GROUPS, TE_STATUSES, and TE_VALID_STATES. The post-setup process merges the staging configuration into the runtime tables. It also deletes runtime entries that are absent from staging. Direct changes to these runtime tables do not replace project configuration and can be overwritten by a subsequent setup.
The expression tables have no APP column. Expression keys are shared with other consumers of the TE Expression framework. Preserve expressions and composite links used by switching, sorting, or other applications.
Status Groups
Configure groups in TE_STATUS_GROUPS_ST.
The base configuration includes groups named OUT, NON, MEET, PLAN, SWP, and FAULT. Use an existing group when the event types must share a workflow. Create a separate group when they require different transitions or initial-state rules. A change to a group's configuration affects every event type mapped to that group.
Event Type Mappings
Configure event type mappings in TE_STATUSES_ST.
TRANS_STATUS is the event type code, not a valid-state key. Use the supported event condition status values for the release, as defined by the event type configuration and Job.h. Map each event condition status to one group; do not configure competing mappings for the same type.
Valid States
Configure states in TE_VALID_STATES_ST.
STATE_KEY and STATE_VALUE are different identifiers. The key selects a particular named state. The value identifies a state category used by JMService logic; its mask value is 1 << STATE_VALUE. For example, the base NEW and P-NEW states have different keys but both use the unacknowledged state bit.
Preserve the meanings of the standard state bit positions. JMService uses them to recognize conditions such as acknowledged, assigned, enroute, restored, complete, and cancelled. Renaming a state or choosing a different key does not change the meaning of its bit position. Refer to TEStatesConst.h and the supplied state definitions when configuring these values.
State Actions
Configure actions in TE_STATE_ACTIONS.
The principal action sources for JMService events are:
The shared loader also recognizes SWS and DA; use them only where the corresponding application supplies those actions. NOTIFY, mentioned in older schema comments, is not a recognized action type in this loader.
For name-based matching, JMService uses the action type and command name. For value-based matching, it uses the action type and numeric value. The loader converts configured action names to lowercase; configure names to match the lowercase commands used by the application. Do not substitute ACT_KEY for ACT_VAL. Reuse the supplied action definitions and supported numeric constants rather than inventing new message or applied-rule codes.
Adding a BUTTON action row does not create a client button or implement a new server command. Configure the client command and its availability separately where required. JMService returns action keys from the current state's configured transitions for use by clients.
State Transitions
Configure allowed transitions in TE_STATE_TRANSITIONS.
JMService selects the event's group from its condition status, then looks for a transition from its current state that matches the incoming action type and name or value. If no transition matches, the state remains unchanged. A transition applies only to its configured group; there is no implicit transition through another group.
Configure one destination for each combination of group, source state, and incoming action. Duplicate matching rows do not represent conditional alternatives. Initial-state expressions are not evaluated as guards on normal transitions.
CLEAR_FLAG controls the state bit mask independently of the destination state key:
• Y: Clear the source state's bit, then set the destination state's bit. Other bits remain set.
• N: Retain the existing mask and add the destination state's bit.
The formulas are:
CLEAR_FLAG = Y: new_mask = (old_mask & ~from_bit) | to_bit
CLEAR_FLAG = N: new_mask = old_mask | to_bit
The current state key and name become those of the destination state in either case. Retaining bits can affect later JMService behavior, so use N only when the workflow requires that information to remain in the mask.
Example: Acknowledge an Outage Event
The supplied base configuration connects the following definitions:
When an operator acknowledges a NEW event in this group, the matching transition changes the event to UAS, clears the unacknowledged bit, and sets the acknowledged bit. The same command needs a separate transition for each additional source state or group where it must cause a state change.
The following is a project SQL template for such a transition. Bind variables represent keys resolved from the project's existing group, state, and action definitions; this is not a complete setup script.
INSERT INTO te_state_transitions
(app, trans_group_key, from_state_key, to_state_key,
trans_act_key, clear_flag, description)
VALUES
('TE', :out_group_key, :new_state_key, :uas_state_key,
:ack_action_key, 'Y', 'NEW --> UAS');
Initial State Configuration
An event's initial state can depend on its type, its source, and other information available when JMService initializes it. For example, an event reported through SCADA can start in S-NEW, while another outage starts in NEW or UAS.
Configure rules in TE_INIT_STATE_RULES.
JMService evaluates the group's rules in ascending numeric RULE_KEY order, from the lowest key to the highest, and stops at the first expression that evaluates to true. Later rules in that group are not evaluated after a match. SQL insertion order, the order of statements in a project SQL file, and EXPR_KEY do not determine rule precedence. Reordering SQL statements without changing their rule keys does not change evaluation order.
Precedence applies within the event's status group. Rules belonging to other groups do not compete with that group's rules. Place specific cases before broader cases by assigning the specific rules lower RULE_KEY values. Changing a rule key can change an event's initial state when more than one rule matches, even if the expressions themselves are unchanged. The selected state must exist in the valid-state configuration and must have the transitions required by that group's workflow.
If the group has no rules, or none evaluates to true, JMService uses the source state with the lowest STATE_KEY among that group's loaded transitions. Merely adding a valid state does not make it the group's default. A group without transitions has no fallback initial state. A true rule that names a nonexistent state is invalid configuration; do not rely on fallback to correct it.
Note: Initial-state fallback is determined by the source state's STATE_KEY, not by the action's ACT_KEY, the state's bit position, or the transition row identifier.
Adding an Initial-State Rule
When adding an entry to TE_INIT_STATE_RULES:
1. Identify the new event's status group through its TE_STATUSES_ST mapping. Use that group's key as GROUP_NUM and use APP = 'TE'.
2. Define or reuse an expression that tests the required conditions using inputs available during initialization. Set EXPR_KEY to that expression's key. Use a composite expression when multiple conditions must be true.
3. Select the destination valid state's STATE_KEY as INIT_STATE and verify that the group has the transitions needed to continue from that state.
4. Review the group's existing rules in ascending RULE_KEY order. Assign an unused rule key that places the new condition before any broader condition that would also match it. Rule keys must remain unique within APP, including across groups.
5. Verify both the specific case and the broader case after applying the configuration. Confirm that an event satisfying both conditions receives the specific case's initial state.
Example: RDO with a Critical Customer Before All RDOs
Suppose a project requires one initial state for a Real Device Outage (RDO) affecting a critical customer and another initial state for other RDOs. Both rules match an RDO affecting a critical customer, so configure their relative order as follows:
JMService checks the more specific condition first. If it is true, evaluation stops and the general RDO rule is not checked. If the specific condition is false, evaluation continues to the general RDO rule. Putting the general RDO rule first would prevent the specific rule from selecting its state for any matching RDO. Here, “more specific” means a narrower matching condition; the number of expressions alone does not determine precedence.
This example illustrates rule precedence. Implement the critical-customer condition only through information actually exposed to the initial-state evaluator in the project's release. The inputs listed below do not include a direct critical-customer count or a CRITICAL_CUSTOMER expression token; the example does not introduce such a token. CRITICAL_MEET is a different event type and is not a substitute for an RDO affecting a critical customer.
TE Expressions
Configure individual tests and composite expressions in TE_EXPRESSIONS.
The initial-state evaluator supplies the following inputs. Other inputs supported elsewhere in the TE Expression framework are not supplied by this initialization path.
Use ==, <, <=, >, or >= for numeric comparisons. For an individual test, & is true when the input and right-side mask share at least one bit. The framework also accepts bitwise |, which tests whether the bitwise OR result is nonzero; it does not test for a shared bit. Use NEGATE = 'T' to express inequality or invert an individual bit test; != is not supported.
Use the supported symbolic constants where available, such as REAL_SERVICE_OUTAGE, PLANNED_OUTAGE, TRBL_UPDATE, SCADA_MASK, and APPT_NONE. Names are case-sensitive. EVENT_TYPE == OUTAGE is a supported category test covering probable, real, confirmed, momentary, and planned outages, rather than a test for one condition status.
Composite Expressions
To combine tests, define a parent expression with LEFT_SIDE = 'COMPOSITE', RIGHT_SIDE = 'COMPOSITE', and one of these operators:
• &&: All child expressions must be true.
• OR: At least one child expression must be true.
Use NEGATE = 'F' on composite parents. Composite evaluation combines the child results; it does not apply the parent's negate flag. To invert a composite condition, express the inverse using its individual tests and Boolean structure.
Associate children in TE_COMPOSITE_EXPRESSIONS.
Every parent and child used during initialization must be available with EXPR_USAGE equal to 0 or 2 in TE_EXPRESSIONS. A composite can reference other composites to express nested conditions. Keep the expression structure free of cycles and define all referenced expressions.
Example: Select an Initial State for a Real Service Outage
The supplied configuration contains this expression structure:
EVENT_TYPE == REAL_SERVICE_OUTAGE
&&
MESSAGE_TYPE == TRBL_UPDATE
An initial-state rule for the outage group uses this composite to select UAS. Earlier rules in the same group handle notification alarms and SCADA events, so those rules take precedence when they match.
For example, the supplied outage-group rules include these existing rule keys:
For an event that matches both the SCADA test and the real-service-outage composite, rule 20 selects S-NEW; rule 40 is not evaluated. Moving rule 40 above rule 20 in the SQL file does not change this result. Giving a broad matching rule a lower key than the SCADA rule would change the precedence and could prevent the intended SCADA initial state from being selected. The numbers in this example identify supplied rules; check the project's actual keys before changing configuration.
The equivalent project configuration template is:
INSERT INTO te_expressions
(expr_key, left_side, operator, right_side,
negate, description, expr_usage)
VALUES
(:type_expr_key, 'EVENT_TYPE', '==', 'REAL_SERVICE_OUTAGE',
'F', 'Real service outage', 2);
INSERT INTO te_expressions
(expr_key, left_side, operator, right_side,
negate, description, expr_usage)
VALUES
(:message_expr_key, 'MESSAGE_TYPE', '==', 'TRBL_UPDATE',
'F', 'New event', 2);
INSERT INTO te_expressions
(expr_key, left_side, operator, right_side,
negate, description, expr_usage)
VALUES
(:parent_expr_key, 'COMPOSITE', '&&', 'COMPOSITE',
'F', 'Real service outage and new event', 2);
INSERT INTO te_composite_expressions
(parent_expr_key, child_expr_key, seq_num, expr_usage)
VALUES
(:parent_expr_key, :type_expr_key, 0, 2);
INSERT INTO te_composite_expressions
(parent_expr_key, child_expr_key, seq_num, expr_usage)
VALUES
(:parent_expr_key, :message_expr_key, 1, 2);
INSERT INTO te_init_state_rules
(app, rule_key, group_num, expr_key, init_state, description)
VALUES
('TE', :initial_rule_key, :out_group_key, :parent_expr_key,
:uas_state_key, 'Real service outage initially UAS');
Resolve the group and state keys from the project's definitions. Allocate unused expression and rule keys, or reuse equivalent existing expressions. Choose :initial_rule_key to preserve the intended precedence. Do not add duplicate copies of the supplied rules.
Terminal Event States
A terminal state ends the normal event workflow. Typical examples are CMP (Complete) and CNL (Cancel). Configure one active terminationState rule for every distinct terminal state key, including type-specific variants such as planned or SCADA completion states.
The rule is stored in SRS_RULES with the following values:
For example, a rule for the project's complete state uses RULE_VALUE_1 = 'CMP' and RULE_VALUE_2 equal to that state's STATE_KEY. Do not put the state bit position in RULE_VALUE_2 or move this value to RULE_VALUE_INTEGER_1.
Important: The terminationState rule is required for proper JMService operation. JMService uses terminal-state membership in completion and event-memory management. Missing or incorrect terminal-state configuration can leave completed events tracked incorrectly and cause memory leaks. Reaching a terminal state does not mean that the event's historical database records are deleted.
An absence of outgoing transitions does not register a state as terminal. Configure the rule as well as the transitions that reach the state, and do not define normal outgoing transitions from it. Conversely, do not register a state such as Restored or Incomplete as terminal when the workflow still requires further processing.
JMService validates terminal-state keys and any supplied names against the loaded valid states during initialization. Review its log for missing states and name mismatches after applying changes.
Applying and Verifying Configuration
1. Define the intended workflow for each event type. Identify the shared group, initial states, action sources, permitted transitions, and terminal states.
2. Update project SQL configuration. The supplied definitions are in config/nms/sql/nms_te_states.sql; project overrides use the corresponding project te_states SQL family. Update terminal-state rules in the project's SRS rule configuration. Preserve other applications' rows and shared expressions.
3. Load the project configuration through the site's normal setup procedure. Ensure that post-setup processing merges the three staging tables into the runtime tables before JMService starts. In the supplied setup, nms-setup loads the te_states family and nms-postsetup runs postsetup_merge_te_states.
4. Apply the configuration during a planned JMService restart using the site's service-management procedure. These definitions are cached. The implementation marks live statemgr reload as unsupported because sufficiently different configuration can conflict with existing event state. Reloading SRS rules alone does not reload the state tables.
5. Review startup logs for invalid state, action, group, or expression references and terminal-state validation errors. Renaming, removing, or changing the bit meaning of a state used by existing events requires a plan for those events before activation.
6. Create representative events for each affected event type and verify the initial state. Include cases that match each rule, cases that match multiple rules to verify precedence, and a case that uses fallback.
7. Exercise operator commands, crew changes, SRS updates, and event type changes used by the workflow. Check the destination state and any retained state bits. Verify that an action without a configured transition leaves the state unchanged.
8. Complete and cancel representative events. Verify normal closeout and historical access, and confirm that no event remains in a nonterminal state after its workflow is finished. Check associated client action availability and mobile behavior where affected.
Use the following read-only query to inspect a runtime transition and its linked definitions. Bind :group_name to the group being checked.
SELECT g.group_name,
f.state_name AS from_state,
a.act_key, a.act_type, a.act_val, a.act_name,
t.state_name AS to_state,
x.clear_flag
FROM te_state_transitions x
JOIN te_status_groups g
ON g.app = x.app AND g.group_key = x.trans_group_key
JOIN te_valid_states f
ON f.app = x.app AND f.state_key = x.from_state_key
JOIN te_valid_states t
ON t.app = x.app AND t.state_key = x.to_state_key
JOIN te_state_actions a
ON a.app = x.app AND a.act_key = x.trans_act_key
WHERE x.app = 'TE' AND g.group_name = :group_name
ORDER BY f.state_key, a.act_type, a.act_key;
This query displays transitions whose references resolve. Separately check for missing referenced rows when investigating startup errors; an inner join omits broken references.
Troubleshooting