core:index (Identify list entries by order position)

The control attribute core:index can be used in an Import to identify the list item to be updated by its list position.

The 'Index' starts from 0 and counts upwards as an integer. It is completely refreshed immediately before each access. This is particularly important if the addressed elements are to be deleted rather than updated.

Frequently, the data structure of the list item also contains its own index attribute, which, for example, in the case of typed plural attributes, is also named index.

The example on the right shows an XML section of the attributes node of an address object:

  • The first two attributes are belong to a plural attribute of the 'Communication info' type, which have an orderIndex attribute that specifies the order of the list entries, which (as shown here) need not correspond to the order of the nodes in the XML.

  • Below are two values of a plural text attribute of the ACCESS_CODE, type, which use the index attribute generated for typed plural attributes.

<attributes>
...
<base:AddressCommunicationInfo ... orderIndex="1" communicationType="EMAIL" communicationContext="manager">
<communicationValue>u1025@compa.ny</communicationValue>
</base:AddressCommunicationInfo>
<base:AddressCommunicationInfo ... orderIndex="0" communicationType="EMAIL" communicationContext="user">
<communicationValue>u4252@compa.ny</communicationValue> </base:AddressCommunicationInfo>
<base:AddressText ... >
<value textType="ACCESS_CODE" index="0">
<textValue>ABC123456789</textValue>
</value>
</base:AddressText>
<base:AddressText ... >
<value textType="ACCESS_CODE" index="1">
<textValue>XYZ987654321</textValue>
</value>
</base:AddressText>
... </attributes>

In both cases, the respective index attribute can be used to identify a specific list entry by its position during an Import.

However, in both cases the core:index attribute can be used for the same purpose to identify the list entry.

Example 1: Updating a specific entry in a plural attribute

Address data is available for a user account as shown in the introductory example. The Import should update a specific element listed under 'communication info', namely the one with orderIndex=1, which appears in the second position.

Before the Import:

images/download/attachments/201675351/image2021-1-21_19-39-53-version-1-modificationdate-1747137581134-api-v2.png

The Import shown on the right uses the action UPDATE:

  • The user account in question is uniquely identified by ID (4252).

  • The 'communication info' to be updated is only identified via the list position per core:index .

The second entry is assigned a new e-mail address.

 
<?xml version="1.0" encoding="UTF-8"?>
<core:Import ... action="UPDATE">
  <base:User id="4252">
    <address>
      <attributes core:clear="false">
        <base:AddressCommunicationInfo core:index="1">
          <communicationValue>u2407@compa.ny</communicationValue>
        </base:AddressCommunicationInfo>
      </attributes>
    </address>
  </base:User>
</core:Import>

After the Import: (Change by selection highlighted)

images/download/attachments/201675351/image2021-1-21_19-41-17-version-1-modificationdate-1747137581130-api-v2.png

Example 2: Deleting the first two entries for a typed plural attribute

Address data is available for a user account as shown in the introductory example. The Import should delete the (first) two entries for the plural text attribute ACCESS_CODE.

The Import shown on the right uses the action UPDATE:

  • The user account in question is uniquely identified by ID (4252).

  • The text attribute ACCESS_CODE is addressed twice in succession with identical detail data. The core:delete attribute specifies the deletion. The core:index attribute in the value subnode specifies which entry should be deleted. Here the entry in the first position is deleted twice. Since the list's index is refreshed each time it is accessed, the second entry moves up after the first one is deleted.

►NOTE◄ The repeated insertion of the same node in an import structure can be achieved by assigning an integer variable as a 'path' for the corresponding node of the target structure, which defines the number of iterations either statically or by assignment at runtime of the profile.

 
<?xml version="1.0" encoding="UTF-8"?>
<core:Import ... action="UPDATE">
  <base:User id="4252">
    <address>
      <attributes>
        <base:AddressText core:delete="true">
          <value core:index="0" textType="ACCESS_CODE"></value>
        </base:AddressText>
        <base:AddressText core:delete="true">
          <value core:index="0" textType="ACCESS_CODE"></value>
        </base:AddressText>
      </attributes>
    </address>
  </base:User>
</core:Import>

►NOTE◄ You could try to access the two entries to be deleted in the Import with different values for core:index (namely 0 and 1). In this case, the second entry would remain in the list and a third entry (if any) might move up would be deleted. If the deletions were executed in reverse order (first 1 then 0), then the deletion would be successful for both entries.