bannerd

A. Introduction

B. Institutional Requirements

C. Project Software Requirements

D. Topics

E. Tools, References, and Terms

F. SPAN
(NASA Only)

Process Asset Templates

1.Design and Development

1.1 Definition of Process Asset Templates

Process Asset Templates are a natural evolution of guidance in SWEs and Topics. They typically start out as checklists, process step lists, document content structures, or other content and evolve into templates that can be used in project activities or as prototypes to be modified, tailored, and improved before being used in a project.

Process Asset Templates is a general category of pages. Any page that is not a SWE, topic, or the Introduction page is eligible for inclusion here.  These pages include: 

  • Checklists - preformatted checklists to be used in some activity. Can be modified to suit a project's unique needs. 
  • Process Lists - lists of things that may be done in some specified order. Can be modified to suit a project's unique needs. 
  • Principles - a previously not numbered group of pages but are being included in this effort for consistency

A PAT will be numbered so that existing code in templates and macros for references and tools can be reused. The PAT number series will be included in the first 7 characters of the page title. 

1.2 Layout of PATs  

The PATs are being developed in two spaces on the SWEHB site: SITE, and SWEHBVD

In SITE space

  • The SITE space is the location of the PAT Database. This is where the PATs are located. From This location, they will be available to all versions of the SWEHB. The container page is named “PAT Database” and it a child of the “Home” page of SITE.
  • The template for the “pat” is stored in SITE. This is used as the Live Template for creating PAT pages.

In SWEHBVD space


2. Initial Implementation

The description below explains how the first two PATs were implemented. The output of this implementation is:

  • Checklist for implementing a PAT
  • Template for a PAT report
  • Standards for Process Asset Templates in SWEHB

This describes all of the initial setup. see Maintenance for details of ongoing maintenance, adding PATs, etc.

2.1 Initial Structure 

  •  the page "PATS - Process Asset Templates - Database Reports etc" was created under SITE:Home. This is a container for the PATs
    • "PAT Checklists" was created as a child and holds the "Checklists and Guidance Lists" document from Sally
    • "PAT Database" was created as a child and holds all of the actual  PAT pages
    • "Reports for Asset Categories was created and holds all of the report pages for PATS as displayed in SWEs, Topics, and categories of PATs
  • The "7150:reference" template was copied into a new user template in SITE called "pat". The following changes were made to convert "reference" to "pat"
    • In the Show-if statement, "References Table" was changed to "PAT Database"
    • "Citation" was changed to "Origin"
    • In example, Reference was changed to PAT
    • The template was saved in SITE and is used as a live template for all PAT pages
  • PAT Database page contains the same code as the 7150:References Table with the following changes
    • Info panel in the excerpt was changed to note the PAT database
    • Show-to contains a link to PAT Database that only editors can see
    • In the Report Table, Content reporter, scope now points to SITE:PAT Database
    • Report column for Citation was changed to Origin
    • The report on the page mimics the References Table in all of the SWEHB versions
  • The "Reports for Asset Categories" page was created
    • PAT Category Codes section was added to contain all of the codes used in the "SWE or Topic" section of PATs and the reports that they appear in. 
    • "Reports by Category Code and SWE or Topic code" was added with a children macro to display all of the child pages (reports)
  • Report pages were created under "Reports for Asset Categories" for: 
    • 7.10 Process Asset Templates
    • 8.17 Process Asset Templates
    • SWE-084 Process Asset Templates
    • other category reports (one for each category code)
    • "PATs Report Body" page containing report macros that are common to all reports
    •  Typical report page is structured
      • "Excerpt" macro to contain the report that is called and displayed on a page
        • Excerpt contains the text "Click on a link to download a usable copy of the template. " to alert users that they can click on a link to get a download of the item. 
      • Panel with green boarder to denote PAT contents
      • Inside the Panel is the Report list with a Content Reporter and an include page to bring in the rest of the code from the "PATs Report Body"
      • The Content reporter has parameters set to: 
        • Spaces=+SITE
        • Types= page
        • Scope= SITE:PAT Database > children
      • Reporter contains a Text Filter with parameters
        • Key = data:SWE
        • Include= .*7.10.* 
          • The .* brackets are necessary to exclude things before and after the search string
          • the "7.10" is the search string to use when building the report 
      • Reporter contains a Text Sort with parameters
        • Content = title

