RTML Mapping

This page describes how RTML requests are mapped into the scheduler database. Before continuing, be sure you are familiar with the request data hierarchy in the scheduler (see Scheduler Concepts), as well as the RTML 2.3 schema, available in the RTML Programmer's Guide, on the Introduction page (see the full diagram link).

Mapping Basics

The following basic mappings are provided by the scheduler RTML importer:

Request to Plan Mapping

This section describes the mapping from an RTML Request to a scheduler Plan. An RTML document may contain multiple Requests and thus may produce multiple scheduler Plans.

Observer for imported Plans

Each RTML Request must contain a UserName field. If it matches the name of an Observer in the scheduler database, the Plan is created for that Observer. If not, a new Observer is created with the given RTML UserName.

The RTML Importer cannot tell if the scheduler has a single-observer license. Therefore, if it finds that there is only one observer in the database, it ignores the UserName field and imports everything under that one existing Observer. This is a kludge, but the alternatives are worse. If you need to have RTML imported data automatically create users from the UserName field, just make sure there are at least two Observers in the database before importing.

Project for imported Plans

Each RTML Request is checked for a Project field. If it exists, and if there is a Project in the scheduler for the Observer (as determined above), the new Plan will be added to that Project. Otherwise a new Project whose name will be of the form yyyy-mm-dd UTC will be created and the new Plan will be added to it. Note that this action takes place for each RTML Request in the RTML document (there may be more than one).

If a new Project is created, its description will be set to "Project created from imported RTML". In addition the new Project's Contact Name, Email, Organization, and Observers will be set from the corresponding RTML Contact and Request fields, if present in the RTML.

Special feature for ACP web users: If the RTML's Contact User field ends with " [ACP xxxxx]" (note the leading space), where xxxxx is an ACP web login username (not the friendly name), the Scheduler will, by default, store images and logs resulting from observations in the ACP web-visible directories for that ACP user. See Custom Image File and Folder Naming and the information in ImageFileConfig.txt. Feel free to contact DC-3 Dreams for additional information.

Name for imported Plans

Each RTML Request is checked for an ID field. If it exists, the Request's ID field is used as the name for the Plan. If not, the Plan is named "Request n", where n is the sequence number of the Request in the RTML document.

Creating Fixed-Time Plans

To force the dispatcher to start a Plan at a specific time, include a TimeRange element in the Request and set its Earliest and Latest child elements to identical date/time values. This will cause the "fixed-time" flag to be set for the Plan. Fixed-time plans are always started before any other plans, and are thus guaranteed to run. Observations belonging to fixed-time plans may preempt those belonging to other Observations of Plans started before a fixed-time plan is added.

The Request.TimeRange has a special feature for time-critical plans submitted by the VOEvent Receiver. If both the Earliest and Latest are set to 0001-01-01T00:00:00 the plan will be started immediately.

Enabling Monitor Mode in RTML

RTML 2.3 doesn't support Monitor Mode, however you can still enable it on a Plan created from imported RTML. To enable Monitor Mode for a Plan (which results from an RTML Request), put Monitor=n into the Request's Reason attribute, where n is the monitor interval in days.

Other mappings from Request to Plan

Target to Observation Mapping

This section describes the mapping from an RTML Target to a scheduler Observation. Each RTML Request may contain multiple Targets and thus may result in a Plan with multiple Observations.

Name for imported Observations

Each RTML Target must contain a Name field. This name is used as the name for the corresponding Observation. The name may have a sequence number appended if the import results in multiple Observations for the Target (see below).

Description for imported Observations

The RTML Target is checked for a Description field. If it exists, it is used for the Description field of the Observation. If not, the Target is checked for an ID field. If that exists the Description will be set to "RTML Target ID: ID". Otherwise the Description is set to "RTML Target".

Autofocus before imaging a target

If the RTML Target specifies the autofocus attribute to be True, then the Autofocus option will be turned on for the corresponding scheduler Observation. The system will perform an autofocus before acquiring images for the target.

Coordinates for imported Observations

RTML 2.3 supports the three target coordinate types supported by scheduler. Only one type may be legally present in an RTML document:

RightAscension in RTML is in degrees not hours

In addition, all three coordinate types support equatorial position angle for rotators, and this is taken from RTML's Target.PositionAngle.

Targets with count attributes greater than 1 (repeated Targets)

If an RTML Target specifies a count attribute with a value greater than 1, it means that the Target must be repeated, and thus the scheduler must repeat the corresponding Observation. There are three ways that the RTML importer deals with this:

No interval or interval = 0

If the Target has a count attribute greater than 1 and no interval attribute or interval = 0, then count becomes the Observation's repeat count and a single observation is generated with that repeat count.

Interval greater than 0 specified

If the Target has a count attribute greater than 1 and an interval greater than 0, multiple Observations are generated, with the second and subsequent Observations' Time From Previous set to the interval and Timing Tolerance set to 15% of the interval.

Interval greater than 0 and tolerance greater than 0 specified

If the Target has a count attribute greater than 1, an interval greater than 0, and a tolerance greater than 0, multiple Observations are generated, with the second and subsequent Observations' Time From Previous set to the interval and Timing Tolerance set to tolerance.

Notes on repeat sets

The interval and tolerance values in RTML are in hours.

The interval is the time spacing from the start of the previous observation to the start of the current one. If you specify too short an interval, the scheduler will fail the Plan because the Observation will have missed its timing.

Application of Constraints

Historically, RTML specified its constraints in the Request.Schedule section. While this limits the flexibility of RTML as applied to the scheduler (which can have separate constraints for each Observation), it preserves backward compatibility with older versions of RTML. Each Target (which maps to an Observation) carries the same constraints, derived from the Request.Schedule fields. The names of the constraints in Request.Schedule are the same as the standard scheduler constraints.

Multiple Targets

If an RTML Request has multiple Target fields, additional Observations will be added to the parent Plan. The timing between these Observations and previous ones is determined by the Target attributes timefromprev and tolfromprev. If neither are specified, the first Observation generated by the second and subsequent Target will be specified with Immediately After Previous. If timefromprev is specified and is greater than 0, tolfromprev must also be specified and must also be greater than 0. In this case, the first Observation generated will be spaced in time from the start of the previous one by timefromprev, with a tolerance of tolfromprev. This is analogous to using the interval and tolerance fields for a Target with count greater than 0.

If the above seems confusing, it's suggested that you make up some RTML test documents and play with it. Eventually you'll understand. You can also ask for assistance on the DC-3 Dreams Comm Center.

Picture to ImageSet Mapping

The mapping between an RTML Picture element and a scheduler ImageSet is straightforward:

Auto Calibration

Historically, RTML specified its calibration request(s) in the Request.Correction section. While this limits the flexibility of RTML as applied to the scheduler (which can have separate calibration steps for each ImageSet), it preserves backward compatibility with older versions of RTML. The following shows the Correction fields as mapped to scheduler calibration steps in ImageSet.