pixiTagMatchAddForItems

Creates entries in TagMatch that link tags of type 1 (item tags) to items.

Input processing

TagsXML is parsed with OPENXML on the path /Tags/Item/TagList/Tag (element-centric). Every Tag element is one requested assignment.
TagId is read from the Tag element; ItemId and ItemNrInt are read from the parent Item element. The values 0 and the empty string are treated as missing.
The item is resolved as follows: if ItemId is given, it is used as is. Otherwise ItemNrInt is looked up in pixi.ItemCode (Code with CodeTypeId = 2) to find the item key.

Validation, in this order

Requests where the item key does not exist in items or the tag does not exist in Tag with TypeId = 1 get a status:
- TagId missing, or TagId given but neither ItemId nor ItemNrInt given: Error / Mandatory parameter is missing.
- ItemNrInt not found, ItemId unknown, or tag unknown or not an item tag: Error / One of the provided values is not valid.
Remaining requests where the tag/item pair already exists in TagMatch (for a tag of type 1): Warning / Tag is already assigned to that item.
All other requests: Success / Tag was successfully assigned to item. These pairs are inserted into TagMatch (duplicates within the XML are inserted only once).

Result

One row per requested assignment, ordered by the position of the Tag element in the XML, with the tag ID, the resolved item ID, the item number given, and Status/Message.

Notes

The procedure runs in its own transaction, or sets a savepoint if the caller already has an open transaction.
Lookups on items, Tag, TagMatch and pixi.ItemCode use NOLOCK; concurrent calls may therefore insert the same pair twice or see uncommitted data.
If an unexpected error occurs, the transaction is rolled back and the error is logged via log.InsertError (not attached). The CATCH block sets an "Unexpected error" message internally but does not return it as a row, so the caller receives no result set in that case. Whether log.InsertError re-raises the error is not visible in the code.
ItemId takes precedence over ItemNrInt; if both are given, ItemNrInt is only echoed back.
If an ItemNrInt matches several pixi.ItemCode entries, the request may produce several result rows.
Tags whose TypeId is not 1 are rejected as invalid.

Tables used

TagMatch · Write Tag · Read items · Read ItemCode · Read

Parameter Type Default Description

Parameter	Type	Default	Description
`TagsXML`	varchar(max) xml	NULL	XML document with the items and the tags to assign. Each `Item` contains `ItemId` and/or `ItemNrInt` and a `TagList` with one or more `Tag` elements holding a `TagId`. Example: `<Tags> <Item> <ItemId>1234</ItemId> <ItemNrInt/> <TagList> <Tag> <TagId>5</TagId> </Tag> <Tag> <TagId>7</TagId> </Tag> </TagList> </Item> <Item> <ItemId>0</ItemId> <ItemNrInt>ART-10001</ItemNrInt> <TagList> <Tag> <TagId>5</TagId> </Tag> </TagList> </Item> </Tags>`

TagsXML

varchar(max)
xml

NULL

XML document with the items and the tags to assign. Each Item contains ItemId and/or ItemNrInt and a TagList with one or more Tag elements holding a TagId.

Example:

<Tags>
  <Item>
    <ItemId>1234</ItemId>
    <ItemNrInt/>
    <TagList>
      <Tag>
        <TagId>5</TagId>
      </Tag>
      <Tag>
        <TagId>7</TagId>
      </Tag>
    </TagList>
  </Item>
  <Item>
    <ItemId>0</ItemId>
    <ItemNrInt>ART-10001</ItemNrInt>
    <TagList>
      <Tag>
        <TagId>5</TagId>
      </Tag>
    </TagList>
  </Item>
</Tags>

Result set 1 · On success (no unexpected error); one row per `Tag` element in the XML.

Status of each requested tag assignment, ordered by position in the XML.

