SSRF Document Handling & Distribution

The following definitions are used when discussing SSRF document handling:

• The word “document” follows the XML definition, ie the set of elements from <SSRF> to </SSRF> included.
• The word “package” designates an electronic package of information including the SSRF “document” and any attached files.

The challenge for the SSRF standard is to be able to adapt to a variety of scenarios and approaches to sharing information across a wide variety of systems ranging from disconnected laptops to high speed, interconnected central repositories. SSRF supports interoperability between connected and disconnected systems. The important aspect is for information to be shared in a controlled and structured manner.

Due to the variety of environments and constraints within each organization and operational area, this standard cannot and does not mandate the way in which SSRF documents are transmitted; in particular it does not mandate specific transport and security protocols. However, SSRF provides a number of core principles and processes which MUST be followed by every organization when implementing SSRF compliant capabilities to ensure interoperability.

This standard supports many different scenarios, both as an internal communication mechanism to support sharing of information between internal systems within an organization as well as interoperability with external agencies/organizations and other nations.

SSRF XML Document Distribution

The Figure above provides a summary of the different communication mechanisms that MAY be used to share information. Despite these approaches all containing their own rules, they are all similar in that a data file (in this case XML) can be moved from location A to location B.

The connectivity between national and international spectrum management systems vary greatly. The Figures in this paragraph illustrate two simple scenarios:

1. Intra-system interoperability (between two systems the same e.g.: ARCADE to ARCADE)
2. Inter-system interoperability (between two differing systems that may not have direct connectivity)

It should be noted that the standard does not currently provide guidance for direct international connectivity between differing national systems.

XML Intra-system Distribution

Interoperability with external services (or systems with no direct connectivity): This scenario typically involves asynchronous communications between a spectrum management system and one or more external organizations. A physical separation will often exist between the two systems (For example, this may be required to address security barriers or limitations in connectivity or bandwidth).

XML Distribution in Disconnected Environments

Before any communication and interaction can take place an initial handshaking process must occur. This process is detailed in Figure 6.2.4.

Initial Handshake

1. Identify Target User / System

   The first step in setting up communication for SSRF exchange is to identify the communities that are to participate in the exchange.

2. Identify Initial Point of Contact

   Points of contact need to be established to start the manual handshaking process. This is typically conducted through verbal or email dialogue.

3. Establish Communication Strategy

   The communities shall agree on the transport strategy. This could range from web services through to files on physical media.

4. Establish Communication

   Once the strategy has been agreed, it is implemented and communication established.

5. Transmit / Receive Package(s)

   Once the communication between the communities has been established, spectrum management interoperability can be conducted through the use of SSRF.

The standard is based on the assumption that the communication channel between parties ensures the data transfer integrity and security. Classification information for the data items is stored within each document, as described within the data standard (see Volume II, section 1.4).

The generic distribution process of a SSRF package is illustrated below. The SSRF data standard specifies two different types of packages:

• Asynchronous (one way with no answer expected, e.g. providing a Table Of Allocation to another party)
• Synchronous (Request / Response, e.g. request for assignment expecting a notification)

Processing Packages (XML documents)

A SSRF document is essentially a list container; it contains lists of SSRF datasets. Within a SSRF document there is no established minimum configuration: document configuration requirements are business process- specific. Additionally, each SSRF data element has a set of required attributes and elements which together establish a minimum configuration requirement for each respective element type.

SSRF is the root element for any SSRF-XML message. It contains attributes defining the namespace used. Any SSRF-XML message may contain any number of datasets. For example:

<SSRF>
  <Dataset_1/>
  < ... />
  <Dataset_N/>
</SSRF>
            

Because some datasets require other reference data to be present in the data repository (e.g. locations, equipment specifications) in order to be validated, datasets within transactions MUST be ordered to enable the receiving system to immediately resolve dependencies. This order is provided and enforced by the XML Schema (see Volume II, section 2). The order in which each type of dataset appears, as defined by the SSRF Schema, enables the receiving system to resolve dependencies by processing the document sequentially.

For example, a document including location, equipment and frequency assignment datasets will be ordered so that location and equipment specifications will be provided before the frequency assignment data. That way the receiving system can process the location and equipment information into its data repository, and further on will validate the assignment dataset against the newly imported location and equipment datasets.

Distribution of referenced data is decided at the initial handshake or specified using the external attribute of the Administrative element. Two options are available:

