GrooveForms2.UpdateRecords Operation
The UpdateRecords operation updates the records as specified in the RecordDataSet.
HTTP Post URL
The HTTP Post URL targets the Forms tool. This URI is provided by the GrooveTools.Read operation in the ToolData element.
Input Message Header
GrooveRequestHeader specifies information common to all Groove Web Services, including the Groove Identity URL and the Groove Request key.
Input Message Parameters
<RecordDataSet />
<ExceptionIfDeleted />
| Element | Data type | Description |
|---|---|---|
RecordDataSet |
Identifies the records to be updated and provides the updated values. The RecordURI element in each record identifies the record that is to be updated. The record schema name identifies the form used to create the record. |
|
ExceptionIfDeleted |
|
If true and any of the records specified in the RecordDataSet Data element have been previously deleted, then the operation fails and does not update any records. If false, then the operation attempts to update the remaining records even if others have been deleted. |
Output Message Header
GrooveResponseHeader specifies the Response key.
Return Value
None.
Remarks
In this operation, the Schema element should define the record schemas that have instances in the Data element. Within each record in the Data element, the RecordURI field identifies the record that is being updated. The record schema name identifies record schema and must be the same as the form used to create the existing record. The operation updates all fields that are specified in the Data and leaves all omitted fields unchanged.
To modify the unread mark, use the UpdateUnreadMark operation.
In order to update any attachments on a record, you must specify all attachments for the record including their contents. If the attachment contents are included in the Data element, the operation deletes the existing attachments on a record and adds the attachments specified in the Data element. If you do not include the FileAttachmentContent element but do include other FileAttachment elements, such as FullName, the operation ignores the FileAttachment element and leaves the attachments unchanged. If there are multiple files attached to a field, it is not possible to update one without updating all. It is not possible to update the name of an attachment without updating the contents.
If this operation fails for a single record for any reason other than that the record has been deleted, then it fails for all records; the entire transaction is canceled; and the operation returns a SOAP exception. For example, if the user specified by the Identity URL in the header does not have permission to update any of the specified records, then none of the specified records are updated.
If the MaintainRecordVersionHistory property is true for the form used to create a record, the UpdateRecords operation saves the current value of the record as a child to the updated record. The saved child record is assigned a new Record ID.
Note that updating records in the InfoPath Forms tool has different requirements than updating records in the Groove Forms tool. In the InfoPath Forms tool, the InfoPath XML document that describes the entire record is stored in the Forms_Tool_IPContents attachments field. If you are updating records, you may specify the new values either by individual designer-defined fields or by the InfoPath XML document. If the record has a value for the Forms_Tool_IPContents field, it is used to update the record and any other designer-defined field values will be ignored. If the record does not have a value for the Forms_Tool_IPContents field, then the individual fields are updated based on each field's value in the record.
If you specify the Forms_Tool_IPContents field when updating records, the value in this field must be a valid InfoPath X-document for the tool's InfoPath template. Specifically, the following elements of the X-document must match the corresponding elements of the InfoPath template design. See the ReadInfoPathTemplate operation for more information.
The X-document name must match the InfoPath Form ID.
The X-document solutionVersion must match the InfoPath template version.
If you update a record in an InfoPath tool and do not specify a value for the Forms_Tool_IPContents field, the tool automatically updates the InfoPath XML document stored in the record to have the new values for the fields updated by the operation.
See Also
Reference
GrooveForms2 Web Service
Forms2RecordDataSet Complex Type
System Fields in Forms2RecordDataSet