1.Overview

This section describes how to exchange a ProductVersion from an external PLM system to the SAP system and vice versa. As a result, a material master is created or updated.
The Integration allows to do the following use cases:

Direction: External PLM System --> SAP

Create a New Material Master in SAP
Create a New Material Master in SAP based on an existing previously transferred ProductVersion
Create a New Material Master in SAP based on a Material Master Template
Update a Material Master in SAP
Extending a Material Master to Another Plant
Read material master information out of the SAP system

Direction: SAP --> External PLM System

Create a Part in the external PLM system based on an SAP Material Master
Update a Part in the external PLM system based on an SAP Material Master
Read Part information out of the external PLM system and show the information in SAP

Supported Entities	ECC	S/4HANA Cloud, private edition	S/4HANA Cloud, public edition
Material Master	SUPPORTED	SUPPORTED

2. Object Definition

Fieldname

Description

PLMSI Behaviour

key

Leading business ID coming from an external PLM system or SAP

MANDATORY

id

ProductVersion id

Value

Behavior

blank

New Material Master is created with the next free number based on the assigned material number range.

provided

value

In case Material Master does not exist, a Material Master is created with the provided id.
In case Material Master exists, the Material Master is updated. The prerequisite is that the Material master is under integration control.
In case the Material master was created manually in SAP and is now updated via the integration, the request will fail unless the compatibility mode is activated

type

ProductVersion type

ProductVersion Type is mapped to an SAP Material Type.

version

ProductVersion version

Value

Behavior

blank

The payload is rejected.

provided

value

In case ProductVersion represented as Material Master is configured for the PV type, the value is stored in the key mapping but not exposed to the end user.
In case ProductVersion represented as Material Revision is configured for the PV type, the value is used for Revision Level creation. In case the PV has a ChangeObject linked, the revision level is created with the SAP ECM which is represented by the ChangeObject.

tempPLMId

temporary PLM ID of the business entity

The PLM ID is provided if the direction of External PLM System --> SAP or in the response. The PLM Id for example can change if two objects can point to the same material master. (like a manufacturing equivalent)

tempERPId

temporary ERP ID of the business entity

The ERP ID is provided if the direction of SAP --> External PLM System or in the response. The ERP Id contains the SAP Material Master Number, and (if applicable) is concatenated with the current revision level.

controlParameters

(only for posting)

Structure with parameters on how to create/update the PV

OPTIONAL

basedOnProductVersion

key of an existing ProductVersion which should be used as a template for PV creation

This property is only influencing the business logic in case of a new material master creation process

Value

Behavior

blank

Accepted. The material master will be created based on PLMSI configuration without using a dedicated already existing material master as a template.

provided

value

Provided ProductVersion key must exist. Otherwise, the payload gets rejected
A New Material master is created based on the existing SAP Material Master which is mapped to the provided ProductVersion. MARA and MARC attributes are taken over.

keepExistingLinkedDocumentVersions

control if all linked DocumentVersions Links (DVs under integration control) should be updated or merged

This flag is only influencing the business logic in case of an update of a material master creation process

Value	Behavior
false (default if not sent)	The integration deletes all document info record object links which are under integration control (have a valid key mapping). Manually added document links (e.g. a purchasing document that is not coming from an external PLM system) by an end-user within SAP are NOT affected.
true	The integration will add/merge the additionally provided documents to the SAP material master. You do not have to provide the full list of valid documents again. Just the "delta".

changeObject

Key of the change object (only if the object is sent in the context of the change object)

OPTIONAL

key

key of the Change Object MDM entity

Provided COs and corresponding linked SAP ECMs/Change Records must exist in the SAP system, otherwise, the payload gets rejected.

