pixiItemGetByTags · Pixi API documentation

Searches items by the tags assigned to them (table TagMatch).

1. Parsing the filter

TagFilter is an XML document with a root TagFilter and the groups AND, OR and NOT. Each group can contain any number of TagId and TagName elements. Names are trimmed; empty names count as missing.

2. Resolving tags

Each entry is resolved against tags of type TypeId = 1:

TagId is compared with the tag ID.
TagName is compared exactly when PartialTagNameMatch = 0, or with LIKE '%name%' when PartialTagNameMatch = 1. A partial name can resolve to several tags.

3. Validation

The call stops with a status result set and returns no items when:

an entry cannot be resolved to any tag, or
the same tag is resolved more than once. This applies across groups, within a group, and when a tag is given both by ID and by name.

In that case one row is returned per filter entry:

Faulty entries get Status = ERROR.
Valid entries get OK with Complete match on TagName, Partial match on TagName or Complete match on TagId.

4. Selecting items

Only items that have at least one tag assigned in TagMatch are considered. An item is returned if it has none of the NOT tags and at least one of these is true:

no AND and no OR tags were given (only NOT, or an empty filter);
it has all AND tags. With StrictANDCondition = 1 it must also have no other tags at all, so its tag set equals the AND set exactly;
it has at least one OR tag.

AND and OR are combined with OR. OR tags therefore widen the result instead of narrowing it.

The result contains ItemId, ItemNrInt and ItemName. Rows are distinct and not sorted.

Notes

All tables are read with NOLOCK, so uncommitted data may be read.
The conversion of TagFilter to XML happens before the error handling. Malformed XML therefore comes back as a SQL error (SqlMessage), not as a status row.
A non-numeric TagId value causes a conversion error inside the error handling. The result is the single status row Unexpected error occured while parsing the @TagFilter parameter.
The behaviour for a NULL TagFilter is not handled explicitly in the code.
Only tags with TypeId = 1 can be used in the filter.
The strict AND check considers every tag assigned to the item in TagMatch, regardless of its type.
The procedure returns 1 after a status result set. Status rows and item rows never appear in the same call; both arrive as SqlRowSet1. Check for a Status column to tell them apart.
With PartialTagNameMatch = 1, a short name can hit several tags. It can easily overlap with other entries and trigger Tag used in another operation.

Tables used

Tag · Read TagMatch · Read items · Read

Parameter Type Default Description

Parameter	Type	Default	Description
`TagFilter` Required	varchar(max) xml	–	XML filter with root `TagFilter` and optional groups `AND`, `OR` and `NOT`, each containing `TagId` and/or `TagName` elements. Example: `<TagFilter> <AND> <TagId>12</TagId> <TagName>Summer</TagName> </AND> <OR> <TagId>15</TagId> <TagName>New</TagName> </OR> <NOT> <TagId>20</TagId> <TagName>Discontinued</TagName> </NOT> </TagFilter>`
`PartialTagNameMatch`	bit boolean	0	Controls how `TagName` entries are matched against tag names. Allowed values `0` – Exact name match `1` – Name contains the given text (LIKE '%text%') Example: `0`
`StrictANDCondition`	bit boolean	0	Controls how strictly the AND group is applied to the tags of an item. Allowed values `0` – Item must have all AND tags; other tags are allowed `1` – Item must have exactly the AND tags and no other tags Example: `0`

TagFilter

Required

varchar(max)
xml

–

XML filter with root TagFilter and optional groups AND, OR and NOT, each containing TagId and/or TagName elements.

Example:

<TagFilter>
  <AND>
    <TagId>12</TagId>
    <TagName>Summer</TagName>
  </AND>
  <OR>
    <TagId>15</TagId>
    <TagName>New</TagName>
  </OR>
  <NOT>
    <TagId>20</TagId>
    <TagName>Discontinued</TagName>
  </NOT>
</TagFilter>

PartialTagNameMatch

bit
boolean

0

Controls how TagName entries are matched against tag names.

Allowed values

0 – Exact name match
1 – Name contains the given text (LIKE '%text%')

Example: 0

