1.1 Overview

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

Direction: External PLM System --> SAP

Create a new Document Info Record in SAP
Update a Document Info Record in SAP
Receive physical files (originals) in SAP

Direction: SAP --> External PLM System

Create a document in the external PLM system based on an SAP Document Info Record
Update a document in the external PLM system based on an SAP Document Info Record

Supported Entities	ECC	S/4HANA Cloud, private edition	S/4HANA Cloud, public edition
Documented Info Record	SUPPORTED	SUPPORTED

2. Object Definition

Fieldname

Description

PLMSI Behaviour

key

Key of the document version

MANDATORY

id

DocumentVersion id

Value	Behavior
blank	New Document Infor Record Number is created with the next free number based on the assigned number range of the SAP document type
provided value	In case the document does not exist, a DIR is created with the provided id. In case the document exists, the DIR is updated. The prerequisite is that the DIR is under integration control.

In case the SAP key should be changed based on customer-specific logic. E.g. create an internal ID despite receiving an external one or set the document part of the DIR based on a special logic (e.g. language key) you can use a BADI.

A default document info record part can be set via PLMSI configuration.

type

DocumentVersion type

DocumentVersion Type is mapped to an SAP Document Info Record Type.

version

DocumentVersion version

Value	Scenario	Behavior
blank	-	payload rejected
provided value	external assignment	DIR gets the same Version provided via the payload. The version schema of the respective document type must allow the provided value, otherwise, the entity is rejected.
	internal assignment	DIR gets the next available version from the maintained version schema of the respective document type. This means e.g. the domain model value is "A", but the Version of the DIR is "01".
	internal assignment + Revision level creation	If revision-level creation is switched on for the DV type, the integration creates in addition to the above-outlined behavior a revision level with the DM version value. The required ECM is either created implicitly based on the provided valid from date of the DV payload or is used from the DM CO reference if supplied.

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 concatenated SAP Document Info Record Key

controlParameters

Structure with parameters how to create/update the DV (e.g. keepExistingLinkedProductVersions)

OPTIONAL

keepExistingFiles

Determines if existing (previously sent) files should be kept or not

This flag is only influencing the business logic in case of an update of a document info record maintenance request.

Value	Behavior
false (default if not sent)	The integration deletes all files/originals that are under integration control (have a valid key mapping). Manually added originals by an end-user within SAP are NOT affected.
true	The integration will add/merge the additionally provided files/originals to the SAP material master. You do not have to provide the full list of valid documents again. Just the "delta".

keepExistingLinkedProductVersions

Determines if existing (previously sent) linked product versions should be kept or not

This flag is only influencing the business logic in case of an update of a document info record maintenance request.

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

changeObject

