pixiTagMatchAdd · Pixi API documentation

Creates a tag assignment (a row in TagMatch) for the tag given in TagId.

Steps:

Reads the type of the tag from Tag. The type decides which object the tag can be assigned to:
- TypeId = 1: item tag, ItemId is required and must exist as ItemKey in items.
- TypeId = 2: order tag, OrderNr is required and must exist as OrderNr in OrderHeader. The order number is translated to the internal OrderHeaderKey.
Checks whether the tag is already assigned to the given item or order.
Validates in this order and stops at the first failure: missing TagId, unknown tag, missing ItemId/OrderNr for the tag type, unknown item/order, existing assignment.
If all checks pass, inserts the assignment. For an item tag only the item is stored, for an order tag only the order header key is stored; the other parameter is ignored.

The call always returns one row with Status (Success, Warning or Error) and Message.

Notes

The work runs in its own transaction, or in a savepoint if the caller already has an open transaction. On an unexpected error the changes are rolled back, the error is logged via log.InsertError and a status row with Unexpected error: "…" (first 80 characters of the SQL error) is returned instead of a SqlMessage.
Lookups use NOLOCK, so the duplicate check can read uncommitted data; two concurrent calls could both pass the check.
The duplicate check matches the tag against the order or the item. If both OrderNr and ItemId are sent, an existing assignment to either one leads to the Warning, even if it does not belong to the tag type.
For tags whose TypeId is neither 1 nor 2 no item/order validation takes place and a TagMatch row with both ItemId and OrderHeaderId empty is inserted.
OrderNr is the visible order number, not the internal OrderHeaderKey; ItemId is the internal ItemKey.
The header comment of the procedure ("Get tags for objects") does not match its behaviour; the procedure writes data.

Tables used

Tag · Read items · Read OrderHeader · Read TagMatch · Write

Parameter	Type	Default	Description
`TagId` Required	int	–	ID of the tag (`Tag.Id`) to assign. Its type determines whether `ItemId` or `OrderNr` is used. Example: `12`
`OrderNr`	int	NULL	Order number (`OrderHeader.OrderNr`) the tag is assigned to. Required for order tags (`TypeId` = 2), ignored for item tags. Example: `100245`
`ItemId`	int	NULL	Internal item key (`items.ItemKey`) the tag is assigned to. Required for item tags (`TypeId` = 1), ignored for order tags. Example: `4711`

Result set 1 · Always

One status row with the result of the assignment.

Column	Type	Description
`Status`	varchar(10) string	`Success` if the tag was assigned, `Warning` if it was already assigned, `Error` otherwise.
`Message`	varchar(100) string	Result text, e.g. `Tag was successfully assigned` or the reason for the failure.

Response example

<SqlRowSet1>
  <row>
    <Status>Success</Status>
    <Message>Tag was successfully assigned</Message>
  </row>
</SqlRowSet1>

Status	Message	Cause
Error	Mandatory parameter is missing	`TagId` is empty, or `ItemId` is missing for an item tag (`TypeId` = 1), or `OrderNr` is missing for an order tag (`TypeId` = 2). Send the parameter that matches the tag type.
Error	One of the provided values is not valid	The tag does not exist, or the given item (`ItemKey`) or order number does not exist for the tag type. Check the IDs before calling.
Warning	Tag is already assigned	The tag is already assigned to the given item or order. Nothing is inserted.
Error	Unexpected error: "{error}"	An SQL error occurred during processing; `{error}` holds the first 80 characters of the SQL error message. The transaction is rolled back and the error is logged.

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:pixiTagMatchAdd>
      <TagId>12</TagId>
      <!-- <OrderNr>100245</OrderNr> -->
      <!-- <ItemId>4711</ItemId> -->
    </ns1:pixiTagMatchAdd>
  </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:pixiTagMatchAdd>
      <TagId>12</TagId>
      <!-- <OrderNr>100245</OrderNr> -->
      <!-- <ItemId>4711</ItemId> -->
    </ns1:pixiTagMatchAdd>
  </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 = [
    'TagId' => '12',
    // 'OrderNr' => '100245',
    // 'ItemId' => '4711',
];

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

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