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
 
Table to configure
Purpose
TE_STATUS_GROUPS_ST
Defines groups of event types that share state transitions.
TE_STATUSES_ST
Maps each event condition status to a status group.
TE_VALID_STATES_ST
Defines state identifiers, names, and bit positions.
TE_STATE_ACTIONS
Identifies actions that can trigger a transition.
TE_STATE_TRANSITIONS
Maps a group, current state, and action to a destination state.
TE_INIT_STATE_RULES
Selects an initial state using an expression.
TE_EXPRESSIONS
Defines individual tests and composite expressions.
TE_COMPOSITE_EXPRESSIONS
Associates composite expressions with their child expressions.
SRS_RULES
Defines terminal states using the terminationState configuration rule.
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.
 
Column Name
Column Type
Description
APP
VARCHAR2(16)
Application identifier. Use TE for JMService events.
GROUP_KEY
INTEGER
Group identifier, unique within the application.
GROUP_NAME
VARCHAR2(32)
Name of the group.
DESCRIPTION
VARCHAR2(80)
Description of the group.
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.
 
Column Name
Column Type
Description
APP
VARCHAR2(16)
Use TE.
STATUS_KEY
INTEGER
Row identifier, unique within the application.
TRANS_GROUP_KEY
INTEGER
References the group's GROUP_KEY.
TRANS_STATUS
INTEGER
Event condition status code.
DESCRIPTION
VARCHAR2(80)
Description of the event type mapping.
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.
 
Column Name
Column Type
Description
APP
VARCHAR2(16)
Use TE.
STATE_KEY
INTEGER
State identifier, unique within the application. Used by transitions, initial-state rules, and terminal-state rules.
STATE_VALUE
INTEGER
Bit position in the event state mask, from 0 through 31.
STATE_NAME
VARCHAR2(32)
State name, such as NEW, UAS, or CMP.
ALARM
VARCHAR2(1)
Alarm-state flag. Base configuration uses Y or N.
DESCRIPTION
VARCHAR2(160)
Description of the state.
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.
 
Column Name
Column Type
Description
APP
VARCHAR2(16)
Use TE.
ACT_KEY
INTEGER
Action identifier, unique within the application. Referenced by TRANS_ACT_KEY.
ACT_TYPE
VARCHAR2(32)
Source of the action. See the following table.
ACT_VAL
INTEGER
Numeric action value understood by the source. Required even when the action is matched by name.
ACT_NAME
VARCHAR2(32)
Action name, unique within the application. Use the command name expected by the caller.
DESCRIPTION
VARCHAR2(80)
Description of the action.
The principal action sources for JMService events are:
 
Action Type
Matching Value
BUTTON
Work Agenda or other supported event command, normally matched by ACT_NAME, such as ack. Internal button actions can use a numeric value.
CREWMAN
Crew message type in ACT_VAL, such as an assignment, dispatch, or arrival notification.
SRS
Applied-rule code in ACT_VAL, such as outage restored or outage complete.
TE_GRP
Destination status group key in ACT_VAL when an event changes groups.
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.
 
Column Name
Column Type
Description
APP
VARCHAR2(16)
Use TE.
TRANS_KEY
INTEGER
Transition row identifier. The insert trigger assigns it from a sequence, overriding a supplied value.
TRANS_GROUP_KEY
INTEGER
References the applicable status group's GROUP_KEY.
FROM_STATE_KEY
INTEGER
References the current state's STATE_KEY.
TO_STATE_KEY
INTEGER
References the destination state's STATE_KEY.
TRANS_ACT_KEY
INTEGER
References the triggering action's ACT_KEY.
CLEAR_FLAG
VARCHAR2(1)
Controls whether the source state's bit is cleared. Use Y to clear it or N to retain it. T is also accepted as true.
DESCRIPTION
VARCHAR2(80)
Description of the transition.
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:
 
Definition
Base Configuration
Status group
OUT
Event type
Probable Service Outage, mapped to OUT
Source state
NEW
Action
BUTTON action named ack
Destination state
UAS
Clear flag
Y
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.
 