Key of the change object (only if 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	DIR is added as OMR to the ECM. If the ECM has a lock status the DV 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	DIR is added as Solution Item to the SAP Change Record. If the CR has a locked status the DV get rejected. If the validFrom date of the main ECM of the CR is different. a dedicated additional ECM with the DocumentVersion validFrom the payload will be created and a OMR entry get created for the DIR

describedChangeObject

(only for posting data)

Key of the change object, which this DocumentVersion is describing

OPTIONAL

key

key of the Change Object MDM entity

This identifies if a Document Info Record describes a change by providing additional information. The DIR was not created as part of the change. The DIR is attached (object link) to either the SAP ECM or Change Record header.

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 DV is represented by a SAP DIR 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 DIR 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 DIR status

displayURL

URL for data federation a show link to SAP/TC object

URL for the WebGui SAPGUI for SAP Document Info Record

names[]

Contains multi-language short descriptions.

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

Linked to the SAP Document Info Record short text.

language

Language (according ISO 639-1)

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

value

Short text

Text

descriptions[]

Contains multi-language descriptions.

OPTIONAL

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

Linked of SAP Document Info Record Description

language

Language (according ISO 639-1)

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

value

Long text

Text

files[]

Files of a document which are transfered

A file is represented by a SAP original

key

Key of a file

- id

Unique Identifier of the file

technical id and not exposed to the UI

- 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 LOIO.

mimeType

Mimetype (as defined by IANA)

Mime Type and file type is used to determine the SAP workstation application and Storage Category. Configuration to be performed within PLMSI config.

description

description of the file

SAP Original description

fileName

file name

File name of the original within SAP

uploadURL

Upload Url for a file

Generated upload URL to store the physical file in the configured content repository

downloadURL

Download Url for a file

Generated download URL to retrieve the physical file in the configured content repository

linkedProductVersions[]

ProductVersions which are linked

- key

Linked ProductVersion keys

Provided PVs and corresponding linked SAP Material Masters 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 keepExistingLinkedProductVersions flag of the control key section.

linkedVendors[]

Vendors which are linked

S/4HANA ONLY

- key

Linked Vendor keys

Provided Vendors and corresponding linked SAP Business Partners must exist in the SAP system, otherwise, the payload gets rejected.

Within SAP a Document Info Record ↔ Vendor( LFA1) object link is created.

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 and DIR classification.

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 DocumentVersion

{
    "messageId": "{{$guid}}",
    "MessageHeader": {
        "sentDateUTC": "2023-01-10T08:45:08Z",
        "componentVersion": "22.1",
        "APIVersion": 2,
        "application": "TEAMCENTER",
        "logicalInstance": "TCINST_01",
        "configuration": "CONFIG_A",
        "configurationVersion": 1
    },
    "DocumentVersions": [
        {
            "controlParameters": {
                "keepExistingFiles": false,
                "keepExistingLinkedProductVersions": true
            },
            "key": {
                "id": "",
                "tempPLMId": "6855494151674c325a4665",
                "type": "Specification",
                "version": "A"
            },
            "changeObject": {
                "key": {
                    "id": "",
                    "tempPLMId": "",
                    "type": "",
                    "version": ""
                }
            },
            "linkedProductVersions": [],
            "validFrom": "0000-00-00T00:00:00Z",
            "status": "Released",
            "maturity": "",
            "descriptions": [
                {
                    "language": "EN",
                    "value": "Drawing TM-1345"
                }
            ],
            "names": [
                {
                    "language": "EN",
                    "value": "Drawing for brushless motor - Design Specification with all required dimensions"
                }
            ],
            "extensionFields": [
                {
                    "key": "owning_group",
                    "displayName": "Owning Group",
                    "value": "Engineering"
                }
            ]
        }
    ]
}

Update DocumentVersion

{
    "messageId": "{{$guid}}",
    "MessageHeader": {
        "sentDateUTC": "2023-01-10T08:45:08Z",
        "componentVersion": "22.1",
        "APIVersion": 2,
        "application": "TEAMCENTER",
        "logicalInstance": "TCINST_01",
        "configuration": "CONFIG_A",
        "configurationVersion": 1
    },
    "DocumentVersions": [
        {
            "controlParameters": {
                "keepExistingFiles": false,
                "keepExistingLinkedProductVersions": true
            },
            "key": {
                "id": "10000001232",
                "tempPLMId": "6855494151674c325a4665",
                "type": "Specification",
                "version": "A"
            },
            "changeObject": {
                "key": {
                    "id": "",
                    "tempPLMId": "",
                    "type": "",
                    "version": ""
                }
            },
            "linkedProductVersions": [],
            "validFrom": "0000-00-00T00:00:00Z",
            "status": "Released",
            "maturity": "",
            "descriptions": [
                {
                    "language": "EN",
                    "value": "Drawing TM-1345"
                }
            ],
            "names": [
                {
                    "language": "EN",
                    "value": "Drawing for brushless motor - Design Specification with all required dimensions"
                }
            ],
            "extensionFields": [
                {
                    "key": "owning_group",
                    "displayName": "Owning Group",
                    "value": "Engineering"
                }
            ]
        }
    ]
}

Page tree

02 - DocumentVersion

1.1 Overview

2. Object Definition

Fieldname

Description

PLMSI Behaviour

Payload Examples: Direction → PLM2SAP & SAP2PLM