pixiTagUpdate · Pixi API documentation

Updates an existing record in the Tag table, the tags that can be assigned to items or orders.

Steps:

Reads IsSystemTag and TypeId of the tag with the given TagId.
Checks whether another tag with the same Name and the same TypeId already exists. Tags of other types may share the name.
Validates the input in this order and stops at the first failure:
- TagId must not be empty.
- Name must not be NULL or an empty string.
- The tag must not be a system tag (IsSystemTag = 1).
- The tag must exist.
- No other tag of the same type may already use the new name.
If all checks pass, the tag is updated:
- Name is set to Name.
- Description is set to Description. If Description is NULL or left out, the current description is kept.
- RecordModifiedOn is set to the current time.
- RecordModifiedByUserId is set to the user API, or to pixiAdministration if no API user exists.
- RowVersion is increased by 1.

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

Notes

Validation errors are not raised as SQL errors. They are returned as a row with Status = 'Error', so check the Status column.
The update runs in its own transaction. If a transaction is already open, a savepoint is used instead. On an unexpected error the work is rolled back and the error is logged via log.InsertError. That object is not attached, so what it writes is not documented here.
The lookups for the existing tag and for duplicate names use NOLOCK. The update itself uses ROWLOCK.
Name is not trimmed. A name consisting only of spaces passes the empty check, because SQL Server ignores trailing spaces when comparing strings.
Passing an empty string as Description clears the description. Passing NULL or leaving the parameter out keeps the current description.
In unexpected error messages, the original SQL error text is cut to 80 characters.

Tables used

Tag · Write UCS_USERS · Read

Parameter	Type	Default	Description
`TagId`	int	NULL	ID of the tag to update. Effectively mandatory: if it is empty, an error row is returned. Example: `12`
`Name`	varchar(50) string	NULL	New name of the tag. Effectively mandatory; it must be unique among tags of the same type. Example: `Express`
`Description`	varchar(4000) string	NULL	New description of the tag. If NULL, the current description is kept. Example: `Orders that are shipped by express delivery`

Result set 1 · Always

A single status row with the result of the update.

Column	Type	Description
`Status`	varchar(10) string	`Success` if the tag was updated, otherwise `Error`.
`Message` Nullable	varchar(100) string	Success message or the reason for the error.

Response example

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

Status	Message	Cause
Error	Tag could not be updated or changed, TagId is mandatory and was empty	`TagId` was not passed or is NULL. Always pass the ID of the tag.
Error	Tag could not be updated or changed, TagName is mandatory and was empty	`Name` is NULL or an empty string. Pass a non-empty name.
Error	Tag could not be updated or changed, you selected a system Tag	The tag is marked as a system tag (`IsSystemTag = 1`). System tags cannot be changed.
Error	Tag could not be updated or changed, because Tag does not exist	No tag with the given `TagId` exists. Check the ID.
Error	Tag could not be updated or changed, because Tag with this name already exists	Another tag of the same type already uses this name. Choose a different name.
Error	Unexpected error: "{error message}"	An unexpected SQL error occurred during the update. The changes are rolled back and the error is logged; the first 80 characters of the SQL error text are returned.

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