The Basic Meeting List Toolbox

The BMLTAdmin App

NOTE: You cannot use the Server Administrator account with this app! This is a meeting maintenance app; not a server maintenance app! As a matter of policy, you SHOULD NOT be using the Server Admin login for regular meeting maintenance!

Screen Shot 2016-07-26 at 6.58.58 PMThe BMLTAdmin iOS (Apple iPhone or iPad) Administration Tool is an app that allows Service Body Administrators (or Meeting Editors; which may be different, if you are following the best practice outlined in this post) to access the Root Server, and perform administration tasks without the need to log in to the main Web-based control panel.

It has been designed to be absurdly easy to use. It restricts the administrator to only those meetings that they are allowed to edit. If they are allowed to edit meetings in more than one Service body, they can choose to focus on only one Service body, or edit meetings in selected Service bodies. If an administrator is allowed to edit only a single Service Body, there is no penalty. The app is designed to adapt seamlessly to the permissions granted to each Administrator.

Where To Get the App

The BMLTAdmin App is available only through the Apple App Store. It is free.

BMLTAdmin, as with all BMLT work, is completely open-source. Its source is available in this Git repository.

Using BMLTAdmin

BMLTAdmin was written to make it extremely easy and “natural” to edit your meeting list.

NOTE: Because of the ease of use of BMLTAdmin, it can be quite easy to make significant changes to your meeting list! Remember that this is an administration utility, working “live” on your database! You’re playing for keeps!

That said, one of the nice features of BMLTAdmin is the ability to easily undo changes.

Authentication and Security

First, you must have a login as a Service Body Administrator.

The Server Administrator cannot use this utility, because we don’t allow the Server Administrator to use the Semantic Administration functionality (for reasons of security).

Observers cannot use this utility, and it is worthless if you don’t have a login. If you just want to find meetings, then you are probably better off with the BMLT iOS App.

For current iOS devices, BMLTAdmin supports TouchID, which allows you to log in with a simple fingerprint, assuming that you have successfully logged into a server at least one time.

BMLTAdmin will remember Root Server URIs and login IDs. It will not remember passwords unless the device has TouchID. In that case, it stores the passwords securely in the Apple Keychain.

In order to use the app, you need:

  • A URI (Web address) for a BMLT Root Server, running Version 2.8.0 or above, and with Semantic Administration enabled. This is the URI that you usually use to log in and administer the meetings.
  • A login ID for that Root Server, as a Service Body Administrator (Can edit meetings).
  • A password for this login ID.

The app has a force-logout timeout. This can be changed in the settings, and we’ll go over that later. As long as you are using the app, it won’t disconnect. If you go into the background, it will force a disconnect after a preset timeout (the default is ten seconds).

BMLTAdmin takes security every bit as seriously as the Root Server. We also try to reduce the overhead that security imposes on you.

Initial App Startup

Upon app startup, you are presented with an empty Connect Tab:

01-EmptyURL

Fig. 1: The Initial Connection Screen

In order to log in, you need to first type in the URL of your Root Server. This is the URL that you use to log into the Web site, and edit the meetings (the one that presents the blue login screen):

02-WithValidURL

Fig. 2: Entering the URI

While you do this, the app is constantly checking the URI. If it finds the URI connects to a valid Root Server (The URI is correctly pointing to the main directory for the server, the server version is 2.8.0 or above, and semantic administration has been enabled by the Server Administrator), it immediately enables the Login ID field.

At this point, you can enter your login ID:

05-LoginForGNYR

Fig. 3: Entering the Login ID

Once you enter a login ID, the password field becomes available.

Finally, you enter your password:

06-LoginForSASNA

Fig. 4: Entering the Password

At this point, you can touch the “CONNECT” button to make your server connection.

If you have previously logged in, the app will remember your previous connection, and set the login items to that connection. If your device supports TouchID, then you will also see the TouchID icon at the bottom of the screen:

53-TouchID

Fig. 5: The Initial Connection Screen With Remembered Login and Touch ID

