UpdateCollection

An UpdateCollection request/response document modifies a collection (inserting, updating, or deleting records) using the UpdateCollection method of an IDO.

When performing an update or deletion request, identify the records you want to update or delete. There are two ways to do this:

By item ID – To update or delete by item ID, you must perform a LoadCollection first to retrieve the item ID, and then include it in the <Item> node’s ID attribute when performing the UpdateCollection update or delete operation.
By the key data – In this case, specify the attribute UseKeys=”Y” on the <Item> node and set the appropriate properties to the key data when performing the update or delete operation.

For update requests, you can also specify the locking option to be used during an IDO item update by using the UpdateLocking attribute on the <Item> node. There are two options for this:

Row – (Default) This option extracts the row’s item ID to get the Row Pointer and Record Date, and use them to construct the WHERE clause.
Property – This option includes the row’s key values and original property values to construct the WHERE clause. This attribute ensures that any intermediate change on the row is overwritten with the latest values. This property also enables simultaneous users to edit on the same row on different columns.

For insert requests, this information is not needed.

Request data

An UpdateCollection request document has this payload structure and contains data such as the collection name and the rows that are subjected to change, which are required to complete the request:

<RequestData>
  <UpdateCollection Name="collection" RefreshAfterUpdate="Y">
    <Items>
      <Item ID="itemid" ItemNo="0" Action="actiontype">
        <Property Name="propertyname">propertyvalue</Property>
        <Property Name="propertyname">propertyvalue</Property>
      </Item>
      <Item ID="itemid" ItemNo="0" Action="actiontype">
        <Property Name="propertyname">propertyvalue</Property>
        <Property Name="propertyname">propertyvalue</Property>
      </Item>
    </Items>
  </UpdateCollection>
</RequestData>

Response data

An UpdateCollection response document has this payload structure and includes requested data and return values.

<ResponseData>
  <UpdateCollection Name="collection" RefreshAfterUpdate="Y">
    <CollectionID />
    <Items>
      <Item ID="itemid" ItemNo="0" Action="actiontype">
        <Property Name="propertyname">propertyvalue</Property>
        <Property Name="propertyname">propertyvalue</Property>
      </Item>
      <Item ID="itemid" ItemNo="0" Action="actiontype">
        <Property Name="propertyname">propertyvalue</Property>
        <Property Name="propertyname">propertyvalue</Property>
      </Item>
    </Items>
  </UpdateCollection>
</ResponseData>

Element descriptions