Column Name
Column Type
Description
APP
VARCHAR2(16)
Use TE.
RULE_KEY
INTEGER
Rule identifier, unique within the application. Determines evaluation order within a group.
GROUP_NUM
INTEGER
References the status group's GROUP_KEY.
EXPR_KEY
INTEGER
References the expression to evaluate.
INIT_STATE
INTEGER
STATE_KEY to select when the expression is true. This is not a bit position.
DESCRIPTION
VARCHAR2(80)
Description of the rule.
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:
 
Relative RULE_KEY
Condition
Selected Initial State
Lower
RDO and critical customer affected.
Project's initial state for critical-customer RDOs.
Higher
RDO, regardless of critical-customer involvement.
Project's general RDO initial state.
 
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.
 
Column Name
Column Type
Description
EXPR_KEY
INTEGER
Globally unique expression identifier.
LEFT_SIDE
VARCHAR2(32)
Input to test, or COMPOSITE for an expression with children.
OPERATOR
VARCHAR2(2)
Comparison, bitwise test, or composite Boolean operator.
RIGHT_SIDE
VARCHAR2(32)
Supported symbolic constant or numeric text; use COMPOSITE for a composite parent.
NEGATE
VARCHAR2(1)
Use F for a normal individual test or T to invert it.
DESCRIPTION
VARCHAR2(80)
Description of the expression.
EXPR_USAGE
INTEGER
Use 2 for initial-state expressions or 0 for expressions shared across usages.
 
The initial-state evaluator supplies the following inputs. Other inputs supported elsewhere in the TE Expression framework are not supplied by this initialization path.
 
Left Side
Initial-State Input
EVENT_TYPE
Event condition status.
MESSAGE_TYPE
TRBL_PRIORITY_CALL for an additional alarm; TRBL_UPDATE otherwise.
APPLIED_RULE
Event's applied-rule value.
NUM_CALLS
Number of calls associated with the event.
BITMASK
Event status bitmask. This is separate from the event state mask described under State Transitions.
APPT_TYPE
Event appointment type.
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.
 
Column Name
Column Type
Description
PARENT_EXPR_KEY
INTEGER
References the composite parent's expression key.
CHILD_EXPR_KEY
INTEGER
References a child expression key. The parent/child pair is the primary key.
SEQ_NUM
INTEGER
Order of child evaluation. Use distinct values within a parent.
EXPR_USAGE
INTEGER
Usage classification; use 2 for initial-state links. The current child loader selects links by parent key, without filtering this column.
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:
 
Evaluation Order
RULE_KEY
Test
Initial State if True
First
10
Notification alarm (MESSAGE_TYPE == TRBL_PRIORITY_CALL).
NFY
Second
20
SCADA event (BITMASK & SCADA_MASK).
S-NEW
Third
40
Real service outage and MESSAGE_TYPE == TRBL_UPDATE.
UAS
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:
 
Rule Field
Value
SET_NAME
config
RULE_NUM
An unused rule number in the rule set.
RULE_ACTIVE
1
INCIDENT_TYPE
any
RULE_NAME
terminationState
RULE_VALUE_1
State name. It may be empty; when supplied, it must match the configured state name.
RULE_VALUE_2
Valid state key, represented as an integer value.
RULE_VALUE_INTEGER_1 through RULE_VALUE_INTEGER_5
0; unused.
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
 
Symptom
Configuration to Check
Event has no initial state
Event type mapping, referenced group, matching initial rule and state, and availability of a fallback source state.
Event starts in an unexpected state
Ascending RULE_KEY precedence, expression usage, available initialization inputs, and the group's lowest source STATE_KEY.
Action does not change the state
Runtime group mapping, source state key, action type and name/value, and the transition's references. Also check any configured state callbacks or command-specific validation.
State name changes but later behavior is unexpected
Destination STATE_VALUE and CLEAR_FLAG, including bits retained from earlier states.
Expression is missing or evaluates unexpectedly
Case-sensitive tokens, supported operator, EXPR_USAGE, child references, child order, and the distinction between status and state masks.
Completed events remain tracked incorrectly
Missing or incorrect terminationState rules, including type-specific completion and cancellation states.
Project changes do not appear at runtime
Project SQL load order, staging-to-runtime merge, and JMService restart.