bannerd

A. Introduction

B. Institutional Requirements

C. Project Software Requirements

D. Topics

E. Tools, References, and Terms

F. SPAN
(NASA Only)
Notes on needed updates

Content updates needed on this page: 

SWEHBDOC Architecture

1. Introduction

The Architecture of the SWEHB spaces is discussed in this page. It includes the basic Confluence Platform, add-on software like plugins and macro bundles, themes, and a small amount of user (NASA) written macros that give the SWEHB its look and feel.

The architecture of the SWEHB system has been derived over the period of 2010 to today. It was originally built on a server at GSFC and later migrated to MSFC. The servers and network access are the responsibility of an organization under MSFC known as MSFC-IS61 - NCAPS (NASA Consolidated Applications and Platform Services). 

For details, see SWEHBDOC Architecture. 

The Software Engineering Handbook (SWEHB) web site was started in 2010. It was built on a Confluence Wiki platform by Jon Verville from GSFC. There were a number of plugins and macro packages used to built out the rich capability in the product. It was initially an internal to NASA site. 

It was anticipated that revisions to the NPR7150.2 would be used to update the SWEHB and that only one version, in space 7150, based on the most current NPR, would exist. In 2017 the second version of SWEHB was born. It was based on NPR7150.2B in the space SWEHBVB. In 2018 work began on a third version of the SWEHB in space SWEHBVC. The most current version is based on NPR7150.2D and is in space SWEHBVD. 

The architecture of the SWEHB sites is discussed on this page. It includes the basic Confluence Platform, add-on software like plugins and macro bundles, and a small amount of user (NASA) written macros that give the SWEHB its look and feel. 

Additional documentation including Style Guides for certain types of pages are included as pages under this page. 

2. Platform

The SWEHB uses a Wiki from Atlassian Software called Confluence. It is simple to use but made more powerful with the addition of plugins and macro software. 

The MSFC-IS61 - NCAPS organization handles the web Server, SQL Server and Confluence. They also handle all:

  • Backups of Confluence spaces
  • Restoration of Confluence spaces
  • User and group permissions for spaces

Currently, the management of the SWEHB is done by:

  • Bruce Guy – IT administrator for SWEHB
  • Fred Haigh – Content maintenance

2.1 Server

  • Confluence runs on a JAVA virtual server.
  • Operating System is Unix.
  • Application Server is Apache Tomcat. 
  • Database server is My SQL Server

Confluence stores content in a My SQL database. All content is stored in database records using a KEY to identify the space to which the content belongs. This means that multiple spaces can be stored in the same Confluence server / database. See SWEHBDOC Maintenance, tab "6. Space Pagetrees" for a current list of spaces and their keys. 

2.2 Confluence

Initially, Confluence 2.x was used to develop the SWEHB in 2010. Over the years routine updates have been made for bug fixes, security patches and product enhancements.

Originally, SWEHB was deployed in GSFC on version 2.x of Confluence. By 2017 the SWEHB had been moved from GSFC to MSFC. Over the years the platform was upgraded many times by Atlassian.

The Confluence system was upgraded to version 8.5.22 on June 17, 2025. 

2.3 Network Configuration and Access

The server is actually a virtual server managed by the MSFC IT group. It is implemented on servers within the NASA VPN. Details are beyond the scope of this documentation.

The domain alias “SWEHB.NASA.GOV” is used for access by internet users outside of the NASA VPN. Users inside the VPN may access the SWEHB through the “SWEHB.NASA.GOV” alias. From there, editors may login and make changes to the system. 

2.4 License Management

All licenses for software are managed and renewed by MSFC IT. This includes Server OS, SWL Server, Confluence, and all Plugins and Macro bundles.

3. Templates

Confluence has a feature called templates additionally, other pages may be configured and used as templates for building pages. 

3.1 Global Templates

The only Confluence global template in use is “reference”. It contains code used by the “live template” macro and scaffolding plugin to organize information about “references” in the SWEHB. This is fully described in the page “SWEHB References”

3.2 Space Templates

Only the SITE space has a space template in use. It is the “pat” template and is used with the PAT Database. See SWEHBDOC PAT - Process Asset Templates In SWEHB for full details. 

3.3 Page Templates

Almost any page in SWEHB may be used as a template for building similar templates. This is due to the design decision to make pages look and feel similar. For example, Requirements pages (SWEs) all have a similar structure with either 6 or 7 tabs. Topic pages also use tabs and most have a few tabs in common. 