1. Transmit only essential information

   Where spectrum management systems are assumed to be synchronized, transactions normally omit reference datasets. For example, an assignment transaction MAY include only a LocationRef, omitting detailed location information (if the requester knows that the location has been previously defined).

2. Transmit all information

   Where spectrum management systems are assumed not to be synchronized, transactions normally include all reference datasets. For example, an assignment transaction SHOULD include the detailed location information referenced within the assignment.

SSRF documents are based on SMADEF-XML and contain core elements which must be managed and recorded in every SSRF compliant software tool. SSRF documents may also contain national elements that support a specific nation’s requirements.

Within the description of the element, information is provided if an element belongs to a specific nation. For example: “This is a National element (used by: USA).” SSRF implementations MUST support USA national elements as required by the element description, and MUST be prepared to merge USA national elements back into SMADEF-XML or OSMDD formatted datasets received from systems which support those standards when those datasets are owned by DoD.

For national elements, the rules appearing in the section "Input Requirements" (such as "this element is REQUIRED") apply only to the nation(s) implementing this element. All non-USA national elements are considered as optional in the SSRF Schema, and the implementation of national validation rules is left to the nation implementing these elements. Validation rules of a general nature are implemented as part of the standard and are shown in the "Validation rules" section (see Volume II Paragraph 1.1).

For core elements, additional national rules for a Nation XXX may be indicated in sub-paragraphs "Additional checks for XXX". Rules that refer to "USA" MUST be implemented by SSRF compliant software. Rules for other nations MAY be supported as desired within SSRF implementations.

Validation of non-USA rules is OPTIONAL.

1. A modification may not be a simple "purge and replace" operation.

   When a dataset is sent from tool A implementing some national elements to tool B which did not implement them these elements will not be recorded by tool B.

   If tool B sends a modification of this dataset to tool A, this tool A must be able to merge the incoming modified dataset with the existing dataset without losing the national elements currently stored in tool A.

2. The receiver must add their own proprietary markings.

   When a dataset is sent from tool A not implementing some elements specific to nation B expecting them, it is Nation B responsibility to populate and manage these elements.

   The other nations are NOT expected to populate these national elements. The owning (receiving) nation is responsible to ensure that the modification of records (received from non-owning nations) maintain the national elements.

The method for updating and tracking element is “solution specific” and managed and controlled by each spectrum management system. It is the responsibility of each system to conduct its own data management.

The ownership of datasets can be supported by SSRF using the first two parts of the dataset identifier (see Country and orgCode). However, the following MAY be used as guidance for ownership operational policies:

• The owner of a dataset is responsible for the dataset throughout its life cycle.
• Solution specific software systems SHOULD allow only the owner to modify their own datasets;
• If someone other than the owner needs to modify the dataset, the dataset SHOULD be sent to the owner for update action.

The locking of individual datasets is a solution specific procedure. Experience in spectrum management software as well as in other cooperative domains has demonstrated that data integrity can best be ensured when only one user has the ability to modify a specific dataset at any time. A modification of a dataset must be approved or withdrawn from the system before another modification can be created.

Modifying SSRF Records & Dataset Locking

A modification may modify any item within a dataset. However, it cannot be used to modify the dataset identifier (attribute serial), as it constitutes the unique identifier attached to each dataset from its creation until it is deleted.

Warning: The modification and deletion of datasets should be considered very carefully. Modifying or deleting datasets SHOULD be validated where they are inter-related with existing datasets. Amendments to inter-related datasets SHOULD only be permitted within a controlled process. Further details about modifying and deleting specific datasets are contained within the description of each data element.

If a dataset expires or requires deleting the “Deletion” SSRF message is used. The processes for managing the deletion of data are illustrated in Figure 6.5.2. The messages form a request for expiry/deletion. The internal management of datasets is “solution specific”.

Deleting SSRF Records

The messages form a request for expiry / deletion. It is the responsibility of each systems solution to manage its own datasets.

The Administrative message is used to request dataset(s) from other spectrum management systems. This element can be used to request specific datasets by specifying the dataset identifier required. Alternatively it can be used to query another repository for information. It is the responsibility of each spectrum management system to manage and control the release of information.

If a received document contains invalid or missing data then the Administrative message SHOULD be used to request that the document is re-sent with the necessary amendments.

SSRF Data Request

This section contains indications which MAY be taken into consideration when implementing a client/server system.

Users of a centralized system may have one or more roles usually depending upon assigned responsibilities.

