Software Design Document: Hardcoded Events Per Domain

This document describes the enhancement that introduces support for configuring hardcoded events per domain, replacing the previous global-only configuration, and covers deprecated parameters, database changes, ACS WS methods, and UI flow updates.

1. Description

The enhancement introduces support for configuring hardcoded events per domain, replacing the current global-only configuration. This enables service providers to tailor event reporting mechanisms per domain, including destination URLs, message protocols, retries, and timeouts.

This configuration is managed in the Management Portal under Settings → Alerts and Events → Events. If no domain-specific settings are configured, default values (super domain settings) apply.

2. Deprecated Parameters from acs_configuration.xml

2.1. Deprecated and Removed Parameters:

<enableHardcodedEvents>0</enableHardcodedEvents> <!-- removed -->
<hardcodedEventsProtocol>SOAP</hardcodedEventsProtocol> <!-- will be removed later -->

2.2. Parameters No Longer Used by Hardcoded Events (Still Used by Device Events Module):

<timeoutForSendingMonitorResult>10</timeoutForSendingMonitorResult>
<attempsForSendingMonitorResult>10</attempsForSendingMonitorResult>
<rangeForSendingMonitorResult>60</rangeForSendingMonitorResult>
<sendToFEMS>0</sendToFEMS>
<urlForSendMonitorResult>http://google.com</urlForSendMonitorResult>
<urlForSendMonitorResultAdditional>http://google.com</urlForSendMonitorResultAdditional>

3. Database Changes

3.1. New Table: event_hardcoded_settings

-- MySQL
CREATE TABLE event_hardcoded_settings (
  id INT AUTO_INCREMENT PRIMARY KEY,
  isp_id INT DEFAULT 0,
  message_protocol VARCHAR(16) DEFAULT 'SOAP',
  timeout INT DEFAULT 10,
  attempts INT DEFAULT 10,
  pause_time INT DEFAULT 60,
  url VARCHAR(256),
  url_with_ns VARCHAR(256),
  send_to TINYINT(1) DEFAULT 0
);

CREATE INDEX event_hardcoded_settings_isp_id ON event_hardcoded_settings (isp_id);

-- Oracle
CREATE TABLE EVENT_HARDCODED_SETTINGS (
  ID NUMBER(11,0) NOT NULL ENABLE,
  ISP_ID NUMBER(11,0) DEFAULT 0,
  MESSAGE_PROTOCOL VARCHAR2(16) DEFAULT 'SOAP',
  TIMEOUT NUMBER(11,0) DEFAULT 10,
  ATTEMPTS NUMBER(11,0) DEFAULT 10,
  PAUSE_TIME NUMBER(11,0) DEFAULT 60,
  URL VARCHAR2(256),
  URL_WITH_NS VARCHAR2(256),
  SEND_TO NUMBER(11,0) DEFAULT 0
);

CREATE UNIQUE INDEX PK_EVENT_HARDCODED_SETTINGS ON EVENT_HARDCODED_SETTINGS (ID);
CREATE INDEX EVENT_HARDCODED_SETTINGS_ISP_ID ON EVENT_HARDCODED_SETTINGS (ISP_ID);
ALTER TABLE EVENT_HARDCODED_SETTINGS ADD CONSTRAINT PK_EVENT_HARDCODED_SETTINGS PRIMARY KEY (ID)
  USING INDEX PK_EVENT_HARDCODED_SETTINGS ENABLE;

CREATE SEQUENCE EVENT_HARDCODED_SETTINGS_0 START WITH 1 INCREMENT BY 1;

3.2. New Table: event_hardcoded_isp

-- MySQL
create table event_hardcoded_isp
(
  id int unsigned auto_increment primary key,
  isp_id int unsigned default '0' not null,
  event_hardcoded_id int unsigned not null,
  notification tinyint(1) default 1 not null,
  constraint event_hardcoded_isp_isp_id_event_hardcoded_id_unique_idx
    unique (isp_id, event_hardcoded_id)
);

