Register Content with AWIPS Interactive Reference - OCLO

Purpose:

Tasks:

Prerequisites:

• The "Consolidated Reference Management" (CRM) utility is not enabled by default in all VLab communities. Staff of NWS field offices should be members of a CRM-enabled community by default. If the CRM is not visible in the administration menu (step 3 in instructions below), then either (1) you may need to be granted the "AIR Management" role by your VLab community's admin (for NWS field sites, the SOO/DOH/ITOs have admin rights), or (2) your community admin may need to request the utility by sending a request to vlab.admin@noaa.gov.
• This jobsheet assumes you have a pre-made reference available to register with AIR.  See the jobsheets on document upload or web content creation at https://vlab.noaa.gov/web/oclo/air-fp for help with this prerequisite, and know how to find your reference in your community before proceeding.

Registration with the Consolidated Reference Manager

1. After logging in to VLab, select your community by clicking on the circular "Select Community" icon (third from the left in VLab's Control Menu) to launch a "Select Community" pop-up window, and then click on the appropriate community name to go to that community's home page.
2. From the left-side "Admin" menu of your community's VLab page, click on "Content"  to proceed to the content administration interface.
   
3. To register a reference, click on "Consolidated Reference Management" in the left-side menu options, which is within and near the bottom of the expanded "Content" submenu.
   • Your community must have this utility enabled, and you must also have at least the "AIR Management" role granted to you by your community admin to see this. For NWS field sites, community admins who can grant this role include the SOO/DOH/ITO. If the CRM needs to be enabled, send a request to vlab.admin@noaa.gov.
     
4. To register a new reference, click on the "Add Entry" button above the table of registered items.  This brings up the form shown here with labels relevant to the subsequent steps.
   
5. Ensure that the "Enabled" checkbox is checked, so that your reference will be visible in AIR results
6. Link to your asset to this registration entry with the following steps:
   1. Click on the "Browse" button to load a GUI for choosing your asset.
   2. In the "Keywords" text field, type part of the title of your reference, and hit Submit.
   3. Cross reference the title, description, and type ("Document and Media" or "Web Content") to correctly identify your asset from the list of results. If you do not see your reference, modify your search and repeat step 2.
   4. After identifying your asset, click on the "select" button to the right to link to it
   5. You should be returned to the form for "Add/Edit Consolidated Reference Entries." Confirm that your asset title now appears to the left of the "Browse" button.
7. Under the label "Permissions Scope for Reference," click on the radio button for desired permissions for your reference, using the following guidance:
   • For public visibility (no restrictions, no login required) select "Public)"
   • For community access only (which requires being LOGGED IN before AIR will even show the reference in results) select "Community"
8. Choose the appropriate unit from the "Duration Units" drop-down menu, then type the corresponding duration in the "Duration" field above it.
   • Example: A 5-page PDF could be entered as 5 pages. By contrast a simple web content reference might be registered as 1 page.
9. In the "Source" field, type the formal institution who you represent with this reference.
   • e.g. your WFO (like "OAX", "GRB", etc.) or RFC, or a group such as OCLO, WDTD, etc.
10. [NO ACTION REQUIRED] It is not necessary to specify the Site, Location, Thumbnail, or URL options. Also note that the "Approved" checkbox is reserved for those with institutional approval privileges and does not need to be checked for your reference to be registered and visible.
    • IF USING THUMBNAIL: Ensure that your thumbnail is no larger than 100 pixels on any dimension. This is to preserve the readability of search results. Load your favorite graphics editor and create a smaller version of your image if your image is too large. VLab does not automatically resize your image for you.
11. [OPTIONAL STEP FOR DOCUMENT-TYPE REFERENCES] Certain document references, like uploaded PDFs, images, or even movies, may be viewed directly in the web browser rather than in VLab's default preview (or requiring download). This is done by specifying a redirect URL in the "URL" field of the CRM registration form. To take advantage of this optional enhancement at any time, follow the steps below.
    1. Open a new browser window, follow steps 1 and 2 in this jobsheet to load the Content Administration view for your community, then click on "Documents and Media" in the left-side menu options
    2. Find your document in the "Documents and Media" administration interface, and click on it to open it. You should then see a preview pane, and you can toggle the document info panel to display on the right by clicking the circular gray "i" button above and to the right of the preview (note, this page is the default VLab preview which AIR would link to without a redirect URL)
    3. Click on "URL" in the "Get URL" text, which is half-way down the Details pane (to the right of the document preview). This causes a text field to appear below it, which contains the document URL in VLab
       
    4. Click on the text field under "URL" to select the URL inside (this should start with "https://vlab.noaa.gov"), then hold CTRL and C on your keyboard to copy the selected URL
    5. Test your link by opening another browser window, and pasting the link into browser's address field  (click on the address field at the top of the browser and then hold CTRL and V on your keyboard to paste in the copied text), then hit ENTER to go to the URL. 
       • If you see a document preview in the browser window, then this is the preview which will be directly linked to by AIR after following the next steps below.
       • If your link does not work, prompts you to download, or you are unsatisfied with the preview, you may opt not to use this redirect URL for your document. Skip the rest of the optional URL steps and continue with your CRM registration
    6. If you are satisfied with the URL behavior above, return to the browser window with your CRM form in progress
    7. Click inside the CRM's URL text field, then hold CTRL and V on your keyboard to paste the copied URL. You have now specified a redirect URL for your document, and can proceed with the rest of the CRM registration
12. Click the "Save" button at the bottom to complete registration. If prompted, click "Fix" in the popup to approve any permissions changes.  Your reference is now registered with AIR.
13. The next steps will verify that the registered reference appears in AIR searches.  If your reference is restricted to community use, skip the browser setup in this step and resume with Step 14. If your reference is intended to be public, it is best practice to log out of VLAB OR open a private browser session (which simulates a logged-out user). This latter step is done as follows for the respective browsers:
    • In Firefox, hold down CTRL + SHIFT + P. This should open a window indicating you are "Private Browsing"
    • In Chrome, hold down CTRL + SHIFT + N. This should open up a window indicating you are "Incognito"
    • In Explorer, hold down CTRL + SHIFT + P. This should open a window indicating you are "InPrivate"
14. In your logged-out (or "private" session) browser window, go to the URL: https://vlab.noaa.gov/web/guest/awips-reference
15. Type the name of your reference in the "Keywords" field, and then click "Update" to search for it
    
16. Scan the list of results and verify that your newly added reference appears (you may need to click "Next" on the bottom to check for it on subsequent pages)
17. Click on your reference's title and verify that it displays correctly when opened.
    • If you've gotten to this step without any problems, your reference is successfully registered and correctly discoverable by AIR.  Note that in practice, most AIR references will be queried from CAVE with an auto-generated keyword set by right-clicking on the resource legend and selecting "Reference on Product". Through this method, your reference might not appear in a satisfactorily high position in the results display, which requires optimization of the reference's metadata to improve.  Additional steps are provided for that process.
18. IMPORTANT: IF you practiced this jobsheet with a test reference, you must delete your test registration to prevent garbage registrations in AIR
    • If desired, first practice the optimization steps below before deleting your test registration, but be sure to delete it afterwards
    • To delete your registration, click on the downward triangle button labeled "Actions" to the right of your registered item in the CRM admin view, and click "Delete" (this will immediately delete the AIR registration for your item)

Optimizing a Registered AIR Reference For Searches

1. Launch CAVE and load the resource related to your reference (i.e. load the product or tool which you want to trigger this reference)

   • If there isn't JUST ONE resource (for example, your reference is relevant to multiple D2D resources), then load a representative set of resources and apply these steps for each

2. Right click and hold on your loaded resource's text legend and select "Reference on Product" from the menu which pops up (as demonstrated below for the "Tracking Meteogram" tool).  This will launch an AIR query in a browser window.
   

3. On the right-side of the search results, click on "Advanced" to toggle to the advanced view of your search results.
   

4. Look for your reference in the results

   • If you don't see your results on the first page, click on the drop-down menu next to "Rows" at the bottom of the the results list, and select "Show All"

   • If you still don't see your result, then it either has a zero match (which tag optimization may help) or was improperly registered. You should try searching for the exact reference title in the keywords to make sure it can be found before proceeding with optimization.

5. Make note of the following attributes of your reference in the results ranking which you triggered from CAVE:

   • How does your reference generally rank in the results?  Critically, are there clearly irrelevant references which appear above yours? Or is your score acceptably grouped with other relevant hits.

   • What is your reference's "Relevance Score"?  This can be found to the right of your reference title under the column named "Relevance Score".  You can use this to gauge the improvement from your optimization efforts. Is the score comparable to other relevant results, or very low?

6. Make note of the exact set of keywords passed by AWIPS to the AIR search for your D2D resource. (TIP: copy the contents of the keywords field into a text editor to reference later)

   • If you have multiple resources in D2D for which this reference is relevant, perform the AIR search for a representative set of them and copy all the keywords for each into a text editor to compare later

7. In a new web browser window, navigate to your reference in the content administration view for your community. Below are refresher instructions for how to get there:

   1. After logging in to VLab, select your community by clicking on the circular "Select Community" icon (third from the left in VLab's Control Menu) to launch a "Select Community" pop-up window, and then click on the appropriate community name to go to that community's home page.
   2. From the left-side "Admin" menu of your community's VLab page, click on "Content"  to proceed to the content administration interface.
   3. If your reference is web content, click on "Web Content" in the left-hand menu. Otherwise, if it is an uploaded document, click on "Documents and Media"
   4. Navigate through your content directories by clicking on directories to view their contents, and using the "next" and "previous" buttons at the bottom until you find your reference.
8. Once found, click on the vertical ellipsis on the right of your reference title's row and then select the "Edit" option to open it for editing.
9. View the tags for your reference:
   • Uploaded Document: Tags are found below the "Categorization" header lower down in the document editor form
   • Web Content: Tags are viewable below the "Metadata" header lower down in the web content editor form
10. Strategize an improved tag set. The following recommendations are provided roughly in the order that they should be considered. Start with the topmost suggestions, proceed to the subsequent testing steps, and return to later suggestions if an improved score is needed.
    • Can you specifically describe your D2D resource(s) with ONE keyword? This keyword should be specific, not vague, and you are limited to what AWIPS provided in the keyword field. Overly vague keyword examples might include "radar," "model," "GEOS-15," "QPE" and so on if the reference is product-specific, since many different products could reference these.  If such a keyword is available, delete all other tags and test the reference retrieval with just that single tag.
    • Have you made any spelling errors? Misspellings or abbreviations of keywords will score poorly, so be sure to check your spelling if your scoring is low, although searches are NOT case-sensitive.
    • Can you specifically describe your D2D resource(s) with ADJACENT pairs of keywords?  If no single keyword is adequate, are there two (or if necessary three, or more?) keywords adjacent to each other which will accomplish this instead? These keywords must only be separated by a space. Delete other tags and make this combination into a single tag by typing the keywords, separated by spaces, exactly in the order they appear, and concluding with a comma. Test the shortest possible combination tag before deciding to include an additional word in the same tag. If you have multiple resources to match, be careful that the keyword combination appears in all of the resources or it might not work
    • Try combinations of the above, striving for the shortest and most focused tag set.  If a single functional one-word or multi-word tag is impossible to craft for your reference(s), pick an additional meaningful keyword from your AWIPS-provided keyword set and test your reference retrieval with more than one tag. DELETE tags that don't help (to minimize irrelevant hits on your reference when users search for other products), and seek the most focused tag set for your reference.  Note that AIR penalizes long tag sets which will diminish the ranking of references with excessive metadata.
11. Using the above strategies, edit your tags
    • to delete unwanted tags, click on the red "x" within a tag bubble
    • to add a tag, type the word(s)  (space-delimited words if using word combinations) and conclude the tag by typing a comma
12. Save your updated reference by clicking the "Publish" button
13. Repeat the AIR query/queries from step 1 in this optimization workflow, observe the new ranking and determine if further tag optimization is needed
    • It will NOT always be possible or appropriate to optimize tags to achieve the highest ranking search result for a given reference. AIR scoring uses a multi-faceted algorithm and contributors are part of a community which should practice courtesy in tagging their references.
    • Do NOT clutter unrelated searches by including too many tags!
14. IMPORTANT: IF you practiced this jobsheet with a test reference, you must delete your registration to prevent garbage registrations in AIR (see the last step in the registration workflow section above)
15. Jobsheet complete!