Touch ID Auto-Login Support

Since the app supports TouchID in later iDevices, you can very easily log in by simply touching the TouchID icon (that “thumbprint” button), and then touching the TouchID pad after the alert (shown in Figure 6) appears.

54-TouchIDNote

Fig. 6: The TouchID Connection

The App Tab Bar

The main navigation item for the app is the Tab Bar, located along the bottom of the screen:

61-DefaultTabBar

Fig. 7: The Tab Bar in Its Disconnected State

When the app is disconnected, the Tab Bar is black, and the rightmost three items are all disabled. Only “Settings” and “Connect” are enabled.

Once you connect successfully, and have selected Service bodies (more on that in a bit), the Tab Bar turns dark green, and the three rightmost items are enabled:

62-ConnectedAndEnabledTabBar

Fig. 8: The Connected Tab Bar, With All Items Enabled

In some cases, you may get a connection, with the three rightmost items disabled (We’ll cover this circumstance later):

60-DisabledItemsInToolbar

Fig. 9: The Connected Tab Bar, With The Three Rightmost Items Disabled

The Settings Tab

63-SettingsTab

Fig. 10: The Settings Tab

The Connect Tab

62-ConnectedAndEnabledTabBar

Fig. 11: The Connect Tab

The List Tab

64-ListTab

Fig. 12: The List Tab

The Deleted Tab

65-DeletedTab

Fig. 13: The Deleted Tab

The New Tab

66-NewTab

Fig. 14: The New Tab

We’ll go over each of these in detail, later. Notice that each tab has a color that goes with it, and the screen above it follows that color (roughly).

Your First Screen

Once the login is complete, you will be taken to the List Screen (If you have only one Service body, or if you have logged in before), or the Service Body Selection Screen (if this is your first login, and your ID is allowed to edit more than one Service body):

08-SingleSBList

Fig. 15: The List Screen (for IDs That Can Only Edit One Service Body)

06-FirstScreenMultiServiceBody

Fig. 16: The Service Body Selection Screen (for IDs That Can Edit Multiple Service Bodies)

You are only taken to the Service Body Selection Screen the first time that you log in. After that, you will always be taken immediately to the List Screen.

NOTE: It is possible to select zero (0) Service bodies in the Service Body Selection Screen. If you do this, the rightmost three tabs will be disabled (as if the app was disconnected). This is shown in Figure 9. If you get a green bar with disabled tabs, then you probably need to select at least one Service body to edit.

Most administrators will be single Service body admins, so they will never see the Service Body Selection Screen.

15-SingleSB-Connected

Fig. 17: The Connect Tab for Administrators That Can Only Edit One Service Body

If the administrator can edit multiple Service bodies, the Service Body Selection Screen can be accessed from the Connect Tab:

14-Multi-SB-Connected

Fig. 18: The Connect Tab for Administrators That Can Edit More Than One Service Body

The Main Tab Screens

We will now go through each of the Tab Bar screens, from left to right:

The Settings Screen

This screen allows you to specify a few app settings that take effect immediately. It is always enabled.

40-Settings

Fig. 19: The Default Settings Tab Screen

Note that each of the items in the screen has an info icon just to its left. Tapping this icon will bring up a brief alert, that describes the setting:

56-TimeoutHelpNote

Fig. 20: An Example Info Alert

The Timeout Setting

This is the app timeout. It’s an important consideration for security.

The app works by logging you into the server, then maintaining a persistent connection. As long as this connection is active, you can easily make changes to the server. However, it has the drawback that you might be in an area where your WiFi traffic could be intercepted (also, it is possible that your cellular data could get hacked). It is possible that your session could be hijacked. The longer your session is connected, the more likely it is that the session could be compromised.

Basically, it’s a good idea to make sure that you disconnect your session when not actively using the app.

The timeout setting indicates how long the app has to be in the background before the session is terminated.

This goes all the way from “IMMEDIATELY” to 30 minutes. The default is ten seconds.