Value	CO Integration Pattern	Behavior
CO provided	CO is represented by a SAP ECM	Material is added as OMR to the ECM. If the ECM has a lock status the PV get rejected. If the valid_from date of the ECM and the ProductVersion validFrom the payload will be rejected
CO provided	CO is represented by a SAP Change Record	Material is added as Solution Item to the SAP Change Record. If the CR has a locked status the PV get rejected. If the validFrom date of the main ECM of the CR is different. a dedicated additional ECM with the ProductVersion validFrom the payload will be created and a OMR entry get created for the material master

vendorData

Additional information for a Vendor Part

OPTIONAL

vendorKey

Key of the vendor MDM entity

See the Vendor Definition section.

SAP business partner is linked to the material master as a manufacturer.

vendorPartNumber

Manufacturer Part Number of the ProductVersion

Linked to the SAP Material Master Manufacturing Part Number

Attributes

Aligned Attributes

OPTIONAL

validFrom

Contains date and time of the FROM effectivity or release date directly assigned to the object.

e.g. "2022-12-01T07:42:28Z"

This property is only influencing the business logic in case a PV is represented by a SAP Material Master with Revision Levels

Value	Behavior
blank or every date below 01-01-1900	An SAP Engineering Change Master is created with valid-from date 01.01.1900 to create the Material Master Revision Level
provided value	An SAP Engineering Change Master is created with the provided valid-from to create the Material Master Revision Level

status

Contains the status of the business object

The combination of DM Status and DM Maturity is translated based on the PLMSI configuration to an SAP Material status

maturity

Contains the maturity of the business object

The combination of DM Status and DM Maturity is translated based on the PLMSI configuration to an SAP Material status

baseUOM

Base Unit of the Product (ISO-Code)

DM BaseUoM is linked to the SAP Material Master base unit of measure.

basicMaterial

Defines from which basic Material the product is made of.

Not linked to SAP Material Master by default. Refer to How to section

batchManaged

Specifies if this material should be managed under batch control

Not linked to SAP Material Master by default.

weight

Specifies the Gross Weight of the product version.

Linked to the SAP Material Master gross weight.

weightUOM

Unit of Measure of the weight

Linked to the SAP Material Master weight UoM

length

Specifies the dimension "length" of the product version.

Linked to the SAP Material Master length dimension of the base UOM

width

Specifies the dimension "width" of the product version.

Linked to the SAP Material Master width dimension of the base UOM

height

Specifies the dimension "height" of the product version.

Linked to the SAP Material Master height dimension of the base UOM

sizeUOM

Unit of Measure of the dimension

Linked to the SAP Material Master of the base UOM

displayURL

(only for data federation)

URL for data federation à show link to SAP object

URL for the WebGui SAPGUI for SAP Material Master

names[]

name of the product version (multi-language)

OPTIONAL Behavior: You either have to provide names[] or descriptions [] during initial create of a PV

Linked to the SAP Material Master short text.

language

Language key

ISO Language Key like e.g. "EN,"DE", ...

value

Name of the ProductVersion

Text

descriptions[]

description of the product version (multi-language)

OPTIONAL Behavior: You either have to provide names[] or descriptions [] during the initial creation of a PV. If no name is sent during the initial creation, the first 40 chars of the description are used for the SAP short text.

Linked of SAP Material Master Description

language

Language key

ISO Language Key like e.g. "EN,"DE", ...

value

Description of the ProductVersion

Text

classAssignments[]

Class assignments of the PV

OPTIONAL

classKey

Key of the class

Linked to an SAP Class. The class type is maintained in the PLMSI config.

A class key must be unique within the same collection. Otherwise, the payload is rejected.

namespace

namespace of the class

The class id in SAP is calculated based on namespace and id. If a namespace is provided the corresponding SAP ID looks like the following <namespace>_<id>. Otherwise, it is just the id. The SAP system will search for a class with the same id. If the same class is found a class allocation is executed. In case the class is not found a warning message is issued but the PV is still processed.

id

Id of the class

tempPLMId

temporary PLM ID of the business entity

The PLM ID is provided if the direction of External PLM System --> SAP or in the response.

tempERPId

temporary ERP ID of the business entity