2.2 First asset in SWE-084 

  • PAT-001 was created as a child of "PAT Database" and restructured several times 
    • In PAT-001, the Live Template was inserted using the template "pat" 
    • The Live template is inserted into a Panel with a title "PAT detail displays only if you have "edit" permission. "
    • The panel is embedded in a Show-if macro with Space Permissions set to edit. This means that only editors will be able to view the live template display on the page. 
    • This whole structure is positioned at the bottom of the display to be out of the way when the page is viewed normally. 
  • PAT-001 was modified to contain the "FCA Audit Checklist"
    • The checklist was attached to PAT-001 page - FCA Checklist.doc
    • The checklist was assigned a comment - "Updated 20220415" to identify the version of the checklist - the version had been part of the title and was removed before the doc was attached to the PAT
    • The checklist was opened in Word and configured to display the header, and all of the meaningful parts of the body table (omitting extra blank rows). 
    • The checklist could be contained on one Word page and a screenshot was taken of that page. 
    • The screenshot was named "FCA Checklist 20220415" to include both the title and version information. 
    • The screenshot was attached to the PAT
  • The page was edited using the "Edit Contents" function to access the contents of the live template
    • The following data was added
      • Link: https://swehb-pri.msfc.nasa.gov/download/attachments/112656614/FCA%20Checklist.docx?api=v2 - This was copied from the attachment page and is a link directly to the document attachment of the page (right click on the image and select "Copy link address)
      • Title: "PAT-001 - FCA Checklist" - This is the PAT number along with the Title of the document to make it clear what the user is viewing. 
      • SWE or Topic: SWE-084, AudCK, CM - These three attributes denote: 
        • SWE-084 - the SWE in which this PAT is displayed
        • AudCK - The Audit Checklists category of PATS in which this item should appear
        • CM - The configuration Management category of PATS in which this item should appear
      • Origin:  - SWE-084, tab 7 - denotes the original SWE (or topic page) where this asset is first introduced into the SWEHB
      • Notes: "For use on all release candidate audits." - this is used to add any other information of interest about the PAT. 
    • The page was tested to ensure that the item appeared in the appropriate report pages 
  • The PAT-001 page was edited using the "Edit" function to populate the balance of the viewable page
    • The Title was enhanced to contain the PAT number and the asset title
    • An Excerpt was created to contain the first displayable page of the attachment. this is what will be viewable in most SWE or Topic pages. It is inserted into the SWE or Topic page using an Excerpt-Include macro. 
      • Text in the Excerpt "Click on the image to preview the file. From the preview, click on Download to obtain a usable copy. " lets the user know how to use the table below. 
      • Edit the Excerpt macro:  check the "Hide Excerpted Content" box. 
      • Panel in the excerpt contains the image of the attachment
        • Panel Title - "FCA Checklist" is the title of the attachment
        • Panel Border Color is set to Green
      • Image is inserted into the Panel - With the cursor inside the Panel, click "Insert Files and images" on the menu bar
        • attached files and images from the page will be displayed. Select the image you want to appear on the page. 
        • the selected item will show a check mark, then select Insert
      • Once the image is inserted in the Panel, configure it: 
        • Set the size to "800" - this makes it large enough to read on the screen
        • Click on Boarder to turn that feature on
        • Click on the "Center" icon on the page edit menu to center the image on the page
        • Click on Link to associate the document with the image in the Panel
          • When you click on Link you will get a list of documents attached to the page. click on the appropriate one and then Insert it
      • The excerpt in the PAT is now ready to be used once the PAT itself has been saved. 
    • In the body of the page, configure the PAT so that it can be used with an "Include page" macro from a topic or SWE. This method is used for multiple page assets when all pages are necessary to display. When displaying only the first page, the "Excerpt Include" method is preferred. 
      • Copy the text information to the user "Click on the image to preview the file. From the preview, click on Download to obtain a usable copy. "
      • Copy the Panel from the Excerpt next. Paste it in below the text.
        • Strip out the duplicate text from the panel. This will save having to rebuild the panel and the first image. 
        • Note that the panel is already configured green and with the appropriate title
      • Add images of the remaining pages in the document that have been captured, saved with the title and version information, and attached to the PAT along with the first image. 
        • Each image should be configured the same as the first: 800 px, Boarder, Link to the doc file. 
        • Each image should be centered in the panel 
    • Save the page and test everything
      • look at the page in the PAT Database. It should appear in numeric order in the table with all the data properly displayed. 
      • Look at the appropriate Report page. The PAT should appear on all the reports that correlate to the codes in the SWE or Topic field of the Live Template. 
      • Pull the PAT into a test page using a Excerpt Include macro. You should get only the contents of the Excerpt box in the PAT - one page, properly linked. When you click the image you should be taken to a document preview window where you can view the entire document. You should also be able to download the document from the preview window. 
      • Pull the PAT into a test page using a Include Page macro. You should get only the body of the PAT - all pages, properly linked. When you click the each image you should be taken to a document preview window where you can view the entire document. You should also be able to download the document from the preview window. 
      • In this case, the tests were performed on SWE-084

