Semantic Administration – The Basic Meeting List Toolbox

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

ABSTRACT

As of BMLT Root Server Release 2.6.1, we now have the capability to make meeting changes via a semantic interface.

In order to reduce the risk profile of this powerful new feature, it is limited to Service Body Administrators and Observers only. Server Administrators cannot use this feature (the Server Administrator account is too powerful). Also, only meetings can be changed. Service bodies cannot be changed using this interface.

The Basics

In order to use the capability, you need to enable it in your auto-config.inc.php file, and you need to understand how authentication works.

Enabling Semantic Administration

In order to enable this capability, you need two things:

Root Sever Version 2.6.1 or greater; and
An additional line, manually entered into your auto-config.inc.php file (the file created when you installed the server).

The first part is fairly basic. Get and install the correct version of the Root Server.

For the second part, you need to open your existing auto-config.inc.php file with a text editor, and add the following line:

    $g_enable_semantic_admin = TRUE;

Once these conditions are met, you can log in and make meeting changes.

Note that this functionality must be enabled on your Root Server (along with SSL/HTTPS) in order for your administrators to use the NA Meeting List Administrator app.

Session-Based Logins

Semantic Administration uses the same authentication method as the main login. It uses HTTP Sessions. Basically, you log in at the start of a session, then keep the session open while you do your work. Once you close the session, you are automatically logged out.

We use sessions, because it minimizes the exchange of authentication information between the browser and the server. It’s not perfect, but it does add a small layer of security to the process without having to employ cookies (In reality, sessions will often use a special kind of temporary cookie in the background).

Data Exchange Formats

You exchange data by sending specially-formatted URIs to the server, which will respond with XML or JSON responses. You can request information from the server, or send changes to meetings.

A nice feature of this capability is that you can query the server for information that is not readily available via the standard semantic interface, such as observer-only fields (like phone numbers and other contact info), unused formats, or changes to observer-only fields.

Base URI

The base URI will be an extension of your Root Server URI, and will be slightly different, depending upon whether you wish an XML response or a JSON response. You can “mix and match.” You can start with XML, and change to JSON during a session (or vice-versa).

The base URI is:

http://<YOUR BASE ROOT SERVER URI>/local_server/server_admin/<xml.php OR json.php>

after that, you will add an

?admin_action=<SELECTED ACTION>

to it.

NOTE: For all of the below, it is possible to get a detailed XML schema of each response from your server. This will outline exactly what you will get. The schema URI is:

http://<YOUR BASE ROOT SERVER URI>/client_interface/xsd/<SPECIFIED BY THE XML RESPONSE>

The main element of each response will have the URI to the relevant XML schema.

The JSON response is taken directly from the XML, so the response will have an identical structure.

It’s important to note that the response schema files are PHP, so they need to be executed on the Server. If you receive an XML response, it will have the URI to the executable response schema file in its namespace preamble.

Admin Parameters

The possible values for

admin_action

are:

login

This is the initial login call. It will be followed by:

c_comdef_admin_login=<LOGIN ID>: The login ID of the Observer or Service Body Administrator that is establishing the session.
c_comdef_admin_password=<PASSWORD>: The password that is associated with that account.

This call is made once, at the beginning of the session. The credentials are sent in cleartext, but they will not be necessary again, after the initial connection is made.

It doesn’t actually matter if you use the XML URI or the JSON URI for this call. The response is identical.

logout

This has no additional parameters, and will immediately end the authenticated session. It doesn’t actually matter if you use the XML URI or the JSON URI for this call. The response is identical.

get_permissions

This returns a list of the various permissions that your logged-in ID has. It has no additional parameters.

The schema response file for this is ”

<a href="https://github.com/bmlt-enabled/bmlt-root-server/blob/master/main_server/client_interface/xsd/AdminPermissions.php">AdminPermissions.php</a>

.”

get_service_body_info

This returns the information associated with a Service body. It is followed by

&sb_id=<INTEGER BMLT ID OF THE SERVICE BODY>

, with the ID being the one assigned by the Root Server (not the NAWS/World ID).

If you do not specify ”

&sb_id=

,” then all Service bodies available to the logged-in user will be returned.

You can select multiple Service bodies by making this an array parameter:

&sb_id[]=<INTEGER BMLT ID OF THE SERVICE BODY>&sb_id[]=<INTEGER BMLT ID OF THE SERVICE BODY>&sb_id[]=<INTEGER BMLT ID OF THE SERVICE BODY>

NOTE: The response is hierarchical by default. That means that, if, for example,

&sb_id=

represents an RSC, which “contains” one or more ASCs, then each ASC will be listed in its entirety within the Service body element. You can prevent this by adding ”

&flat

” to the URI. If this is added, then each “contained” Service body will be indicated by a relatively simple element.

The schema response file for this is ”

<a href="https://github.com/bmlt-enabled/bmlt-root-server/blob/master/main_server/client_interface/xsd/HierServiceBodies.php">HierServiceBodies.php</a>

.”

get_format_info

This returns information about various formats. It can be followed by ”

format_id=<INTEGER BMLT SHARED ID OF THE FORMAT>

.”

As with the Service bodies, the ”

format_id=

” parameter can be specified as an array, for various specific formats. If it is not specified at all, then information for all available formats on the Root Server will be returned. It should be noted that this will return ALL of the formats; not just the ones used in the database.

The schema response file for this is the same one that used for the standard semantic format response: ”

<a href="https://github.com/bmlt-enabled/bmlt-root-server/blob/master/main_server/client_interface/xsd/GetFormats.php">GetFormats.php</a>

.”

get_changes

