--- title: "Keystone (ITM) Integration" canonical: "https://kb.myframeworks.com.au/space/FRAM/85032987/Keystone%20(ITM)%20Integration" format: markdown --- The **Keystone (ITM)** integration connects Frameworks to the ITM Support Office data warehouse via the Keystone API. The integration automates the management of supplier Electronic Product Catalogue (EPC) records and promotions for ITM member stores, so pricing and product data stays current without manual file imports. ITM (Independent Timber Merchants) is a cooperative of independently-owned timber and building supply stores. ITM Support Office negotiates centralised supply agreements on behalf of member stores and maintains a single source of truth for supplier pricing, product data and promotions. The Keystone integration is how individual stores receive that data into Frameworks. > ✅ For implementation steps, see [EPC Update from Keystone - Implementation Guide](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/85131277). ## Who Uses the Keystone Integration The Keystone integration is used by Frameworks customers who are ITM cooperative member stores. These stores order from individual suppliers but are billed centrally through ITM Support Office. The integration applies to: - **Inventory teams** maintaining current and future supplier pricing. - **Pricing administrators** managing supplier promotions and catalogue updates. - **Branch managers** ensuring price files reflect the supplier and branch they trade with. The integration does not affect customer-facing functionality directly. Stores still raise purchase orders to individual suppliers and handle their own customer pricing. What changes is *how* supplier price and product data is loaded into Frameworks. ## Key Benefits The Keystone (ITM) integration provides: - **Centralised pricing maintenance.** ITM Support Office maintains supplier pricing in a single data warehouse. Stores receive validated, mapped data without managing supplier files themselves. - **Automatic current and future pricing.** Both current-effective and future-dated EPC records are imported and retained, so upcoming promotions and price changes are visible before they take effect. - **Automated daily updates.** A scheduled task pulls the latest pricing each day, removing the need to import files manually. - **Promotion automation.** When the [EPCApiPromoLoad](https://sterlandsupport.atlassian.net/wiki/spaces/FSS/pages/718307359) flag is enabled, supplier promotions published by ITM Support Office are loaded into EPC records during the daily EPC Update from Keystone task run. - **Common product identification.** ITM SKU codes provide a consistent product identifier across the cooperative, supporting reliable supplier-side mapping even where individual stores use different internal product codes. ## How It Works The Keystone integration follows a daily data flow from supplier through ITM Support Office to the individual store. ### Data Flow 1. **Suppliers publish pricing** to ITM Support Office. 2. **ITM Support Office consolidates** supplier data into the Keystone data warehouse, applying the ITM SKU as the common product identifier. 3. **Frameworks pulls data daily** via the Keystone API for each supplier and branch combination configured in the store. 4. **Frameworks matches records** against the store's product file using a fallback hierarchy. 5. **Records are stored** in Frameworks as supplier EPCs, with both current and future-dated pricing retained. > Macro (excerpt) > > > ℹ️ **When EPC costs are applied, Frameworks adjusts for purchasing unit of measure.** The API returns a purchasing conversion factor for each product — the ratio between the purchasing unit of measure (UOM) and the stocking UOM. Where a conversion factor exists, Frameworks divides the EPC cost by that factor to derive the correct standard cost per stocking unit: *Standard Cost = EPC Cost ÷ Purchasing Conversion Factor*. If **Retain GP Up** is enabled on the product, the sell price is recalculated automatically from the corrected standard cost. Products where the purchasing UOM equals the stocking UOM are unaffected. 6. **Promotions load automatically** if the **EPCApiPromoLoad** system flag is enabled. 7. **Future-dated EPCs are merged** into the current-price EPC once their effective date passes, keeping the current EPC accurate. 8. **Users review and apply the EPC** to the product file via the standard EPC workflow. The Keystone integration prepares the EPC; applying it to product records remains a user task. ### Product Matching Hierarchy When the Keystone API returns pricing data, Frameworks matches each record against the local product file using a four-level fallback. The integration looks for a match in this order, stopping at the first match found: 1. **ITM SKU** - The common code maintained by ITM Support Office. This is the preferred match. 2. **Catalogue number** - The vendor catalogue number on the local product record. 3. **Barcode** - The product barcode. 4. **Product ID** - The local Frameworks product code. Records that fail to match on a given field display in **red** in the EPC dashboard, signalling where product mapping needs review. When applying pricing, users can update by Supplier SKU (the ITM code) and by product/barcode (the catalogue number) - applying both is recommended to maximise the match rate. ### Mapping Layers The integration relies on three mapping layers, each configured during implementation: - **Supplier mapping.** Each supplier in Frameworks is mapped to ITM Support Office by setting the ITM creditor on the supplier's [Trading Terms tab](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/28390076/Supplier+Maintenance#Trading-Terms). This routes billing centrally through ITM. - **Branch mapping.** Each Frameworks branch carries a Store ID that identifies it to the Keystone API. The Store ID is set on the branch record in [Branch Maintenance](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/28390994). - **Unit of Measure translation.** Supplier files use ITM-standard units of measure that may differ from the units a store uses internally. [EPC Import Translation Maintenance](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/28409542) maps incoming UOMs to the store's local UOMs across the four UOM types: pricing, purchase, selling and stocking. ### Direct to Site (DTS) Pricing Some supplier products are priced as Direct to Site (DTS) - delivered directly from the supplier to a job site rather than via the store. When the Keystone API returns a record with a `pricingStructureType` beginning with "DTS", Frameworks creates a separate product code by appending the DTS structure code to the base product code. For example, a base product `ABCD` with structure `DTS1` becomes `ABCDDTS1`. This keeps DTS pricing distinct from standard branch pricing for the same product. > ✅ ## Related Information > ✅ > ✅ - [EPC Update from Keystone - Implementation Guide](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/85131277) - Step-by-step setup of the Keystone integration. > ✅ - [EPC Dashboard](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/28409332) - Manage supplier EPC records. > ✅ - [Branch Maintenance](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/28390994) - Where the Store ID is set per branch. > ✅ - [Supplier Maintenance](https://sterlandsupport.atlassian.net/wiki/spaces/FRAM/pages/28390076) - Where the ITM creditor is set per supplier.