Data Event Formats - Ratings

Summary

CWMS needs a message structure to notify clients of rating-related events.

Opinions

Opinion 1

Summary: Use the structures described below for rating-related events.

All messages will be published to the appropriate REALTIME_OPS topic. Subscribers can set up appropriate filters to receive the desired messages.

After implementation, the RatingStored messages published to various TS_STORED and REALTIME_OPS topics will be deprecated and removed.

Author: Mike Perryman

Rating Templates

Only values necessary to uniquely identify a rating template (“type”, “template_id”) are required for RatingTemplateCreated, RatingTemplateUpdated, and RatingTemplateDeleted messages.

RatingTemplateCreated Message Structure

Message Type	Structure
RatingTemplateCreated	Value Type Value Name Value String “type” “rating_template_created” Object “template_id” The rating template identifier String “description” The description for the template

Example RatingTemplateCreated message

{
    "type": "rating_template_created",
    "template_id": {
            "office_id": "SWT",
            "name": "Stage;Flow.Logarithmic"
    },
    "description": "USGS-style stage/flow ratings"
}

RatingTemplateUpdated Message Structure

Message Type	Structure
RatingTemplateUpdated	Value Type Value Name Value String “type” “rating_template_updated” Object “template_id” The rating template identifier String “description” The description for the template

Example RatingTemplateUpdated message

{
    "type": "rating_template_updated",
    "template_id": {
            "office_id": "SWT",
            "name": "Stage;Flow.Logarithmic"
    },
    "description": "USGS-style stage/flow BASE ratings"
}

RatingTemplateDeleted Message Structure

Message Type	Structure
RatingTemplateDeleted	Value Type Value Name Value String “type” “rating_template_deleted” Object “template_id” The rating template identifier

Example RatingTemplateDeleted message

{
    "type": "rating_template_deleted",
    "office_id": "SWT",
    "template_id": "Stage;Flow.Logarithmic"
}

Rating Specifications

Only values necessary to uniquely identify a rating specification (“type”, “specification_id”) are required for RatingSpecificationCreated, RatingSpecificationUpdated, and RatingSpecificationDeleted messages.

Message Type

Structure

RatingSpecificationCreated

Value Type Value Name Value String “type” “rating_specification_created” Object “specification_id” The rating specification identifier String “source_agency” The entity that generates ratings for this specification String “in_range_method” The interpoloation method used when values are in range of rating values String “out_range_low_method” The extrapolation method used when values are below the range of rating values String “out_range_high_method” The extrapolation method used when values are above the range of rating values boolean “active” Whether the specification is active boolean “auto_update” Whether ratings with this specification should be automatically updated boolean “auto_activate” Whether ratings with this specification should be set to active when automatically updated boolean “auto_migrate_extensions” Whether ratings with this specification should have existing rating extensions migrated when automatically updated String “independent_rounding” Rounding specifications for independent parameters, in order, comma separated String “dependent_rounding” Rounding specification for the dependent parameter String “description” The description for the specification

Example RatingSpecificationCreated message

{
    "type": "rating_specification_created",
    "specification_id": {
            "office_id": "SWT",
            "name": "Tulsa.Stage;Flow.Logarithmic.Production"
    },
    "source_agency": "ABRFC",
    "in_range_method": "LINEAR",
    "out_range_low_method": "NEAREST",
    "out_range_high_method": "NEAREST",
    "active": true,
    "auto_update": true,
    "auto_activate": true,
    "auto_migrate_extensions": true,
    "independent_rounding": "4444444444",
    "dependent_rounding": "4444444444",
    "description": "USGS streamflow rating for the Arkansas River at Tulsa, OK"
}

RatingSpecificationUpdated Message Structure

Message Type

Structure

RatingSpecificationUpdated