Element	Description
`CollectionID`	Optional. This element is used when reporting errors that occur while processing items in an UpdateCollection request. If this element is omitted in the request, the IDO name is used instead for any error response. An UpdateCollection request can contain hierarchical (nested) requests. Having a collection ID allows the system response to include both the error message and which item caused the error. (See example 3.)
`Item`	This element can contain these attributes: Action – This attribute can be Insert, Update, or Delete. For Insert operations, if the InitiatorType is set to Replication, the insert is treated as an update if the record already exists. ItemNo – This number is user-defined and optional. It must be a valid 32-bit signed integer. If RefreshAfterUpdate is Y and this number is specified, the response includes the record number value, so that you can match updated records with the originals and see more easily what has changed. ID – This value is used within the system to identify the item. When requesting an update or deletion of existing records, you must include either this, the item ID attribute, or the UseKeys attribute. Omitting the ID attribute defaults to the same behavior as UseKeys="Y". UseKeys: Y (the default value) indicates that the update or delete request is to use key data, rather than item IDs. N indicates that the request is to include item IDs. UpdateLocking: Row (the default value) extracts the row’s indentifying property (ItemID) to get the RowPointer and RecordDate, and use them to construct the WHERE clause. Property includes the row’s key values and original values to construct the WHERE clause. RecordDate and RowPointer are omitted from the WHERE clause.
`Property`	Include in your request any properties that you plan to update, as well as all non-nullable properties that do not have a default value. You can omit properties that have default values that do not change because of the update. This element can contain these attributes: Name – This is the name of the property. Modified – This value specifies whether the property was updated. Only values flagged as `"Modified=Y"` are updated in the database. OriginalValue – This attribute contains the original value of the property. Use this attribute when the `<Item>` node’s `UpdateLocking=”Property”`.
`UpdateCollection`	This element can include these attributes: Name – This attibute contains the name of the IDO collection. RefreshAfterUpdate: Y indicates that the response document should show information for inserted or updated items that was updated after the update was done. Deleted items are not updated. N indicates that the response document information was not updated after the modification. TxnScope – Optional. This attibute can be set to Collection (the default value) or Item. When this is set to Item, each individual item in the UpdateCollection request is saved in a separate transaction. For a hierarchical (nested) UpdateCollection request, the value of the TxnScope attribute at the root level determines the behavior for the entire UpdateCollection request. If an exception occurs while processing an UpdateCollection request for an item using the TxnScope attribute, records that were saved before the exception are still committed, but no additional records are saved. If the TxnScope attribute is omitted or is set to Collection, the request is processed in a single transaction. This attribute has no effect when it is included in an inner UpdateCollection within hierarchical requests.
`LinkBy`	This element is valid only in CONTAINS relationships, much like the LINKBY keyword. The information within this pair of tags tells how the CONTAINS relationship is linked to the parent collection. For example: <LinkBy> <PropertyPair Child="Item" Parent="Item" /> <!-- Optional: more sets of PropertyPair tags --> </LinkBy>

Example 1 - Using UpdateCollection for Insert, Update, and Delete operations

This example request shows how you can perform different actions for each row in the collection within a single request. This request 1) creates a new user, 2) updates the description of user wsmith, and 3) deletes the record of user cdelune.

<IDORequest ProtocolVersion="6.03" SessionID="bde8caa4-1343-4808-9bca-ed844ffe7129">
  <RequestHeader Type="UpdateCollection">
    <InitiatorType />
    <InitiatorName />
    <SourceName />
    <SourceConfig />
    <TargetName />
    <TargetConfig />
    <RequestData>
      <UpdateCollection Name="UserNames" RefreshAfterUpdate="Y">
        <Items>
          <Item ID="PBT=[UserNames] UserNames.DT=[2019-08-13 14:14:23.453] UserNames.ID=[122cb5af-c5fb-4109-a95b-a331cb4e258c]" ItemNo="0" Action="Insert">
            <Property Name="UserDesc">John Doe</Property>
            <Property Name="Username">jdoe</Property>
          </Item>
          <Item ID="PBT=[UserNames] UserNames.DT=[2019-08-15 17:30:09.870] UserNames.ID=[b3aedc23-722f-4058-b12c-f14bdfd955b4]" ItemNo="0" Action="Update">
            <Property Name="UserDesc">Will Smith Sr.</Property>
          </Item>
          <Item ID="PBT=[UserNames] UserNames.DT=[2019-08-15 17:30:52.253] UserNames.ID=[018ae411-42c3-48cb-a50b-b943dcb70dbe]" ItemNo="2" Action="Delete" />
        </Items>
      </UpdateCollection>
    </RequestData>
  </RequestHeader>
</IDORequest>

This example response includes the updated description of user wsmith, and the details of the new user jdoe.