The ERP ID is provided if the direction of SAP --> External PLM System or in the response. The ERP Id contains the SAP id of the class and class type.

version

version of the class

Version is ignored in SAP

type

type for class (e.g. “01” (see IRDI))

Type is ignored in SAP

classDescription

Description of Class (optional, only for better reading)

Ignored by the SAP system.

properties[]

Properties of the class

Linked to an SAP Characteristic of the parent SAP Class

- namespace

namespace of the property

The char id in SAP is calculated based on namespace and id. If a namespace is provided the corresponding SAP ID looks like the following <namespace>_<id>. Otherwise, it is just the id. The SAP system will search for a class with the same id. If the same class is found a class allocation is executed. In case the class is not found a warning message is issued but the PV is still processed.

- id

id of the property

- tempPLMId

temporary PLM ID of the business entity

The PLM ID is provided if the direction of External PLM System --> SAP or in the response.

- tempERPId

temporary ERP ID of the business entity

The ERP ID is provided if the direction of SAP --> External PLM System or in the response. The ERP Id contains the SAP 300 class id.

- version

version of the property

Version is ignored in SAP

- type

type of the property (e.g. “02” (see IRDI))

Type is ignored in SAP

- description

Description of Property (optional, only for better reading)

Ignored by the SAP system.

- values[]

- - value

Linked to the characteristic value within SAP.

If the value is longer than the provided characteristic length definition, the value gets cut.

Only one of the value fields must be provided. An error message is returned if more than one value field is filled.

The value can also be empty/initial.

- - valueInt

- - valueDec

- - valueBoolean

linkedDocumentVersions[]

additional DocumentVersions which should be linked to the ProductVersion

OPTIONAL

key

Linked document keys

Provided DVs and corresponding linked SAP Document Infor Records must exist in the SAP system, otherwise, the payload gets rejected.

Within SAP a Material Master ↔ Document Infor Record object link is created.

Update logic is controlled to keepExistingLinkedDocumentVersions flag of the control key section.

factoryData[]

factory data of a ProductVersion

OPTIONAL

factoryKey

Key of the factory

The factory is linked to an SAP Plant. The link is configured as part of the PLMSI configuration.

sourcingStrategy

Sourcing strategy for the related factory

Not linked to SAP Material Master by default.

status

ProductVersion Status of the related factory

The combination of DM Status and DM Maturity is translated based on the PLMSI configuration to an SAP plant-specific material status

maturity

ProductVersion Maturity of the related factory

The combination of DM Status and DM Maturity is translated based on the PLMSI configuration to an SAP plant-specific material status

extensionFields[]

Extension fields to exchange additional attributes on the factory level

Extension Fields can be mapped based on the PLMSI Field and Value (FVM) mapping to SAP standard MARC fields.

variantDefinitionKey

VariantDefinition link to a PV

OPTIONAL

id

Id of the linked VariandDefinition MDM entity

See VariantDefinition is represented by a 300 class. For further details see the VariantDefinition section.

If you sent a VariantDefinition Linkg following actions will take place:

The 300 class is linked to the SAP Material Master
A configuration profile is created for the combination of SAP Material Master and 300 class. ( Description of the config profile is taken from the PLMSI config)
In case a dependency net or procedures were created as part of VariontOptionRule or Variant Option Transfer the entities are assigned to the configuration profile

tempPLMId

temporary PLM ID of the business entity

The PLM ID is provided if the direction of External PLM System --> SAP or in the response.

tempERPId

temporary ERP ID of the business entity

The ERP ID is provided if the direction of SAP --> External PLM System or in the response. The ERP Id contains the SAP 300 class id.

extensionFields[]

extension fields to exchange additional attributes

OPTIONAL

Extension Fields can be mapped based on the PLMSI Field and Value mapping (FVM) to SAP standard fields, Material classification or custom MARA fields

key

Key to identifying the extension field

Key must be unique per entity

subkey

SubKey to further identify the extension field

The subkey must be unique per entity and per key.

