General Schreiben

pixiTagUpdate

Benennt einen benutzerdefinierten Tag um und aktualisiert optional dessen Beschreibung; liefert eine Status/Message-Zeile.

Aktualisiert einen vorhandenen Datensatz in der Tabelle Tag, also einen Tag, der Artikeln oder Aufträgen zugeordnet werden kann.

Ablauf:

IsSystemTag und TypeId des Tags mit der übergebenen TagId werden gelesen.
Es wird geprüft, ob bereits ein anderer Tag mit demselben Name und derselben TypeId existiert. Tags anderer Typen dürfen denselben Namen tragen.
Die Eingaben werden in dieser Reihenfolge geprüft; die Prüfung endet beim ersten Fehler:
- TagId darf nicht leer sein.
- Name darf weder NULL noch eine leere Zeichenkette sein.
- Der Tag darf kein System-Tag sein (IsSystemTag = 1).
- Der Tag muss existieren.
- Kein anderer Tag desselben Typs darf den neuen Namen bereits verwenden.
Sind alle Prüfungen erfolgreich, wird der Tag aktualisiert:
- Name wird auf Name gesetzt.
- Description wird auf Description gesetzt. Ist Description NULL oder fehlt der Parameter, bleibt die bisherige Beschreibung erhalten.
- RecordModifiedOn wird auf den aktuellen Zeitpunkt gesetzt.
- RecordModifiedByUserId wird auf den Benutzer API gesetzt, ersatzweise auf pixiAdministration, falls kein Benutzer API existiert.
- RowVersion wird um 1 erhöht.

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

Hinweise

Validierungsfehler werden nicht als SQL-Fehler ausgelöst. Sie werden als Zeile mit Status = 'Error' zurückgegeben; daher die Spalte Status auswerten.
Die Aktualisierung läuft in einer eigenen Transaktion. Ist bereits eine Transaktion offen, wird stattdessen ein Savepoint gesetzt. Bei einem unerwarteten Fehler wird zurückgerollt und der Fehler über log.InsertError protokolliert. Dieses Objekt ist nicht beigefügt; was es schreibt, ist hier nicht dokumentiert.
Die Abfragen nach dem vorhandenen Tag und nach doppelten Namen verwenden NOLOCK. Das Update selbst verwendet ROWLOCK.
Name wird nicht getrimmt. Ein Name, der nur aus Leerzeichen besteht, besteht die Leer-Prüfung, da SQL Server nachfolgende Leerzeichen beim Zeichenkettenvergleich ignoriert.
Eine leere Zeichenkette als Description leert die Beschreibung. NULL oder ein fehlender Parameter behält die bisherige Beschreibung.
Bei unerwarteten Fehlern wird der ursprüngliche SQL-Fehlertext auf 80 Zeichen gekürzt.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`TagId`	int	NULL	ID des zu ändernden Tags. Faktisch Pflicht: Ist der Wert leer, wird eine Fehlerzeile zurückgegeben. Beispiel: `12`
`Name`	varchar(50) string	NULL	Neuer Name des Tags. Faktisch Pflicht; der Name muss unter den Tags desselben Typs eindeutig sein. Beispiel: `Express`
`Description`	varchar(4000) string	NULL	Neue Beschreibung des Tags. Bei NULL bleibt die bisherige Beschreibung erhalten. Beispiel: `Orders that are shipped by express delivery`

Antwort

Result-Set 1 · Immer

Eine einzelne Statuszeile mit dem Ergebnis der Aktualisierung.

Spalte	Typ	Beschreibung
`Status`	varchar(10) string	`Success`, wenn der Tag geändert wurde, sonst `Error`.
`Message` Kann leer sein	varchar(100) string	Erfolgsmeldung oder Fehlerursache.

Beispielantwort

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

Fehlermeldungen

Status	Meldung	Ursache
Error	Tag could not be updated or changed, TagId is mandatory and was empty	`TagId` wurde nicht übergeben oder ist NULL. Immer die ID des Tags übergeben.
Error	Tag could not be updated or changed, TagName is mandatory and was empty	`Name` ist NULL oder leer. Einen nicht leeren Namen übergeben.
Error	Tag could not be updated or changed, you selected a system Tag	Der Tag ist als System-Tag markiert (`IsSystemTag = 1`). System-Tags können nicht geändert werden.
Error	Tag could not be updated or changed, because Tag does not exist	Es existiert kein Tag mit der angegebenen `TagId`. Die ID prüfen.
Error	Tag could not be updated or changed, because Tag with this name already exists	Ein anderer Tag desselben Typs verwendet diesen Namen bereits. Einen anderen Namen wählen.
Error	Unexpected error: "{error message}"	Beim Update ist ein unerwarteter SQL-Fehler aufgetreten. Die Änderungen werden zurückgerollt und der Fehler protokolliert; die ersten 80 Zeichen des SQL-Fehlertexts werden zurückgegeben.

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:pixiTagUpdate>
      <!-- <TagId>12</TagId> -->
      <!-- <Name>Express</Name> -->
      <!-- <Description>Orders that are shipped by express delivery</Description> -->
    </ns1:pixiTagUpdate>
  </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:pixiTagUpdate>
      <!-- <TagId>12</TagId> -->
      <!-- <Name>Express</Name> -->
      <!-- <Description>Orders that are shipped by express delivery</Description> -->
    </ns1:pixiTagUpdate>
  </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',
    // 'Name' => 'Express',
    // 'Description' => 'Orders that are shipped by express delivery',
];

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

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

Verwendete Tabellen

Tag · Schreiben UCS_USERS · Lesen

SQL-Objekt:: dbo.pipiTagUpdate