This allows things like system dialogs to pop up from time to time, pushing BMLTAdmin into the background temporarily. If we have a ten-second timeout, then we can generally be back in the app again before the connection is terminated.

“IMMEDIATELY” is most secure, but it can be frustrating to have the connection terminated when you get a notification or accidentally bring up the Control Center. That’s why the default is ten seconds.

Although we give them as choices, it’s inadvisable to choose any timeout over 30 seconds.

The Require HTTPS Setting

If this switch is on (default is off), then the server connection MUST use SSL/TLS (HTTPS).

If you are currently connected to a server using non-SSL, and this setting is turned on, your session will be terminated immediately:

42-RequireHTTPSChangedDisconnect

Fig. 21: The Non-HTTPS Session Was Disconnected

The Default Duration Setting

This only affects the “New” Tab Screen. It defines the default meeting duration value for new meetings. It has no effect on existing meetings.

The Connect Screen

We have already discussed this screen. It is the initial screen presented to you when you start the app. It is always enabled.

The List Screen

This is usually the first screen that appears upon login, and is where you will spend most of your time in this app. It is where you edit existing meetings. This tab is only enabled if we have a successful login, and your login ID is allowed to (and has selected) edit at least one Service body.

Figure 15 shows a List Screen display for a single Service body chosen for edit. The following shows what it might look like for multiple Service bodies:

68-iPhoneListMultiSB

Fig. 22: A List Screen Display When Editing Multiple Service Bodies

Note that the Service body for each meeting is indicated after the town.

If a row is colored orange, it indicates a meeting that is “unpublished”.

Filtering The List

At the top of the List Screen, you see a row of checkboxes. These will filter the displayed meetings, so you only see ones that gather on selected weekdays.

Additionally, you can filter on the town the meeting gathers in. We consider “boroughs” (city subsections, like “Manhattan,” “Brooklyn,” or “Brookline”) to be “towns,” as this is generally how people that live in these communities look at them.

Response time is instantaneous. No need to reload anything.

Where Am I Now?

This is a useful capability. Just above the list of meetings, you will see a button called “Where Am I Now?”. This is a quick way to immediately go to an editor for a meeting that you are currently attending. It looks at your location and the current time. If you are within 15 minutes of the meeting start and stop time, and within 100 meters from its long/lat coordinate, the app will open the meeting directly in the Edit Screen.

Editing Meetings

When you touch one of the rows of meetings in the list of meetings, you will be taken to the Edit Screen, which is a long, vertically-scrolling screen that allows you to edit most of the standard BMLT properties. The very top has an ID that can’t be edited. This is the BMLT ID of the meeting.

15-EditMeetingTop

Fig. 23: The Top of the Editor Screen

16-EditMeetingMiddleMap

Fig. 24: The Map

18-EditMeetingFormats

Fig. 25: The Formats and Comments

The map can be displayed as either a standard map, or as a satellite view.

At the very bottom of the Edit Screen, is a red “Delete This Meeting” button. It does pretty much exactly what it says on the tin.

Notice that the background is usually a bright yellow. However, if you uncheck the “Published” checkbox at the top, the background turns orange.

17-EditMeetingMiddleSatellite

Fig. 26: The Map as A Satellite Image

19-EditMeetingDeleteButton

Fig. 27: The Delete Button (at the Bottom)

20-EditMeetingUnpublished

Fig. 28: The Orange Unpublished Background

Editing meeting information is fairly straightforward. Each item is a standard editing item (text, checkbox or scroll wheel).

Editing the Map and Address

The address items are fairly straightforward. They are Editable text items. The state should always use the “2-letter” code, such as “NY”, “MA” or “CA”.

The map can be manipulated by tapping, which will move the marker. You can also do the various pinch and zoom manipulations, and display the map as a satellite image (by tapping the switch under the map).

Set Address to My Location

Above the address items, is a button, called “Set Address to My Location”. Tapping this will cause the app to determine your location (you may be asked to give the app permission to know your location). It will then reverse geocode that information, and determine an address; which it will insert into the address items.