A Role (or Job Account) is assigned to an office or position so the account does not change as staff within an office or organization change. The Role identifies the account which has edit authority / control of the proposed action. One or more roles can be assigned to a spectrum manager who has more than one distinctly different areas of responsibility (e.g., a tactical and a sustaining-base function) and who may use the same computer to perform both jobs.

The Role is similar to an e-mail address because it is used like an address for workflow routing dataset of proposals.

A new Role, if created on a client computer, is uploaded to the server where it is validated before being made available to other clients on the network. Once a Role has been established, the operator can use it to route a dataset within the system.

Status tracking codes are assigned to datasets as they move through the approval cycle. As a proposal is passed from one user to another, the receiving user’s Role is added to the proposal. When a Role is added to a proposal / action it has an associated status entry and may have related status comments when applicable.

Once a Role has been sent a copy of a dataset (for action or information), that Role will continue to get all updates to that dataset (as long as that Role remains active) or until the dataset is finally approved. Before creating a new Role, the existing list of accounts should be checked to prevent duplicates.

The Area of Interest (AOI) defines the datasets that are to be transferred from a superior level to a subordinate level (or vice-versa). They consist of the data in use by the subordinate level (and its own subordinate levels), and also the "background" data which may not belong to this Force Element or Command but which are used in the same or adjacent area and must therefore be considered.

The definition of the AOI results (from a data request response or query response) may be used in two ways depending on the implementation of the hierarchical dialog:

• The AOI may be used by the subordinate level to "pull" all relevant datasets from its superior level (most efficient in a client-server architecture over a network)
• The AOI may be used by the superior level to "push" all relevant datasets to each of its subordinates (solution to be used when the different levels are not permanently connected).

From a user perspective, the mechanisms used for attaching files to a SSRF document to form a package should remain largely transparent, similar to e-mail attachments.

The storage and management of the receipt of attachments is “solution specific” to be managed by the implementation, this could include:

• storage as Binary Large Objects (BLOB’s) within a data repository or
• files stored within a set of folders.

The transport protocol will dictate how the package should be distributed.

The Package File is intended for use in disconnected environments or between dissimilar systems. It supports the transfer of multiple datasets of various types along with their associated attachments in a single file. The package file is a ZIP archive that contains a single XML file containing all the datasets, and binary files as needed, containing the attachments associated with the datasets in the XML file.

It is RECOMMENDED that sending implementations limit the package file contents to no more than 65534 (64k - 2) attachments and limit the total compressed file size to no larger than 2 GB. When using E-Mail exchanges, it is RECOMMENDED to limit the total compressed file size to no larger than 2 MB to avoid E-Mail server limitations. In any case, it is RECOMMENDED to check the local (operational) limitations before starting the exchanges.

The sending implementation MAY create multiple package files, each within the recommended constraints in order to transfer all the desired datasets. Adhering to these constraints will increase the probability that the package file can be processed by the receiving implementation.

The datasets in a package MUST be stored in an XML file named "datasets.xml" at the root level of the archive. The order of the datasets within the XML file is significant. The attachments are described in ExtReference datasets, and will also be stored at the root level of the archive.

The file name of each attachment SHOULD be derived from the ExtReference.serial data with colons":" replaced by dashes"-", and its normal extension as given by the originating software package. As the serial numbers are unique, using the naming convention will create unique file names in the package with no risk of collision.

Following is an example of an XML document with datasets that have associated attachments to illustrate the relationship between ExtReference and file names.

ExternalReference contains bibliographic or any other references applicable to the dataset except those placed in Derivative Classification Authority (Data element ClsDerived).

Example:

<ExternalReference cls="U">
  <Serial cls="U">USA:AF:EX:123</Serial>
  <Type cls="U">Document</Type>
  <Title cls="U">plan 5027</Title>
  <Organisation cls="U">PACOM</Organisation>
  <Date cls="U">2000-04-27</Date>
  <ResourceLocator cls="U">USA-AF-EX-123.PDF</ResourceLocator>
</ExternalReference>

Notes:

• When an ExternalReference is exported from the data repository the attachment file MAY automatically be exported with the dataset.
• When attaching a file, user SHOULD follow current national / NATO information security policies.

Shown below is a view of the contents of the package file created using the datasets in the example XML document.

Example of a ZIP-compressed SSRF Package

There are two categories of SSRF document validation:

• Document Format

  Validates that the SSRF document is well formed XML and passes all standard XML schema validation checks using the SSRF XML Schema Definition (XSD) document.

