Designing or amending a form through the API

You can create a new form by first creating an XML document that describes the controls on the form. Controls xml tag name are case-sensitive. Please see xml sample below for a list of all controls (at the time of writing). When using formula, it is recommended to escape special characters. Please note that all "UserFormFieldId" must be set to "0" to create the new control. So for a brand new form, all your UserForm and UserFormFieldIds should be set to zero.

You will notice the use of the BOUserFormDesigner object 

The best way to get an up to date format of the XML required is to  create a dummy form containing all the controls and then export it to get the template.

This may not be functionality that you ever need to use, but we have had more than one customer who has automated their library of office forms by parsing word documents and creating the WorkMobile version of the document through the API

 

The XML supplied below is an illustrative example only.

You should be aware of the following limitations when creating forms both through the API and the UI

1. Only a max of 950 data capture controls (E.g. Textbox) can be created through the API. There is no limitation on read only controls (E.g. Label)
2. Minimum numeric value for number control is: -9223372036854775808
3. Maximum numeric value for number control is: 9223372036854775806
4. Minimum date value is: 1/1/1753
5. Maximum date value is: 31/12/9999
6. Maximum number of characters in "caption" attribute is: 150

Exceptions

All controls on a form are validated before actuating changes. Any validation errors will raise a "FormValidationException". The validation error type is returned as an Exception Object, E.g. FormValidationException.MaxValueNumericValidator.

C#

BOUserFormDesigner form = new BOUserFormDesigner(); 
form.UserFormId = 0;
System.Xml.XmlDocument doc = new System.Xml.XmlDocument(); 
doc.Load("xmlDocument.xml");
form.UserFormFieldList = doc.InnerXml; 
form.Published = false; 
form.LocationAware = false; 
form.FormName = "My New Form";
form.Description = "A new form through the API"; 

int newFormId = service.Add(bud, credentials);

Java


BOUserFormDesigner form = new BOUserFormDesigner(); 
form.setUserFormId(0);
String xml = getXmlFromSomewhere(); 
form.setUserFormFieldList(xml); 
form.setPublished(false); 
form.setLocationAware(false);  
form.setFormName("My New Form"); 
form.setDescription("A new form through the API"); 

int newFormId = service.add(bud, credentials);

Example Contents of xmlDocument.xml

<?xml version="1.0" encoding="UTF-8"?>
<UserForm>
   <TextBoxControl UserFormFieldId="0" Caption="New Textbox" ShowCaption="True" Required="True" ReadOnly="False" Hidden="False" MultiLine="False" MinLength="1" MaxLength="50" />
   <TextBoxControl UserFormFieldId="0" Caption="New Textbox1" ShowCaption="True" Required="True" ReadOnly="False" Hidden="False" MultiLine="False" MinLength="1" MaxLength="50" Formula="='New Textbox'" />
   <CalendarControl UserFormFieldId="0" Caption="New Calendar" ShowCaption="True" ReadOnly="False" Hidden="False" MinValue="1950-01-01" MaxValue="2020-12-31" />
   <LineControl UserFormFieldId="0" />
   <DropDownControl UserFormFieldId="0" Caption="New Drop-down" ShowCaption="True" Required="True" ReadOnly="False" Hidden="False" InitialValue="One">
      <Entries>
         <Entry Value="One" />
         <Entry Value="Two" />
         <Entry Value="Three" />
      </Entries>
   </DropDownControl>
   <CheckBoxControl UserFormFieldId="0" Caption="New Checkbox" ShowCaption="True" ReadOnly="False" Hidden="False" InitialValue="0" />
   <LabelControl UserFormFieldId="0" Caption="New Label" />
   <OptionControl UserFormFieldId="0" Caption="New Radio Button List" ShowCaption="True" Required="True" ReadOnly="False" Hidden="False" InitialValue="One">
      <Entries>
         <Entry Value="One" />
         <Entry Value="Two" />
         <Entry Value="Three" />
      </Entries>
   </OptionControl>
   <ExplorerLabelControl UserFormFieldId="0" Formula="='test'" />
   <HeaderControl UserFormFieldId="0" Caption="New Header" />
   <NumberControl UserFormFieldId="0" Caption="New Number" ShowCaption="True" Required="True" ReadOnly="False" Hidden="False" MinValue="-1000000" MaxValue="1000000" NumberType="Whole" />
   <TimeControl UserFormFieldId="0" Caption="Ne+w Time" ShowCaption="True" ReadOnly="False" Hidden="False" />
   <SignatureControl UserFormFieldId="0" Caption="New Signature" ShowCaption="True" />
   <PageBreakControl UserFormFieldId="0" Caption="New PageBreak" />
   <ImageControl UserFormFieldId="0" Filename="ccv0936125625000.jpg" Alignment="1" Background="#ffffff" />
   <BarcodeControl UserFormFieldId="0" Caption="New Barcode" ShowCaption="True" Required="False" />
   <PhotoControl UserFormFieldId="0" Caption="New Photo" ShowCaption="True" Required="True" />
   <DataLinkDropdownControl UserFormFieldId="0" Caption="Parent" ShowCaption="True" Required="False" ReadOnly="False" Hidden="False" Filename="myData" DataField="Car" />
   <DataLinkDropdownControl UserFormFieldId="0" Caption="Child" ShowCaption="True" Required="False" ReadOnly="False" Hidden="False" Filename="myData" DataParent="Parent" DataField="Model" />
   <FormattedLabelControl UserFormFieldId="0" Filename="FLabelTest.htm" />
   <FileAttachmentControl UserFormFieldId="0" Caption="New File Attachment" ShowCaption="True" />
   <ExplorerLabelControl UserFormFieldId="0" Formula="='New Number' + 2" />
</UserForm>

 

Editing a form

You can edit an existing form design. Please Retrieve the BOUserFormDesigner object first, to get the relevant "UserFormFieldId" for the control to be edited. 

New controls UserFormFieldId should be set to "0". 

Please note that if a control XML tag/definition is omitted from the XML document, this will delete the control.

C#

BOUserFormDesigner bud = new BOUserFormDesigner();
bud.UserFormId = 32123; 
bud = (BOUserFormDesigner)getServiceObj().RetrieveById(bud, getCredential());
bud.Published = true; 
bud.LocationAware = true;
bud.UserFormFieldList = bud.UserFormFieldList.Replace("New Textbox", "Edited TextBox");
int newID = service.Add(bud, credentials);

Deleting a form

You can remove a forms definition like any other object. To do so however you must empty theform of data using wither purge or shred methods above.

Any job types using this form must be also removed - or at least be changed to reference a different form

 
C#

BOUserFormDesigner bud = new BOUserFormDesigner(); 
bud.UserFormId = formId;
bud.UserFormFieldList = ""; 
service.Delete(bud, credentials);

Difference between BOUserForm and BOUserFormDesigner

BOUserForm transacts with the form data - but not form design and controls.
 The Add and Delete operations are not available for BOUserForm

BOUserFormDesigner transacts with all properties, including form design and controls.The Retrieve data operations are not available for this entity. Please use BOUserForm entity for this operation.