create index event_hardcoded_isp_isp_id_idx
  on event_hardcoded_isp (isp_id);

-- Oracle
create table EVENT_HARDCODED_ISP
(
  ID NUMBER(11) constraint PK_EVENT_HARDCODED_ISP primary key,
  ISP_ID NUMBER(11) default 0 not null,
  EVENT_HARDCODED_ID NUMBER(11) not null,
  NOTIFICATION NUMBER(1) default 1 not null
);

create index EVENT_HARDCODED_ISP_ISP_ID_IDX
  on FTACS.EVENT_HARDCODED_ISP (ISP_ID);

create unique index FTACS.EVENT_HARDCODED_ISP_ISP_ID_EVENT_HARDCODED_ID_UNIQUE_IDX
  on FTACS.EVENT_HARDCODED_ISP (ISP_ID, EVENT_HARDCODED_ID);

create sequence EVENT_HARDCODED_ISP_0;

3.3. Modify Existing Table: event_receiver_url

-- MySQL
ALTER TABLE event_receiver_url ADD COLUMN isp_id INT DEFAULT 0;
CREATE INDEX event_receiver_url_isp_id ON event_receiver_url (isp_id);

-- Oracle
ALTER TABLE EVENT_RECEIVER_URL ADD (ISP_ID NUMBER(11,0) DEFAULT 0);
CREATE INDEX EVENT_RECEIVER_URL_ISP_ID ON EVENT_RECEIVER_URL (ISP_ID);

3.4. Modify Existing Table: event_hardcoded

alter table EVENT_HARDCODED drop column notification;

3.5. Liquibase Changeset

<databaseChangeLog
  xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
    http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.11.xsd">

  <property name="clob.type" value="clob" dbms="oracle"/>
  <property name="clob.type" value="longtext" dbms="mysql"/>
  <property name="blob.type" value="blob" dbms="oracle"/>
  <property name="blob.type" value="mediumblob" dbms="mysql"/>
  <property name="now" value="sysdate" dbms="oracle"/>
  <property name="now" value="now()" dbms="mysql"/>
  <property name="number" value="int(11) unsigned" dbms="mysql"/>
  <property name="number" value="number(11)" dbms="oracle"/>
  <property name="big_number" value="bigint(20) unsigned" dbms="mysql"/>
  <property name="big_number" value="number(20)" dbms="oracle"/>
  <property name="tiny_number" value="tinyint(1)" dbms="mysql"/>
  <property name="tiny_number" value="number(1)" dbms="oracle"/>
  <property name="date" value="datetime" dbms="mysql"/>
  <property name="date" value="date" dbms="oracle"/>

  <changeSet id="6.4.12_35700_1" author="vadim">
    <createTable tableName="event_hardcoded_settings">
      <column name="id" type="${number}" autoIncrement="true">
        <constraints primaryKey="true" nullable="false" primaryKeyName="PK_EVENT_HARDCODED_SETTINGS"/>
      </column>
      <column name="isp_id" type="${number}" defaultValueNumeric="0"/>
      <column name="message_protocol" type="varchar(16)" defaultValue="SOAP"/>
      <column name="timeout" type="${number}" defaultValueNumeric="10"/>
      <column name="attempts" type="${number}" defaultValueNumeric="10"/>
      <column name="pause_time" type="${number}" defaultValueNumeric="60"/>
      <column name="url" type="varchar(256)"/>
      <column name="url_with_ns" type="varchar(256)"/>
      <column name="send_to" type="${tiny_number}" defaultValueNumeric="0"/>
    </createTable>
    <createIndex tableName="event_hardcoded_settings" schemaName="ftacs"
                 indexName="event_hardcoded_settings_isp_id_idx" unique="false">
      <column name="isp_id"/>
    </createIndex>
  </changeSet>

  <changeSet id="6.4.12_35700_2" author="vadim" dbms="oracle">
    <createSequence
      incrementBy="1"
      sequenceName="EVENT_HARDCODED_SETTINGS_0"
      startValue="1"
      schemaName="ftacs"/>
  </changeSet>

  <changeSet id="6.4.12_35700_3" author="vadim">
    <addColumn schemaName="ftacs" tableName="event_receiver_url">
      <column name="isp_id" type="${number}" defaultValueNumeric="0">
        <constraints nullable="false"/>
      </column>
    </addColumn>
    <createIndex tableName="event_receiver_url" schemaName="ftacs"
                 indexName="event_receiver_url_isp_id_idx" unique="false">
      <column name="isp_id"/>
    </createIndex>
  </changeSet>

  <changeSet id="6.4.12_35700_4" author="eduard">
    <createTable tableName="event_hardcoded_isp">
      <column name="id" type="${number}" autoIncrement="true">
        <constraints primaryKey="true" nullable="false" primaryKeyName="PK_EVENT_HARDCODED_ISP"/>
      </column>
      <column name="isp_id" type="${number}" defaultValueNumeric="0">
        <constraints nullable="false"/>
      </column>
      <column name="event_hardcoded_id" type="${number}">
        <constraints nullable="false"/>
      </column>
      <column name="notification" type="${tiny_number}" defaultValueNumeric="1">
        <constraints nullable="false"/>
      </column>
    </createTable>
    <createIndex tableName="event_hardcoded_isp" schemaName="ftacs"
                 indexName="event_hardcoded_isp_isp_id_idx" unique="false">
      <column name="isp_id"/>
    </createIndex>
    <createIndex tableName="event_hardcoded_isp" schemaName="ftacs"
                 indexName="event_hardcoded_isp_isp_id_event_hardcoded_id_unique_idx" unique="true">
      <column name="isp_id"/>
      <column name="event_hardcoded_id"/>
    </createIndex>
  </changeSet>

  <changeSet id="6.4.12_35700_5" author="eduard" dbms="oracle">
    <createSequence
      incrementBy="1"
      sequenceName="EVENT_HARDCODED_ISP_0"
      startValue="1"
      schemaName="ftacs"/>
  </changeSet>

  <changeSet id="6.4.12_35700_6" author="eduard">
    <sql>
      INSERT INTO event_hardcoded_isp (isp_id, event_hardcoded_id, notification)
        (SELECT 0, id, notification FROM event_hardcoded);
      ALTER TABLE event_hardcoded DROP COLUMN notification;
    </sql>
  </changeSet>