This returns change records for meetings. It will only return changes for meetings for which the logged-in user can observe or administer, and will include changes to hidden fields.

The action can have the following parameters:

from_date

This is the date of the first change, and is given in the standard form “YYYY-MM-DD” (Example: “2014-07-4” for July 4, 2014).

start_date

This is the date of the first change, given as an integer, representing the POSIX Epoch Date (Example: “1404446400” for July 4, 2014).

to_date

This is the date of the last change, and is given in the standard form “YYYY-MM-DD” (Example: “2014-07-4” for July 4, 2014).

end_date

This is the date of the last change, given as an integer, representing the POSIX Epoch Date (Example: “1404446400” for July 4, 2014).

service_body_id

This is the BMLT ID of a Service body, and changes will be filtered so that only meetings that are within the Service body hierarchy are selected (for example, if the service_body_id represented an RSC, then changes for meetings within “contained” ASCs would be returned).

user_id

This is the BMLT ID of a particular user, and changes will be filtered so that only meetings that were made by a particular user are returned.

meeting_id

This is the BMLT ID of a particular meeting, and changes will be filtered so that only meetings that were made to a particular meeting are returned.

The schema response file for this is the same one used for standard semantic access (”

<a href="https://github.com/bmlt-enabled/bmlt-root-server/blob/master/main_server/client_interface/xsd/GetChanges.php">GetChanges.php</a>

“).

get_field_templates

This returns the available fields for modification. There are no additional parameters.

The schema response file for this is ”

<a href="https://github.com/bmlt-enabled/bmlt-root-server/blob/master/main_server/client_interface/xsd/FieldTemplates.php">FieldTemplates.php</a>

.”

modify_meeting

This is the way that you make changes to an existing meeting. It can be followed by the following parameters:

meeting_id

This one is required. This is an integer with the BMLT ID of the meeting to be modified.

meeting_field

This is specified for each meeting field you want to change. The format of the value is ”

“, where ”

” is one of the keys returned by the ”

get_field_templates

” call, and ”

” is the new value for that field.

This parameter can be specified as an array.

The schema response file for this is ”

<a href="https://github.com/bmlt-enabled/bmlt-root-server/blob/master/main_server/client_interface/xsd/ChangeResponse.php">ChangeResponse.php</a>

.” The response will contain the “before and after” values of any fields that were changed. It will not return fields that were not changed.

add_meeting

This adds a new meeting. You can use the same ”

meeting_field

” parameters as in the ”

modify_meeting

” call, but you do not specify a ”

meeting_id

” value.

If your user is capable of modifying meetings in multiple Service bodies, then you should also provide a ”

service_body_id

” parameter.

When a meeting is created, it is created as gathering on Sunday, at 8:30PM. If you wish this to be different, you should supply ”

meeting_field[]=weekday_tinyint,<1 - 7>&meeting_field[]=start_time,<HH:MM:SS>

The schema response file for this is ”

<a href="https://github.com/bmlt-enabled/bmlt-root-server/blob/master/main_server/client_interface/xsd/ChangeResponse.php">ChangeResponse.php</a>

.”

delete_meeting

This deletes an existing meeting. You supply a ”

meeting_id

” parameter with it (required).

The schema response file for this is ”

<a href="https://github.com/bmlt-enabled/bmlt-root-server/blob/master/main_server/client_interface/xsd/ChangeResponse.php">DeletedMeeting.php</a>

.”

INTRODUCED IN ROOT SERVER VERSION 2.8.0:

The following commands were added in the 2.8.0 version of the Root Server:

rollback_meeting_to_before_change

This call allows you to roll a meeting back to BEFORE a given change ID (Remember the “before”).

The action must have the following parameters:

meeting_id: This is the BMLT ID of a particular meeting that you want to rollback.
change_id: This is the BMLT ID of a particular change that was made to that meeting. Remember that you want to rollback to the state before this change.

restore_deleted_meeting

This call allows you to restore a deleted meeting.

The action must have the following parameter:

meeting_id: This is the BMLT ID of a particular meeting that you want to restore.

The response to both of these, is a subset of the meeting data, defined in the ”

<a href="https://github.com/bmlt-enabled/bmlt-root-server/blob/master/main_server/client_interface/xsd/RestoreDeletedMeeting.php">RestoreDeletedMeeting.php</a>

” schema file.

NOTE: You can add

lang_enum=<LANGUAGE SELECTOR>

to any of the above calls, and it will switch the server to use the specified language (if supported by the server). It will not have a noticeable effect on the

logout

directives.

INTRODUCED IN ROOT SERVER VERSION 2.12.5:

The following command was added in the 2.12.5 version of the Root Server:

get_user_info

This returns a list of various info on the current logged-in ID. It has no additional parameters.

The schema response file for this is ”

<a href="https://github.com/bmlt-enabled/bmlt-root-server/blob/master/main_server/client_interface/xsd/UserInfo.php">UserInfo.php</a>

.”

Logging In

The login call can’t be combined with any other call.

The login URI looks like this:

http://<YOUR BASE ROOT SERVER URI>/local_server/server_admin/<xml.php OR json.php>?admin_action=login?&c_comdef_admin_login=<YOUR LOGIN ID>&c_comdef_admin_password=<YOUR PASSWORD>

You will receive a very simple ”

” as the only text upon successful login, or you will receive ”

<h1>NOT AUTHORIZED</h1>

” if the login failed. We deliberately keep this simple, so that hackers won’t easily see what went wrong if they are trying brute-force attacks (in reality, it isn’t a big blocker, but every bit helps).

Once you are logged in, you can call any of the parameters above.