Login    Sites MenuBlueStep

BlueStep Platform Support

Relate Components
Outline full outline 
General Concepts/Getting Started 
Relate Within the BlueStep Platform 
Relate Data Organization 
Configuration Elements 
External Relate Connections 
Permissions and Relate 
The Relate Inspector 
Relate Structure 
Folders 
Forms 
Fields 
Text Fields 
Memo Fields 
Date/Time Fields 
Number Fields 
Boolean Fields 
Single-Select Fields 
Multi-Select Fields 
Signature Fields 
Document Fields 
Relationship Fields 
Spacer Fields 
Section Header Fields 
Merge Report Fields 
Biometric Field 
Option Lists and Groups 
Multi-Entry Reports 
Merge Reports* 
Formulas* 
End Points 
Wizards* 
Permission Report 
Other Elements and Functions* 
Using Relate Outside Relate* 
Relate Mini-World Pages* 
Query and Report Pages* 
Wizard Pages* 
Group Entry Pages* 
Composite Pages and Pagelets* 
Site Sign-Up and Invite* 
Team Roster* 
Dynamic Security Groups* 
User Accounts* 
Design Patterns 
The compound form problem 

Relationship fields are very unique in the way they are configured and used.  They can do many different things and interact in many ways depending on configuration.  At their core, however, they always connect two or more form entries to each other.

One-time settings
There are three settings which can only be set during the creation of a relationship field.  They can never be modified after the field is created.
Setting Description
Type Relationship fields may either be intra-record or cross-record.  Intra-record relationship can only relate form entries that belong to the same record.  Cross-record relationship can connect form entries from any two records (including entries from the same record).
Form Relationship fields connect form entries from two specific forms:  the current form and the form selected by this setting.  When a relationship field is created, a reciprocal relationship field is also created on the other form.  The two relationship fields are permanently connected to each other. Settings changed on one side automatically affect the other side.  Deleting one field causes the other to also be deleted.  Many settings have a parallel effect on both sides of a relationship.  These are discussed below under each individual setting's description.
Symmetric Relationships This setting is seldom seen and more rarely used.  A symmetric relationship requires that the current form and selected form be the same form.  In this special case the relationship may also be marked symmetric.  A symmetric relationship is identical from both sides.  It only creates a single relationship field instead of two linked fields.  The single field is linked to itself.  Since there is only one field, all settings are identical on "both sides" of the relationship.  Symmetric relationships in real life are things like friend, spouse and co-worker where the relationship is equal and (at least in theory) identical from both sides with no opposite role.  Non-symmetrical relationship are far more common: husband/wife, teacher/student, boss/employee involve differences in roles from each side.
Changeable settings
Most settings can be changed.  Only the settings unique to relationship fields are documented below.
Setting Description
Single/Multi Relationship