2.3 Asset Standardization

Each PAT needs to have a simple structure that can be used by project teams. To ensure this reusability aspect, Assets will be created and saved as Word, Excel, or other editable format, not as a PDF. 

Each should have a simple minimalist structure for the user to embellish as they see fit.

See section 3.1 Configuring an Asset as a PAT below for the full details on standardization. 

2.4 Challenges and Workarounds

2.4.1 Creation of report macros for Resource tabs

The creation of new user macros requires using HTML instead of Wiki Markup. Since most of the legacy macros are in Wiki Markup, new macros cannot be created easily. They must be created in HTML.

This creates a future problem. Eventually, Wiki Markup macros will not work and everything will need to be rewritten in HTML.

Workaround: Build a report that uses a manual method for selecting content. This is working effectively for pages under Topic 7.18. It needs to be implemented for all pages under 7.18 and 8.16.

Strategy: I will investigate a method for converting Wiki Markup macros to HTML. There are some promising ways of doing this on the internet.

2.4.2 Including a PAT in pages outside of SITE space

Confluence is supposed to support attachments from pages in one space being referenced in another space. This has proven to be difficult to do as documented by Atlassian. 

Workaround:

  • Use an Include-Page macro to pull in the whole PAT page. The PAT page must include images of the attachment as a thumbnails. Each image is displayed on the page with the document linked. The drawback to this is the Live Template that is also on the page. The Live Template is being hidden in a Show-if macro. It will be necessary to test this in production so that anonymous users can see the thumbnail but not the PAT structure detail. 
  • Use an Excerpt macro to contain the linked image of the first page of an attachment.  When only one page of the attachment needs to be displayed, use the Excerpt-Include macro to pull just the excerpt. 


3. PAT Maintenance

3.1 Assets in a PAT

Every asset that becomes a Process Asset Template in SWEHB gets it's own page in the SITE space. From this location, the PAT can be: 

  • maintained under the version control afforded by Confluence, 
  • has certain standard formatting, as Word documents, Excel spreadsheets, PowerPoint presentations, etc.
  • made available to all versions of SWEHB by using the Include Page and Excerpt Include macros. 

3.2 PAT Life cycle

Each Process Asset Template goes through a life cycle where it is created, implemented in a SWEHB page, updated, and finally retired or replaced. 

  1. Create a PAT according to SWEHB standards - May be a Word doc, Excel Spreadsheet, or other type of reusable format. 
    1. Must be stored in usable format, not a PDF. 
    2. Details in Configuring an Asset as a PAT
  2. Implement PAT in SWEHB pages
    1. Create the PAT page in PAT Database


Expand the items below as needed to complete items in the PAT flow. 

Each PAT needs to have a simple structure that can be used by project teams. To ensure this reusability aspect, Assets will be created and saved as Word, Excel, or other editable format, not as a PDF. 

