Mappings Wizards

• Jan 23, 2019
• 4 minutes to read

The task of establishing mappings between fields in a data table and an appointment’s properties is tedious, and may cause obscure application errors due to typos in field names or incorrect relations. Mappings Wizards help you create mappings with less hassle and in a short amount of time.

The Scheduler provides two wizards - one to map appointment fields, and another for resources. The wizards can be invoked by clicking the scheduler control’s smart tag, as illustrated in the picture, or via the ellipsis button of the Mappings item in the SchedulerStorage property pages.

Click the Generate button. The built-in algorithm attempts to guess which field matches a particular appointment property. In most cases the resulting mappings are correct, although you are strongly advised to check the mappings to avoid mistakes. You can clear all mappings, generate them as suggested by the Wizard and modify them if needed, by selecting fields in the drop-downs.

Several fields are required for the Gantt view only. They are grayed out by default. To map these fields, select the Gantt view mappings check box. The hyperlink below the check box navigates to the How to: Create a Gantt Chart Application topic.

Note

If you map the AppointmentId field (or the AppointmentMappingInfo.AppointmentId in code), consider whether you have to change the AppointmentStorage.CommitIdToDataSource property value. It is set to true by default, and the scheduler will attempt to store an appointment id value in the database when a new appointment record is created. If record IDs are generated by the data source itself, this may lead to an error.

After you click Next, the Wizard validates mappings and displays a diagnostic message.

The second page of the Wizard allows you to create mappings for custom fields (i.e., fields that are not included in a standard appointment property set). Double-click the field name on the left to create a mapping. Default custom field name is the same as the field’s name. However if the Correct custom field name check box is set, the name is automatically modified to become a valid name of the custom field.

You can specify an arbitrary name for the custom field of an appointment. A custom mapping does not create a control to display or edit its value in the appointment form. If an editor for an appointment custom field is required, you will need to customize a form or provide your own appointment editing dialog. Review the Getting Started for more information.

The Wizard for resources looks simpler and provides less options because resources are not editable.

You can map custom properties for resources as well.

When all settings are complete, you can use the built-in capabilities of the Wizards to validate mappings. Click the Check Mappings smart tag to get either the default “Mappings are correct!” message or a more descriptive one, as illustrated below:

This diagnostic message informs you that:

1. The RecurrenceInfo property is mapped to a non-existing field. It may be due to a typo in the field’s name.
2. There are two properties (Start, End) mapped to the same data field (StartTime). This is not allowed.
3. You have defined two custom fields with the same name (AdditionalInfo).

Note that incorrect mappings may lead to errors that are difficult to diagnose, so be sure to double-check them. Review the Data Sources topic for data type requirements.

Note

It is recommended that you thoroughly check the mappings after they have been generated by Wizards. Mappings Wizards have their own logic in finding matching fields. For eXpress Persistent Objects (XPO) data sources, the Wizard often maps the XPBaseObject.This or the XPObject.Oid properties to resource or appointment identifier fields, causing the Scheduler to behave incorrectly.