Show full documentation

 Show full documentation

Definition

An interface to query material master data.

Business Context and Use

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>

Prerequisites

There are no prerequisites.

Constraints and Integrity Conditions

General Rules for Using this Web Service

Material

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.

Description

The Description node element contains a language-dependent description.

Example

<Description>
    <Description languageCode="EN">A sample description</Description>
</Description>

Detail

The Details node element contains a language-dependent detailed description.

Example

<Detail>
    <ContentText languageCode="EN">A detailed description of the product</ContentText>
</Detail>

Identified Stock Type Code

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

Quantity Conversion

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

Quantity Characteristic

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

Purchasing

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>

Planning

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>

Availability Confirmation

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

Sales

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>

Logistics

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>

Valuation

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>

Deviant Tax Classification

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 Classification

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.

Customer Part Number

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>

Supplier Part Number

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>

Attachment Folder

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>

More Information

General Information

You can find general information about Web services, their structure and consumption in the Web Services documentation. Please open the Web Services document in a new window.

Scenarios

The following example scenarios can be carried out using the material query service.

E-Commerce Integration

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>

Product Engineering Integration:

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>

 Show full documentation

 Show full documentation

Definition

To query material data by elements.

Business Context and Use

The request message of the operation FindByElements contains the MaterialSelectionByElements node that groups all possible selection parameters.

Structure

Request

Material Selection By Elements

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.

Response

The response contains the list of found materials, log items, and processing conditions.

Material

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.