Generally, when building a new page of a particular type, it is normal to make a copy of a similarly configured page. The copy is then edited and changes are made to:

  • Title - create a unique title for the page
  • Tab structure - edit the "tabsetup" macro putting in new tab titles
  • Div structures - add or delete the Div macros which contain the content
  • Add content - Put the new content into the appropriate Div content containers
  • Test and fix problems - make sure the page looks like it should


4. Plugins And Macros

Plugins and Macro Bundles give the Wiki additional capabilities beyond what comes with Confluence. The plugins and Macro Bundles currently in use in the SWEHB are listed below.

The links for the macros below may be opened in a new tab or page to show where the macro is used in the SWEHB. 

4.1 Confluence Advanced Macros

Most of these are used extensively in all versions. 

4.2 Reporting

This plugin uses data collected in the Scaffolding plugin and stored in pages. The reporting plugin allows the developer to select values, sort data, and build reports to display the selected data in a meaningful way for the viewer. 

For example, in SWEHB, the References section of SWE pages contains a report listing of references mentioned in the page, or having an obvious relationship to the page. See SWEHBDOC References in SWEHB. 

4.3 Scaffolding

This plugin allows for identifying variables and storing values for the variables in Confluence pages. Once the values are embedded in the page, they can be used by other plugins and macros to enhance the value of the content.

For example, in SWEHB, data on references is collected and stored in SWEREF pages: 

  • Link - URL for the reference
  • Title - Title of the referenced document
  • Citation - additional information about the reference such as, author, publisher, dates of publication, etc. 
  • Notes - other descriptive information of interest
  • Affiliated SWE - internal page references within the SWEHB where the reference is called out

See SWEHBDOC References in SWEHB for implementation details. This is also extensively used in PATs - see SWEHBDOC PAT - Process Asset Templates In SWEHB. 

4.4 Basic Macros

Panel is used extensively

4.5 Mosaic

 Commonly used macros. Used extensively. 

4.6 Visibility for Confluence

This plugin provides a set of simple-to-use macros to show or hide content section based on who is viewing the page. 

Key features:

  • "Show If" macro to show a content section based on parameters.
  • "Hide If" macro to hide a content section, also based on parameters.
  • Various context parameters to choose from; users, groups, labels, permissions, content types, and more

SWEHB uses only the "Show If" macro.  View the Service Rocket documentation for this plugin. 

4.7 Information Macros Plugin

Used extensively in all versions. 

4.8 Layout Macros

Used in all versions. 

4.9 Confluence Expand Macro

Used extensively in some topic and SWE pages to compress some content and make it viewable on demand. 

4.10 Confluence HTML Macros

4.11 Wiki Markup Plugin

4.12 Scroll Exporter Extensions

This is being phased out. Still in use in some reports. 

4.13 Composition

This functionality is replaced by "tabsetup" User Macro. The "float" macro is used on some pages. 

4.14 Advanced Tables for Confluence

 Used on some tables but is being phased out in favor of Confluence tables. 

4.15 Gliffy Diagrams for Confluence

Used in Activity View and other places. 

4.16 Confluence View File Macro

 Used rarely. 

4.17 Code Macro Plugin

 Not in current use

4.18 Table of Contents Plugin

 Not in current use

4.19 Page Tree Plugin

 Not in current use

4.20 Cache for Confluence

Not in current use

4.21 Linking for Confluence

Not in current use

4.22 Confluence Content Report Plugin

Not in current use

4.23 Confluence Contributors Plugin

Not in current use

4.24 Confluence Create Content Plugin

Not in current use

4.25 Confluence Live Search Macros Plugin

Not in current use

4.26 Dashboard Macros

Not in current use

4.27 Refined for Confluence

 This plugin is used for the Advanced Theme used to control the look and feel of all SWEHB pages. It is used to configure the Header area and Footer area of all pages. 

4.28 Redirection Plugin

Currently there is no license for Redirection in Confluence. 

See SWEHBDOC Redirect Tools for details on the currently deployed workaround for this macro. 

5. User Macros

User Macros are custom developed by the SWEHB maintenance staff. They are used as tools to perform certain functions on pages. See SWEHBDOC - User Macros in SWEHB for details on each User Macro in current use. 

5.1 User Macros

The usage counts below are from the admin "Macro Usage" section. 