Column	Type	Description
`TagId` Nullable	int	Tag ID from the XML (NULL if missing or 0).
`ItemId` Nullable	int	Item key, either from the XML or resolved from `ItemNrInt`; NULL if it could not be determined.
`ItemNrInt` Nullable	varchar(50) string	Internal item number as given in the XML (NULL if empty).
`Status`	varchar(254) string	`Success`, `Warning` or `Error`.
`Message`	varchar(2000) string	Explanation of the status.

Response example

<SqlRowSet1>
  <row>
    <TagId>5</TagId>
    <ItemId>1234</ItemId>
    <Status>Success</Status>
    <Message>Tag was successfully assigned to item</Message>
  </row>
  <row>
    <TagId>7</TagId>
    <ItemId>1234</ItemId>
    <Status>Warning</Status>
    <Message>Tag is already assigned to that item</Message>
  </row>
</SqlRowSet1>

Status	Message	Cause
Error	Mandatory parameter is missing	The `Tag` element has no `TagId` (or 0), or neither `ItemId` nor `ItemNrInt` is given for the item. Provide both a tag and an item identifier.
Error	One of the provided values is not valid	The `ItemNrInt` was not found in `pixi.ItemCode`, the `ItemId` does not exist, or the tag does not exist or is not an item tag (`TypeId` 1).
Warning	Tag is already assigned to that item	The tag/item pair already exists in `TagMatch`; nothing is inserted for this request.
Error	Something went wrong, an undefined error occurred	Fallback status for an undefined validation result; not expected under normal conditions.

POST https://apigateway.descartes.com/tms/pixi/
Content-Type: text/xml; charset=utf-8
Authorization: Basic BASE64(USERNAME:PASSWORD)

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiTagMatchAddForItems>
      <!-- <TagsXML><![CDATA[<Tags><Item><ItemId>1234</ItemId><ItemNrInt></ItemNrInt><TagList><Tag><TagId>5</TagId></Tag><Tag><TagId>7</TagId></Tag></TagList></Item><Item><ItemId>0</ItemId><ItemNrInt>ART-10001</ItemNrInt><TagList><Tag><TagId>5</TagId></Tag></TagList></Item></Tags>]]></TagsXML> -->
    </ns1:pixiTagMatchAddForItems>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

curl -X POST 'https://apigateway.descartes.com/tms/pixi/' \
  --user 'USERNAME:PASSWORD' \
  --header 'Content-Type: text/xml; charset=utf-8' \
  --data-binary @- <<'XML'
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiTagMatchAddForItems>
      <!-- <TagsXML><![CDATA[<Tags><Item><ItemId>1234</ItemId><ItemNrInt></ItemNrInt><TagList><Tag><TagId>5</TagId></Tag><Tag><TagId>7</TagId></Tag></TagList></Item><Item><ItemId>0</ItemId><ItemNrInt>ART-10001</ItemNrInt><TagList><Tag><TagId>5</TagId></Tag></TagList></Item></Tags>]]></TagsXML> -->
    </ns1:pixiTagMatchAddForItems>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML

<?php

$soapClient = new SoapClient(null, [
    'login' => 'USERNAME',
    'password' => 'PASSWORD',
    'location' => 'https://apigateway.descartes.com/tms/pixi/',
    'uri' => 'https://apigateway.descartes.com/tms/pixi/',
]);

$arguments = [
    // 'TagsXML' => '<Tags><Item><ItemId>1234</ItemId><ItemNrInt></ItemNrInt><TagList><Tag><TagId>5</TagId></Tag><Tag><TagId>7</TagId></Tag></TagList></Item><Item><ItemId>0</ItemId><ItemNrInt>ART-10001</ItemNrInt><TagList><Tag><TagId>5</TagId></Tag></TagList></Item></Tags>',
];

$soapArguments = [];
foreach ($arguments as $name => $value) {
    $soapArguments[] = new SoapVar($value, XSD_STRING, '', '', $name);
}

$response = $soapClient->__soapCall('pixiTagMatchAddForItems', $soapArguments);

Notes

Tables used

Result set 1 · On success (no unexpected error); one row per Tag element in the XML.

Response example

Result set 1 · On success (no unexpected error); one row per `Tag` element in the XML.