• Document Semantics

  Validates that the SSRF data elements contain all required fields and configurable parameters and that all field values contain valid enumerated types, where specified within the SSRF XML Schema Definition (XSD) document.

A SSRF document is considered invalid, and an error message SHOULD be returned, if:

• The document is not “well-formed” (i.e. does not have a correct XML structure);
• The document does not validate against the standard via the SSRF Schema.

If an invalid document is received the sender SHOULD be informed that the document could not be processed and requesting that the data is re-issued. This is accomplished using the Administrative message with reason="INVMSG".

Invalid SSRF Document Handling Process

SSRF transactions MAY omit reference datasets and send only the dependent dataset that is of interest. For example, an Assignment document MAY include only a LocationRef, omitting detailed location information.

If referenced data is not included in the SSRF document the receiving system SHOULD check if this data exists locally and SHOULD generate an error if the data does not exist locally.

If the data does not exist locally then the receiving system MAY automatically create a transaction using the Administrative dataset to request the required reference data from the sender.

When a sending system does not have all the reference data associated with a dataset it SHOULD indicate or allow the user to discover that it lacks some reference data before sending the dataset to the receiving system. In general systems that send SSRF data SHOULD be able to provide the data required to resolve dependencies in outgoing transactions. Note that there may be security or other policy or procedural considerations involved in transferring reference data associated with dependent datasets.

SSRF is the root element for any SSRF-XML message. It contains attributes defining the namespace used. Any SSRF-XML message may contain any number of datasets.

SSRF Data Object

See the OpenSSRF Javadoc for more details.

A de minimis example:

<SSRF xmlns:ssrf="urn:us:gov:dod:standard:ssrf:3.1.0" 
      xmlns:xs="http://www.w3.org/2001/XMLSchema" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Datasets_here/>
</SSRF>

The sequence diagram shown below demonstrates a sample set of interactions between two spectrum management systems sharing assignment information.

Example SSRF Data Exchange of Assignment Information

A complete SSRF Assignment example describing the CKCO-TV Canadian (civilian) broadcast television service.

