Description | Query Materials |
Name | QueryMaterialIn |
Namespace | http://sap.com/xi/A1S/Global |
Process Component Description | Product Data Maintenance |
Process Component Name | ProductDataMaintenance |
Process Component Namespace | http://sap.com/xi/AP/FO/Product/Global |
Deployment Unit Description | Foundation |
Endpoint Activation | By Scoping of Process Component | Operations |
Release Status | Released |
An interface to query material master data.
The web service interface Query Material In enables you to connect external applications to your SAP Business ByDesign system and to query and read materials in your system. The web service interface Query Material In is relevant if your company wants to access and manage product data from external applications.
The web service interface Query Material In offers the operation Find By Elements.
Here is an example of a simple web service request:
<n0:MaterialByElementsQuery_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <MaterialSelectionByElements> <SelectionByInternalID> <InclusionExclusionCode>I</InclusionExclusionCode> <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode> <LowerBoundaryInternalID>MAT*</LowerBoundaryInternalID> <UpperBoundaryInternalID/> </SelectionByInternalID> </MaterialSelectionByElements> <ProcessingConditions> <QueryHitsMaximumNumberValue>100</QueryHitsMaximumNumberValue> <QueryHitsUnlimitedIndicator>false</QueryHitsUnlimitedIndicator> </ProcessingConditions> </n0:MaterialByElementsQuery_sync>
There are no prerequisites.
The Material node element contains all basic information about the material such as ID, product category, and base unit of measure. These fields can be found in the material UI as General data. The InternalID element corresponds to the Material ID on the user interface - the UUID element is not visible on the UI, but can be retrieved only via query and read web services.
Fields that are shared between several processes are also found on this level, for example, the InventoryValuationMeasureUnitCode, which is used in the logistics and financials processes.
The Description node element contains a language-dependent description.
Example
<Description> <Description languageCode="EN">A sample description</Description> </Description>
The Details node element contains a language-dependent detailed description.
Example
<Detail> <ContentText languageCode="EN">A detailed description of the product</ContentText> </Detail>
An IdentifiedStock is a subset of a material that shares a set of common characteristics, is logistically handled separately from other subsets of the same material and is uniquely identified.
The IdentifiedStockTypeCode is used to assign an industry-specific name to the IdentifiedStock.
Identified Stock Type Codes:
Identified Stock Type Code | Description |
---|---|
01 | Batch |
02 | Lot |
03 | Optional Specified Stock |
04 | Mandatory Specified Stock |
Materials support quantity conversion between different units of measure. For example, if the base unit of measure is handled in "Each" but sold as "Pallets", then a conversion rule between these units is needed, as the following example shows.
Note: XPX corresponds to Pallet and Ea to Each.
Example:
<QuantityConversion actionCode="01"> <Quantity unitCode="XPX">1</Quantity> <CorrespondingQuantity unitCode="Ea">100</CorrespondingQuantity> </QuantityConversion>
Quantity Unit Codes:
Quantity unit code | Description |
---|---|
XSX | Set |
XPX | Pallet |
XPK | Package |
XCT | Carton |
XCS | Case |
XCR | Crate |
XBX | Box |
XBG | Bag |
LPA | Liter of pure alcohol |
LTR | Liter |
GLL | Gallon (US) |
GLI | Gallon (UK) |
FTQ | Cubic foot |
MTQ | Cubic meter |
K6 | Kiloliter |
R9 | Thousand cubic meter |
CEN | Hundred |
SEC | Second |
MIN | Minute |
HUR | Hour(s) |
DAY | Day(s) |
WEE | Week |
MON | Month |
ANN | Year |
28 | Kilogram per square meter |
P1 | Percent |
PR | Pair |
MIL | Thousand |
NCL | Number of cells |
CTM | Metric carat |
GRM | Gram |
GFI | Gram of fissile isotope |
ONZ | Ounce |
LBR | Pound |
KUR | Kilogram of uranium |
KSH | Kilogram of caustic soda |
KCC | Kilogram of choline chloride |
KDW | Kilogram drained net weight |
KGM | Kilogram |
KHY | Kilogram of hydrogen peroxide |
KMA | Kilogram of methylamine |
KNI | Kilogram of nitrogen |
KPH | Kilogram of caustic potash |
KPO | Kilogram of potassium oxide |
KSD | Kilogram of substance 90 % dry |
KPP | Kilogram of phosphoric anhydride |
STN | Ton (US) or short ton (UK/US) |
TNE | Ton (metric ton) |
GT | Gross ton |
LTN | Tonne (UK) or long ton (US) |
MMT | Millimeter |
CMT | Centimeter |
INH | Inch |
FOT | Foot |
YRD | Yard |
MTR | Meter |
KMT | Kilometer |
SMI | Mile (statute mile) |
JOU | Joule |
KWH | Kilowatt hour |
MWH | Megawatt hour (1000 kW.h) |
D30 | Terajoule |
D50 | Volt per meter |
EA | Each |
E49 | Working day(s) |
DZN | Dozen |
CCT | Carrying capacity in metric ton |
MTK | Square meter |
ACT | Activity |
5B | Batch |
The Quantity Characteristic node element contains quantity characteristics specifying, for example, the net weight or gross weight for each unit of measure.
In the following example, the net weight (12 kg) and the gross weight (13 kg) are specified.
Example
<QuantityCharacteristic> <QuantityMeasureUnitCode>EA</QuantityMeasureUnitCode> <CharacteristicQuantity unitCode="KGM">12</CharacteristicQuantity> <CharacteristicQuantityTypeCode>NET_WT</CharacteristicQuantityTypeCode> </QuantityCharacteristic> <QuantityCharacteristic> <QuantityMeasureUnitCode>EA</QuantityMeasureUnitCode> <CharacteristicQuantity unitCode="KGM">13</CharacteristicQuantity> <CharacteristicQuantityTypeCode>GROSS_WT</CharacteristicQuantityTypeCode> </QuantityCharacteristic>
Quantity type codes:
Quantity type code | Description |
---|---|
NET_WT | Net Weight |
GROSS_WT | Gross Weight |
NET_VOL | Net Volume |
GROSS_VOL | Gross Volume |
DIM_LENGTH | Length |
BREADTH | Width |
HEIGHT | Height |
The Purchasing node element is organization independent. Therefore, there can be just one Purchasing node within one material.
Purchasing information contains the PurchasingMeasureUnitCode, LifecycleStatusCode, and the purchasing text.
LifeCycleStatusCode
The LifeCycleStatus is a status that indicates the current stage in the life cycle of a material.
Three LifeCycleStatusCodes can exist, InPreparation, Active and Blocked.
When a material is created and exists in the system the status is InPreparation.
When the material is ready to be procured by the customers then the status is Active.
If the customer can no longer use the material the status is Blocked.
LifeCycle StatusCode | Description |
---|---|
1 | In Preparation |
2 | Active |
3 | Blocked |
PurchasingMeasureUnitCode
By default, the base unit of measure is applied as the purchasing unit of measure. If necessary, a different Purchasing UoM can be selected.
If the purchasing UoM is different from the base UoM, a quantity conversion between them is maintained.
PurchasingNote
Purchasing Notes are displayed on purchase orders created for the material. They contain additional product information from a purchasing point of view.
Example:
<Purchasing> <LifeCycleStatusCode>2</LifeCycleStatusCode> <PurchasingMeasureUnitCode>EA</PurchasingMeasureUnitCode> <PurchasingNote> <ContentText languageCode="EN">Purchase Note</ContentText> </PurchasingNote> </Purchasing>
The planning node encapsulates all supply-planning relevant data. The forecast category is valid for all supply planning categories; therefore, it is part of the planning header.
For each supply planning node, which is identified by the SupplyPlanningAreaID, its own planning data can be maintained, which is similar to the corresponding material UI.
It consists of LifeCycleStatus and PlanningQuantity values. Their values always reference the PlanningMeasureUnitCode, which is part of the Material node. The LifeCycleStatusCode can be either In Preparation (1) or Active(2).
ProcurementTypeCode
The ProcurementMethodCode specifies whether and in which form procurement is done.
Procurement Type Code | Description |
---|---|
1 | In-house production |
2 | External procurement |
3 | Source of supply priority rule |
Example:
<ProcurementMethodCode>1</ProcurementMethodCode>
DemandManagementProcedureCode
A DemandManagementProcedureCode specifies a profile for forecast requirements.
The profile for forecast requirements controls the relevance of forecast requirements for planning. It also controls the consumption and creation of forecast requirements.
Demand Management Procedure Code | Description |
---|---|
ADRF | All demand reduce forecast |
ATOS_CPC | All demand consumes current forecasts |
ATOS_MPC | All demand consumes preceding forecasts |
ATOS_SPC | All demand consumes adjacent forecasts |
LotSizeProcedureCode
A lot-size procedure specifies in which form a lot-size during Supply Planning is determined.
The LotSizeProcedureCode is used in Supply Planning to create procurement proposals with suitable lot size quantities to cover uncovered requirements.
Lot Size Procedure Code | Description |
---|---|
1 | Lot-for-lot |
2 | Fixed lot size |
3 | Periodic lot size |
4 | Target stock level |
5 | Target days of supply |
Example:
<LotSizeProcedureCode>1</LotSizeProcedureCode>
PlanningProcedureCode
A Supply Planning Procedure calculates for given requirements the quantity and availability dates of planned receipts.
Planning Procedure Code | Description |
---|---|
1 | Demand-driven Planning |
2 | Consumption-based planning |
3 | Manual planning |
Example:
<PlanningProcedureCode>1</PlanningProcedureCode>
PlannedDeliveryDuration
PlannedDeliveryDuration node element specifies a period of time of a particular length without a fixed start or end time. This period of time is expressed in calendar days.
The representation is as follows:
PnD where 'n' denotes the number of days.
Example:
<PlannedDeliveryDuration>P10D</PlannedDeliveryDuration>
GoodsReceiptProcessingDuration
GoodsReceiptProcessingDuration node element specifies a goods receipt processing duration where only values for hours, minutes, seconds and fractions of seconds are allowed.
The representation is as follows:
PTnHnMnS
Example:
<GoodsReceiptProcessingDuration>PT4H12M40S</GoodsReceiptProcessingDuration>
The AvailabilityConfirmation node offers the maintenance of availability confirmation-related data for each planning area. The status is set to Active before it can be used within its corresponding process.
Example
<AvailabilityConfirmation> <PlanningAreaID>P1100</PlanningAreaID> <LifeCycleStatusCode>2</LifeCycleStatusCode> <ReplenishmentLeadTimeDuration>P4D</ReplenishmentLeadTimeDuration> <AvailabilityCheckScopeCode>A22</AvailabilityCheckScopeCode> <GoodsIssueProcessingDuration>PT5H0M0S</GoodsIssueProcessingDuration> <AvailabilityCheckHorizonDuration>P3D</AvailabilityCheckHorizonDuration> <DisableAutomaticShipFromDeterminationIndicator>true</DisableAutomaticShipFromDeterminationIndicator> </AvailabilityConfirmation>
The LifeCycleStatusCode can be either In Preparation (1) or Active(2).
AvailabilityCheckScopeCode
AvailabilityCheckScopeCode defines the basic methods of the availability check and the sequence of their execution. Basic methods are elementary methods for checking availability. Basic methods are:
· Product availability
· Check against product allocation
· Forecast check
AvailabilityCheckScopeCode | Description |
---|---|
A11 | Stock |
A12 | Stock and released receipts |
A13 | All supply except unfirm receipts |
A14 | Stock and all receipts |
A21 | Stock within horizon |
A22 | Stock and released receipts in horizon |
A23 | Supply except unfirm receipts in horizon |
A24 | Stock and all receipts within horizon |
The Sales node contains all information regarding sales processes. Each sales process is defined by the SalesOrganisationID and the DistributionChannelCode, which can be either Direct sales (01) or Indirect sales (02).
Furthermore, the LifeCycleStatusCode can be either In Preparation (1) or Active (2). The status is set to Active to use the entitlement product in sales processes.
Warranties and sales notes can also be defined for each sales process definition.
The ItemGroupCode can contain the following values:
Item Group Code | Description |
---|---|
CONS | Spare part - consumable |
NORM | Product - delivery-based |
PICK | Spare part (engineer pick-up/sales) |
SHIP | Spare part (advanced ship/sales) |
Example
<Sales> <SalesOrganisationID>P1110</SalesOrganisationID> <DistributionChannelCode>01</DistributionChannelCode> <LifeCycleStatusCode>1</LifeCycleStatusCode> <SalesMeasureUnitCode>EA</SalesMeasureUnitCode> <MinimumOrderQuantityValue>1</MinimumOrderQuantityValue> <ItemGroupCode>NORM</ItemGroupCode> <CashDiscountDeductibleIndicator>true</CashDiscountDeductibleIndicator> <ReferencePriceMaterialInternalID>10000230</ReferencePriceMaterialInternalID> <Warranty> <ProductInternalID>P100702</ProductInternalID> <ValidityPeriod> <StartDate>2012-01-24</StartDate> <EndDate>9999-01-24</EndDate> </ValidityPeriod> </Warranty> <InternalNote> <ContentText>Internal Comments</ContentText> </InternalNote> <SalesNote> <ContentText languageCode="EN">Sales Note</ContentText> </SalesNote> </Sales>
The Logistics node contains information that is relevant for logistics processes. The data of this node is displayed as Logistics data in the material UI. The data refers to a site and can be used in the respective process as soon as the LifeCycleStatus is "Active". Especially storage and production categories can be assigned to a site using this node.
The LifeCycleStatusCode can be either In Preparation (1) or Active(2).
Example
<Logistics> <SiteID>A1100</SiteID> <LifeCycleStatusCode>2</LifeCycleStatusCode> <!-- means "active" --> <CycleCountPlannedDuration>P3D</CycleCountPlannedDuration> <ProductionCategoryID>100001</ProductionCategoryID> <StorageCategoryID>100002</StorageCategoryID> </Logistics>
The material valuation can be defined for a specific company/business residence combination. The financial data cannot be activated unless the material valuation data has been maintained in the system.
Example:
<Valuation> <LifeCycleStatusCode>1</LifeCycleStatusCode> <CompanyID>1000</CompanyID> <BusinessResidenceID>P1100</BusinessResidenceID> </Valuation>
The DeviantTaxClassification node contains tax information that differs from the default taxes. They are used for sales processes and can be found on the UI as Sales.
Note: Tax Codes are dependent on the country and region.
Example
<DeviantTaxClassification> <CountryCode>DE</CountryCode> <RegionCode>03</RegionCode> <TaxTypeCode listID="">1</TaxTypeCode> <TaxRateTypeCode listID="">2</TaxRateTypeCode> <TaxExemptionReasonCode listID="">1</TaxExemptionReasonCode> </DeviantTaxClassification>
Withholding tax classifications are only relevant for purchasing processes. They are maintained similarly to the deviant taxes explained above.
Example
<WithholdingTaxClassification> <CountryCode>CN</CountryCode> <TaxTypeCode listID="">2</TaxTypeCode> <WithholdingTaxIncomeTypeCode>1</WithholdingTaxIncomeTypeCode> </WithholdingTaxClassification>
WithholdingTaxIncomeTypeCode
WithholdingTaxIncomeTypeCode indicates the type of income from a supplier point of view. Each type of income has a rate defined for withholding tax.
The CustomerInternalID identifies an account. The ProductCustomerID contains the customer part number.
Data of this node can be found as part of the Sales data on the material UI.
Example:
<CustomerPartNumber> <CustomerInternalID>CP100110</CustomerInternalID> <ProductCustomerID>CP100110-P100702</ProductCustomerID> </CustomerPartNumber>
The supplier part numbers that are used within purchasing processes.
The SupplierInternalID identifies a supplier. The ProductSupplierID contains the supplier part number.
Example
<SupplierPartNumber actionCode="01"> <SupplierInternalID>S100402</SupplierInternalID> <ProductSupplierID>S100402-M1</ProductSupplierID> <SupplierLeadTimeDuration>P10D</SupplierLeadTimeDuration> </SupplierPartNumber>
The AttachmentFolder node element contains the material attachments.
In the web service request, links and files are differentiated through the CategoryCode:
Category code | Description |
---|---|
1 | Folder |
2 | Document |
3 | Link |
The category codes 2 and 3 are only supported.
The different types of attachments are differentiated by the TypeCode:
Type code | Description |
---|---|
10001 | Standard Attachment |
10011 | Product Image |
10015 | Technical Drawing |
10018 | Product Specification |
10043 | Details for Supplier |
Example
<AttachmentFolder> <Document> <VisibleIndicator>true</VisibleIndicator> <CategoryCode>3</CategoryCode> <TypeCode>10001</TypeCode> <Name>SAP AG Link</Name> <ExternalLinkWebURI>http://www.sap.com</ExternalLinkWebURI> <AlternativeName>SAP AG URL</AlternativeName> <Description languageCode="EN">A hyperlink to SAP AG</Description> </Document> </AttachmentFolder>
You can find general information about Web services, their structure and consumption in the Web Services documentation.
The following example scenarios can be carried out using the material query service.
The following example request returns all materials with IDs beginning with MAT, including general data, description, quantity conversion, and sales data.
<n0:MaterialByElementsQuery_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <MaterialSelectionByElements> <SelectionByInternalID> <InclusionExclusionCode>I</InclusionExclusionCode> <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode> <LowerBoundaryInternalID>MAT*</LowerBoundaryInternalID> </SelectionByInternalID> </MaterialSelectionByElements> <ProcessingConditions> <QueryHitsUnlimitedIndicator>true</QueryHitsUnlimitedIndicator> </ProcessingConditions> <RequestedElements materialTransmissionRequestCode="2"> <Material descriptionTransmissionRequestCode="2" quantityConversionTransmissionRequestCode="2" salesTransmissionRequestCode="1" /> </RequestedElements> </n0:MaterialByElementsQuery_sync>
The following example request returns all materials, including general data, description, and quantity conversion.
<n0:MaterialByElementsQuery_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <MaterialSelectionByElements> <SelectionByInternalID> <InclusionExclusionCode>I</InclusionExclusionCode> <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode> <LowerBoundaryInternalID>*</LowerBoundaryInternalID> </SelectionByInternalID> </MaterialSelectionByElements> <ProcessingConditions> <QueryHitsUnlimitedIndicator>true</QueryHitsUnlimitedIndicator> </ProcessingConditions> <RequestedElements materialTransmissionRequestCode="2"> <Material descriptionTransmissionRequestCode="2" quantityConversionTransmissionRequestCode="2" /> </RequestedElements> </n0:MaterialByElementsQuery_sync>
Description | Find materials |
Name | FindByElements |
Synchronous | yes |
Release Status | Released |
To query material data by elements.
The request message of the operation FindByElements contains the MaterialSelectionByElements node that groups all possible selection parameters.
This node groups all selection parameters. The selection parameters are:
Selection Parameter | Remark |
---|---|
SelectionByDescription | Selection by description LanguageCode attribute can be omitted to search in all languages or have to be specified explicitly, for example, EN for English. |
SelectionByInternalID | Selection by internal ID |
SelectionByIdentifiedStockTypeCode | Selection by identified stock type code:01 Batch 02 Lot 03 Optional Specified Stock 04 Mandatory Specified Stock |
SelectionBySearchText | Selection by search text (Basic Search) |
SelectionByCreatedSinceDateTime | Selection by “created since” date and time Select all materials which were created since the specific date and time. |
SelectionByLastChangeSinceDateTime | Selection by last changed since date and time Select all materials which were last changed since the specific date and time. |
The response contains the list of found materials, log items, and processing conditions.
In this node, all found materials are contained including their material data according to the RequestedElements provided in the query request. This includes the ChangeStateID that may be needed for subsequent change requests using web services as well.