</databaseChangeLog>

4. ACS WS Changes

4.1. New API Methods:

getHardcodedEventsGeneralSettingsByDomain(ispId: Integer)
- Returns the hardcoded events configuration for a specific domain identified by ispId.
- The response includes:
  - protocol: protocol used to send events (e.g., SOAP)
  - sendToFems: delivery target (0 = Web service, 1 = FEMS, 2 = both)
  - url, urlAdditional: destination endpoints
  - timeout, attempts, range: delivery control parameters
  - ispId: identifier of the domain
saveHardcodedEventsGeneralSettings(settings: EventHardcodedSettingsWS)
- Persists the hardcoded event settings per domain.
- Accepts the same fields described above.
removeHardcodedEventsGeneralSettings(ispId: Integer)
- Removes the hardcoded events configuration for a specific domain identified by ispId.
- Unable to delete for "Super domain" (ispId=0)

4.2. Changes in Existing Methods:

createReceiverUrls and updateReceiverUrls now require the ispId field to be passed, to associate each receiver URL with the correct domain.

4.3. Modified Object:

EventReceiverUrlListWS: added the field ispId.

4.4. ACS Logic Adjustments:

On first startup, if event_hardcoded_settings is empty, populate it from the existing configuration file.
Use database values during hardcoded event processing.
These settings can be cached in the hardcoded event configuration cache.

5. UI Flows Changes

The UI must NOT use acs_configuration.xml for hardcoded event configurations.
The UI MUST use the new API methods:
- getHardcodedEventsGeneralSettingsByDomain
- saveHardcodedEventsGeneralSettings
ispId must be included in:
- changeHardcodedEvent
- createReceiverUrls
- updateReceiverUrls