You are here

You are here

Accessing and Updating Eform Custom Form Fields

Working with a SpringCM electronic form (Eform) via the API is nearly identical to working with any other document.  Eforms are represented by the SCMDocument object, similar to a standard document such as a Microsoft Word or PDF document.  All of the same operations such as search or metadata updates that are used with standard documents can be used with electronic forms.  The SCMDocument object exposes a boolean IsFormDocument property to indicate if the object is representing a standard document or electronic form.

Electronic forms expose some additional functionality in the API.  In particular, electronic forms can contain standard HTML form fields that get saved on the form in what are known as "Custom Form Fields".  These are not searchable or reportable in the way that document attributes are, they just exist as additional data on the form.  However, these fields are exposed on the SCMDocument object as an array of SCMFormField objects accessed via the CustomFormFields property.

The custom form fields array can be looped through and the data from the HTML form fields is accessed via a Key and Value property exposed on the SCMFormField object.  The values may be updated and then committed back to SpringCM by calling the SaveCustomFormData method if the form has "Allow Updates" set to true.

The data on the document will be completely overwritten with what is passed in. Repeating custom fields must not change their set name and number, and adding new repeating entries through this method is not allowed. If repeating entries need to be added, a new repeating metadata set should be added first and then custom field data may be associated with it. The method will error if:

  • The document is not a form document.
  • Invalid or nonexistent set number and name are used for repeating custom fields.
  • The set number has value and the set name is blank and vice versa.
  • Insufficient permissions, including read only form.

This method will not update any other properties of the document, but the custom form data.

When retrieving custom form data, the loadExtendedMetadata parameter must be set to true for any method that exposes this as an option.

Vertical Tabs

c#
string documentId = "<Source document Id retrieved by other method calls>";
SCMDocument doc = springCMService.DocumentGetById(token, documentId, true);
 
bool formDataIsUpdated = false;
if (doc.IsFormDocument)
{
   foreach (var field in doc.CustomFormFields)
   {
	   Console.WriteLine("Field with key {0} has value {1}", field.Key, field.Value);
 
	   //Here we can check for a certain Key value of the field and update it
	   if (field.Key == "Approver")
	   {
		   field.Value = "approver@springcm.com";
		   formDataIsUpdated = true;
	   }
   }
 
   //The form must allow updates for this to be successful
   if(formDataIsUpdated)
   {
	   springCMService.SaveCustomFormData(token, doc);
   }
}
java
String documentId = "<Source document Id retrieved by other method calls>";
SCMDocument doc = springCMService.documentGetById(token, documentId, true);
 
boolean formDataIsUpdated = false;
if (doc.getIsFormDocument())
{
 for (SCMFormField field : doc.getCustomFormFields())
 {
	 System.out.format("Field with key %s has value %s\n", field.getKey(), field.getValue());
 
	 //Here we can check for a certain Key value of the field and update it
	 if (field.getKey().equals("Approver"))
	 {
		 field.setValue("approver@springcm.com");
		 formDataIsUpdated = true;
	 }
 }
 
 //The form must allow updates for this to be successful
 if(formDataIsUpdated)
 {
	 springCMService.saveCustomFormData(token, doc);
 }
}