Add new components_json field to the jira_fields table.

Also add deprecation advice and code comments for systems, subsystems, cscs, components, primary_software_components and primary_hardware_components.

alembic/versions/49ef39173f83_add_components_json_field_to_jira_.py

@@ -0,0 +1,42 @@
+"""add components_json field to jira_fields table
+
+Revision ID: 49ef39173f83
+Revises: 54f755dbdb6f
+Create Date: 2024-12-18 17:01:39.676895
+
+"""
+import logging
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "49ef39173f83"
+down_revision = "54f755dbdb6f"
+branch_labels = None
+depends_on = None
+
+
+JIRA_FIELDS_TABLE_NAME = "jira_fields"
+
+
+def upgrade(log: logging.Logger, table_names: set[str]) -> None:
+    if JIRA_FIELDS_TABLE_NAME not in table_names:
+        log.info(f"No {JIRA_FIELDS_TABLE_NAME} table; nothing to do")
+        return
+    log.info("Add 'components_json'")
+
+    op.add_column(
+        JIRA_FIELDS_TABLE_NAME,
+        sa.Column("components_json", sa.JSON(), nullable=True),
+    )
+
+
+def downgrade(log: logging.Logger, table_names: set[str]) -> None:
+    if JIRA_FIELDS_TABLE_NAME not in table_names:
+        log.info(f"No {JIRA_FIELDS_TABLE_NAME} table; nothing to do")
+        return
+
+    log.info("Drop 'components_json'")
+    op.drop_column(JIRA_FIELDS_TABLE_NAME, "components_json")

src/narrativelog/create_tables.py

@@ -8,7 +8,7 @@
 
 import sqlalchemy as sa
 import sqlalchemy.types as saty
-from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.dialects.postgresql import JSONB, UUID
 
 # Length of the site_id field.
 SITE_ID_LEN = 16
@@ -60,8 +60,14 @@ def create_message_table(metadata: sa.MetaData) -> sa.Table:
         sa.Column("date_invalidated", saty.DateTime(), nullable=True),
         sa.Column("parent_id", UUID(as_uuid=True), nullable=True),
         # Added 2022-07-19
+        # 'systems' field is deprecated and will be removed in v1.0.0.
+        # Please use 'components_json' instead
         sa.Column("systems", saty.ARRAY(sa.Text), nullable=True),
+        # 'subsystems' field is deprecated and will be removed in v1.0.0.
+        # Please use 'components_json' instead
         sa.Column("subsystems", saty.ARRAY(sa.Text), nullable=True),
+        # 'cscs' field is deprecated and will be removed in v1.0.0.
+        # Please use 'components_json' instead
         sa.Column("cscs", saty.ARRAY(sa.Text), nullable=True),
         # Added 2022-07-37
         sa.Column("date_end", saty.DateTime(), nullable=True),
@@ -110,10 +116,18 @@ def create_jira_fields_table(metadata: sa.MetaData) -> sa.Table:
         sa.Column(
             "id", UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
         ),
+        # Added 2024-12-16
+        sa.Column("components_json", JSONB, nullable=True),
+        # 'components' field is deprecated and will be removed in v1.0.0.
+        # Please use 'components_json' instead
         sa.Column("components", saty.ARRAY(sa.Text), nullable=True),
+        # 'primary_software_components' field is deprecated
+        #  and will be removed in v1.0.0. Please use 'components_json' instead
         sa.Column(
             "primary_software_components", saty.ARRAY(sa.Text), nullable=True
         ),
+        # 'primary_hardware_components' field is deprecated
+        #  and will be removed in v1.0.0. Please use 'components_json' instead
         sa.Column(
             "primary_hardware_components", saty.ARRAY(sa.Text), nullable=True
         ),

src/narrativelog/message.py

@@ -46,13 +46,21 @@ class Message(BaseModel):
     )
     # Added 2022-07-19
     systems: None | list[str] = Field(
-        title="Zero or more system names.",
+        title="Zero or more system names. "
+        "This field is deprecated and will be removed in v1.0.0. "
+        "Please use 'components_json' instead.",
+    )
+    subsystems: None | list[str] = Field(
+        title="Zero or more subsystem names. "
+        "This field is deprecated and will be removed in v1.0.0. "
+        "Please use 'components_json' instead.",
     )