<?xml version="1.0" encoding="UTF-8"?>
<SSRF xmlns:ssrf="urn:us:gov:dod:standard:ssrf:3.1.0" 
      xmlns:xs="http://www.w3.org/2001/XMLSchema" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <Transmitter cls="U">
      <Serial cls="U">CAN:IC:TX:0d6ad4883d8840</Serial>
      <EntryDateTime cls="U">1986-01-23T05:00:00Z</EntryDateTime>
      <Generic cls="U">Yes</Generic>
      <OutputDeviceType cls="U">Klystron</OutputDeviceType>
      <TxMode>
         <ModeID cls="U">TV</ModeID>
         <Description cls="U">Broadcast Television</Description>
         <Power>
            <PowerMin cls="U">59.27370363039024</PowerMin>
            <PowerType cls="U">Carrier</PowerType>
            <Calculated cls="U">No</Calculated>
         </Power>
      </TxMode>
   </Transmitter>
   <Antenna cls="U">
      <Serial cls="U">CAN:IC:AN:e0e5e6a303b042</Serial>
      <EntryDateTime cls="U">1986-01-23T05:00:00Z</EntryDateTime>
      <Generic cls="U">No</Generic>
      <AntType cls="U">Other</AntType>
      <Nomenclature>
         <Type cls="U">Civilian/Commercial</Type>
         <Name cls="U">MFR not declared</Name>
      </Nomenclature>
      <AntMode>
         <ModeID cls="U">2005-PRECISE</ModeID>
         <ModeUse cls="U">Transmit Only</ModeUse>
         <MotionType cls="U">Directional</MotionType>
         <SectBlanking cls="U">No</SectBlanking>
         <PolarisationType cls="U">Horizontal linear</PolarisationType>
         <BeamType cls="U">Shaped Beam</BeamType>
         <AntPattern>
            <Type cls="U">HH</Type>
            <Calculated cls="U">No</Calculated>
            <AntPatternPoint>
               <Dir cls="U">359.0</Dir>
               <Gain cls="U">-5.1032</Gain>
            </AntPatternPoint>
            <AntPatternPoint>
               <Dir cls="U">357.0</Dir>
               <Gain cls="U">-4.721</Gain>
            </AntPatternPoint>
            <AntPatternPoint>
               <Dir cls="U">350.0</Dir>
               <Gain cls="U">-1.6205</Gain>
            </AntPatternPoint>
            <AntPatternPoint>
               <Dir cls="U">346.0</Dir>
               <Gain cls="U">-0.5634</Gain>
            </AntPatternPoint>

            <AntPatternPoint ... />

            <AntPatternPoint>
               <Dir cls="U">16.0</Dir>
               <Gain cls="U">-0.0847</Gain>
            </AntPatternPoint>
            <AntPatternPoint>
               <Dir cls="U">15.0</Dir>
               <Gain cls="U">-0.0619</Gain>
            </AntPatternPoint>
            <AntPatternPoint>
               <Dir cls="U">11.0</Dir>
               <Gain cls="U">-0.6033</Gain>
            </AntPatternPoint>
            <AntPatternPoint>
               <Dir cls="U">9.0</Dir>
               <Gain cls="U">-1.2376</Gain>
            </AntPatternPoint>
            <AntPatternPoint>
               <Dir cls="U">7.0</Dir>
               <Gain cls="U">-2.5382</Gain>
            </AntPatternPoint>
            <AntPatternPoint>
               <Dir cls="U">2.0</Dir>
               <Gain cls="U">-4.555</Gain>
            </AntPatternPoint>
         </AntPattern>
      </AntMode>
   </Antenna>
   <Assignment cls="U">
      <Serial cls="U">CAN:IC:AS:2ccba89c0dab41</Serial>
      <EntryDateTime cls="U">1986-01-23T05:00:00Z</EntryDateTime>
      <LastChangeDateTime cls="U">2012-03-21T04:00:00Z</LastChangeDateTime>
      <CaseNum>
         <Country cls="U">Canada</Country>
         <Type cls="U">callsign</Type>
         <Identifier cls="U">CKCO-TV-3</Identifier>
      </CaseNum>
      <UsageType cls="U">Approved Permanent</UsageType>
      <EffectiveDateTime cls="U">1986-01-23T05:00:00Z</EffectiveDateTime>
      <AssignmentAuthority cls="U">User-assigned</AssignmentAuthority>
      <DataSource cls="U">Industry Canada</DataSource>
      <FCCFileNum cls="U">3897</FCCFileNum>
      <OriginalAssignmentDate cls="U">1986-01-23T05:00:00Z</OriginalAssignmentDate>
      <SupplementaryDetails cls="U">CTV</SupplementaryDetails>
      <TypeOfService cls="U">Broadcast</TypeOfService>
      <Configuration>
         <ConfigID cls="U">OP:CKCO-TV-3</ConfigID>
         <Description cls="U">Class C</Description>
         <Usage>
            <EqpFnct cls="U">Broadcast Radio/Television</EqpFnct>
            <StnClass cls="U">BT</StnClass>
            <RadioService cls="U">Broadcasting Service</RadioService>
         </Usage>
         <ConfigFreq idx="1">
            <FreqMin cls="U">0.638</FreqMin>
            <InBand cls="U">Yes</InBand>
            <Priority cls="U">Primary</Priority>
         </ConfigFreq>
         <TxRef>
            <Serial cls="U" xsi:type="TSerial">CAN:IC:TX:0d6ad4883d8840</Serial>
            <TxModeRef>
               <ModeID cls="U">TV</ModeID>
            </TxModeRef>
            <TxAntModeRef>
               <Serial cls="U" xsi:type="TSerial">CAN:IC:AN:e0e5e6a303b042</Serial>
               <ModeID cls="U">2005-PRECISE</ModeID>
            </TxAntModeRef>
         </TxRef>
      </Configuration>
      <Station>
         <StationID cls="U">OP: Operational</StationID>
         <CallSign cls="U">CKCO-TV-3</CallSign>
         <AntStructureHeight cls="U">497</AntStructureHeight>
         <POCInformation>
            <Type cls="U">User</Type>
         </POCInformation>
         <StationLoc/>
      </Station>
      <Link>
         <LinkID cls="U">CKCO-TV-3</LinkID>
         <IntermediateFunction cls="U">BROADCAST</IntermediateFunction>
         <MajorFunction cls="U">BROADCAST</MajorFunction>
         <StationConfig>
            <Type cls="U">Transmit Only</Type>
            <ConfigID cls="U">OP: Operational</ConfigID>
            <StationID cls="U">CKCO-TV-3</StationID>
            <EIRPMin cls="U">59.27370363039024</EIRPMin>
            <AntFeedpointHeight cls="U">497</AntFeedpointHeight>
         </StationConfig>
      </Link>
   </Assignment>
</SSRF>

See the OpenSSRF Javadoc for more details.