Payload structure for SuccessFactors Upsert in SAP Cloud Integration

The SuccessFactors OData V2 Receiver adapter enables you to communicate with the SuccessFactors system. The Upsert operation is an SAP SuccessFactors function import to update or insert records. SuccessFactors OData V2 receiver supportes Upsert with content-type : atom+xml only.

This blog covers the payload structure for Upsert operation in SAP Cloud Integration.

1. Simple Upsert
2. Upsert with deep insert
3. Upsert with reference link
4. UPSERT in $batch

1. Simple Upsert

Upsert payload schema

<EntitySetName>
	<EntityTypeName>
		<propertyN>..</propertyN>
		...
	</EntityTypeName>
	<EntityTypeName>
		<propertyN>..</propertyN>
		...
	</EntityTypeName>
</EntitySetName>

Upsert payload sample

<User>
    <User>
        <status>active</status>
        <userId>CaptainAmerica</userId>
        <username>CaptainAmerica</username>
        <firstName>Steve</firstName>
        <lastName>Rogers</lastName>
        <city>Brooklyn</city>
        <state>New York</state>
        <country>USA</country>        
    </User>
	<User>
        <status>active</status>
        <userId>SpideMan</userId>
        <username>SpideMan</username>
        <firstName>Peter</firstName>
        <lastName>Parker</lastName>
        <city>Queens</city>
        <state>New York</state>
        <country>USA</country>        
    </User>
</User>

2. Upsert with Deep Insert

 Schema

<EntitySetName>
	<EntityTypeName>
		<propertyN>..</propertyN>
		<NavigationPropertyName1>	
			<NavigationEntityTypeName1>
				<PropertyOfNavigation1>..</PropertyOfNavigation1>
			</NavigationEntityTypeName1>
		</NavigationPropertyName1>
		<NavigationPropertyName2>
			<NavigationEntityTypeName2>
				<PropertyOfNavigation2>..</PropertyOfNavigation2>
			</NavigationEntityTypeName2>
		</NavigationPropertyName2>
	</EntityTypeName>
</EntitySetName>

Deep Insert Sample

<User>
	<User>
		<status>active</status>
		<userId>SpideMan</userId>
		<manager>
			<User>
				<userId>IronMan</userId>
				<status>active</status>
				<username>IronMan</username>
				<firstName>Tony</firstName>
				<lastName>Stark</lastName>
			</User>
		</manager>     
	</User>
	<User>
		<status>active</status>
		<userId>Thor</userId>
		<hr>
			<User>
				<userId>NickFury</userId>
				<status>active</status>
				<username>NickFury</username>
			</User>
		</hr>        
	</User>
</User>

3. Upsert with Links

NOTE: Linking multiple Entities with pipe(|) symbol is not supported in SuccessFactors OData adapter.

Schema

<EntitySetName>
	<EntityTypeName>
		<propertyN>..</propertyN>
		<link>
			<NavigationPropertyName1>
				<NavigationEntityTypeName1>
					<keyOfNavigation1>..</keyOfNavigation1>
				</NavigationEntityTypeName1>
			</NavigationPropertyName1>
			<NavigationPropertyName2>
				<NavigationEntityTypeName2>
					<keyOfNavigation2>..</keyOfNavigation2>
				</NavigationEntityTypeName2>
				<NavigationEntityTypeName2>
					<keyOfNavigation2>..</keyOfNavigation2>
				</NavigationEntityTypeName2>
			</NavigationPropertyName2>
		</link>
	</EntityTypeName>
</EntitySetName>

Upsert with links Sample

<User>
	<User>
		<userId>Hulk</userId>
		<status>active</status>                
		<firstName>Bruce</firstName>
		<lastName>Banner</lastName>
		<link>
			<manager>
				<User>
					<userId>NO_MANAGER</userId>
				</User>
			</manager>
			<matrixManager>
				<User>
					<userId>matrixManager1</userId>
				</User>
				<User>
					<userId>matrixManager2</userId>
				</User>
			</matrixManager>
			<customManager>
				<User>
					<userId>customManager1</userId>
				</User>
				<User>
					<userId>customManager2</userId>
				</User>
				<User>
					<userId>customManager3</userId>
				</User>
			</customManager>
			<proxy>
				<User>
					<userId>Proxy1</userId>
				</User>
				<User>
					<userId>Proxy2</userId>
				</User>
				<User>
					<userId>Proxy3</userId>
				</User>
			</proxy>
		</link>
	</User>
</User>

4. UPSERT in $batch

Upsert can be configured with batch processing.

Request Schema

