Published using Google Docs
ImportAdventureLabs.gsk Usage Manual
Updated automatically every 5 minutes

ImportAdventureLabs.gsk Usage Manual

Macro Authors: C3GPS and Eravau

Macro Download Thread: https://gsak.net/board/index.php?showtopic=35358

Macro Support Thread: https://gsak.net/board/index.php?showtopic=35359&st=0

This macro was designed and written to take advantage of the Adventure Lab API by Groundspeak. The authors of this macro want to be clear that you can NOT log adventure labs using this macro. You must still go to the lab locations and answer the questions just as Groundspeak intended. This macro was written simply to make administration of Lab Caches in GSAK easier and more complete.

Source Of Adventure Labs

  1. Use Browser At Right As Source: Uses the HTML source in the browser shown to the right as the source for importing Adventure Labs into your database.

There have been cases where the browser on this window doesn’t properly route to labs.geocaching.com after logging in. If the right side of the macro window doesn’t show your list of Adventure Lab finds use this button to route to that site after logging in, if needed.

        

NOTE: If you have found one or more stages of an Adventure Lab, but not all stages, and you have the “Import Unfound Stages from Labs Partially Completed” checkbox checked (explained in the next section) then the unfound stages will also be imported into GSAK but they will not be marked as found.

  1. Adventure Lab ID: (Optional) Using this setting is used only when you know the ID of a specific Adventure Lab that you want to import. Generally, you will only know the ID if you’ve already found one stage, if a Lab owner supplies you the ID or if someone who has imported the labs into GSAK supplies it to you from the LabID custom data field.

        

If you are the Lab owner, you can find your Lab ID by browsing to the Lab Builder in a browser and opening your Adventure Lab. The ID will be the last part of the URL in your browser.

  1. Coordinates: Enter the coordinates you wish to use as a center point and the number of Miles/Kilometers/Meters you wish to be the radius and the macro will import all Adventure Labs in that circle. The maximum radius is 500 miles (804672 meters).

        

NOTE: Groundspeak has imposed a 500 lab limit so regardless of your radius, you will not get more than 500 to load at a time.

The Home button will grab your home coordinates from geocaching.com and fill them into the coordinates box.

The Current Cache button will set the coordinates to match the coordinates of the currently selected cache.

        

The Copy From Map button will display a new window with a Bing map on it. On the map, browse to the desired center point and right click in that location. A menu will appear that will show the coordinates. Click “Copy” under the coordinates and they will be copied to your clipboard. Click the “Exit and Populate Center Point” button and the window will close and the Coordinates box will be populated with the coordinates from your clipboard. Due to limited space, if you don’t see the coordinates then adjust your map to move your desired point closer to the top of the window. That will leave room to show your coordinates when you right click the map.

 The locations dropdown contains a list of locations you have stored in GSAK in Tools > Options…, Locations tab. Choosing the location will populate the text box with the decimal formatted coordinates associated with your location.

Import Settings

  1. Download Adventure Lab Description If Not Downloaded In Last: Since the descriptions for Adventure Labs and their Stages are not updated often, this allows the macro to update the find date (if applicable), country/state/county/elevation, appended Adventure Lab name formatting and other info without having to perform the slow call to Geocaching HQ for the description data again. Instead it uses the description data that it has previously saved. The soonest that you can update this description data is once a day (24 hours). But even that is much more often that is likely to be needed.
  2. Import Labs logged: Allows you to choose labs that you logged:
  1. On or Before the date chosen
  2. On or After the date chosen
  3. Only On the date chosen

NOTE: If you try to import and nothing is added, this date setting is the likely culprit.

  1. Today button: Click this to set the date in the date box to today’s date.
  2. Skip Found Stages: If this is checked then each stage to be imported will first be checked in the browser pane on the right. If found there, the stage will not be imported since only found stages are shown there. This will be unavailable if the Browser Pane option is chosen since the purpose of using that option is to import found stages.
  3. Import Unfound Stages from Labs Partially Completed: If you have not completed an entire Adventure Lab but have completed at least one stage, this option allows you to choose whether to import the unfound stages into GSAK or not.
  4. Update Found Status: Marks the Labs found upon import if there is a find date in the HTML file.
  5. Using found log text: The text that is entered into your found log in GSAK. This value is ONLY stored in GSAK and is not uploaded to your Lab logs online. It is meant to be similar to a note for your personal use.
  6. Code Prefix: Allows you to choose what prefix you want for the Code in GSAK (AKA, the GC Num). The rest of the code will be generated by the macro using the Lab ID and Stage ID’s. If you leave this blank the default value will be LC.
  7. Prepend Lab Name to Stage Name: If checked, this uses the settings in the Prefix Format section to determine the Prefix used in the waypoint name.
  1. Lab Name = Abbreviated: Puts the abbreviation in the waypoint name. For example, if the Adventure Lab is called “Cool Adventure Lab” and the stage is called “Cool Stage 1”, the Waypoint name in GSAK will be “CAL: Cool Stage 1” (Assuming : is used as the separator as explained below). This is useful for knowing which lab stages are part of the same Adventure Lab.
  2. Lab Name = Full Name: This will simply prepend the waypoint name with the full name of the Adventure Lab.
  3. Separator: This is the character, or characters, that will be used to separate the Lab Name value from the Stage Name in the waypoint name column. You CAN, and probably should, use spaces here. If no separator is indicated, a space will be used by default.
  1. Add Stage Number to Name for Linear Labs: This will add numbers to the stage name corresponding to the order in which they must be done. This only applies for Labs that must be done sequentially.

  1. Add Stage Question To: 
  1. Description: Tells the macro to add the question to each stage in the description.
  2. User Note Field: Tells the macro to add the question to each stage in the user note field.
  3. Hint: Tells the macro to add the question to each stage in the hint.
  1. Update Country, State, County and Elevation: Updates those fields appropriately if checked.
  2. Check User Flag on Imported Labs: Does just what it says. This allows you to easily filter for the labs that were imported so that you know what was either added or updated.

  1. Add Posted Coordinates of Adventure Lab as Child Waypoint: This will add a child Reference Point to each stage that contains the coordinates, Lab name, Code and comment populated with the Lab ID.

  1. Import Caches Whose GC Numbers Are In Descriptions: This will import any caches whose GC numbers are mentioned in the Lab descriptions. Although this will usually be bonus caches, we really have no way to guarantee that as a Lab owner may simply be mentioning a cache near one of the stages. The description of the imported cache will contain a link to the associated lab.

  1. Container Size: Set container size of imported Labs. NOTE: This is container size NOT CONTAINER TYPE