<IDOResponse ProtocolVersion="6.03" SessionID="bde8caa4-1343-4808-9bca-ed844ffe7129">
  <ResponseHeader Type="UpdateCollection">
    <InitiatorType />
    <InitiatorName />
    <SourceName />
    <SourceConfig />
    <TargetName />
    <TargetConfig />
    <ResponseData>
      <UpdateCollection Name="UserNames" RefreshAfterUpdate="Y">
        <CollectionID />
        <Items>
          <Item ID="PBT=[UserNames] UserNames.DT=[2019-08-15 17:32:43.233] UserNames.ID=[b3aedc23-722f-4058-b12c-f14bdfd955b4]" ItemNo="0" Action="Update">
            <Property Name="UserDesc">Will Smith Sr.</Property>
          </Item>
          <Item ID="PBT=[UserNames] UserNames.DT=[2019-08-15 17:32:43.283] UserNames.ID=[1a69ed89-a34e-4634-95fd-dad989ef3a39]" ItemNo="0" Action="Insert">
            <Property Name="UserDesc">John Doe</Property>
            <Property Name="Username">jdoe</Property>
            <Property Name="InWorkflow">0</Property>
          </Item>
        </Items>
      </UpdateCollection>
    </ResponseData>
  </ResponseHeader>
</IDOResponse>

Example 2 - Nested UpdateCollection

UpdateCollection requests can be hierarchichal. For example, this request document inserts a user-defined type and its value in a single request, by nesting UserDefinedTypeValues IDO UpdateCollection request inside the UserDefinedTypes IDO UpdateCollection request.

<IDORequest ProtocolVersion="6.03" SessionID="bde8caa4-1343-4808-9bca-ed844ffe7129">
  <RequestHeader Type="UpdateCollection">
    <InitiatorType />
    <InitiatorName />
    <SourceName />
    <SourceConfig />
    <TargetName />
    <TargetConfig />
    <RequestData>
      <UpdateCollection Name="UserDefinedTypes" RefreshAfterUpdate="Y">
        <Items>
          <Item ID="" ItemNo="0" Action="Insert">
            <Property Name="Description">An amount of time used with calendars</Property>
            <Property Name="Name">Month</Property>
            <UpdateCollection Name="UserDefinedTypeValues" RefreshAfterUpdate="Y">
              <LinkBy>
                <PropertyPair Parent="Name" Child="TypeName" />
              </LinkBy>
              <Items>
                <Item ID="" ItemNo="0" Action="Insert">
                  <Property Name="TypeName">Month</Property>
                  <Property Name="Value">January</Property>
                </Item>
              </Items>
            </UpdateCollection>
          </Item>
        </Items>
      </UpdateCollection>
    </RequestData>
  </RequestHeader>
</IDORequest>

This example response contains the complete information regarding the new user-defined type and its value.

<IDOResponse ProtocolVersion="6.03" SessionID="bde8caa4-1343-4808-9bca-ed844ffe7129">
  <ResponseHeader Type="UpdateCollection">
    <InitiatorType />
    <InitiatorName />
    <SourceName />
    <SourceConfig />
    <TargetName />
    <TargetConfig />
    <ResponseData>
      <UpdateCollection Name="UserDefinedTypes" RefreshAfterUpdate="Y">
        <CollectionID />
        <Items>
          <Item ID="PBT=[UserDefinedTypes] UserDefinedTypes.ID=[f22b0d6b-fdba-4b14-b008-4fd418b0cd75] UserDefinedTypes.DT=[2019-08-16 09:54:34.450]" ItemNo="0" Action="Insert">
            <Property Name="Description">An amount of time used with calendards</Property>
            <Property Name="Name">Month</Property>
            <Property Name="InWorkflow">0</Property>
            <UpdateCollection Name="UserDefinedTypeValues" RefreshAfterUpdate="Y">
              <LinkBy>
                <PropertyPair Parent="Name" Child="TypeName" />
              </LinkBy>
              <CollectionID />
              <Items>
                <Item ID="PBT=[UserDefinedTypeValues] UserDefinedTypeValues.ID=[54a99f45-7a9e-4c3b-a974-7fe496db8c8b] UserDefinedTypeValues.DT=[2019-08-16 09:54:34.463]" ItemNo="0" Action="Insert">
                  <Property Name="TypeName">Month</Property>
                  <Property Name="Value">January</Property>
                  <Property Name="InWorkflow">0</Property>
                </Item>
              </Items>
            </UpdateCollection>
          </Item>
        </Items>
      </UpdateCollection>
    </ResponseData>
  </ResponseHeader>
