Receiving Extended Data

Receive attributes of your own alongside the standard fields GAINS sends you. The attributes can come from GAINS itself, or from data you loaded with Sending Extended Data or a Custom Schema. Which attributes each subject returns, and the API label each is returned under, are set up by your GAINS representative; see Extended Data.

Extended data is configured per outbound subject, and applies to every interface that delivers that subject: the GET endpoint and, where one exists, the matching webhook. For example, extended data configured for purchase orders appears both in GET /replenishment/purchase-orders and in the POSubmit webhook. Which subjects carry extended data, and their webhooks, are listed in Outbound Subjects.

Reading extended data

Each record that has extended data configured carries an ExtendedData object, holding one entry per attribute, keyed by its API label. On subjects whose records are nested, it can be configured at each level. For example, an inventory policy can carry it for the item and for each of its locations:

{
  "DataType": "inventory_policy",
  "Data": [
    {
      "ItemCode": "ASM-7701",
      "ItemDescription": "Hub assembly, front",
      "Locations": [
        {
          "LocationCode": "CHI01",
          "LocationName": "Chicago DC",
          "InventoryPolicy": {
            "AdjustedOrq": 120,
            "MinimumOrq": 50,
            "IncrementalOrq": 10,
            "CalcOrq": 118,
            "Rsq": 0,
            "RsqOverride": 0,
            "CalcSs": 34,
            "AdjustedSs": 40,
            "SsOverride": 0,
            "ServiceLevel": 0.95,
            "ServiceLevelMinimum": 0.9,
            "InventoryClass": "A",
            "StockIndicator": "S",
            "LeadTime": 2.0,
            "ForecastError": 0.18,
            "AvgLTTotalDemand": 96
          },
          "ExtendedData": {
            "Region": "Midwest",
            "PlannerCode": null
          }
        }
      ],
      "ExtendedData": {
        "ItemWeightClass": "Heavy"
      }
    }
  ],
  "Paging": {
    "NextCursor": null,
    "CurrentDataCount": 1
  }
}

What to expect in ExtendedData:

• Every record at a configured level carries it, with the same set of keys. An attribute with no value for that record is returned as null rather than left out.
• A level with no extended data configured carries no ExtendedData at all.
• Values keep their type in GAINS: text is returned as a string and a number as a number.

Where extended data can appear

A webhook carries ExtendedData at the same levels as the matching GET. To deliver only the events whose extended data has a given value, see Webhook Filters (ExtendedData.<ApiLabel>).

Filtering by extended data

An attribute your GAINS representative has made available as a filter (IsAvailableAsQueryParam in GET /extended-data) can be passed as a query parameter named after its API label, on any of the endpoints above:

GET /api/v1/inventory/policies?Region=Midwest&InventoryClass=A

• The parameter name is matched case-insensitively; the value exactly. region=Midwest filters like Region=Midwest, but Region=midwest does not match Midwest.
• Each filter takes a single value. To read several values, send one request per value.
• Several filters combine with AND, with each other and with the endpoint's standard parameters.
• On attributes of standard GAINS data, only text attributes filter. A filter on a number or date attribute of standard GAINS data is ignored, without an error. Attributes that come from a custom schema filter whatever their type, with the value compared as given.
• A parameter that is not a filterable attribute is ignored, without an error. A misspelled label therefore returns unfiltered results, so check the label if a filter seems to have no effect.

Errors

When the extended-data setup of your environment is inconsistent, reads of the affected subject answer 400 with the Reason Results are unavailable due to misconfigured extended data. Please validate your extended data configuration. Nothing in your request causes it, so resending does not help: contact your GAINS representative to correct the configuration. Other errors are described in Errors & Retries.

Related

• Extended Data: what extended data is and how it is set up.
• Sending Extended Data
• Outbound Subjects: which subjects and webhooks carry extended data.
• Replenishment Orders
• Forecasts & Demand History
• Inventory Policies
• Webhook Filters
• Webhooks