Save Settings

This will allow you to save settings for future use. For example, if you travel to Indianapolis frequently, you could set everything as you want and save the settings. Then, the next time you travel to Indianapolis, you would just need to choose your settings here to quickly set everything.

After the first time you run this macro, settings called “... Last active” will be saved. Those settings will always be set to the settings used the last time you pressed the Import button or the macro is exited properly.

Buttons

        

  1. Import: Begins the import.
  2. Export: Opens the Export window.
  3. Exit: Saves all of the settings you’ve chosen and then exits the macro.
  4.  Opens these instructions in a new browser window.

Export Window

Options will be added here that cannot be easily accomplished through the built in Export function in GSAK.

  1. Export Type: Currently the only option is Cachetur Bulk Load File. The Cachetur Bulk Add Waypoints function verifies that you are not trying to export more than 300 labs (the max allowed) and it adds the data to the clipboard which can then be pasted into Cachetur. Only caches with type Lab will be exported.
  2. Filter: Choose the filter to use to export. Again, any records that are not type Lab will not be exported, even if they are present in the filter.
  3. Export file: If a full path and filename are populated here, the same results that are in the clipboard will be added to this file.

End Result

The description will be filled with the name, the stage number, whether it must be played in order or not, and the coordinates which are a hyperlink that will open google maps to the location.

Further down, the description contains the coordinates, question, Lab ID, Stage ID, Geofence size in meters and the date the Adventure Lab was published.

Running Macro from External Source:

Beginning with version 1.25, the macro can now be run “silently”.

There are 4 methods you can use to run it.

  1. Requires 4 parameters with each parameter separated by ~. In order, they are:
  1. Settings Name
  2. Center Point Latitude
  3. Center Point Longitude
  4. Radius

The settings name refers to settings that you have previously saved. Your settings must have “Coordinates” chosen as the source. The center point latitude, longitude and radius values will replace the values in your previously saved settings, effectively ignoring them. In addition, currently no found data can be obtained since that requires that the form be fully loaded and the web control fully load the html of your finds in the macro form.

An example of this when called from another macro:

MACRO File="ImportAdventureLabs.gsk?Port St. Lucie~27.311803~-80.550023~50" VarScope=Local

2. Requires Settings Name as a parameter. This will use the center point and radius saved in the settings to the search.

MACRO File="ImportAdventureLabs.gsk?Port St. Lucie” VarScope=Local

3. Requires Settings Name and a found database name as parameters. All settings saved will be used and the finds will be determined by looking in the specified Found database for matching codes.

MACRO File="ImportAdventureLabs.gsk?Port St. Lucie~FoundDB" VarScope=Local

4. Requires Settings Name, Latitude, Longitude, Radius and Found Database. The latitude, longitude and radius passed will override the corresponding values in the Settings. Finds will be determined by looking in the specified Found database for matching codes.

MACRO File="ImportAdventureLabs.gsk?Port St. Lucie~27.311803~-80.550023~20~FoundDB" VarScope=Local

A variable called $advProgress will contain the final import statistics so they can be used in a message when run from an external source.

Current TODO Items:

  1. Fix Memory issue.  → Hopefully memory issue made less intrusive in 1.21
  2. Fix issue with importing labs that have been “deleted” but still show in the HTML → Fixed 1.21
  3. Fix issue with apostrophe’s in username. → Attempted fix in 1.21
  4. Fix incorrect found dates. → Fixed in 1.21
  5. Check into main labs as children problem. → Appears cachly doesn’t like hyphens in GC codes
  6. Reduce the number of trips to the API to get OwnerID.
  7. Fix Add Stage Number to Name checkbox always adding stage number. → Fixed 1.22
  8. Fix cases where some stages have given coords and some don’t.
  9. Fix unfound labs not getting imported when Import Unfound from Partially found unchecked. → Fixed 1.28

Possible Enhancements or Features

  1. Add rating information to the description → Added to version 1.21
  2. Add MacroParms for unattended execution or execution from other macros → Added to 1.25
  3. Add option to import GC’s mentioned in stage or lab descriptions. → Added to 1.26
  4. Add deeplink to allow for opening AL app from description on phones. → Added to 1.22
  5. Add option to include the question in the User Note GSAK field. → Added to 1.26
  6. Allow search for found status when run silently. → Added to 1.28
  7. Add ability to add the question to the hint field → Added to 1.28
  8. Add GC Code for “bonus” caches to the User Data field