General Schreiben

pixiTagMatchAdd

Weist ein vorhandenes Tag je nach Tag-Typ einem Artikel oder einem Auftrag zu und liefert eine Statuszeile.

Legt eine Tag-Zuordnung (eine Zeile in TagMatch) für das in TagId angegebene Tag an.

Ablauf:

Der Typ des Tags wird aus Tag gelesen. Der Typ bestimmt, welchem Objekt das Tag zugeordnet werden kann:
- TypeId = 1: Artikel-Tag, ItemId ist Pflicht und muss als ItemKey in items existieren.
- TypeId = 2: Auftrags-Tag, OrderNr ist Pflicht und muss als OrderNr in OrderHeader existieren. Die Auftragsnummer wird in den internen OrderHeaderKey übersetzt.
Es wird geprüft, ob das Tag dem angegebenen Artikel bzw. Auftrag bereits zugeordnet ist.
Die Prüfungen erfolgen in dieser Reihenfolge, die erste fehlgeschlagene bestimmt das Ergebnis: fehlende TagId, unbekanntes Tag, fehlende ItemId/OrderNr für den Tag-Typ, unbekannter Artikel/Auftrag, bereits vorhandene Zuordnung.
Sind alle Prüfungen erfolgreich, wird die Zuordnung angelegt. Bei einem Artikel-Tag wird nur der Artikel gespeichert, bei einem Auftrags-Tag nur der Auftragskopf-Schlüssel; der jeweils andere Parameter wird ignoriert.

Der Aufruf liefert immer genau eine Zeile mit Status (Success, Warning oder Error) und Message.

Hinweise

Die Verarbeitung läuft in einer eigenen Transaktion bzw. in einem Savepoint, wenn der Aufrufer bereits eine Transaktion geöffnet hat. Bei einem unerwarteten Fehler werden die Änderungen zurückgerollt, der Fehler über log.InsertError protokolliert und statt einer SqlMessage eine Statuszeile mit Unexpected error: "…" (erste 80 Zeichen der SQL-Fehlermeldung) geliefert.
Die Abfragen verwenden NOLOCK; die Dublettenprüfung kann daher nicht festgeschriebene Daten lesen, und zwei parallele Aufrufe könnten beide die Prüfung bestehen.
Die Dublettenprüfung vergleicht das Tag mit dem Auftrag oder dem Artikel. Werden OrderNr und ItemId gemeinsam übergeben, führt eine vorhandene Zuordnung zu einem der beiden zur Warning, auch wenn sie nicht zum Tag-Typ passt.
Bei Tags, deren TypeId weder 1 noch 2 ist, findet keine Artikel-/Auftragsprüfung statt, und es wird eine TagMatch-Zeile mit leerem ItemId und OrderHeaderId angelegt.
OrderNr ist die sichtbare Auftragsnummer, nicht der interne OrderHeaderKey; ItemId ist der interne ItemKey.
Der Kopfkommentar der Prozedur („Get tags for objects“) passt nicht zum Verhalten; die Prozedur schreibt Daten.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`TagId` Pflicht	int	–	ID des zuzuordnenden Tags (`Tag.Id`). Sein Typ bestimmt, ob `ItemId` oder `OrderNr` verwendet wird. Beispiel: `12`
`OrderNr`	int	NULL	Auftragsnummer (`OrderHeader.OrderNr`), der das Tag zugeordnet wird. Pflicht für Auftrags-Tags (`TypeId` = 2), bei Artikel-Tags ignoriert. Beispiel: `100245`
`ItemId`	int	NULL	Interner Artikelschlüssel (`items.ItemKey`), dem das Tag zugeordnet wird. Pflicht für Artikel-Tags (`TypeId` = 1), bei Auftrags-Tags ignoriert. Beispiel: `4711`

Antwort

Result-Set 1 · Immer

Eine Statuszeile mit dem Ergebnis der Zuordnung.

Spalte	Typ	Beschreibung
`Status`	varchar(10) string	`Success`, wenn das Tag zugeordnet wurde, `Warning`, wenn es bereits zugeordnet war, sonst `Error`.
`Message`	varchar(100) string	Ergebnistext, z. B. `Tag was successfully assigned` oder der Grund des Fehlers.

Beispielantwort

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

Fehlermeldungen

Status	Meldung	Ursache
Error	Mandatory parameter is missing	`TagId` fehlt, oder `ItemId` fehlt bei einem Artikel-Tag (`TypeId` = 1), oder `OrderNr` fehlt bei einem Auftrags-Tag (`TypeId` = 2). Den zum Tag-Typ passenden Parameter übergeben.
Error	One of the provided values is not valid	Das Tag existiert nicht, oder der angegebene Artikel (`ItemKey`) bzw. die Auftragsnummer existiert für den Tag-Typ nicht. IDs vor dem Aufruf prüfen.
Warning	Tag is already assigned	Das Tag ist dem angegebenen Artikel bzw. Auftrag bereits zugeordnet. Es wird nichts angelegt.
Error	Unexpected error: "{error}"	Bei der Verarbeitung ist ein SQL-Fehler aufgetreten; `{error}` enthält die ersten 80 Zeichen der SQL-Fehlermeldung. Die Transaktion wird zurückgerollt und der Fehler protokolliert.

Beispiele

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);

Verwendete Tabellen

Tag · Lesen items · Lesen OrderHeader · Lesen TagMatch · Schreiben

SQL-Objekt:: dbo.pipiTagMatchAdd