This setting defines the cardinality of the relationship.  It answers the question: how many are allowed.  For each side of the relationship you may allow only a single relationship or you may allow multiple relationships.  Usually, all four combinations may be selected: one-to-one, one-to-many, many-to-one and many-to-many.  For symmetric relationships only one-to-one and many-to-many are possible.  The most common setting is one-to-many (or many-to-one depending on which side you're editing).  Some of the side effects of a single-only relationship can be confusing, but are fairly intuitive if you compare them to human relationships:

Consider the one-to-one relationship of "ballroom dance partner".  If Bob is dancing with Betty, and Carl is dancing with Carol, then Bob decides to cut-in and dance with Carol...what happens?  All four people are no-longer dancing with the person they were previously dancing with.  Of course if Bob and Betty weren't dancing when Bob cuts-in then only three people are affected.  If no-one is dancing when Bob decides to dance with Carol then only two people are affected.  The same things occur in a one-to-one relationship field:   Two, three or four form entries may be affected by a single change.

Next consider the one-to-many relationship of "telephone provider".  If Sally signs up for new phone service with AT&T, then Sally and AT&T have a new relationship.  None of AT&T's other customers are affected because many relationships are allowed on AT&T's side of the relationship.  If Sally then changes her provider to Sprint, it terminates her telephone provider relationship with AT&T because Sally's is only allowed one telephone provider relationship.  With a one-to-many or many-to-one relationship two or three form entries may be affected by a single change.

Many-to-many relationships such as "friend" are the most intuitive in this area:  Any change affects exactly two form entries.  Regardless of how relationships are connected or disconnected, they never affect other relationships.  (Except in real llfe when your old friends don't like your new friends...we won't get into that because computers don't get to have opinions.)

This setting is equivalent to choosing between a single-select and multi-select field.  However, it can be changed after the field is created, unlike select fields.  From an end-user's perspective a relationship field looks and behaves exactly like a single select field or a multi-select field depending on how this setting is configured.  If multiple relationships are allowed on this form, then the field will look exactly like a multi-select field.  If only a single relationship is allowed on this form, then the field will look like a single-select field.  The only exception is for intra-record relationships to a single-entry form.  This scenario is described under the "Label (Related)" setting below.

Changing this setting can be dangerous if data already exists and/or formulas have already been written.  If you reduce the cardinality from many-allowed down to one-allowed and existing data already has multiple relationships, the existing relationships do not cease to exist immediately. However, only one can be represented while editing the field, and which is shown is arbitrary.  The next time a change occurs to one of the existing relationships, the new single-only rule will be enforced with unpredictable results since all but one relationship must be terminated under the new rules.  If you increase the cardinality from one-allowed up to many-allowed and formulas exist which only use the first related item, they will fail to recognize and properly deal with the additional relationships that can now be created.

Query/Report

This setting is only available for cross-record relationships, not intra-record relationships.  It determines which records may have their form entries related.  It does NOT affect which entries of a multi-entry form may be selected, even if the query/report chosen has search criteria for the related multi-entry form.

This setting affects available options for both sides of the relationship.  This is easier to understand if considering human relationships:  Imagine a world where nerds are happy to have a relationship with any woman, but women are only willing to have a relationship with nerds who have a net worth over $500,000.  In this imaginary scenario nerds cannot actually have a relationship unless they have a high net worth.

Relationship fields work in the same way.  If you configure a relationship field between doctors and patients, you can configure the query/report setting on the doctor's side of the relationship to include only active clients but the query/report setting on the patient's side of the relationship to allow any doctor.  If you look at a doctor's record and attempt to select a patient, you will see all active patients as expected.  However, by the same rule, if you then go to an inactive patient's record and try to select a doctor there will be no doctors to select, not because the inactive patient is restricted to particular doctors, but because the current record does not meet the requirements of any doctor.

This can be particularly powerful when used with the unit settings of queries and reports.  If a query is used on each side of the relationship which shows the current unit and sub units, then effectively only records in the same unit can be related because if one record is in a parent unit of the other, then the record in the child unit cannot be related to the record in the parent unit.  This senario is not generally useful.  However, it can be become useful if one side of the relationship uses a query that shows the current unit and below, and the other side of the relationship uses a query that shows all units (starts at the top unit and shows sub-units).  What actually occurs, is that the side that is configured to show "all" units actually shows the current unit and above because those are the only units which allow the relationship.  The "current and below" rule gets applied in reverse to the opposite side of the relationship.

If there are no available options to select, then the relationship field becomes hidden, unless the current user is a Relate administrator.  Relate administrators see a message indicating why there are no available options.

This setting does not affect any existing data.  Changing this setting cannot cause existing data to be changed in any way.  Similarly, if a record is modified in such a way that it no longer meets the criteria of the query/report setting, no relationship data will be lost.  Relationships which are currently established, but are no longer allowed by the query/report setting are still shown both when viewing and editing data.  In this case the relationship is considered "invalid" but is still allowed to exist.  When editing relationship field data, invalid relationships can be unselected.  However, if an invalid relationship is unselected (and saved) it cannot be re-selected by going back and editing again.  This is because it will not longer be listed in the available options.

Changing this setting has significant consequences because it will change the list of potential relationships available to users editing the data on both sides of the relationship.  It may remove items from the list that should be there, add some that shouldn't, or change the list to something completely different.  Be careful when modifying this setting.

Multi-Entry Report This setting is only available if the related form is a multi-entry form.  It determines which entries of the multi-entry form may be related.  All of the rules that apply to the "query/report" setting apply equally to the "multi-entry report" setting.  See the description above.
Display Field This setting is available except for intra-record relationships where the related form is single entry.  It determines the displayed label of each item that is available to be selected.  Normally, it must be a field from the related form.  However, for cross-record relationship where the related form is single-entry, the record name may also be used.  The display field always shows a plain-text label.  No HTML formatting is allowed.  Because of the no-html rule, document fields, merge-report fields and biometric fields don't work.  Also, another relationship field cannot be selected as this could potentially cause an infinite loop looking for a label.  (Imagine two relationship fields between the same two forms.  On the first form relationship field "FieldA" is connected to "FieldB" on the second form.  Also, on the first form relationship field "FieldC" is connected to "FieldD" on the second form.  If "FieldA" has its display field set to "FieldD" and "FieldD" has it's display field set to "FieldA" then an infinite loop occurs.  This is not easy to detect because the loop may consist of any number of relationship fields.  Also, even without infinite loops, looking up two or three or more form entries in search of a label can be computationally expensive and eventually cause performance problems)
Label (Related)
Label (Unrelated) 
These two settings are available only for intra-record relationships where the related form is single entry.  If a relationship field is restricted to a single record and that record is restricted to a single form entry, then there is, at most, one entry to be connected to.  This effectively turns the relationship field into a boolean field:  Either the relationship is connected, or it is not.  When the "related" label is filled out but the "unrelated" label is not, then the relationship field looks like a checkbox-boolean field.  If both the "related" label and "unrelated" label are filled out, then the relationship field looks like a radio-button-boolean field.
Format

The "format" setting only applies to single-relationship fields.  To be precise, it only applies when the "single/multi relationship" setting is single-relationship for this form.  It determines whether the relationship field uses a list of radio buttons or a drop-down list.  Radio buttons are more appropriate with a short list of options, and drop-down lists are more appropriate for longer lists of options.  However, each record can have a different number of options available for the same relationship field, so there is no way to make a universal choice between radio buttons and a drop-down list.

The format setting defines the cut-off point when the field transitions from radio buttons to a drop-down list.  If the format option is blank, or the number of available options is smaller than the configured value, then radio buttons are shown.  Otherwise, a drop-down select field is shown.  Valid values for the "format" setting are between 0 and 1000.

Columns With multi-relationship fields, or single relationship fields shown as radio-buttons, this setting determines how many columns the available options are divided into.
Link Back This option, if enabled, provides a link to the related form entries selected, or available for selection, by the relationship field.  If the relationship field is shown as a drop-down list, there will be a "Go" button next to the field.  If shown as a radio-button list or checkbox list, then the label of each option is a link to the other form entry.  If shown as a boolean field the "related" label will be linked.  When a relationship field is shown read-only, each listed relationship will be linked to the related form.