| Description | Product Design Replication A2A |
| Name | ProductEngineeringFoundationProductDesignReplicationIn |
| Namespace | http://sap.com/xi/AP/PC/ProductEngineeringFoundation/Global |
| Product | SAP Business ByDesign |
| Process component | Product Engineering |
| Process component namespace | http://sap.com/xi/AP/PC/ProductEngineeringFoundation/Global |
| Deployment unit | Foundation |
| Endpoint Activation | By Communication Arrangement | Operations |
|
| Release Status | Not Released |
| Technical documentation on the SAP API Business Hub | Product Design Replication A2A |
| General web service documentation | A2X Web Services (SOAP) |
An interface to replicate a product design.
The web service interface Product Design Replication Request enables you to connect external CAD applications to your SAP Business ByDesign system, and through the engineering design, to automatically create and update product designs in your system.
The web service interface Product Design Replication Request is relevant if your company wants to create and update Product Designs from external CAD applications.
The web service interface Product Design Replication Request offers the operations ReplicateProductDesign and ReplicateProductDesignBulk.
The Product Design can be created or updated by the asynchronous service Product Design Replication Request. In most cases, there will be a corresponding object in the engineering system. In the service definition and in this document the corresponding object of the engineering system is called Engineering Design. In concrete systems, this object would be called differently, for example, engineering BOM, assembly, part, or item.
The logical communication takes place between the objects Engineering Design and Product Design. In SAP Business ByDesign Materials can be assigned to Product Designs and Product Designs can be converted into Production Bills of Material Variants. Production Bills of Material Variants are not created directly using the inbound interface but require additional steps on the SAP Business ByDesign side.
An Engineering Design cannot be assigned to more than one Product Design. In addition, one Product Design can refer to only one Engineering Design.
If an Engineering Design is not assigned to a Product Design. This means, that the Engineering Design has not been replicated in SAP Business ByDesign. The second Engineering Design is assigned to a Product Design in SAP Business ByDesign. This assignment cannot be changed afterwards and the Engineering Design cannot be assigned to another Product Design. The last Product Design has no reference to an Engineering Design, meaning this Product Design has been created manually in SAP Business ByDesign.
Besides the mapping between an Engineering Design and a Product Design, there is also the mapping between an Engineering Design Version and a Product Design Version. In existing engineering systems Engineering Design Version may represent a version, a revision or another entity. Once a Product Design Version has been assigned to an Engineering Design Version via the CAD-integration interface, the assignment can’t be changed any longer.
Each Product Design must have at least one version in order to be displayed in the UI. Similar to the mapping between Engineering Design and Product Design, a version of an Engineering Design can be assigned at maximum to one version of a Product Design and vice versa.
Not all versions of an engineering design need to be replicated to SAP Business ByDesign. On the other hand it is possible to manually create a version for a Product Design that refers to an Engineering Design.
Example of a simple web service request:
Show full documentation
Show full documentation <ns1: ProductDesignReplicationRequest xmlns:ns1="http://sap.com/xi/AP/PC/ProductEngineeringFoundation/Global" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<MessageHeader>
<ID>20101001003</ID>
<CreationDateTime>2011-11-23T11:00:48.000+01:00</CreationDateTime>
<SenderBusinessSystemID>X</SenderBusinessSystemID>
<BusinessScope>
<TypeCode>3</TypeCode>
<ID>229</ID>
</BusinessScope>
</MessageHeader>
<ProductDesign actionCode="04" versionListCompleteTransmissionIndicator="false">
<ID>PD_1</ID>
<EngineeringDesignBusinessSystemName>Eng_Sys</EngineeringDesignBusinessSystemName>
<EngineeringDesignBusinessSystemID>Eng_Sys_ID</EngineeringDesignBusinessSystemID>
<EngineeringDesignID>ENG_1</EngineeringDesignID>
<EngineeringDesignInternalID>ENG_1</EngineeringDesignInternalID>
<CategoryCode>1</CategoryCode>
<ResponsibleEmployeeID>7000001</ResponsibleEmployeeID>
<Version actionCode="04" versionCompleteTransmissionIndicator="true">
<EngineeringDesignVersionID>1</EngineeringDesignVersionID>
<EngineeringDesignVersionInternalID>1</EngineeringDesignVersionInternalID>
<PredecessorVersionEngineeringDesignBusinessSystemName/>
<PredecessorVersionEngineeringDesignBusinessSystemID/>
<PredecessorVersionEngineeringDesignID/>
<PredecessorVersionEngineeringDesignInternalID/>
<PredecessorVersionEngineeringDesignVersionID/>
<PredecessorVersionEngineeringDesignVersionInternalID/>
<BaseQuantity unitCode="EA">1</BaseQuantity>
<BaseQuantityTypeCode/><ProposedProcurementMethodCode/>
<EngineeringDesignVersionStatusName>Released by Engineering</EngineeringDesignVersionStatusName>
<EngineeringDesignVersionResponsibleEngineerPersonFamilyName/>
<EngineeringDesignVersionResponsibleEngineerPersonGivenName/>
<EngineeringDesignVersionReplicationCancelledIndicator>false</EngineeringDesignVersionReplicationCancelledIndicator>
<EngineeringDesignVersionCreationDateTime>2009-12-01T09:37:40.000+01:00</EngineeringDesignVersionCreationDateTime>
<EngineeringDesignVersionLastChangeDateTime>2009-12-01T09:37:40.000+01:00</EngineeringDesignVersionLastChangeDateTime>
<ExecutionUsageBlockingStatusCode/>
<EngineeringDesignVersionReleaseStatusCode>3</EngineeringDesignVersionReleaseStatusCode>
<Description languageCode="en">Uploaded Design</Description>
<Component>
<ProductDesignComponentID>10</ProductDesignComponentID>
<BaseQuantity unitCode="EA">2</BaseQuantity>
<BaseQuantityTypeCode listID="" listVersionID="" listAgencyID="" listAgencySchemeID="" listAgencySchemeAgencyID=""></BaseQuantityTypeCode>
<EngineeringDesignBusinessSystemName>Producstream</EngineeringDesignBusinessSystemName>
<EngineeringDesignBusinessSystemID>PS01</EngineeringDesignBusinessSystemID>
<EngineeringDesignID schemeID="" schemeVersionID="" schemeAgencyID=""></EngineeringDesignID>
<EngineeringDesignInternalID schemeID="" schemeVersionID="" schemeAgencyID="">TEST_ASSEMBLY_HIER</EngineeringDesignInternalID>
<EngineeringDesignVersionID>3</EngineeringDesignVersionID>
<EngineeringDesignVersionInternalID>3</EngineeringDesignVersionInternalID>
<TextCollection >
<Text >
<TypeCode>10006</TypeCode>
<ContentText languageCode="EN">Component text</ContentText>
</Text>
</TextCollection>
</Component>
<TextCollection >
<Text >
<TypeCode>10011</TypeCode>
<ContentText languageCode="EN">Version text</ContentText>
</Text>
</TextCollection>
</Version>
</ProductDesign>
</ns1:ProductDesignReplicationRequest>
For a Material to be used in a Product Design, it has to be maintained first.
Action codes represent an instruction to the recipient of the web service request to process transmitted message node elements.
The action codes determine whether an object shall be created, updated or deleted. In the ProductDesignReplication message action codes exist both on product design level and on version level.
It is possible to distinguish between strict and weak action codes:
Strict action codes
01 Create
02 Change
03 Delete
Weak action codes
04 Save
05 Remove
The strict action codes prevent the unintended update of an incorrectproduct design. If for example a new product design is created and the message contains the wrong EngineeringDesignInternalID, another object may be updated instead of creating an error task because of the incorrect ID/action code combination.
It is important to note that the action code for the product design may be different than the action code for a version. If for example a new version is added to an existing product design, then the action code Change or Save must be used for the product design but the action code Create or Save must be used for the version.
The following is a list of available action codes:
| Action Code | Description |
|---|---|
| 01 | Create - A new product design shall be created. If the corresponding product design already exists, the message processing stops with an error. |
| 02 | Change - An existing product design shall be updated. If the corresponding product design doesn’t exist yet, the message processing stops with an error. |
| 03 | Delete - An existing product design version will never be deleted automatically by an incoming message. If this action code is used, the ReplicationCancelledIndicator is set for the specified product design version. This means, that no further message updates are expected. If the product design version is not released yet, it can then be deleted manually. If the product design version doesn’t exist yet, the processing stops with an error. |
| 04 | Save - combines the two action codes Create and Change: If the product design doesn’t exist yet, it will be created. If it already exists it will be modified. The action code Save guarantees, that the update message is processed. If strict action codes are used and the update message is processed before the create message, the processing of the update message ends with an error task. The create message is processed successfully afterwards. |
| 05 | Remove - For all versions of a product design the replication cancelled indicator shall be set to true. (This action code works in the same manner as action code Delete described above.) |
The XML message can be used to transfer either parts of an engineering design or the complete engineering design. On version level it is also possible to transfer only parts of an engineering design version or the complete definition of the engineering design version. The CompleteTransmissionIndicators are used to differentiate between these two cases.
If the indicator is set to true for an engineering design version, then an existing product design version is replaced by the engineering design version. If the product design version contains data which is not included in the corresponding message, the data is deleted. Of course this is only true for data that can be created and/or changed by the inbound interface. If the indicator is set to false, only the attributes which are included in the current message are updated.
Example
The XML message contains data for a specific engineering design version. A product design version for this engineering design version has already been created by a previous message. The previous message also included information about components, meaning that the corresponding product design version contains components too. The current message doesn’t contain any components. The following table displays the result of the indicator in this situation:
| Complete Transmition Indicator Value | Description |
|---|---|
| False | The component information of the product design version is not changed. The message is interpreted as a delta message which doesn’t update the component information. |
| True | The component information of the product design version is deleted. The message is interpreted as a complete picture of the engineering design. Since the message doesn’t contain any components, the existing components of the product design version have to be removed. |
On engineering design level, the indictor is used to synchronize the number of replicated versions. If the VersionListCompleteTransmissionIndicator is set to true, then all engineering design versions, that shall be replicated, have to be part of the message. For each product design version that belongs to the same engineering design, but has no corresponding engineering design version in the current message, the ReplicationCancelledIndicator will be set to true. Versions that are included in the message but that are not created yet in SAP Business ByDesign, will be created during processing of the message. It is possible to create several product design versions with one message call.
If the versionListCompleteTransmissionIndicator is set to true, then synchronization between the engineering system and SAP Business ByDesign takes place. In order synchronize both systems, the complete definition of the individual versions shall be transferred. Even if it is not enforced by the system, the versionCompleteTransmissionIndicator shall be set to true for all included versions. If a missing product design version has to be created in SAP Business ByDesign and the engineering design version has already been released, then the complete message processing would stop with an error if the version is set to false.
If the product design version has been released by engineering, then the main parts of the product design version can no longer be changed by the replication message. Therefore, it has to be ensured, that the definition of the product design version is complete when the engineering design release takes place. For this reason, the processing of the message would stop with an error if the engineering release is transferred and the versionCompleteTransmissionIndicator is set to false. Once the product design version has been released by engineering, the following delta messages are accepted again.
The order in which messages are processed by the receiving part is important. The sequence of the messages may always be changed at runtime. This can happen because the used infrastructure doesn’t guarantee the message sequence or because of errors that occur during message processing. The inbound interface for the product design is able to detect and to handle obsolete messages. This is done by the element EngineeringDesignVersionLastChangeDateTime. This contains the timestamp when the engineering design has been changed in the engineering system. This timestamp is stored in the corresponding product design version. If a product design version is updated by a replication message, then the EngineeringDesignVersionLastChangeDateTime of the message is compared with the corresponding timestamp of the product design version. Only if the message contains a “newer” timestamp, the message is processed. If the message contains the same timestamp or an older one, the message is ignored (and no error is raised).
Using this mechanism it is guaranteed that newer data is never overwritten by outdated data. Only in the following situation a temporary inconsistency can occur: Message 1 contains the complete definition of an engineering design version. The engineering design gets changed and message 2 is sent with delta information only. Message 2 is processed in SAP Business ByDesign first. When message 1 gets processed, the inbound interface detects that a newer message has already been processed and ignores the message. Since Message 1 was a complete transmission but message 2 was only a delta message, some attributes of Message 1 are missing. At latest during the engineering release, this temporary inconsistency is removed, because another complete transfer is required. Engineering release with a delta message is not possible.
A second type of sequencing problems is handled by the business object Product Design. If an engineering design version references another engineering design version that has not been transferred yet, then the corresponding product design version gets the status inconsistent. The product design version can be released by engineering but it can’t be activated in SAP Business ByDesign. Only if the inconsistencies are corrected, the version can be activated. In order to remove the inconsistencies, the missing engineering design versions have to be transferred to SAP Business ByDesign. After the corresponding product design versions have been created successfully in SAP Business ByDesign, the inconsistent product design version can be repaired in the following two ways:
The user corrects it manually in the UI by clicking the button “Check consistency”
The product design version is corrected automatically if another message for the inconsistent product design version is successfully processed.
Schedule the automated action Product Design Check Run (available from FP3.0), so that once all the messages arrive, the automated action changes the status to Consistent.
Note: It is not sufficient to just send the missing engineering design versions to SAP Business ByDesign. At least one of the aforementioned steps has to happen in order to remove the inconsistency.
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.
Create a Multi-Level Product Design
<nm:ProductDesignReplicationRequest xmlns:nm="http://sap.com/xi/AP/PC/ProductEngineeringFoundation/Global" xmlns:prx="urn:sap.com:proxy:GU1:/1SAI/TXS442C0D777CE7F63613B6:802">
<MessageHeader>
<ID>ARENA_ERPLOGIC1332164431350</ID>
<CreationDateTime>2012-03-19T13:40:31.352Z</CreationDateTime>
<SenderBusinessSystemID>ERPLOGIC</SenderBusinessSystemID>
<SenderParty>
<InternalID schemeID="CommunicationSystemID" schemeAgencyID="310">ERPLOGIC</InternalID>
</SenderParty>
<BusinessScope>
<TypeCode>3</TypeCode>
<ID>229</ID>
</BusinessScope>
<BusinessScope>
<TypeCode>2</TypeCode>
<ID>226</ID>
</BusinessScope>
</MessageHeader>
<ProductDesign actionCode="04" versionListCompleteTransmissionIndicator="true">
<ID>PD_SAP_DEMO_MOBILE01</ID> <EngineeringDesignBusinessSystemName>ARENA</EngineeringDesignBusinessSystemName> <EngineeringDesignBusinessSystemID>ERPLOGIC</EngineeringDesignBusinessSystemID> <EngineeringDesignInternalID>SAP_DEMO_MOBILE01</EngineeringDesignInternalID>
<Version actionCode="04" versionCompleteTransmissionIndicator="true">
<EngineeringDesignVersionID>01</EngineeringDesignVersionID>
<EngineeringDesignVersionInternalID>01</EngineeringDesignVersionInternalID>
<EngineeringDesignChangeOrderID>BCV2382766420</EngineeringDesignChangeOrderID>
<BaseQuantity unitCode="EA">1.0</BaseQuantity>
<BaseQuantityTypeCode>EA</BaseQuantityTypeCode>
<EngineeringDesignVersionResponsibleEngineerPersonFamilyName>HL</EngineeringDesignVersionResponsibleEngineerPersonFamilyName> <EngineeringDesignVersionResponsibleEngineerPersonGivenName>Prashantha</EngineeringDesignVersionResponsibleEngineerPersonGivenName>
<EngineeringDesignVersionReleaseDate>2012-03-19</EngineeringDesignVersionReleaseDate>
<EngineeringDesignVersionCreationDateTime>2012-03-19T14:36:23Z</EngineeringDesignVersionCreationDateTime>
<EngineeringDesignVersionLastChangeDateTime>2012-03-19T14:36:23Z</EngineeringDesignVersionLastChangeDateTime>
<EngineeringDesignVersionReleaseStatusCode>3</EngineeringDesignVersionReleaseStatusCode>
<Component>
<BaseQuantity unitCode="EA">1.0</BaseQuantity>
<BaseQuantityTypeCode>EA</BaseQuantityTypeCode>
<EngineeringDesignID>SAP_DEMO_CABLE01</EngineeringDesignID>
<EngineeringDesignInternalID>SAP_DEMO_CABLE01</EngineeringDesignInternalID>
<EngineeringDesignVersionInternalID>01</EngineeringDesignVersionInternalID>
</Component>
<Component>
<BaseQuantity unitCode="EA">1.0</BaseQuantity>
<BaseQuantityTypeCode>EA</BaseQuantityTypeCode>
<EngineeringDesignID>SAP_DEMO_CHARGER01</EngineeringDesignID>
<EngineeringDesignInternalID>SAP_DEMO_CHARGER01</EngineeringDesignInternalID>
<EngineeringDesignVersionInternalID>01</EngineeringDesignVersionInternalID>
</Component>
<ProductAssignment>
<Product>
<InternalID>SAP_DEMO_MOBILE01</InternalID>
<TypeCode>1</TypeCode>
</Product>
<DefaultIndicator>false</DefaultIndicator>
</ProductAssignment>
</Version>
</ProductDesign>
</nm:ProductDesignReplicationRequest>
Create a Multi-Level Product Design Version
<nm:ProductDesignReplicationRequest xmlns:nm="http://sap.com/xi/AP/PC/ProductEngineeringFoundation/Global" xmlns:prx="urn:sap.com:proxy:GU1:/1SAI/TXS442C0D777CE7F63613B6:802">
<MessageHeader>
<ID>ARENA_ERPLOGIC1332165331932</ID>
<CreationDateTime>2012-03-19T13:55:31.937Z</CreationDateTime>
<SenderBusinessSystemID>ERPLOGIC</SenderBusinessSystemID>
<SenderParty>
<InternalID schemeID="CommunicationSystemID" schemeAgencyID="310">ERPLOGIC</InternalID>
</SenderParty>
<BusinessScope>
<TypeCode>3</TypeCode>
<ID>229</ID>
</BusinessScope>
<BusinessScope>
<TypeCode>2</TypeCode>
<ID>226</ID>
</BusinessScope>
</MessageHeader>
<ProductDesign actionCode="04" versionListCompleteTransmissionIndicator="true">
<ID>PD_SAP_DEMO_MOBILE01</ID>
<EngineeringDesignBusinessSystemName>ARENA</EngineeringDesignBusinessSystemName>
<EngineeringDesignBusinessSystemID>ERPLOGIC</EngineeringDesignBusinessSystemID>
<EngineeringDesignInternalID>SAP_DEMO_MOBILE01</EngineeringDesignInternalID>
<Version actionCode="04" versionCompleteTransmissionIndicator="true">
<EngineeringDesignVersionID>02</EngineeringDesignVersionID>
<EngineeringDesignVersionInternalID>02</EngineeringDesignVersionInternalID>
<EngineeringDesignChangeOrderID>BCV2382766432</EngineeringDesignChangeOrderID>
<BaseQuantity unitCode="EA">1.0</BaseQuantity>
<BaseQuantityTypeCode>EA</BaseQuantityTypeCode>
<EngineeringDesignVersionResponsibleEngineerPersonFamilyName>HL</EngineeringDesignVersionResponsibleEngineerPersonFamilyName>
<EngineeringDesignVersionResponsibleEngineerPersonGivenName>Prashantha</EngineeringDesignVersionResponsibleEngineerPersonGivenName>
<EngineeringDesignVersionReleaseDate>2012-03-19</EngineeringDesignVersionReleaseDate>
<EngineeringDesignVersionCreationDateTime>2012-03-19T14:36:23Z</EngineeringDesignVersionCreationDateTime>
<EngineeringDesignVersionLastChangeDateTime>2012-03-19T14:36:23Z</EngineeringDesignVersionLastChangeDateTime>
<EngineeringDesignVersionReleaseStatusCode>3</EngineeringDesignVersionReleaseStatusCode>
<Component>
<BaseQuantity unitCode="EA">1.0</BaseQuantity>
<BaseQuantityTypeCode>EA</BaseQuantityTypeCode>
<EngineeringDesignID>KTDEMO_MYMOB01</EngineeringDesignID>
<EngineeringDesignInternalID>KTDEMO_MYMOB01</EngineeringDesignInternalID>
<EngineeringDesignVersionInternalID>02</EngineeringDesignVersionInternalID>
</Component>
<Component>
<BaseQuantity unitCode="EA">2.0</BaseQuantity>
<BaseQuantityTypeCode>EA</BaseQuantityTypeCode>
<EngineeringDesignID>SAP_DEMO_CABLE01</EngineeringDesignID>
<EngineeringDesignInternalID>SAP_DEMO_CABLE01</EngineeringDesignInternalID>
<EngineeringDesignVersionInternalID>01</EngineeringDesignVersionInternalID>
</Component>
<Component>
<BaseQuantity unitCode="EA">1.0</BaseQuantity>
<BaseQuantityTypeCode>EA</BaseQuantityTypeCode>
<EngineeringDesignID>SAP_DEMO_CHARGER01</EngineeringDesignID>
<EngineeringDesignInternalID>SAP_DEMO_CHARGER01</EngineeringDesignInternalID>
<EngineeringDesignVersionInternalID>01</EngineeringDesignVersionInternalID>
</Component>
<ProductAssignment>
<Product>
<InternalID>SAP_DEMO_MOBILE01</InternalID>
<TypeCode>1</TypeCode>
</Product>
<DefaultIndicator>false</DefaultIndicator>
</ProductAssignment>
</Version>
</ProductDesign>
</nm:ProductDesignReplicationRequest>
| Description | Replicate product design |
| Name | ReplicateProductDesign |
| Synchronous | no |
| Release Status | Released |
To replicate a product design based on data of an engineering design.
Additional details regarding these and other attributes can be found in the SAP Global Data Type Catalog.
Message Header
| Attribute | Description | Type | Example |
|---|---|---|---|
| ID | A unique ID that identifies the message. | Char35 | 20090825101230, xzhUjjgstv, Msg256 |
| CreationDateTime | Timestamp of the creation of the message | Timestamp | 2007-03-01T23:59:59.1234Z |
| TestDataIndicator | Indicates, whether the current message is a test message or a real message. | Boolean | Values: true - interface is processed but data is not stored; false - data of the message is stored |
| SenderBusinessSystemID | ID of the sending system, that is, ID of the engineering system. This is an arbitrary ID that doesn’t have to be created in any kind of SLD. | Char60 | EES01, EngineeringSystem1, TDM1 |
| BusinessScope | Two entries for business scope are required for the correct processing of the message. The code values denote the sending and the receiving components. | These entries are fixed for the product design replication interface and have to be specified in the following way: BusinessScope[1]-TypeCode = 3; BusinessScope[1]-ID = 229; BusinessScope[2]-TypeCode = 2; BusinessScope[2]-ID = 226 |
The following attributes of the message header are not needed or must not be filled:
| Attribute | Description |
|---|---|
| UUID | UUID of the message |
| ReferenceID | ID of a message which is referenced by the current message (for example, predecessor) |
| ReferenceUUID | UUID of the referenced message |
| ReconciliationIndicator | Indicator for SAP Business ByDesign internal error handling. If this attribute is filled for the product design interface, then it has to be set to false. |
| RecipientBusinessSystemID | ID of recipient system. Doesn’t have to be filled. |
| SenderParty | Information about the sender party. Parties are relevant for B2B messages only and must not be filled for the product design replication. |
| RecipientParty | Information about the recipient party. Parties are relevant for B2B messages only and must not be filled for the product design replication. |
Example for a valid message header:
<MessageHeader>
<ID>20101001003</ID>
<CreationDateTime>2011-11-23T11:00:48.000+01:00</CreationDateTime>
<SenderBusinessSystemID>X</SenderBusinessSystemID>
<BusinessScope>
<TypeCode>3</TypeCode>
<ID>229</ID>
</BusinessScope>
</MessageHeader>
The business object ProductDesign and the message type ProductDesignReplicationRequest offer internal IDs and IDs for the mapping between ProductDesign and EngineeringDesign. The IDs are used for display in the UI but they play no role for the mapping between the objects. (Exception: initial creation of mapping between a manually created ProductDesign and an EngineeringDesign.) The mapping is only based on the Internal ID.
What the internal ID looks like depends on the engineering system: this may be a GUID, a unique number, or even the same value that is used for the ID. The only requirement for the Internal ID is the uniqueness. An initial value is not allowed for the Internal ID. There are no restrictions for the ID, meaning that it is not required that the ID is unique. Even if the ID is empty, the message can be processed. In this case the Internal ID is copied to the ID field. Of course the user could not use the displayed information if the InternalID represents a GUID.
It is possible to connect several engineering systems to one SAP Business ByDesign instance. In this case it may happen that both engineering systems contain an engineering design with the same (internal) ID. In order to handle this situation, Engineering Design Business System Name and Engineering Design Business System ID have to be specified in addition to the Engineering Design (Internal) ID. The Business System Name is shown on the UI, whereas the Business System ID is used for the mapping. Similar to the Engineering Design (Internal) ID, the Business System ID is a required field. If the Business System Name is initial, the message can still be processed and the Business System ID is copied into the Name attribute. Thus the combination of EngineeringDesignBusinessSystemID and EngineeringDesignInternalID has to be unique.The ResponsibleEmployeeID is the person responsible for creating the Product Design.
Note, that the EngineeringDesignBusinessSystemID always has to be filled in, even if only one engineering system is connected to SAP Business ByDesign.
The version specific attributes of the product design are described in this section. A product design can have any number of versions. It is possible to have both automatically created versions as well as manually created versions for the same product design. A manually created version cannot be modified by the web service. An automatically created product design version cannot be modified manually, as long as the engineering design version release status code has value 1 (not released). Once it is released, only a few attributes can still be modified by the web service (for example, EngineeringDesignVersionStatusName). Most of the attributes can no longer be changed , while some can be changed manually (for example, component ID).
The ActionCode determines how the Product Design version shall be processed. The following values are supported:
| Action Code | Description |
|---|---|
| 01 | Create - A new product design version shall be created. If the corresponding product design version already exists, the message processing stops with an error. |
| 02 | Change - An existing product design version shall be updated. If the corresponding product design version doesn’t exist yet, the message processing stops with an error. |
| 03 | Delete - For the specified product design version the replication cancelled indicator is set to true. If the corresponding product design version doesn’t exist yet, the message processing stops with an error. |
| 04 | Save - If the product design version doesn’t exist yet, it will be created. If it already exists it will be modified. |
| 05 | Remove - For the specified product design version the replication cancelled indicator is set to true. |
For an existing product design, versions can be created, modified or deleted. If a new product design is created, only create or save can be used on the version level.
This element indicates, whether the current message contains all attributes of the Engineering Design Version that shall be replicated in the SAP Business ByDesign system (see also the chapter about delta messages and complete transmission). The following values are supported:
| LCTI | Description |
|---|---|
| False | Only the specified attributes of the version are processed. |
| True | The existing product design version is replaced completely by the current message. Attributes that are not filled in the current message lead to deletion of existing values on the product design level. If a complete section is not specified (for example, version components), then the corresponding data in SAP Business ByDesign is deleted as well. Example: First web service call created a product design version with two components. Second web service call contains no components - existing components in ByD are deleted. |
Note: An engineering design version can only be released by a web service if the versionCompleteTransmissionIndicator is set to true.
| Attribute | Description | Type |
|---|---|---|
| EngineeringDesignVersionID | The ID of the Engineering Design Version in the Engineering System. This ID is shown in the UI to show how the corresponding version in the engineering system is called. The ID can be updated by susbsequent messages. If the EngineeringDesignVersionID is initial, theEngineeringDesignVersionInternalID is used (shown) instead. This attribute is used for display purposes only. | Char40 (optional) |
| EngineeringDesignVersionInternalID | Internal ID of the engineering design version in the engineering system. This ID is used to hold the mapping between the Version of the engineering design and the version of the Product Design. Any ID is allowed. If the Engineering Design Version Internal ID is initial, the inbound processing stops with an error. | Char40 (required) |
It is possible to specify a predecessor engineering design version for the current engineering design version. This is a link to another engineering design version that can be taken over from the engineering system. The exact semantics of the link depends on the engineering system. It is optional information that can be skipped. If it is specified, an error task is created if the incomplete data is passed. If no product design version exists for the specified predecessor engineering design version, the product design version has the status inconsistent. If the missing product design version has been created, the inconsistent product design version can be corrected manually (using the check action) or automatically by another update.
The predecessor engineering design version can belong to any engineering design of any engineering system. If both versions belong to the same engineering system or even to the same engineering design, some attributes can be left empty. In order to identify the corresponding product design version, only the internal IDs of the predecessor engineering design version are needed. The remaining IDs are only if no product design version exists yet for the specified predecessor engineering design version. In this case, the IDs are used to create an error message with meaningful IDs.
The following table shows the allowed combination of attributes and the default behavior of the interface.
| Specified Action | Reaction | Result |
|---|---|---|
| BusinessSystemID; InternalID; VersionInternalID | Data used as specified | Data used as specified |
| InternalID; VersionInternalID | Default logic | The BusinessSystemID of the current Engineering Design Version is used as default for the business system of the predecessor engineering design system, that is, both versions belong to the same engineering system. |
| VersionInternalID | Default logic | The BusinessSystemID of and the InternalID of the current Engineering Design Version are used as default for the predecessor engineering design, that is, both versions belong to the same engineering design. |
| BusinessSystemID; VersionInternalID | Error | If PredecessorVersionEngineeringDesign-BusinessSystemID is specified, then no default logic is applied (unclear semantics) |
| BusinessSystemID; InternalID | Error | If a predecessor is specified, then the EngineeringDesignVersion is a required field. |
| BusinessSystemID | Error | If a predecessor is specified, then the EngineeringDesignVersion is a required field. |
| InternalID | Error | If a predecessor is specified, then the EngineeringDesignVersion is a required field. |
Also in the following cases the processing stops with an error:
PredecessorVersionEngineeringDesignBusinessSystemName is not initial but PredecessorVersionEngineeringDesignBusinessSystemID is initial
PredecessorVersionEngineeringDesignID is not initial but PredecessorVersionEngineeringDesignInternalID is initial
PredecessorVersionEngineeringDesignVersionID is not initial but PredecessorVersionEngineeringDesignVersionInternalID is initial
If one of the readable IDs is initial but the internal ID is filled, then the internal ID is used in error messages instead.
The data can be changed by the web service if the engineering design version release status code has value 1 (not released).
| Attribute | Changeability | Type | Additional Information |
|---|---|---|---|
| EngineeringDesignChangeOrderID | By web service if engineering design version release status code has value 1 (not released). | Char40 (optional) | This attribute can be used to store the ID of a control object in the engineering system that has been used to perform/control/group the changes in the engineering system. It depends on the engineering system if such an object exists and how it is named there. Any ID is taken over and stored in the database without any checks. No functionality associated with this attribute. Currently the attribute is not part of the UI. |
| BaseQuantity | By web service if version not created manually and engineering design version release status code has value 1 (not released). | Dec31,14 (optional); UnitCode (Char3) | Base quantity of the engineering design version. If the base quantity is initial, a default value is determined by the business object Product Design. Even if VersionCompleteTransmissionIndicator is set to true, the BaseQuanity is not cleared, if an initial value is passed. The MeasurementUnitCode of the base quantity. Measurement units are represented in the attribute unitCode in accordance with UN/ECE Recommendation #20 or X12 355 |
| BaseQuantityTypeCode | By web service if engineering design version release status code has value 1 (not released). | Char10 (optional) | A coded representation of the type of the base quantity (such as gross weight, net weight). If the BaseQuantityTypeCode is not specified, it is calculated by the system. If it is specified and if it doesn’t fit to the BaseQuantityUnitCode, a warning message is put into the log (unfortunately the log is currently not shown in the UI). |
| ProposedProcurementMethodCode | By web service if engineering design version release status code has value 1 (not released). | Char2 (optional) | The engineering system can specify/propose how an engineering design shall be handled in follow-on processes. The following code values are supported: 1 - In-house production; 2 - External procurement; 3 - Determination based on source of supply priority rule. This information is stored in the database but currently not shown in the UI. No functionality is associated with this field. |
| EngineeringDesignVersionStatusName | Always by web service | Char40 (optional) | A detailed status can be passed by the engineering system if a fine-granular status scheme is used in the engineering system. This is just a string which is stored without any checks in the database. Currently it is not shown in the UI. No functionality associated with this attribute. |
| EngineeringDesignVersionResponsibleEngineerPersonFamilyName; EngineeringDesignVersionResponsibleEngineerPersonGivenName | By web service if engineering design version release status code has value 1 (not released). | Char40 (optional) | FamilyName and GivenName of the responsible engineer in the engineering system can be passed. These are just two strings that are stored without any checks in the database. Currently they are not shown in the UI. No functionality is associated with this attribute. Especially no conversion into a SAP Business ByDesign employee or SAP Business ByDesign identity takes place! |
| EngineeringDesignVersionReleaseDate | By web service if engineering design version release status code has value 1 (not released). | Date (optional) | Date when the engineering design has been released in the engineering system. The date is stored in the database but currently not shown in the UI. No functionality is associated with this attribute. |
| EngineeringDesignVersionReplicationCancelledIndicator | Always by web service | Boolean (optional) | The ReplicationCancelledIndicator specifies whether an automatically created product design version is still getting updated via web service. If the indicator is set to true, then no further updates via web service are expected. If the product design version is not released, it could theoretically be deleted (currently not offered in SAP Business ByDesign-UI). The engineering system cannot make any assumption about the status of the product design version: it might be deleted or it might stay in the system. If the Indicator is set to true, it can be deleted again by another web service. In this case the Indicator has to be set to false of course and the correct action_code has to be used (save or update). The ReplicationCancelledIndicator doesn’t change the manual changeability of a product design version. |
| EngineeringDesignVersionPrimaryViewableCreationDateTime | By web service if engineering design version release status code has value 1 (not released). | Timestamp (optional) | This attribute can be used to transfer the timestamp at which the primary viewable of the engineering design version has been created. It is stored in the database but currently not shown in the UI. No checks or functionality associated with the field. |
| EngineerDesignVersionCreationDateTime | By web service if engineering design version release status code has value 1 (not released). | Timestamp (optional in case of update) | Specifies when the engineering design has been created in the engineering system. It is a required field when a new product design version will be created. If an existing product design version is updated, the field is optional but it can be overwritten. The attribute is currently not shown in the UI. |
| EngineerDesignVersionChangeDateTime | Always by web service | Timestamp (optional in case of create) | Specifies when the engineering design has been updated in the engineering system. It is an optional field when a new product design version is created. If an existing product design version will be updated, the field is mandatory. The attribute is currently not shown in the UI. Important: The EngineeringDesignVersionChangeDateTime is used to identify obsolete messages which can be skipped because a newer message has already been processed. In the inbound processing the ChangeDateTime of the current message is compared with the ChangeDateTime stored in the product design version. Only if the ChangeDateTime of the message is newer than then stored value, the message is being processed. If it is older or the same, the message is ignored. |
| ExecutionUsageBlockingStatusCode | By web service if engineering design version release status code has value 1 (not released). | Char2 (optional) | With this attribute, the handover to execution (meaning the conversion into PBOM) can be blocked for a product design version. If the PD version is blocked, it can’t be released. The code list can have the following values: 1 - not blocked; 3- blocked. Important: This attribute is currently not supported by the SAP Business ByDesign UI. Therefore it must not be set to blocked by the agent, because in this case the PD version could not be released and user would not know why (attribute is not displayed). |
| EngineeringDesignVersionReleaseStatusCode | By web service if engineering design version release status code has value 1 (not released). | Char2 (mandatory) | With this attribute an engineering design version can be released by the external system. Once the corresponding PD version has been released, the main attributes can’t be changed any longer by the inbound interface. It is the prerequisite for release of the complete PD version. The following code values are supported: 1 - Not released; 3 - Released; 4 - Release discarded; 5 - Release cancelled. The following status transitions are supported: Not released - Release discarded; Not released - Released (version complete transmission has to be true); Released - Released Cancelled. Release discarded means, that a PD version shall not be released. If an already released PD version becomes obsolete, then release cancelled can be used. It is not possible to get back to any other status once a PD version has the status release discarded or release cancelled. The inbound handling is error tolerant; therefore also the transition Not released - Release cancelled is supported. Important: Transition from not released to released is only possible, if the versionCompleteTransmissionIndicator is set to true. |
The complete key of an engineering design version consists of the combination of EngineeringDesignBusinessSystemID, EngineeringDesignInternalID and EngineeringDesignVersionInternalID. The EngineeringDesignVersionInternalID is used for the mapping internally. For the display on the UI the EngineeringDesignVersionID is used.
The EngineeringDesignVersion (Internal) ID is only unique in the context of an EngineeringDesign (+ Engineering System). Therefore in most cases, all three attributes have to be specified. In some cases it is possible to leave the information about the engineering system or the engineering design empty. The inbound interface then applies default logic.
If a new product design version is created the complete data is required. No default logic is applied here. The same is true for the identification of a product design version that is updated. Only in case of references (parts or predecessor information), default logic can be applied.
This section is used to create the component information of an engineering design version. As the version component has no unique key (the component ID is optional), components can’t be identified during an update step. Therefore updates on single components are not supported. If components shall be changed, all existing components of a product design version will be deleted first and re-created. If no component is specified in the message, the behavior depends on the versionCompleteTransmissionIndicator: if it is set to true, then all existing components will be deleted. If it is set to false, existing components will not be deleted. If the message contains at least one component, all existing components will be deleted first and then the components that are specified in the message will be recreated. This is also true for sub nodes of components: text-collections and attachments. They can only be created together with their component, no update is supported.
Components of a product design version can be deleted and created by the inbound interface as long as the corresponding product design version has not been released by engineering. If the version has been released, the component IDs can be changed manually.
| Attribute | Description | Type |
|---|---|---|
| ProductDesignComponentID | ID of the component. If it is not specified, an ID is determined by the business object. | char40 (optional) |
| BaseQuantity and BaseQuantityTypeCode | The base quantity on component level is a required field that has to be specified. The base quantity type code is optional and will be determined by the system if it is not specified. If it is specified but doesn’t fit to the specified base quantity, then the wrong base quantity type code will be ignored and replaced by a default value. | see quantity fields on version level |
| EngineeringDesignBusinessSystemName | Business system name of the referenced engineering design. The name is needed for display purpose only in case of error messages. If the engineering design business system name is empty, the engineering design business system ID is used instead. If both system name and system ID are empty, the system data of the corresponding engineering design version is used as default. | char80 (optional) |
| EngineeringDesignBusinessSystemID | This attribute holds the system ID of the referenced engineering design. If the ID is empty but the system name is specified, an error message is raised and processing stops with an error task. If both system name and system ID are empty, the system data of the corresponding engineering design version is used as default | char60 (optional) |
| EngineeringDesignID | ID name of the referenced engineering design. The ID is needed for display purpose only in case of error messages. If the engineering design ID is empty, the engineering design internal ID is used instead. | char80 (optional) |
| EngineeringDesignInternalID | Internal ID of the referenced engineering design. If the internal ID is not specified, the message processing stops with an error and an error task is created. | char40 (required) |
| EngineeringDesignVersionID | The ID of the referenced engineering design version is only used for display purposes in case of error messages. If the version ID is empty but the version internal ID is filled, then the internal ID is used for display. | char40 (optional) |
| EngineeringDesignVersionInternalID | The internal ID of the referenced engineering design is an optional field because product designs can reference other product designs without specifying a concrete version. Version determination is then done based on the version validity of the referenced product design. In business configuration it can be specified, that a concrete version has to be specified on component level. If this setting is active but no version is specified via the inbound interface, the resulting product design version is set to inconsistent. The message processing itself is finished successfully. An error task will be raised, if the engineering design version ID is specified but the engineering design version internal ID is empty. | char40 (optional) |
It is possible to transfer a list of materials that is assigned to the product design version. The list of product assignments can be changed via the inbound service as long as the engineering design version has not been released. Once it has been released (engineering design version release status code = released), the data cannot be changed by the SAP Business ByDesign user. If invalid material information is sent to SAP Business ByDesign, the corresponding entry will be ignored. If invalid type codes are sent, the processing stops with an error task (see below). As soon as one product assignment is included in the message or the version complete transmission indicator is set to true, existing product assignments for the corresponding product design version are deleted.
| Attribute | Description | Type |
|---|---|---|
| Product.InternalID | If a material with the specified ID doesn’t exist yet in the system, the complete entry is being ignored; no error task will be created. If the InternalID of a product assignment is empty, an error task will be created because the InternalID is the only supported ID for the material identification. | char40 (required) |
| Product.UUID | The ProductUUID is currently not supported by the inbound message. The product UUID is determined based on the Internal ID. UUIDs specified by the external system are ignored. | UUID, Raw36 (not used) |
| Product.TypeCode | Currently only type code 1 – Material is supported. If any other type code is passed or if the type code is initial, an error task is being created. | char2 (required) |
| DefaultIndicator | The default indicator shall be set to true for exactly one product assignment. If the default indicator is set for more than one material, the indicator is set to false for all product assignments of the corresponding product design version. If the default indicator is not set to true for a product, it can be set manually by the user once the engineering design version has been released. | Boolean (required) |
The description of product design versions can be changed by the inbound service as long as the engineering design is not being released. The structure and data types are described in the section ProductDesign.Description. Note that on product design level the changeability is different than on version level.
Not all attributes of the attachment folder are currently supported. Unfortunately the attachment folder data type even contains some required attributes that are not used. These attributes have to be specified in the XML message; the content plays no role as long as the data type format is correct.
| Attribute | Description | Type |
|---|---|---|
| AttachmentFolder.Document.PathName | Element is required, but content is not used - can stay empty | string (required) |
| AttachmentFolder.Document.Name | Name of the document | string (required) |
| AttachmentFolder.Document.SystemAdminstrativeData | This structure is required, data is not taken over. Please note, that also the included attributes have to be part of the XML message – again they can be initial: CreationDateTime; CreationUserAccountID; LastChangeDateTime; LastChangeUuserAccountID | |
| AttachmentFolder.Document.VisibleIndicator | Not used, shall be set to true | Boolean (required) |
| AttachmentFolder.Document.VersioningEnabledIndicator | Can be set to true or false | Boolean (required) |
| AttachemntFolder.Document.CategoryCode | The following category codes are supported: 2 - Document; 3 - Link | Char1 (required) |
| AttachmentFolder.Document.AlternativeName | This attribute is used to fill in the document title of the attachment. If no alternative name is specified, the name is also used for the document title. | String (optional) |
| AttachmentFolder.Document. ExternalLinkWebURI | If the document represents an URI (category code = 3), this attribute has to be filled with an URI (the syntax is specified in the IETF RFC 2396 recommendation). | any URI (optional) |
| AttachmentFolder.Document.File | If the document represents a real document (category code = 2, not an URI), then the binary representation of the document has to be added here. | Binary stream (optional) |
Example
<AttachmentFolder>
<Document>
<PathName/>
<Name>File</Name>
<SystemAdministrativeData>
<CreationDateTime/>
<CreationUserAccountID/>
<LastChangeDateTime/>
<LastChangeUserAccountID/>
</SystemAdministrativeData>
<VisibleIndicator>true</VisibleIndicator>
<VersioningEnabledIndicator>false</VersioningEnabledIndicator>
<CategoryCode>2</CategoryCode>
<FileContentBinaryObject>HGBNMJBLU…</FileContentBinaryObject>
</Document>
</AttachmentFolder>
Example
<AttachmentFolder>
<Document>
<PathName/>
<Name>Link</Name>
<SystemAdministrativeData>
<CreationDateTime/>
<CreationUserAccountID/>
<LastChangeDateTime/>
<LastChangeUserAccountID/>
</SystemAdministrativeData>
<VisibleIndicator>true</VisibleIndicator>
<VersioningEnabledIndicator>false</VersioningEnabledIndicator>
<CategoryCode>3</CategoryCode>
<AlternativeName>SAP Homepage</AlternativeName>
<ExternalLinkWebURI>http://www.sap.com</ExternalLinkWebURI>
</Document>
</AttachmentFolder>
Supported attachment types:
10001 - Standard Attachment
10011 - Product Image
10013 - Image
10018 - Product Specification
10036 - CAD Viewable
10037 - Primary CAD Viewable (unique)
No special handling for attachment of components. Details are described above for Product Design Version Attachment Folder.
Currently this is not supported by the SAP Business ByDesign UI. Therefore no attachments shall be transferred as they will not be shown at all. The structure is the same as described in section Product Design Version Attachment Folder.
Note: it is not possible to delete attachments on root level. Therefore an attachment shall be transferred only once (if at all).
For the creation of texts only the following attributes of the structure are required:
Text.TypeCode
The following type code is supported: 10011 – internal comment
Text.ContextText
In addition to the text the language_code of the text has to be specified.
Example
<TextCollection > <Text > <TypeCode>10011</TypeCode> <ContentText languageCode="EN">My text</ContentText> </Text> </TextCollection>
No special handling of text-collection of components. Details are described above for Product Design Version Text Collection.
The following text type code is supported: 1006.
Only one text for each component is supported.
Currently this is not supported by the SAP Business ByDesign UI. Therefore no texts shall be transferred as they will not be shown at all. The structure is the same as described in section ProductDesign.Version.TextCollection.
Supported text types:
10011 - Internal Comment
This section contains information about the description of a product design (description of a product design version is part of the ProductDesign.Version section).
On the product design version level we have status information that controls, whether a product design version can still be changed by the engineering system or whether it is blocked against changes from the engineering system. On the product design level there is no status attribute to have a similar behavior. However, it must be ensured, that a manual change of the product design description will be overwritten by a subsequent update from the engineering system. Therefore the following behavior is implemented in the inbound processing: descriptions on product design level are only stored, if no product design description for the specified language exists. This means, that new descriptions can be created by the web service interface, but no updates of existing descriptions are possible. With this limitation we can ensure that manual changes of the description are not overwritten.
| Attribute | Description | Type |
|---|---|---|
| Description | Char80 | |
| LanguageCode | Language code of the description (English: EN, German: DE). If no language code is specified, the current system language is used (meaning active language during web service processing). If only the language code is specified and the description is empty, the complete entry is ignored. | Char2 |
If an invalid language code is specified, then this will not be detected by the inbound handling but rather when the description is saved. Because of the large number of valid codes, this check is done only once at a central place. In case of error a generic error task (error during saving product design) will be created.