-    subsystems: None | list[str] = Field(title="Zero or more subsystem names.")
     cscs: None | list[str] = Field(
         title="Zero or more CSCs names. "
         "Each entry should be in the form 'name' or 'name:index', "
-        "where 'name' is the SAL component name and 'index' is the SAL index."
+        "where 'name' is the SAL component name and 'index' is the SAL index. "
+        "This field is deprecated and will be removed in v1.0.0. "
+        "Please use 'components_json' instead.",
     )
     # Added 2022-07-27
     date_end: None | datetime.datetime = Field(
@@ -61,15 +69,21 @@ class Message(BaseModel):
     # Added 2023-08-10
     components: None | list[str] = Field(
         title="Zero or more component names. "
-        "Each entry should be a valid component name entry on the OBS jira project.",
+        "Each entry should be a valid component name entry on the OBS jira project. "
+        "This field is deprecated and will be removed in v1.0.0. "
+        "Please use 'components_json' instead.",
     )
     primary_software_components: None | list[str] = Field(
         title="Zero or more primary software component names. "
-        "Each entry should be a valid component name entry on the OBS jira project.",
+        "Each entry should be a valid component name entry on the OBS jira project. "
+        "This field is deprecated and will be removed in v1.0.0. "
+        "Please use 'components_json' instead.",
     )
     primary_hardware_components: None | list[str] = Field(
         title="Zero or more primary hardware component names. "
-        "Each entry should be a valid component name entry on the OBS jira project.",
+        "Each entry should be a valid component name entry on the OBS jira project. "
+        "This field is deprecated and will be removed in v1.0.0. "
+        "Please use 'components_json' instead.",
     )
     # Added 2023-10-24
     category: None | str = Field(
@@ -78,16 +92,35 @@ class Message(BaseModel):
     time_lost_type: None | str = Field(
         title="Type of time lost.",
     )
+    # Added 2024-12-16
+    components_json: None | dict = Field(
+        default_factory=dict,
+        title="JSON representation of systems, subsystems and components "
+        "on the OBS jira project. An example of a valid payload is: "
+        "`{\"systems\": [\"Simonyi\", \"AuxTel\"], "
+        "{\"subsystems\": [\"TMA\", \"Mount\"], "
+        "{\"components\": [\"MTMount CSC\"]}`. "
+        "For a full list of valid systems, subsystems and components "
+        "please refer to: https://rubinobs.atlassian.net/wiki/spaces/LSSTCOM"
+        "/pages/53741849/Systems+Sub-Systems+and+Components+Proposal+for+JIRA",
+    )
 
     class Config:
         orm_mode = True
         from_attributes = True
 
 
 JIRA_FIELDS = (
+    # 'components' field is deprecated and will be removed in v1.0.0.
+    # Please use 'components_json' instead
     "components",
+    # 'primary_software_components' field is deprecated
+    #  and will be removed in v1.0.0. Please use 'components_json' instead
     "primary_software_components",
+    # 'primary_hardware_components' field is deprecated
+    #  and will be removed in v1.0.0. Please use 'components_json' instead
     "primary_hardware_components",
+    "components_json",
 )
 MESSAGE_FIELDS = tuple(
     set(Message.schema()["properties"].keys()) - set(JIRA_FIELDS)

src/narrativelog/routers/add_message.py

@@ -41,37 +41,62 @@ async def add_message(
     systems: None
     | list[str] = fastapi.Body(
         default=None,
-        description="Zero or more systems to which the message applies.",
+        description="Zero or more systems to which the message applies. "
+        "**This field is deprecated and will be removed in v1.0.0**. "
+        "Please use 'components_json' instead.",
     ),
     subsystems: None
     | list[str] = fastapi.Body(
         default=None,
-        description="Zero or more subsystems to which the message applies",
+        description="Zero or more subsystems to which the message applies. "
+        "**This field is deprecated and will be removed in v1.0.0**. "
+        "Please use 'components_json' instead.",
     ),
     cscs: None
     | list[str] = fastapi.Body(
         default=None,
         description="Zero or more CSCs to which the message applies. "
         "Each entry should be in the form 'name' or 'name:index', "
-        "where 'name' is the SAL component name and 'index' is the SAL index.",
+        "where 'name' is the SAL component name and 'index' is the SAL index. "
+        "**This field is deprecated and will be removed in v1.0.0**. "
+        "Please use 'components_json' instead.",
     ),
     components: None
     | list[str] = fastapi.Body(
         default=None,
         description="Zero or more components to which the message applies. "
-        "Each entry should be a valid component name entry on the OBS jira project.",
+        "Each entry should be a valid component name entry on the OBS jira project. "
+        "**This field is deprecated and will be removed in v1.0.0**. "
+        "Please use 'components_json' instead.",
     ),
     primary_software_components: None
     | list[str] = fastapi.Body(
         default=None,
         description="Primary software components to which the message applies. "
-        "Each entry should be a valid component name entry on the OBS jira project.",
+        "Each entry should be a valid component name entry on the OBS jira project. "
+        "**This field is deprecated and will be removed in v1.0.0**. "
+        "Please use 'components_json' instead.",
     ),
     primary_hardware_components: None
     | list[str] = fastapi.Body(
         default=None,
         description="Primary hardware components to which the message applies. "
-        "Each entry should be a valid component name entry on the OBS jira project.",
+        "Each entry should be a valid component name entry on the OBS jira project. "
+        "**This field is deprecated and will be removed in v1.0.0**. "
+        "Please use 'components_json' instead.",
+    ),
+    components_json: None
+    | dict = fastapi.Body(
+        default=None,
+        description="JSON representation of systems, subsystems and components "
+        "on the OBS jira project. An example of a valid payload is: "
+        "`{\"systems\": [\"Simonyi\", \"AuxTel\"], "
+        "{\"subsystems\": [\"TMA\", \"Mount\"], "
+        "{\"components\": [\"MTMount CSC\"]}`. "
+        "For a full list of valid systems, subsystems and components "
+        "please refer to: [Systems, Sub-Systems and Components Proposal "
+        "for the OBS Jira project](https://rubinobs.atlassian.net/wiki/spaces/LSSTCOM/"
+        "pages/53741849/Systems+Sub-Systems+and+Components+Proposal+for+JIRA)",
     ),
     urls: list[str] = fastapi.Body(
         default=[],
@@ -147,8 +172,14 @@ async def add_message(
                 user_agent=user_agent,
                 is_human=is_human,
                 date_added=curr_tai.tai.datetime,
+                # 'systems' field is deprecated and will be removed in v1.0.0.
+                #  Please use 'components_json' instead
                 systems=systems,
+                # 'subsystems' field is deprecated and will be removed in v1.0.0.
+                #  Please use 'components_json' instead
                 subsystems=subsystems,
+                # 'cscs' field is deprecated and will be removed in v1.0.0.
+                #  Please use 'components_json' instead
                 cscs=cscs,
                 category=category,
                 time_lost_type=time_lost_type,
@@ -166,17 +197,33 @@ async def add_message(
         if any(
             field is not None
             for field in (
+                # 'components' field is deprecated and will be removed in v1.0.0.
+                #  Please use 'components_json' instead
                 components,
+                # 'primary_software_components' field is deprecated
+                #  and will be removed in v1.0.0. Please use 'components_json' instead
                 primary_software_components,
+                # 'primary_hardware_components' field is deprecated
+                #  and will be removed in v1.0.0. Please use 'components_json' instead
                 primary_hardware_components,
+                components_json,
             )
         ):
             result_jira_fields = await connection.execute(
                 jira_fields_table.insert()
                 .values(
+                    # 'components' field is deprecated and will be removed in v1.0.0.
+                    #  Please use 'components_json' instead
                     components=components,
+                    # 'primary_software_components' field is deprecated
+                    #  and will be removed in v1.0.0.
+                    #  Please use 'components_json' instead
                     primary_software_components=primary_software_components,
+                    # 'primary_hardware_components' field is deprecated
+                    #  and will be removed in v1.0.0.
+                    #  Please use 'components_json' instead
                     primary_hardware_components=primary_hardware_components,
+                    components_json=components_json,
                     message_id=row_message.id,
                 )
                 .returning(sa.literal_column("*"))