Macros used in SWEHB spaces

  • Macros not used — This page contains User Macros that are not used in any space. 
  • HTML Macros
    • applicable-b — HTML - SWE Applicability by Software Class  Used in SWEHBVB
    • applicable-c — HTML - SWE Applicability by Software Class  Used in SWEHBVC and SWEHBVD
    • applicable-sa — HTML - SWE Applicability by Software Class  Used in SAEHB 
    • floatbox — HTML - Provide floating box for setting apart quotations from other text
    • ifnotzero — HTML - Used in other macros to detect if a parameter is not zero
    • ifzero — HTML - Used in other macros to detect if a parameter is zero
    • small — HTML - used in macros to change font size  
    • swerefn — HTML - Provides a superscript code for referring to a reference - link takes the user to Resources tab
    • tablink2 — HTML - redirect user to a specific tab in a tabsetup  
  • Macros no longer used
    • scroll-only — Not used: formerly was used in ref report code 
    • sectionheader — No longer used - was used in development 
  • Markup Macros
    • applicable — Markup - SWE Applicability by Software Class  Used in 7150 
    • pattable-topic — Markup - PAT table of assets used in topic pages - not used 
    • refstable — Markup - Builds a list of references from the references database for SWE pages
    • refstable-intro — Markup - Builds a list of references from the references database for the A. Introduction page
    • refstable-topic — Markup - Builds a list of references from the references database for Topic pages
    • tabsetup — Markup - Divide pages into a set of tabs 
    • toolstable — Markup - Builds a statement about tools in SWE page. No code, just text. Could replace with a page to include. 
    • toolstable-topic — Markup - Builds a statement about tools in Topic page. No code, just text. Could replace with a page to include. 


6. Content

The content of the SWEHB is contained in three sites on different virtual servers. 

6.1 Production 

The link for the Production Site is "https://swehb.nasa.gov/". This NDS alias takes you to the production server. It is also the entry point for internet users outside of NASA. 

For those with editor permissions, they can login to the site through Single Sign On (IT needs make the permissions changes on Confluence). Once you are logged in, you may exercise parts of the SWEHB that others cannot: 

  • Edit pages
  • Add pages, attachments, etc.
  • Delete pages

Production pages are regularly edited with content changes. This makes the changes immediately available once the page is saved. 

Changes to software (macros, plugins, templates or other software (operating system, Confluence, SWL Server, etc) are tested on other sites before being deployed on Production. 

6.2 Staging 

The link to Staging is: https://swehb-staging-pri.msfc.nasa.gov/. Staging is used primarily as a testing area for:

  • Changes to user macros
  • Changes to plugins
  • Other software before loading into Production
  • Testing large scale changes to structure of SWEHB before loading into Production  (such as relocating References from 7150 to SITE) 

For those with editor permissions, they can login to the site through Single Sign On (IT needs make the permissions changes on Confluence). Once you are logged in, you may exercise parts of the SWEHB that others cannot: 

  • Edit pages
  • Add pages, attachments, etc.
  • Delete pages

Changes to software (macros, plugins, templates or other software (operating system, Confluence, SWL Server, etc) are tested on Staging  before being deployed on Production. 

6.2.1 Macro Changes

Any changes to User Macros are made first on the Staging server. Once the changes are tested and proven, the macro code is manually copied to the Production server. Backup of macro code is the responsibility of SWEHB maintainers and MSFC IT so that a trustworthy method of reverting to Known Working Code is maintained.

6.2.2 Updating Staging

Staging pages are regularly updated with content changes from Production. This is done by taking a backup from Production and loading it into Staging. (See 6.4 Models and Simulations Site below).  

6.3 Development 

The link to Development is: "https://swehb-dev-pri.msfc.nasa.gov/"  . Dev is used primarily as a testing area for:

  • Other software before loading into Production

Development pages are updated as needed with content changes from Production. This is done by taking a backup from Production and loading it into Development. 

Changes to software (macros, plugins, templates or other software (operating system, Confluence, SWL Server, etc.) are tested on Development before being deployed on Staging and Production. 

6.4 Models and Simulations 

In 2025 a site was added to Staging to house the Models and Simulations Site. It will be available to M&S users once the content is added. When loading of Staging is done, the M&S spaces must be reloaded after the SWEHB content is restored to Staging. 

It is located in the staging server because: 

  • Access was needed for NASA only - this precludes locating it on Production since all of Production is open to the internet. 
  • Regular backups are needed to protect the content 

Two spaces were setup for use by the M&S group: 

The basic handbook was built from two M&S documents and released for further development to: 

  • Jerry Myers at GRC-LTX0 

The IT group backs these spaces up regularly and can restore them to Staging after each Production to Staging refresh of data for the SWEHB. 

6.5 Spaces And Their Use

6.5.1 Main Spaces

See SWEHBDOC Maintenance, tab 6, for details on spaces, pagetrees and structures for spaces. 


  • No labels
Page Editor: Tim Crumbley
NASA Official: Tim Crumbley
Accessibility
NASA Software Engineering Handbook - A service of the NASA Office of the Chief Engineer
NASA Privacy Statement
______________________________________________________________________________