spm-override-proposal.md

Create an SPM Overide: Proposal to Modify Catalog Service HTTP Interface

As part of implementing PAG-1353 we propose an addition to the In Season Catalog Customer Choice HTTP API that will permit the creation of Store Planning Management (SPM) overrides.

Things that the final implementation must permit:

• Create an SPM override-value for a SKU + location combo
• Create an SPM override-value for a CC + location combo

(Existing) Create SPM override for CC + Location

Adam and Jim began adding SPM override capabilities to the Catalog Service. The following example demonstrates how a user would create a a single SPM override associated with a customer choice w/id f9a45623-f427-4405-a6c7-efc7f9ffe776:

Request:

HTTP POST
/allocation/in-season/allocated-customer-choices/ti-overrides

{
    "id": "f9a45623-f427-4405-a6c7-efc7f9ffe776",
    "ccOverrides": [
        {
            "locationId": "01d13476-793b-4220-8a57-00425d6b9af6",
            "overrideValue": 24.0,
            "overrideFactor": null,
            "expirationDate": "2017-06-15",
            "effectiveDate": "2017-01-01"
        }
    ]
}

Response:

HTTP 200 OK "TI overrides successfully saved"

Thoughts on this design:

1. It is not immediately apparent (to me) how this design would be extended to support SKU + location-level overrides
2. overrideFactor can be applied by clients for purposes of effecting a new overrideValue - as such, it can be removed from the API
3. effectiveDate can be removed from the API if overrideFactor is removed from the API
4. It is not clear to me if this design permits clients to remove SPM overrides from locations after they've been created (the PDM states that they expect a planner to nullify an override by setting its expiry date to sometime in the past)
5. Unsure if this is a goal: It is not immediately apparent to me how this design could be extended to admit New Store overrides

Alternative A: Create SPM Override for (SKU or CC) + Location

This proposal addresses items #1, #2, #3 and #4 from above - but admits only SPM overrides (does not address #5):

Request:

HTTP POST
/allocation/in-season/allocated-customer-choices/ti-overrides

{
    "level_identifier_type": "CUSTOMER_CHOICE_ID",
    "level_identifier_value": "f9a45623-f427-4405-a6c7-efc7f9ffe776",
    "location_id": "01d13476-793b-4220-8a57-00425d6b9af6",
    "expiry_date": "2016-06-15",
    "value": 25.6
}

Response:

HTTP 204 No Content

Request:

HTTP POST
/allocation/in-season/allocated-customer-choices/ti-overrides

{
    "level_identifier_type": "SKU_NBR",
    "level_identifier_value": "1895510210000",
    "location_id": "01d13476-793b-4220-8a57-00425d6b9af6",
    "expiry_date": "2016-06-15",
    "value": 15
}

Response:

HTTP 204 No Content

Notes:

• "Create SPM" is an idempotent operation; previous override matching location and customer choice id is replaced (note: overrides cannot be deleted, only replaced)
• SKU and CC-level overrides are visible in the In Season Catalog Customer Choice JSON (implementation: TBD)
• Overrides do not have identity (they are subordinate to/embedded within some other HTTP "resource")
• URL handles creation of SPM overrides only (you'll note that there's no way to specify a version or that the override relates to a new-location instead of location)

Alternative B: Create SPM Override for (SKU or CC) + Location

This proposal addresses items #1, #2, #3, #4, and #5 from above:

Request:

HTTP POST
/allocation/in-season/allocated-customer-choices/ti-overrides

{
    "version": "STORE_PLANNING_MANAGEMENT",
    "level_identifier_type": "CUSTOMER_CHOICE_ID",
    "level_identifier_value": "f9a45623-f427-4405-a6c7-efc7f9ffe776",
    "location_identifier_type": "LOCATION_ID",
    "location_identifier_value": "01d13476-793b-4220-8a57-00425d6b9af6",
    "expiry_date": "2016-06-15",
    "value": 25.6
}

Response:

HTTP 204 No Content

Request:

HTTP POST
/allocation/in-season/allocated-customer-choices/ti-overrides

{
    "version": "NEW_STORE",
    "level_identifier_type": "SKU_NBR",
    "level_identifier_value": "1895510210000",
    "location_identifier_type": "NEW_LOCATION_ID",
    "location_identifier_value": "fdbb9d86-34a8-47d2-b498-b4b5dbac82cc",
    "expiry_date": "2016-06-15",
    "value": 25.6
}

Response:

HTTP 204 No Content

Notes:

• Permits associating the override with either a new-location or a location (NEW_LOCATION_ID or LOCATION_ID)
• Permits different override "verions": NEW_STORE and STORE_PLANNING_MANAGEMENT

Some quick thoughts:

Is a general purpose endpoint appropriate?

• Do we know if all overrides look the same? Does an inventory push override look like an SPM override?
• What does it mean to set an override for a CC? Does it make sense to only support setting an override for a sku/location at the API level?
• If setting an override does make sense at a CC level, is there logic associated with how the factor or the value is applied to each sku? Is that logic consistent between override types (new store, spm, inventory push)
• If this endpoint is general purpose, does it make sense to drop effective date and factor from the API? Perhaps inventory push can create overrides that start in the future.
• I see you're attempting to eliminate factor, but I wonder if factor is a value that can be applied to the base TI at any point between the start and end date.
• Is the logic of applying the factor something that should be pushed to clients of this API? Or is applying the factor something that is best consolidated inside of the TI service.

I like the idea of an idempot endpoint, but...

• Can there be more than one SPM override for a cc/location? Idempotent collection resources are, you know, fussy.
• I wonder how this would work if overrides need to be persisted to maintain a history / audit trail.