StrictANDCondition

bit
boolean

0

Controls how strictly the AND group is applied to the tags of an item.

Allowed values

0 – Item must have all AND tags; other tags are allowed
1 – Item must have exactly the AND tags and no other tags

Example: 0

Result set 1 · On success (filter fully resolved, no duplicate tags)

Distinct items matching the tag filter, unsorted.

Column	Type	Description
`ItemId`	int	Item key (`items.ItemKey`).
`ItemNrInt` Nullable	string	Internal item number.
`ItemName` Nullable	string	Item name.

Result set 2 · Instead of the item list, if a filter entry is not found, a tag is resolved more than once, or parsing fails

One status row per filter entry, showing the resolution result. On an unexpected error, a single row with all columns NULL except Status and StatusMessage.

Column	Type	Description
`Operation` Nullable	varchar(3) string	Filter group: `AND`, `OR` or `NOT`.
`XMLTagId` Nullable	nvarchar(1024) string	`TagId` value as given in the XML.
`XMLTagName` Nullable	nvarchar(1024) string	`TagName` value as given in the XML (trimmed).
`TagId` Nullable	int	Resolved tag ID; NULL if not found.
`TagName` Nullable	varchar(50) string	Resolved tag name; NULL if not found.
`Status`	varchar(10) string	`OK` or `ERROR`.
`StatusMessage`	varchar(255) string	Explanation of the status, e.g. `Complete match on TagId` or `TagId or TagName not found`.

Response example

<SqlRowSet1>
  <row>
    <ItemId>4711</ItemId>
    <ItemNrInt>ART-10023</ItemNrInt>
    <ItemName>Garden chair teak</ItemName>
  </row>
  <row>
    <ItemId>4712</ItemId>
    <ItemNrInt>ART-10024</ItemNrInt>
    <ItemName>Garden table teak</ItemName>
  </row>
</SqlRowSet1>

Status	Message	Cause
ERROR	TagId or TagName not found	A `TagId` or `TagName` entry matches no tag with `TypeId = 1`, or a name is empty. Use existing tag IDs or names.
ERROR	Tag used in another operation	The same tag is resolved by more than one filter entry: in different groups, twice in one group, by ID and name, or via overlapping partial names. Each tag may appear only once in the whole filter.
ERROR	Insufficient data to identify Error	A resolved entry could not be classified while the status list was built after another error. Review the other status rows.
ERROR	Unexpected error occured while parsing the @TagFilter parameter	Any error during XML processing or tag resolution, e.g. a non-numeric `TagId` value. Send numeric tag IDs and a valid structure.

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:pixiItemGetByTags>
      <TagFilter><![CDATA[<TagFilter><AND><TagId>12</TagId><TagName>Summer</TagName></AND><OR><TagId>15</TagId><TagName>New</TagName></OR><NOT><TagId>20</TagId><TagName>Discontinued</TagName></NOT></TagFilter>]]></TagFilter>
      <!-- <PartialTagNameMatch>0</PartialTagNameMatch> -->
      <!-- <StrictANDCondition>0</StrictANDCondition> -->
    </ns1:pixiItemGetByTags>
  </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:pixiItemGetByTags>
      <TagFilter><![CDATA[<TagFilter><AND><TagId>12</TagId><TagName>Summer</TagName></AND><OR><TagId>15</TagId><TagName>New</TagName></OR><NOT><TagId>20</TagId><TagName>Discontinued</TagName></NOT></TagFilter>]]></TagFilter>
      <!-- <PartialTagNameMatch>0</PartialTagNameMatch> -->
      <!-- <StrictANDCondition>0</StrictANDCondition> -->
    </ns1:pixiItemGetByTags>
  </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 = [
    'TagFilter' => '<TagFilter><AND><TagId>12</TagId><TagName>Summer</TagName></AND><OR><TagId>15</TagId><TagName>New</TagName></OR><NOT><TagId>20</TagId><TagName>Discontinued</TagName></NOT></TagFilter>',
    // 'PartialTagNameMatch' => '0',
    // 'StrictANDCondition' => '0',
];

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

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