Value Type Value Name Value String “type” “rating_specification_updated” Object “specification_id” The rating specification identifier String “source_agency” The entity that generates ratings for this specification String “in_range_method” The interpoloation method used when values are in range of rating values String “out_range_low_method” The extrapolation method used when values are below the range of rating values String “out_range_high_method” The extrapolation method used when values are above the range of rating values boolean “active” Whether the specification is active boolean “auto_update” Whether ratings with this specification should be automatically updated boolean “auto_activate” Whether ratings with this specification should be set to active when automatically updated boolean “auto_migrate_extensions” Whether ratings with this specification should have existing rating extensions migrated when automatically updated String “independent_rounding” Rounding specifications for independent parameters, in order, comma separated String “dependent_rounding” Rounding specification for the dependent parameter String “description” The description for the specification

Example RatingSpecificationUpdated message

{
    "type": "rating_specification_updated",
    "specification_id": {
            "office_id": "SWT",
            "name": "Tulsa.Stage;Flow.Logarithmic.Production"
    },
    "source_agency": "ABRFC",
    "in_range_method": "LINEAR",
    "out_range_low_method": "NULL",
    "out_range_high_method": "NEAREST",
    "active": true,
    "auto_update": true,
    "auto_activate": true,
    "auto_migrate_extensions": true,
    "independent_rounding": "0223456782",
    "dependent_rounding": "0222233332",
    "description": "USGS streamflow rating for the Arkansas River at Tulsa, OK"
}

RatingSpecificationDeleted Message Structure

Message Type	Structure
RatingSpecificationDeleted	Value Type Value Name Value String “type” “rating_specification_deleted” Object “specification_id” The rating specification identifier

Example RatingSpecificationDeleted message

{
    "type": "rating_specification_deleted",
    "office_id": "SWT",
    "specification_id": "Tulsa.Stage;Flow.Logarithmic.Production"
}

Ratings

Only values necessary to uniquely identify a rating (“type”, “specification_id”, “effective_time”) are required for RatingCreated, RatingUpdated, and RatingDeleted messages.

RatingCreated Message Structure

Message Type

Structure

RatingCreated

Value Type Value Name Value String “type” “rating_created” Object “specification_id” The rating specification identifier long “effective_time” The date/time the rating comes into effect, in epoch milliseconds long “transition_time” The date/time the to begin linear interpolation from the previous rating, in epoch milliseconds long “creation_time” The date/time before which no there is no knowlege of this rating, in epoch milliseconds boolean “active” Whether this rating is active String “rating_type” “lookup”, “expression”, “usgs”, “virtual”, or “transitional”

Example RatingCreated message

{
    "type": "rating_created",
    "specification_id": {
            "office_id": "SWT",
            "name": "Tulsa.Stage;Flow.Logarithmic.Production"
    },
    "effective_time": 1782190800000,
    "transition_time": 1780981200000,
    "creation_time": 1787140800000,
    "active": false,
    "rating_type": "usgs"
}

RatingUpdated Message Structure

Message Type

Structure

RatingUpdated

Value Type Value Name Value String “type” “rating_updated” Object “specification_id” The rating specification identifier long “effective_time” The date/time the rating comes into effect, in epoch milliseconds long “transition_time” The date/time the to begin linear interpolation from the previous rating, in epoch milliseconds long “creation_time” The date/time before which no there is no knowlege of this rating, in epoch milliseconds boolean “active” Whether this rating is active String “rating_type” “lookup”, “expression”, “usgs”, “virtual”, or “transitional”

Example RatingUpdated message

{
    "type": "rating_updated",
    "specification_id": {
            "office_id": "SWT",
            "name": "Tulsa.Stage;Flow.Logarithmic.Production"
    },
    "effective_time": 1782190800000,
    "transition_time": 1780981200000,
    "creation_time": 1787140800000,
    "active": true,
    "rating_type": "usgs"
}

RatingDeleted Message Structure

Message Type	Structure
RatingDeleted	Value Type Value Name Value String “type” “rating_deleted” Object “specification_id” The rating specification identifier long “effective_time” The date/time the rating comes into effect, in epoch milliseconds

Example RatingDeleted message

{
    "type": "rating_deleted",
    "specification_id": {
            "office_id": "SWT",
            "name": "Tulsa.Stage;Flow.Logarithmic.Production"
    },
    "effective_time": 1782190800000
}

Decision Status

Status: request for comments

References