</IDOResponse>

Example 3 - UpdateCollection using item IDs

This example request updates an existing record using the ID attribute. To find a specific ID, perform a LoadCollection request on the data before performing the UpdateCollection.

<IDORequest ProtocolVersion="6.03" SessionID="bde8caa4-1343-4808-9bca-ed844ffe7129">
  <RequestHeader Type="UpdateCollection">
    <InitiatorType />
    <InitiatorName />
    <SourceName />
    <SourceConfig />
    <TargetName />
    <TargetConfig />
    <RequestData>
      <UpdateCollection Name="UserNames" RefreshAfterUpdate="Y">
        <Items>
          <Item ID="PBT=[UserNames] UserNames.DT=[2019-08-15 17:32:43.233] UserNames.ID=[b3aedc23-722f-4058-b12c-f14bdfd955b4]" ItemNo="0" Action="Update">
            <Property Name="UserDesc">Will Smith</Property>
          </Item>
        </Items>
      </UpdateCollection>
    </RequestData>
  </RequestHeader>
</IDORequest>

This example response includes the updated description of user wsmith.

<IDOResponse ProtocolVersion="6.03" SessionID="bde8caa4-1343-4808-9bca-ed844ffe7129">
  <ResponseHeader Type="UpdateCollection">
    <InitiatorType />
    <InitiatorName />
    <SourceName />
    <SourceConfig />
    <TargetName />
    <TargetConfig />
    <ResponseData>
      <UpdateCollection Name="UserNames" RefreshAfterUpdate="Y">
        <CollectionID />
        <Items>
          <Item ID="PBT=[UserNames] UserNames.DT=[2019-08-15 18:38:30.520] UserNames.ID=[b3aedc23-722f-4058-b12c-f14bdfd955b4]" ItemNo="0" Action="Update">
            <Property Name="UserDesc">Will Smith</Property>
          </Item>
        </Items>
      </UpdateCollection>
    </ResponseData>
  </ResponseHeader>
</IDOResponse>

Example 4 - UpdateCollection using keys

This example request updates an existing record using the UseKeys attribute which indicates that the update or delete request will use key data.

<IDORequest ProtocolVersion="6.03" SessionID="bde8caa4-1343-4808-9bca-ed844ffe7129">
  <RequestHeader Type="UpdateCollection">
    <InitiatorType />
    <InitiatorName />
    <SourceName />
    <SourceConfig />
    <TargetName />
    <TargetConfig />
    <RequestData>
      <UpdateCollection Name="UserNames" RefreshAfterUpdate="Y">
        <Items>
          <Item ItemNo="0" Action="Update" UseKeys="Y">
            <Property Name="UserDesc">John Mark Doe</Property>
            <Property Name="UserId" Modified="N">45</Property>
          </Item>
        </Items>
      </UpdateCollection>
    </RequestData>
  </RequestHeader>
</IDORequest>

This example response includes the updated description of the user with user ID 45.

<IDOResponse ProtocolVersion="6.03" SessionID="bde8caa4-1343-4808-9bca-ed844ffe7129">
  <ResponseHeader Type="UpdateCollection">
    <InitiatorType />
    <InitiatorName />
    <SourceName />
    <SourceConfig />
    <TargetName />
    <TargetConfig />
    <ResponseData>
      <UpdateCollection Name="UserNames" RefreshAfterUpdate="Y">
        <CollectionID />
        <Items>
          <Item ID="PBT=[UserNames] UserNames.DT=[2019-08-15 18:46:16.520] UserNames.ID=[1a69ed89-a34e-4634-95fd-dad989ef3a39]" ItemNo="0" Action="Update">
            <Property Name="UserDesc">John Mark Doe</Property>
            <Property Name="UserId" Modified="N">45</Property>
          </Item>
        </Items>
      </UpdateCollection>
    </ResponseData>
  </ResponseHeader>
</IDOResponse>