General Schreiben

pixiTagCreate

Legt einen neuen Tag eines angegebenen Tag-Typs (für Artikel oder Aufträge) an, sofern noch kein Tag mit gleichem Typ und Namen existiert.

Legt einen Tag-Datensatz in Pixi an. Tags dienen zur Kennzeichnung von Artikeln oder Aufträgen. Der Aufruf liefert eine Statuszeile mit Status und Message.

Ablauf:

Prüfung. TypeID muss auf einen vorhandenen Tag-Typ verweisen, und Name darf nicht leer sein. Schlägt die Prüfung fehl, wird kein Tag angelegt und Status ist Error. Die Prüfungen erfolgen in dieser Reihenfolge:
- TypeID und Name fehlen beide
- TypeID fehlt
- kein Tag-Typ mit dieser TypeID vorhanden
- Name leer
Dublettenprüfung. Es wird gezählt, wie viele Tags mit gleicher TypeID und gleichem Name bereits existieren. Ist mindestens einer vorhanden, wird nichts eingefügt und Status ist Information.
Anlage. Andernfalls wird ein neuer Tag angelegt mit:
- dem angegebenen Typ und Namen
- Description; NULL wird als Leerstring gespeichert
- IsSystemTag = 0
Status ist dann Success.

Die ID des neuen Tags wird nicht zurückgegeben.

Hinweise

Transaktionen: Der Aufruf läuft in einer eigenen Transaktion. Wird er innerhalb einer bestehenden Transaktion aufgerufen, wird stattdessen ein Savepoint verwendet. XACT_ABORT ist aktiv.
Fehlerbehandlung: Bei einem unerwarteten Fehler wird die Transaktion zurückgerollt und der Fehler über log.InsertError protokolliert (Definition nicht beigefügt). Es wird trotzdem eine Statuszeile mit Status = Error geliefert; ein SQL-Fehler wird nicht ausgelöst.
Dubletten: Die Prüfungen auf Tag-Typ und Dubletten lesen mit NOLOCK. Gleichzeitige Aufrufe mit gleichem Typ und Namen können daher beide einen Tag anlegen, sofern kein Unique-Constraint auf Tag dies verhindert; ein solcher Constraint ist im Code nicht ersichtlich.
Namensvergleich: Ob Namen unter Beachtung der Groß-/Kleinschreibung verglichen werden, hängt von der Datenbank-Collation ab.
Meldungstext: In der Meldung 'already exists' wird der Name auf 20 Zeichen gekürzt.
Tag-ID: Die ID des neuen Tags wird nicht zurückgegeben und muss separat ermittelt werden.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`TypeID`	int	NULL	ID des Tag-Typs (`TagType.Id`). Faktisch Pflicht; muss auf einen vorhandenen Tag-Typ verweisen. Beispiel: `1`
`Name`	varchar(50) string	NULL	Name des neuen Tags. Faktisch Pflicht; darf nicht leer sein. Zusammen mit `TypeID` muss er eindeutig sein, sonst wird kein Tag angelegt. Beispiel: `Express`
`Description`	varchar(4000) string	–	Optionale Beschreibung des Tags. `NULL` wird als Leerstring gespeichert. Beispiel: `Orders to be shipped with express delivery`

Antwort

Result-Set 1 · Immer

Eine Statuszeile mit dem Ergebnis des Aufrufs.

Spalte	Typ	Beschreibung
`Status`	varchar(254) string	Ergebnis des Aufrufs: `Success` (Tag angelegt), `Information` (Tag existiert bereits) oder `Error` (Prüf- oder unerwarteter Fehler).CHECK_PLACEHOLDER
`Message` Kann leer sein	varchar(2000) string	Text zum Ergebnis bzw. zum Fehler.

Beispielantwort

<SqlRowSet1>
  <row>
    <Status>Success</Status>
    <Message>New tag was successfully created</Message>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status	Meldung	Ursache
Error	Mandatory parameters TypeID and Name are missing	Weder `TypeID` noch `Name` wurde übergeben. Beide Parameter übergeben.
Error	Mandatory parameter TypeID is missing	`TypeID` wurde nicht übergeben. Die ID eines vorhandenen Tag-Typs übergeben.
Error	Tag type with TypeID: {TypeID} does not exist	Es existiert kein Tag-Typ mit der angegebenen `TypeID`. Eine gültige Tag-Typ-ID verwenden.
Error	Mandatory parameter Name is missing	`Name` fehlt oder ist leer. Einen nicht leeren Tag-Namen übergeben.
Information	Tag with TypeID({TypeID}) and TagName({Name}) already exists	Ein Tag mit gleichem Typ und Namen existiert bereits; es wurde nichts eingefügt. Der Name in der Meldung wird auf 20 Zeichen gekürzt.
Error	Unexpected error: "{error message}"	Ein unerwarteter SQL-Fehler ist aufgetreten, z. B. eine Constraint-Verletzung. Die Transaktion wird zurückgerollt und der Fehler protokolliert. Der Fehlertext wird auf 80 Zeichen gekürzt.

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:pixiTagCreate>
      <!-- <TypeID>1</TypeID> -->
      <!-- <Name>Express</Name> -->
      <!-- <Description>Orders to be shipped with express delivery</Description> -->
    </ns1:pixiTagCreate>
  </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:pixiTagCreate>
      <!-- <TypeID>1</TypeID> -->
      <!-- <Name>Express</Name> -->
      <!-- <Description>Orders to be shipped with express delivery</Description> -->
    </ns1:pixiTagCreate>
  </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 = [
    // 'TypeID' => '1',
    // 'Name' => 'Express',
    // 'Description' => 'Orders to be shipped with express delivery',
];

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

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

Verwendete Tabellen

TagType · Lesen Tag · Schreiben

SQL-Objekt:: dbo.pipiTagCreate