GrooveForms2.CreateRecords Operation
The CreateRecord operation creates new Forms tool records.
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 />
| Element | Data type | Description |
|---|---|---|
RecordDataSet |
The Schema defines the record schemas and the Data contains the records to be created. |
Output Message Header
GrooveResponseHeader specifies the Response key.
Return Value
<CreateRecordsResult>
<!-- Array of --> <string />
</ CreateRecordsResult>
| Element | Data type | Description |
|---|---|---|
CreateRecordsResult |
Array of |
The URIs that identifies the created records. The URIs are returned in the same order as the records appear in the input parameter. Each URI can be used as a parameter in the DeleteRecords, ReadRecords, and UpdateUnreadMark operations. This is the same URI as returned in the RecordURI field in the RecordDataSet. The CreateRecordsResult array may contain zero or more string elements. |
Remarks
In the Data element, the record schema name specified for each record identifies the structure of the record and the form used to create the record. Any field that is omitted from a record will be assigned its default value. If you specify the _ParentID field, the record is created as a child of the specified record. If you are cloning records from one Forms tool to another, you can set the _CreatedBy, _CreatedByURL, _ModifiedBy, and ModifiedByURL fields to their original values.
If this operation fails for a single record, 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 create records, then none of the specified records are updated.
It is not possible to create a record and a child of that record in a single operation. You must follow these steps to create parent and child records:
Create the parent record.
Use the returned RecordURI to read the newly created record with ReadRecords and get its _RecordID.
Create the child record, specifying the parent record's ID in the _ParentID element.
You cannot create new records using a form that has been deleted by a Forms tool designer. If any record in the Data element specifies a record schema name of a deleted form, the operation fails and no records are created.
Note
The Schema should contain a record schema for each record type in the Data element, and each record schema should define all fields specified within the records for that record type. If a field name is omitted from a record schema, then CreateRecords ignores all values specified for that field in the records in the Data element. If an entire record schema is omitted from the Schema element, then CreateRecords ignores all fields in the records in the Data element specified for that record type and creates records using the default values for all fields.
Creating records in the InfoPath Forms tool has different requirements than creating 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 creating records, this field must be present in each record and it defines the values of all designer-defined fields. If you also specify values in the individual designer-defined fields, these values are ignored when creating a record. When creating 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.
See Also
Reference
GrooveForms2 Web Service
Forms2RecordDataSet Complex Type
System Fields in Forms2RecordDataSet