displayName

Readable name for the extension field

Display name of readability only and for data federation

value

Value of the extension field

Only one of the value fields must be provided. An error message is returned if more than one value field is filled.

The value can also be empty/initial.

valueDescription

Value Description

valueInt

Value Integer

valueDec

Value Decimal

valueDate

Value Date

valueDuration

Value Duration

Payload Examples: Direction → PLM2SAP & SAP2PLM

Create/Update: External Provided Business Id

{
  "messageId": "{{$guid}}",
  "MessageHeader": {
    "sentDateUTC": "2022-12-01T07:42:28Z",
    "componentVersion": "22.1",
    "APIVersion": 2,
    "application": "TEAMCENTER",
    "logicalInstance": "TCINST_01",
    "configuration": "CONFIG_A",
    "configurationVersion": 1
  },
  "ProductVersions": [
    {
      "key": {
        "id": "TM-4711",
        "tempPLMId": "",
        "type": "Semi-finished Product",
        "version": "A"
      },
      "controlParameters": {
        "basedOnProductVersionKey": {
          "id": "",
          "tempPLMId": "",
          "type": "",
          "version": ""
        },
        "keepExistingLinkedDocumentVersions": true
      },
      "changeObject": {
        "key": {
          "id": "",
          "tempPLMId": "",
          "type": "",
          "version": ""
        }
      },
      "variantDefinitionKey": {
        "id": "",
        "tempPLMId": ""
      },
      "classAssignments": [],
      "validFrom": "0000-00-00T00:00:00Z",
      "baseUOM": "PCE",
      "status": "Released",
      "maturity": "Series",
      "basicMaterial": "",
      "weight": 12.000000,
      "weightUOM": "GRM",
      "descriptions": [
        {
          "language": "EN",
          "value": "Brushless Motor"
        }
      ],
      "names": [
        {
          "language": "EN",
          "value": "Complete Motor"
        }
      ],
      "extensionFields": [
        {
          "key": "owning_project",
          "displayName": "Owning Project",
          "value": "PRJ-1",
          "valueDescription": "Project 1"
        }
      ]
    }
  ]
}

Create Material Master: Empty Business Id

{
  "messageId": "{{$guid}}",
  "MessageHeader": {
    "sentDateUTC": "2022-12-01T07:42:28Z",
    "componentVersion": "22.1",
    "APIVersion": 2,
    "application": "TEAMCENTER",
    "logicalInstance": "TCINST_01",
    "configuration": "CONFIG_A",
    "configurationVersion": 1
  },
  "ProductVersions": [
    {
      "key": {
        "id": "",
        "tempPLMId": "",
        "type": "Semi-finished Product",
        "version": "A"
      },
      "controlParameters": {
        "basedOnProductVersionKey": {
          "id": "",
          "tempPLMId": "",
          "type": "",
          "version": ""
        },
        "keepExistingLinkedDocumentVersions": true
      },
      "changeObject": {
        "key": {
          "id": "",
          "tempPLMId": "",
          "type": "",
          "version": ""
        }
      },
      "variantDefinitionKey": {
        "id": "",
        "tempPLMId": ""
      },
      "classAssignments": [],
      "validFrom": "0000-00-00T00:00:00Z",
      "baseUOM": "PCE",
      "status": "Released",
      "maturity": "Series",
      "basicMaterial": "",
      "weight": 12.000000,
      "weightUOM": "GRM",
      "descriptions": [
        {
          "language": "EN",
          "value": "Brushless Motor"
        }
      ],
      "names": [
        {
          "language": "EN",
          "value": "Complete Motor"
        }
      ],
      "extensionFields": [
        {
          "key": "owning_project",
          "displayName": "Owning Project",
          "value": "PRJ-1",
          "valueDescription": "Project 1"
        }
      ]
    }
  ]
}

Page tree

01 - ProductVersion

1.Overview

2. Object Definition

Payload Examples: Direction → PLM2SAP & SAP2PLM