NOTE: Reverse geocode is a “guess,” and can result in strange addresses. It can also sometimes hit the nail squarely on the head. Your mileage may vary.
Set Map Location to Address

Below the address items, and above the map, is another button, titled “Set Map Location to Address”. Touching this button will geocode the address, and move the map marler to what it believes is the location for that address.

Geocoding tends to be a lot more accurate than reverse geocoding, but make sure that you don’t mess up the address (for example, by adding statements like “Just around the corner from Kroger’s” in the “Street Address” field).

Editing the Formats

Below the map, you will find a set of checkboxes. These represent the choices that you have for formats in the meeting. You should know what the codes mean. Checking a checkbox means that the meeting has that format. Only checked formats will be associated with the meeting.

Comments

At the bottom of the window is a “Comments” editable text field. This will allow you to enter some unstructured comments. Be concise, as these take up a lot of room in the printed lists.

Delete This Meeting

At the very bottom of the Edit Screen, is a “Delete This Meeting” button. Touching this brings up an “Are You Sure?” alert:

21-AreYouSureDelete

Fig. 29: The Confirmation Alert for Deleting A Meeting

Saving Edits, or Canceling the Session

In the black Navigation Bar at the top of the Edit Screen, are three buttons:”Cancel” (Leftmost), “Save” and “History” (Rightmost). We’ll discuss the first two here.

The “Save” Button

If you tap the “Save” button, and no changes have been made to the meeting, you will be presented with the following confirmation alert:

22-SaveChanges

Fig. 30: The Confirmation Alert for Saving an Unchanged Meeting

You can either return to the List Screen without any changes, or save the meeting as a copy.

Saving the Meeting As A Copy

If you choose “Save As A Copy”, then a new meeting will be created with exactly the same data as the meeting you are editing. It will appear as unpublished, and will be selected for editing for you. You should make whatever changes are necessary to differentiate the new meeting, then publish it and save it.

If you tap the “Save” button, and changes have been made to the meeting, you will be presented with the following confirmation alert (Say we unpublished the meeting):

Saving the Meeting With Changes

23-SaveAlteredMeeting

Fig. 31: The Confirmation Alert for Saving a Meeting That Has Been Modified

In this case, a new choice has been added: “Save Changes”. If you tap this, then the original meeting will be changed, and you will be returned to the List Screen.

If you select “Cancel”, you are simply returned to the meeting editor.

In the above case, when you get back to the List Screen, you will now see the meeting marked as “unpublished” (orange color):

69-MeetingNowUnpublished

Fig. 32: The Meeting Is Now Unpublished

The “Cancel” Button

If no changes have been made, and you tap the “Cancel” button, you are simply returned to the List Screen.

However, if you have made changes to the meeting, you will be presented with the following confirmation alert:

25-CancelConfirmation

Fig. 33: The Cancel Confirmation for a Modified Meeting

If you select “Lose Changes”, the changes are thrown away, and you are returned to the List Screen. If you select “Cancel”, you are simply returned to the meeting editor.

Now, if you were sharp, you noticed something a little different about the Edit Screen in that last figure. We’ll get to that soon.

The History Screen

The third Navigation Bar button, “History”, when tapped, will bring in another screen that will show the last 5 meeting edits (this number can be changed by the Server Administrator. 5 is the default that most people use):

26-SimpleHistory

Fig. 34: The History Screen

27-HistoryNoRollback

Fig. 35: The History Screen With First Item No Rollback

Rollback A Meeting

One of the really powerful (and dangerous) things that you can do with BMLTAdmin, is “rollback” a meeting to the state it was before a given change. Note the blue “Rollback” buttons in the History Screen. Also note that the screen shown in Figure 35 does not have a “Rollback” button on its first history item. That’s because it was the creation event, and First, All Was Darkness. You can’t roll back before creation (although many of us dearly would like to).