Each should have a simple minimalist structure for the user to embellish as they see fit. Specifically: 

Standardizing the template includes the following items:

  • No logos or other Header information in the template. If a project wants that, they can apply it themselves.
  • Header block with the following items at a minimum:
    • Dates of use (example Audit Dates)
    • Project
    • User name (example: Auditors) – people filling out or using the template in the project
    • Some indicator for the version of the template. This can be version number or version date
  • Usage instructions – minimal instructions for the user when filling out / using the template
  • Table of checklist items, steps, or other list items with some form of
    • Col 1 - numbering system for the checklist
    • Col 2 - instruction or item 
    • Col 3 - acknowledgement of use (example Yes/No)
    • Col 4 - Comment area
    • Col 5 - Initials of the user (optional)
  • Other customizations are optional such as:
    • Heading styles
    • Colorizing table areas
    • Addition of summary or comment areas
  • Naming PAT item preparing it for attachment to individual PAT pages. examples
    • PAT-001 - FCA Checklist
    • PAT-002 - PCA Checklist
  • Each attachment is affixed to the appropriate PAT page
  • PAT pages are children of the PAT Database page under SITE:Home page
  • See "Add a New Pat" for instructions on building a PAT page. 

Attachments on PAT pages must be updated as new or updated assets are created. 

When an attachment is added,

  • ensure that the asset name is spelled out fully, don't use abbreviations if possible, 
  • don't include any version coding in the asset name. Embed the versioning code in the document Properties or in a Header in the document itself. 
  • Drag and drop the asset onto the appropriate box in the "Attach Files" area
  • Use the Properties option to add a Comment to an attachment. The Comment can be used to contain the version information. 