<batchParts>
    <batchChangeSet>      <!--a batchChangeSet may contain multiple batchChangeSetPart -->
        <batchChangeSetPart>
            <method>upsert</method> <!-- The value of method must be upsert -->
            <headers> <!--this is optional-->
                <header>
                    <headerName/>
                    <headerValue/>
                </header>
            </headers>
            <EntitySetName> <!--This structure is similar to upsert operation -->
                <EntityTypeName>
                    <propertyN/>
                </EntityTypeName>
                <EntityTypeName>
                    <propertyN/>
                    <NavigationPropertyName1>
                        <NavigationEntityTypeName1>
                            <keyOfNavigation1>..</keyOfNavigation1>
                        </NavigationEntityTypeName1>
                    </NavigationPropertyName1>
                </EntityTypeName>
            </EntitySetName>
        </batchChangeSetPart>
    </batchChangeSet>
</batchParts>

Upsert in batch Sample

<batchParts>
	<batchChangeSet>
		<batchChangeSetPart>
			<method>upsert</method>
			<User>
				<User>
					<userId>CaptainMarvel</userId>
					<status>active</status>
					<firstName>Carol</firstName>
					<lastName>Danvers</lastName>
					<link>
						<manager>
							<User>
								<userId>NO_MANAGER</userId>
							</User>
						</manager>						
					</link>
				</User>
				<User>
					<userId>BlackPanther</userId>
					<status>active</status>                
					<firstName>T'Challa</firstName>
					<matrixManager>
						<User>
							<userId>NickFury</userId>
						</User>
					</matrixManager>
				</User>
			</User>
		</batchChangeSetPart>
	</batchChangeSet>
	<batchChangeSet>
		<batchChangeSetPart>
			<method>upsert</method>
			<User>
				<User>
					<status>active</status>
					<userId>Hawkeye</userId>
					<firstName>Clinton</firstName>
					<lastName>Barton</lastName>
				</User>
			</User>
		</batchChangeSetPart>
	</batchChangeSet>
</batchParts>

Response Schema for Success

<batchPartsResponse>
    <batchChangeSetReponse><!--a batchChangeSetResponse may contain multiple batchChangeSetPartResponse if success.-->
        <batchChangeSetPartReponse>    <!--Success ChangeSet response-->
            <statusCode/>
            <statusInfo/>
            <contentId/>
            <headers>
                <header>
                    <headerName/>
                    <headerValue/>
                </header>
            </headers>
            <body>
                <UpsertResponses>
                    <EntitySetName>
                        <upsertResponseProperties>...</upsertResponseProperties>
                    <EntitySetName>
                </UpsertResponses>
            </body>
        </batchChangeSetPartReponse>
    </batchChangeSetReponse>
    <batchChangeSetResponse>    <!--Failure ChangeSet response-->
        <batchChangeSetPartResponse>
            <headers>
                <Accept/>
                <Accept-Language/>
                <Content-Length>320</Content-Length>
                <DataServiceVersion>1.0</DataServiceVersion>
                <Content-Type>application/xml; charset=utf-8</Content-Type>
            </headers>
            <statusInfo>Internal Server Error</statusInfo>
            <contentId/>
            <body>
                <error>
                    <code>ServerErrorException</code>
                    <message lang="en-US">
                     
                    </message>
                </error>
            </body>
            <statusCode>500</statusCode>
        </batchChangeSetPartResponse>
    </batchChangeSetResponse>
</batchPartsResponse>

Response Sample for Success and Failure

<batchPartResponse>
	<batchChangeSetResponse>   <!--Successs ChangeSet Response-->
		<batchChangeSetPartResponse>
			<headers>
				<Accept/>
				<Accept-Language/>
				<Content-Length>581</Content-Length>
				<DataServiceVersion>1.0</DataServiceVersion>
				<Content-Type>application/atom+xml; charset=utf-8</Content-Type>
			</headers>
			<statusInfo>OK</statusInfo>
			<contentId/>
			<body>
				<UpsertResponses>
					<User>
						<key>CaptainMarvel</key>
						<status>OK</status>
						<editStatus>UPDATED</editStatus>
						<message null="true"/>
						<index type="Edm.Int32">0</index>
						<httpCode type="Edm.Int32">204</httpCode>
						<inlineResults type="Bag(SFOData.UpsertResult)"/>
					</User>
				</UpsertResponses>
			</body>
			<statusCode>200</statusCode>
		</batchChangeSetPartResponse>
	</batchChangeSetResponse>
	<batchChangeSetResponse>       <!--Failure ChangeSet response-->
		<batchChangeSetPartResponse>
			<headers>
				<Accept/>
				<Accept-Language/>
				<Content-Length>320</Content-Length>
				<DataServiceVersion>1.0</DataServiceVersion>
				<Content-Type>application/xml; charset=utf-8</Content-Type>
			</headers>
			<statusInfo>Internal Server Error</statusInfo>
			<contentId/>
			<body>
				<error>
					<code>ServerErrorException</code>
					<message lang="en-US">ChangeSet index 1 - DUPLICATE_USERNAME : Failed to add/update user [Testing] "" (N/A;N/A;N/A): Duplicate Username - "Hawkeye".
					</message>
				</error>
			</body>
			<statusCode>500</statusCode>
		</batchChangeSetPartResponse>
	</batchChangeSetResponse>
</batchPartResponse>