...

The Display As property is not available for the following schema controls: Message, Date, Time, Date/Time, T/F.

Required Schema Controls

The required property is disabled for controls from XSD. This is because validation is based on the XSD. Values in the xsd for the required property can be overidden with a business rule. 

...

If you want to change whether or not the control is required:

1. Write a business rule to make the field required.
   

2. Edit the XSD and update it in the schema's tab for that application.

There are times when you have several fields that you want hidden and then only want to make visible depending on the value entered into another field. Thus only when the fields are visible do you want them to be required. Currently hidden required fields are still required and prevent the form from being submitted. Automatically making hidden fields not-required may be added in a future release of .

Imagine a form asks if a student speaks Spanish. If the answer is yes you want to make additional fields visible and required. But when the student doesn't speak Spanish the controls should remain hidden and not be required. Here is a solution for this use case:

For each control that needs to be required only when visible, edit the XSD and set minOccurs="1". The control must default to required in the XSD

1. Drag/Drop a Section control from the  palette into the form
2. Uncheck the visible and required properties on the section control
3. Drag all of the from XSD controls that need to be required only when visible into the section control
4. Add a form.load rule that sets <section>.required=false. It is not enough to set the required checkbox in the section's properties panel. It must also be done in a form.load rule
5. Add a 2nd rule that sets <section>.required=true when you make the fields visible, with an else clause to hide the fields that clears all values from those hidden controls AND sets <section>.required=false

Here is an example form.load rule where SpanishOnly is the name of the section control.

if (form.load) {
  SpanishOnly.required = false;
}

Here is an example show/hide rule where name and age are required fields only for Spanish speaking students.

if (spanish.value == 'yes') {
  SpanishOnly.required = true;
  SpanishOnly.visible = true;
}
else {
  // Must clear values in hidden fields
  // Must be done BEFORE setting <section>.required=false
  name.value = null;
  age.value = null;
  SpanishOnly.required = false;
  SpanishOnly.visible = false;
}

Elements with a Nillable Attribute

, version 5.0 only, fully supports nillable element attributes in schema. In previous versions, a required field (minOccurs = 1 or greater) in a form generated from schema, HAD to have a value for the form to be submitted. The control was considered required, ie. the control would display a yellow background color. Nillable attributes override the fact that the field is required and, if present and set to true, required controls will now be considered optional.  When you submit a form and do NOT have a value in a minOccurs > 0 nillable field, the XML document  generated by  will contain an EMPTY element like this <control name xsi:nil="true"/>.

This is how it works for uploaded schemas:

• Elements that contain both nillable=true and minOccurs=0, will NOT be generated in the  xml document.
• Elements that are required, minOccurs > 0, and nillable = true will be treated as an optional element. This means that the UI will generate an optional control for this element instead of a required one.
• When the value is not specified in use mode,  will generate the element with xsi:nil=true. Ex: <control name xsi:nil="true"/>     

Let's take a look at an example with Simple Repeating Elements in the schema:

...

1. 
   Let's say a designer created a form from a schema that contained a non-required Text field - minOccurs = 0.  The designer adds a Trigger control named tr1 and this simple rule to make the field required when the trigger control is clicked.
   
   Here is the relevant section of the xsd:

   Section
   Column width 33% Code Block </xsd:element> <xsd:element minOccurs="0" name="OptionalText" type="xsd:string"> <xsd:annotation> <xsd:appinfo> <frevvo:displaytype>Text</frevvo:displaytype> <frevvo:label>OptionalText</frevvo:label> </xsd:appinfo> </xsd:annotation> </xsd:element> Column width 33% Code Block if(tr1.clicked){ Non_RequiredControl.required = true; } Column width 34%  Image Added

2. Edit the XSD and update it in the schema's tab for that application.

There are times when you have several fields that you want hidden and then only want to make visible depending on the value entered into another field. Thus only when the fields are visible do you want them to be required. Currently hidden required fields are still required and prevent the form from being submitted. Automatically making hidden fields not-required may be added in a future release of .

Imagine a form asks if a student speaks Spanish. If the answer is yes you want to make additional fields visible and required. But when the student doesn't speak Spanish the controls should remain hidden and not be required. Here is a solution for this use case:

For each control that needs to be required only when visible, edit the XSD and set minOccurs="1". The control must default to required in the XSD

1. Drag/Drop a Section control from the  palette into the form
2. Uncheck the visible and required properties on the section control
3. Drag all of the from XSD controls that need to be required only when visible into the section control
4. Add a form.load rule that sets <section>.required=false. It is not enough to set the required checkbox in the section's properties panel. It must also be done in a form.load rule
5. Add a 2nd rule that sets <section>.required=true when you make the fields visible, with an else clause to hide the fields that clears all values from those hidden controls AND sets <section>.required=false

Here is an example form.load rule where SpanishOnly is the name of the section control.

if (form.load) {
  SpanishOnly.required = false;
}

Here is an example show/hide rule where name and age are required fields only for Spanish speaking students.

if (spanish.value == 'yes') {
  SpanishOnly.required = true;
  SpanishOnly.visible = true;
}
else {
  // Must clear values in hidden fields
  // Must be done BEFORE setting <section>.required=false
  name.value = null;
  age.value = null;
  SpanishOnly.required = false;
  SpanishOnly.visible = false;
}

Elements with a Nillable Attribute

, version 5.0 only, fully supports nillable element attributes in schema. In previous versions, a required field (minOccurs = 1 or greater) in a form generated from schema, HAD to have a value for the form to be submitted. The control was considered required, ie. the control would display a yellow background color. Nillable attributes override the fact that the field is required and, if present and set to true, required controls will now be considered optional.  When you submit a form and do NOT have a value in a minOccurs > 0 nillable field, the XML document  generated by  will contain an EMPTY element like this <control name xsi:nil="true"/>.

This is how it works for uploaded schemas:

• Elements that contain both nillable=true and minOccurs=0, will NOT be generated in the  xml document.
• Elements that are required, minOccurs > 0, and nillable = true will be treated as an optional element. This means that the UI will generate an optional control for this element instead of a required one.
• When the value is not specified in use mode,  will generate the element with xsi:nil=true. Ex: <control name xsi:nil="true"/>     

Let's take a look at an example with Simple Repeating Elements in the schema:

<element name="simpleRepeatingNillables">
    <complexType>
        <sequence>
            <element name="simpleR_nil_req1" type="string" nillable="true" minOccurs="1" maxOccurs="unbounded"></element>
        </sequence>     </complexType>
</element>    

The image below shows the form with data entered only in the fields that are required.

Image Removed 

The XML document generated by  when the form is submitted looks like this: Notice the xsi:nil="true" for all controls where minOccurs > 0 AND nillable=true and the user did not enter a value into the form.

<p0:simpleRepeatingNillables xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:p0="http://www.example.org/nillables">
  <simpleR_nil_req1 xsi:nil="true"/>
  <simpleR_nil_req3 xsi:nil="true"/>
  <simpleR_nil_req3 xsi:nil="true"/>
  <simpleR_nil_req3 xsi:nil="true"/>
  <simpleR_req1>value1</simpleR_req1>
  <simpleR_req3>value2</simpleR_req3>
  <simpleR_req3>value3</simpleR_req3>
  <simpleR_req3>value4</simpleR_req3>
</p0:simpleRepeatingNillables>

Elements with Enumerations

If you add an element with enumerations from schema to your form, any dynamic options must conform to the schema.  For example, you can create a drop down from a schema that restricts values to say red, green, blue and in a rule set the options to Mr, Mrs and Ms. In the form if you choose one of the values from the dropdown (Mr) you will get an Invalid value message since it's not part of the original schema.

Annotations

TBD

Updating a Schema

If you need to make changes beyond those allowed in the Forms Designer, make the changes in your XSD file and replace the old schema in your  application with the new one. 

To update a schema:

1. Click Schemas from the left-hand menu. (Remember, schemas are application-specific, so if you don’t see your schema, it may be in another application.) 
2. You’ll see all a list of all uploaded schemas. Click the  icon underneath the name of the schema you are updating.
3. On the Update Schema page, click Browse and locate the new XSD file. You may change the schema name and description but this is optional.
4. Click Update.

Note that you can also change the Name, Description and Root XSD File using Update Schema. For example if you only want to change the Name you set for this XSD then use this page to set a new name and click Update. This will only change the name and not the schema itself.

Image Removed 