When an asset is to be updated,

  1. Download the asset from the PAT page. 
  2. Make updates to the asset as necessary
  3. Embed a version code into the document. Either as part of the Header of the document or in the document Properties (in Word, go to  File, Info, Properties, Comments. 
  4. Save the document to your local drive. ensure that the filename has not changed. 
  5. Drag and Drop the asset onto the Attach Files section of the PAT page attachments. 
  6. Verify that the file has been updated in the PAT page. The Configuration Management features of Confluence will recognize that there is now a new version of the same document. View all the versions by clicking on the ">" to the left of the document attached to the PAT. You should see all the versions stored in the page. 


3.2 Building / Updating PAT Pages 

The easiest way to build a new PAT is to copy an existing PAT. By doing this you will avoid forgetting some seemingly minor feature and causing major problems. 

Make sure you have the following items ready for use: ;

  • Asset is ready to be attached to the new PAT - verify that it is in standardized format.  File name should not contain version coding. 
  • Screenshots of Asset have been prepared - one shot per page of the document. Image title should be the Asset Name, version code, and sequence number (if more than one shot). 

Perform the following steps: 

  1. Open the PAT Database in a new tab. 
  2. Review the existing PATs and make a note of the next unused PAT number. 
  3. Open an existing PAT in a new tab. Initiate a copy command to create a new PAT. 
    1. Space and Parent page should not be changed. 
    2. Uncheck the "Include attached files and images" box - These will be added after the new page is created. 
    3. Click Copy to complete the action. 
  4. The new page is opened in Edit mode. Cleanup the new page: 
    1. Change the title to be the new PAT number followed by the name of the asset. 
    2. Delete any "Unknown Attachment" markers created by building the copy without the old attachments. 
    3. Save the new PAT. 
    4. Verify that the new page was created by looking at the PAT Database (refresh if necessary). 
  5. Attach the Asset and Screenshots to the new PAT. Drag and drop is a quick way to do that. 
    1. For the asset, use the Properties option to add a Comment. The Comment should include the version code (number or date) of the Asset version. 
    2. Click on each of the attachments to ensure that the viewer opens and displays the file properly. 
    3. Once you are satisfied that the attachments are all ready for use, go back to View Page. 
  6. Select "Edit Contents" to open the Live Template at the bottom of the page (embedded in a Show-If macro. Add the PAT attributes: 
    1. Link - go to the attachments and right click on the asset, select "Copy link address", paste this into the Link data cell. 
    2. Title - this is the full name of the PAT - example: "PAT-999 New Asset"
      1. using the PAT number in the title ensure that the asset will not get confused with a non-PAT document. 
    3. SWE or Topic - Put in the appropriate codes for the pages on which this asset appears. Also includes codes for categories of which this asset is a member
      1. All entries are separated by a comma and a space
      2. Last entry ends with a comma and a space. 
      3. DO NOT ADD A CARRIAGE RETURN AT THE END OF THE FIELD
      4. for example: "SWE-999, Topic 9.88, AudCK, "
    4. Origin - Enter the code and location for the first use of this asset. Typically it is a SWE or Topic. 
    5. Notes - Enter any other information of interest about the asset. 
    6. Save the page and review the PAT in the PAT Database to
      1. verify that the information is visible
      2. view the "Reports for Asset Categories" and select the reports for which the asset should appear (entries in the SWE or Topic field) 
  7. Select "Edit" to configure the parts of the PAT page that will be displayed on other SWEHB pages. 
    1. In the Excerpt macro, ensure that the Hidden parameter is set to "true". This will hide the excerpt when the entire PAT is included in a SWEHB page. 
    2. Ensure that the text in the Excerpt body makes sense. Currently the text is set at "Click on the image to preview the file. From the preview, click on Download to obtain a usable copy."
    3. Check the Panel macro inside the Excerpt.
      1. title should be the title of the asset, without the PAT number. It should match the title of the document that is in the document. 
      2. Border Color should be set to green. 
    4. In the body of the Panel, insert the image corresponding to the first page of the PAT. Use the "Insert Files and Images icon in the edit menu. 
      1.  Size of the image set to "800"
      2. Border should be set to "on"
      3. Link should be set to the PAT document attached to the page. 
      4. Image should be set to Centered on the edit menu. 
    5. Testing will be done later
    6. Below the excerpt macro is the balance of the page body. This will be displayed if included into a SWEHB page
      1. Ensure that the text in the page body makes sense. Currently the text is set at "Click on the image to preview the file. From the preview, click on Download to obtain a usable copy."
      2. Below the body text is the Panel macro containing all of the images of the PAT pages. This is used in instances where it is desirable to display the whole document on the SWEHB page. This panel is formatted identically to the panel in the excerpt. 
      3. In the body of the Panel, insert the image corresponding to the first page of the PAT. Use the "Insert Files and Images icon in the edit menu. 
        1.  Size of the image set to "800"
        2. Border should be set to "on"
        3. Link should be set to the PAT document attached to the page. 
        4. Image should be set to Centered on the edit menu.
        5. Continue these steps, adding the rest of the images 
      4. Save the page 
  8. Testing the PAT before using ensures that all parts of the page are working. 
    1. Use the page: PAT Test Page
    2. Test and fix problems until the test page performs as expected.
  9. You are now ready to deploy the PAT into SWEHB pages. 


Once an update to an Asset has been stored on the PAT page (see Managing Attachments), the page must be edited to ensure that the images and links are repaired in the PAT page. 

NEW Images

A new set of images for the updated asset must be created for inclusion into the page. 

  1. Open the asset as though you are going to edit it. 
  2. Size the editor window so that a full page of the asset is visible. 
  3. Use the Snipping Tool to grab an entire page at a time. 
  4. Snip and save all pages of the document as images
  5. Name the images: Asset name, sequence number (page number), version code (number or date to match the asset versioning)
    1. Example: "FCA Checklist P1 20220415."
  6. drag and drop the new images onto the attachments area of the PAT page. 
  7. Verify that each image opens in the viewer when you click on it. 

Putting New Asset into the PAT page

Once  the attachments are all in the page (updated asset and new images) you are ready to rebuild the page. 

  1. Select Edit in the menu bar. 
  2. In the Excerpt section, click on the image and delete it - leave the Panel on the page. 
  3. In the body of the PAT, click on each of the images and delete them. Leave the Panel on the page. 
  4. Put the cursor in the Panel section of the Excerpt,
    1. select "Insert files and images" icon in the editor menu bar. 
    2. select the image corresponding to the first page of the asset. 
    3. configure the asset image
      1. Size should be 800 
      2. Click the Border option
      3. Click on Link and select the updated asset 
    4. Click on the image just added and click on the Center option  in the editor to center it on the page. 
  5. Put the cursor in the Panel section of the Body of the page, For each image (for all of the pages of the asset)
    1. select "Insert files and images" icon in the editor menu bar. 
    2. select the image corresponding to the page of the asset. 
    3. configure the asset image
      1. Size should be 800 
      2. Click the Border option
      3. Click on Link and select the updated asset 
    4. Click on the image just added and click on the Center option  in the editor to center it on the page. 
    5. Continue for all the images for the updated asset
  6.  When all images have been added to the body, save the page and verify:
    1. Clicking on each image should put you in preview mode. 
    2. Clicking download from any image should download the full document. 
  7. Select "Edit Contents" to add the PAT attributes: 
    1. Link - go to the attachments and right click on the asset, select "Copy link address", paste this into the Link data cell. 
    2. Title - this is the full name of the PAT - example: "PAT-999 New Asset"
    3. SWE or Topic - Put in the appropriate codes for the pages on which this asset appears. Also includes codes for categories of which this asset is a member
      1. All entries are separated by a comma and a space
      2. Last entry ends with a comma and a space. 
      3. DO NOT ADD A CARRIAGE RETURN AT THE END OF THE FIELD
      4. for example: "SWE-999, Topic 9.88, AudCK, 
    4. Origin - Enter the code and location for the first use of this asset. Typically it is a SWE or Topic. 
    5. Notes - Enter any other information of interest about the asset. 
    6. Save the page and review the PAT in the PAT Database to
      1. verify that the information is visible
      2. view the "Reports for Asset Categories" and select the reports for which the asset should appear (entries in the SWE or Topic field)

Once a PAT has been created and stored in the PAT database, it may be added to a SWE, Topic or other page. The steps below accomplish this. 

On a SWE or Topic Page 

In Edit mode: 

  1. Go to the location where the PAT is to be inserted. It may be an existing subheading in a tab, or a new subheading may need to be created. 
  2. If you want to pull in only a single image, use the "Excerpt Include" macro to bring in just the first page image. Otherwise, go to step 3 below. 
    1. Be sure to get the PAT from the SITE: space
    2. Check the box to "Remove Surrounding Panel"
    3. Pull in the PAT to preview it and make sure the location can be found
    4. Go to step 4. 
  3. If is is appropriate to pull in all of the pages of a document, use the instructions here: 
    1. Use the "Include Page" macro to bring in the whole of the PAT
    2. Be sure to get the PAT page name from the SITE: space
    3. Pull in the PAT to preview it and make sure the location can be found
    4. Note that the include page will pull in the Live Template information but that will be only seen by editors, not users. 
  4. Save the page to ensure that the PAT is visible and located where you want it. 
  5. Return to edit mode and insert any "SWEREFN" macros to point the user to the resources tab. This is done just like the references. 
  6. Go to tab 5 and add subheading 5.3 if necessary. 
    1. use an "Include Page" macro to pull in the appropriate PAT report page for the PATs in the SWE or Topic. 
    2. the PAT is pulled into these reports based on the codes in the Affiliated SWE section of the live template. 

Building a PAT Report Page

PAT Report pages are children of the SITE: Reports for Asset Categories page. 

  1. Find the page for the page you are adding the topic or SWE into, if a new page is needed, build a new page from a copy of an existing page. 
    1. Copy the existing page. 
    2. Change the SWE or Topic title as appropriate.
    3. In the Text Filter, change the Include parameter to the SWE-999 or Topic 9.99 designation so the report can be built properly.
    4.  Save all
    5. Test to see if the correct PATs are included in the report page. 
  2. Once the page exists, the report is built based on the include code for the SWE or Topic you are inserting it into. Check to see that the PAT appears in the report. 
  3. Once the report page is working, insert it into section 5.3 (or appropriate subheading on the Resources page. 


4. 

  • No labels

0 Comments

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
______________________________________________________________________________