If you touch one of the “Rollback” buttons, you will be telling BMLTAdmin that you want to change the meeting so that its state will be exactly as it was BEFORE the history event. Touching that button will give you the following confirmation alert:

28-RollbackConfirm

Fig. 36: The Rollback Confirmation Alert

If you touch “Rollback Meeting”, the meeting will be changed, and you will be returned to the List Screen.

If you touch “Cancel”, you will simply be returned to the History Screen.

The Edit Screen for Multiple Service Bodies

If you are logged in with an ID that can edit more than one Service body, and you have selected more than one, the Edit Screen will have an additional item:

29-MultiServiceBody

Fig. 37: The Multi Service Body Selection Wheel

Notice the new “Service Body” selection wheel in Figure 36. This allows you to change the Service body affiliation of the meeting.

The Deleted Tab

This tab will load all of the deleted meetings for the chosen Service body (or bodies, if you are editing more than one).

Upon first selecting the tab, you may have to wait through a fairly lengthy loading process, which will end up displaying a list of deleted meetings, most recently deleted on top:

30-WaitForDeleted

Fig. 37: Wait for It. Wait for It…

17-DeletedMeetings

Fig. 38: The Deleted Screen

Restoring Deleted Meetings

If you tap on one of the deleted meetings in the list, you will be shown the following confirmation alert:

18-RestoreConfirm

Fig. 39: The Restore Confirm Alert

Tapping on “Restore Meeting” will save the meeting as a new, unpublished meeting, return you to the List Tab, and will expose the new meeting for you.

Newly restored meetings are always unpublished. They will also have the history from before their deletion restored.

The New Tab

This tab is a fairly straightforward one. The screen is comprised of an almost exact duplicate of the Edit Screen. However, there is no meeting ID, Published Checkbox, Delete Button or History Button. “Cancel” is also replaced by “Reset” in the Navigation Bar:

36-New

Fig. 40: The New Tab

Figure 40 shows a New Tab screen for an ID that can edit multiple Service bodies. If the ID can only edit one Service body, or if the app is set to edit only one body, then the “Service Body” scroll wheel will not be shown.

Note the “Duration” Item. This is the “Default Duration” that you selected in the Settings Tab.

If you make any changes to the meeting data in this tab, the “Reset” and “Save” buttons in the Navigation Bar will become active:

37-NewSaveActive

Fig. 41: The New Tab with Active Navigation Bar Buttons

If you tap on the “Save” button, a familiar alert will be shown:

38-New-SaveChanges

Fig. 42: The New Tab Save Confirmation Alert

If you tap “Save Changes”, the new meeting will be saved, you will be taken to the List Tab, and the new meeting will be selected. New meetings are always unpublished.

If you tap “Cancel”, then you will simply be returned to the New Tab Screen.

If you tap on the “Reset” Button, you will get an alert similar to the one shown for the “Cancel” button in the Edit Screen:

39-New-ResetConfirm

Fig. 43: The New Tab Reset Confirmation Alert

If you tap “Lose Changes”, the New Tab will be reset to default (disabling the “Save” and “Reset” buttons), and the changes you made will be discarded.

If you tap “Cancel”, then you will simply be returned to the New Tab Screen.

Technical Details

The BMLTAdmin is a native iOS application, written entirely* in the Swift Programming Language.

In order to be able to build, extend and maintain BMLTAdmin, you need to have an Apple Macintosh computer, running a late version of MacOS, and Xcode.

BMLTAdmin requires iOS Version 9.0 or above to run.

In order to distribute, deploy, or run a beta-test of BMLTAdmin with TestFlight, you need to have a paid Apple Developer account.

BMLTAdmin uses the Semantic Administration Toolbox in the Root Server. It requires that the Root Server be Version 2.8.0 or above. It will refuse to work on servers of a lower version.

In addition the Root Server being version 2.8.0 or greater, you need to ensure that you have enabled semantic administration on the Root Server.


*With the exception of one small piece. We use the FXKeychain Utility, written in Objective-C, to make it easier to provide the TouchID service.