When you open (edit) any form that used the schema, the Data Sources area will be refreshed automatically. Do not delete the updated elements from the Data Sources area unless you are absolutely sure no controls in your form were generated from the elements in the previous version of the schema.  '''Also, do not delete the elements and try to re-add them'''. This will cause any controls that relied on the schema to become unbounded and moved out of the schema XML document into the form's default XML document.

If you do not specify a Name when you first upload your XSD it will default to the file name. However if you leave Name blank in Update Schema it will retain the original name set when you uploaded the first time.

<element name="simpleR_nil_req3" type="string" nillable="true" minOccurs="3" maxOccurs="unbounded"></element>
            <element name="simpleR_nil_opt" type="string" nillable="true" minOccurs="0" maxOccurs="unbounded"></element>
            <element name="simpleR_opt" type="string" minOccurs="0" maxOccurs="unbounded"></element>
            <element name="simpleR_req1" type="string" minOccurs="1" maxOccurs="unbounded"></element>
            <element name="simpleR_req3" type="string" minOccurs="3" maxOccurs="unbounded"></element>
        </sequence>
    </complexType>
</element>    

The image below shows the form with data entered only in the fields that are required.

Image Added 

The XML document generated by  when the form is submitted looks like this: Notice the xsi:nil="true" for all controls where minOccurs > 0 AND nillable=true and the user did not enter a value into the form.

<p0:simpleRepeatingNillables xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:p0="http://www.example.org/nillables">
  <simpleR_nil_req1 xsi:nil="true"/>
  <simpleR_nil_req3 xsi:nil="true"/>
  <simpleR_nil_req3 xsi:nil="true"/>
  <simpleR_nil_req3 xsi:nil="true"/>
  <simpleR_req1>value1</simpleR_req1>
  <simpleR_req3>value2</simpleR_req3>
  <simpleR_req3>value3</simpleR_req3>
  <simpleR_req3>value4</simpleR_req3>
</p0:simpleRepeatingNillables>

Elements with Enumerations

If you add an element with enumerations from schema to your form, any dynamic options must conform to the schema.  For example, you can create a drop down from a schema that restricts values to say red, green, blue and in a rule set the options to Mr, Mrs and Ms. In the form if you choose one of the values from the dropdown (Mr) you will get an Invalid value message since it's not part of the original schema.

Annotations

TBD

Updating a Schema

If you need to make changes beyond those allowed in the Forms Designer, make the changes in your XSD file and replace the old schema in your  application with the new one. 

To update a schema:

1. Click Schemas from the left-hand menu. (Remember, schemas are application-specific, so if you don’t see your schema, it may be in another application.) 
2. You’ll see all a list of all uploaded schemas. Click the  icon underneath the name of the schema you are updating.
3. On the Update Schema page, click Browse and locate the new XSD file. You may change the schema name and description but this is optional.
4. Click Update.

Note that you can also change the Name, Description and Root XSD File using Update Schema. For example if you only want to change the Name you set for this XSD then use this page to set a new name and click Update. This will only change the name and not the schema itself.

Image Added 

When you open (edit) any form that used the schema, the Data Sources area will be refreshed automatically. Do not delete the updated elements from the Data Sources area unless you are absolutely sure no controls in your form were generated from the elements in the previous version of the schema.  '''Also, do not delete the elements and try to re-add them'''. This will cause any controls that relied on the schema to become unbounded and moved out of the schema XML document into the form's default XML document.

If you do not specify a Name when you first upload your XSD it will default to the file name. However if you leave Name blank in Update Schema it will retain the original name set when you uploaded the first time.

Let's say you upload a schema with two controls and build a form from that schema. Then you modify your schema and delete one of the controls from the xsd. You update the original schema with the modified one. When you go to the Form/Flow Home page, the form/flow may be flagged with an error. When schema update is done, any controls that were that are no longer valid to that schema are "detached" and fall into the default from scratch schema.  marks them in error to give the designer a visual cue that some investigation is necessary. The error message will clear if the form/flow is edited then saved even if the designer does not change anything.

Image Added

If you click the Image AddedTest icon when the form is in this state, this error message displays.

Image Added

You will NOT see this behavior if you update a schema for a workflow. This feature is planned for a future release.

Adjusting Your Form after Schema Updates

...