Import Business Documents Using OData Service CUAN_BUSINESS_DOCUMENT_IMP_SRV, 1702

Transcription

1 Integration Guide SAP Hybris Marketing On Premise Document Version: Import Business Documents Using OData Service CUAN_BUSINESS_DOCUMENT_IMP_SRV, 1702

2 Typographic Conventions Type Style Example Example EAMPLE Example Example <Example> EAMPLE Description Words or characters quoted from the screen. These include field names, screen titles, pushbuttons labels, menu names, menu paths, and menu options. Textual cross-references to other documents. Emphasized words or expressions. Technical names of system objects. These include report names, program names, transaction codes, table names, and key concepts of a programming language when they are surrounded by body text, for example, SELECT and INCLUDE. Output on the screen. This includes file and directory names and their paths, messages, names of variables and parameters, source text, and names of installation, upgrade and database tools. Exact user entry. These are words or characters that you enter in the system exactly as they appear in the documentation. Variable user entry. Angle brackets indicate that you replace these words and characters with appropriate entries to make entries in the system. Keys on the keyboard, for example, F2 or ENTER. Typographic Conventions 2012 SAP AG. All rights reserved. 2

3 Version Date Change Initial Version 2012 SAP AG. All rights reserved. 3

4 Table of Contents 1 Import Business Documents Using OData Service CUAN_BUSINESS_DOCUMENT_IMP_SRV Overview Technical Prerequisites Structure of OData Service CUAN_BUSINESS_DOCUMENT_IMP_SRV ImportHeader BusinessDocument Company Person ProductItem Offer AdditionalObjectReference Basic Concepts The Different Modes Request Mode: Create & Update (ActionCode 04) Request Mode: Delete (ActionCode 05) Confirmation Mode: Set External Keys (ActionCode 02) Specifics for SAP Hybris Cloud for Customer Integration Person and Company Entity (Lead Processing) Entity Type ProductItem SAP AG. All rights reserved. 4

5 1 Import Business Documents Using OData Service CUAN_BUSINESS_DOCUMENT_IMP_SRV 1.1 Overview OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV is used for standard SAP Hybris Marketing integration with SAP Hybris Cloud for Customer. It is used in marketing-driven, and sales-driven processes to replicate SAP Hybris Cloud for Customer business documents to SAP Hybris Marketing interactions. For details of standard SAP Hybris Marketing integration with SAP Hybris Cloud for Customer see chapter 1.2. Note: In standard SAP Hybris Marketing integration with SAP Hybris Cloud for Customer OData service CUAN_BUSINESS_PARTNER_IMP_SRV is used to replicate customers of SAP Hybris Cloud for Customer to SAP Hybris Marketing contacts. For more information on external interfaces that SAP Hybris Marketing provides for creating or updating Interaction Contacts, Interactions, Interests, Corporate Accounts, Product Categories, and Products, see Data Management Upload Interfaces. Within marketing-driven processes, SAP Hybris Marketing campaign actions are used to create business documents in SAP Hybris Cloud for Customer (leads, appointments, phone calls and tasks). For each SAP Hybris Cloud for Customer business document, a SAP Hybris Marketing interaction is created in the campaign action (exception: only for the task no interaction is created). The SAP Hybris Cloud for Customer business document is created with reference to the SAP Hybris Marketing interaction, that is, it stores the IDs of the SAP Hybris Marketing interaction and campaign. When a SAP Hybris Cloud for Customer business document is created, a confirmation message is returned, mapped to OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV, and the SAP Hybris Marketing interaction is updated with the IDs of the SAP Hybris Cloud for Customer business document. Within sales-driven processes, SAP Hybris Cloud for Customer business documents (leads, opportunities, appointments, visits, and phone calls) can be replicated to SAP Hybris Marketing to create corresponding interactions. Whenever a business document is created, or changed the Simple Object Access Protocol (SOAP) outbound service request message is triggered containing all business document data and mapped in PI or HCI middleware to OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV. Request messages are also created in marketing-driven processes whenever the business document created via a campaign action is changed afterwards. OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV can also be used to create SAP Hybris Marketing interactions from business documents from any source system, named external driven processes. In contrast to OData service CUAN_IMPORT OData service, CUAN_BUSINESS_DOCUMENT_IMP_SRV supports the change of interactions. Each business document is represented by an interaction, and is identified by the key of the business document in the external system SAP AG. All rights reserved. 5

6 Note: If your process doesn t require to update the interactions then use OData service CUAN_IMPORT for better performance. 1.2 Technical Prerequisites OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV is available as part of standard integration with SAP Hybris Cloud for Customer. For more information, see the installation guide on SAP Help Portal at Installation and Upgrade Information Installation Guide the SAP PI or SAP HCI integration guide on SAP Service Marketplace at Structure of OData Service CUAN_BUSINESS_DOCUMENT_IMP_SRV The CUAN_BUSINESS_DOCUMENT_IMP_SRV OData service consists of the following entity sets, and entity types: Entity Set Entity Type Entity Type Description ImportHeaders ImportHeader Technical Import Message Header BusinessDocuments BusinessDocument Business Document Companies Company Company (can only be used in standard SAP Hybris Marketing integration with SAP Hybris Cloud for Customer for replication of leads) Persons Person Person (can only be used in standard SAP Hybris Marketing integration with SAP Hybris Cloud for Customer for replication of leads) ProductItems ProductItem Product Items Offers Offer Offers AdditionalObjectReferences AdditionalObjectReference Additional object references of an interaction ImportHeader The entity type ImportHeader describes the technical header of an import of multiple business documents. The properties Id and Timestamp are used for logging the external data request. If an error occurs during the posting of the business documents, additionally to the import header data the error message and the failed record are saved. These data can be checked with the Integration Errors App. For every service request, a new, unique Id is required. If no Id value is provided it is defaulted internally. The timestamp is defaulted if it is not provided. The SourceSystemId and SourceSystemType property allows you to distinguish between different source systems. The SourceSystemId and SourceSystemType are a mandatory attributes SAP AG. All rights reserved. 6

7 The value C4C for the SourceSystemType is exclusively for the integration to SAP Hybris Cloud for Customer. Property Description Edm Core Max Mandatory Key Type Length Id Unique technical identifier of import run. Edm.String 32 Timestamp SourceSystemType SourceSystemId Timestamp of the run Type of the source system e.g. ERP Identifier of the source system Edm.DateTime 0 Edm.String 20 Edm.String BusinessDocument For each ImportHeader several business documents can be passed. BusinessDocument is mapped to interactions. Property Description Edm Core Type Max Manda Key Length tory Id Key of the interaction that is updated. Only mandatory when action code 02 Edm.String 32 ContactIdOrigin ID origin of the Edm.String 20 1 contact. If the ContactID is filled the ID Origin from the external system must be set e.g. SAP_C4C_BUPA Mandatory when ActionCode 04 ContactId Id of the contact in Edm.String the external system. Mandatory when ActionCode 04 InternalContactId obsolete Edm.String 255 InternalObjectType Interaction type only Edm.String 20 1 Mandatory when ActionCode 04 ExternalObjectType Type of the external Edm.String 30 object e.g. MARKETING_LEAD ExternalId ID of the external object Edm.String SAP AG. All rights reserved. 7

8 ExternalStatusCode ExternalTimeStamp Content ExpectedRevenue Currency PredecessorId ActionCode ContentTitle EndTimeStamp Reason ExternalAdditionalId Amount StatusCode Status of the external object Creation or change timestamp of the external object. Timestamp is used to process messages in the right sequence Long Description of the external object Expected revenue of an opportunity. Currency of the amount fields. Must be set if ExpectedRevenue or Amount is filled Lead predecessor Id can be passed. Campaign is copied from predecessor document. Can only be used on request mode. The action code controls how an interaction is posted the following values are supported: 02 confirmation mode 04 request mode 05 remove Short Description of the external object Endtimestamp of the validity of the external object Reason oft he interaction Additional ID of the external object. Amount of the external object. Currency Field must be filled if amount is populated Internal Status of the interaction. The following status are defined: Edm.String 2 Edm.DateTime 0 Edm.String 0 Edm.Decimal 0 Edm.String 5 Edm.String 50 Edm.String 2 Edm.String 255 Edm.DateTime 0 Edm.String 20 Edm.String 50 Edm.Decimal 0 Edm.String SAP AG. All rights reserved. 8

9 Timestamp CampaignId 01 In Process 02 Released 03 Completed 04 Cancelled 05 Converted 06 Successful 07 Unsuccessful Timestamp of external object in the source system e.g. order date. Filled with ExternalTimeStamp if empty Hybris Marketing Campaign Id Edm.DateTime 0 Edm.String 10 Note: If you use OData adapter in PI or HCI middleware then fill the field Id with an initial value. This is necessary since OData adapter requires to fill mandatory OData fields. 1 Only mandatory when the field ActionCode has the value Company This entity can only be used in standard SAP Hybris Marketing integration with SAP Hybris Cloud for Customer for replication of leads. For more details see chapter 1.6. Per business document one company can be passed. Property Description Edm Core Max Length Mandatory Key Type Id Id of the Edm.String 100 Company in the external system IdOrigin ID_ORIGIN to Edm.String 20 identify companies from external systems InternalID ID of the Edm.String 100 company on hybris marketing LastChangeDate obsolete Edm.DateTime 0 must be filled for compatibility reasons CompanyName Company Edm.String 80 Name CountryCode Country Code Edm.String SAP AG. All rights reserved. 9

10 RegionCode Region Code Edm.String 3 CityName City Name Edm.String 40 PostalCode Postal Code Edm.String 10 Street Street Edm.String 60 HouseNumber House Edm.String 10 Number Address Address Edm.String 241 PhoneNumber Phone Edm.String 30 Number FaxNumber Fax Number Edm.String 30 WebSite Web URI Edm.String IndustryCode Industry Code Edm.String 4 LanguageCode Preferred Language Code Edm.String Person This entity can only be used in standard SAP Hybris Marketing integration with SAP Hybris Cloud for Customer for replication of leads. For more details see chapter 1.6. Per business document, one person can be passed. Property Description Edm Core Max Length Mandatory Key Type ID Id of the Edm.String 100 person in the external system IdOrigin ID_ORIGIN to Edm.String 20 identify person from external systems InternalID ID of the Edm.String 100 company on hybris marketing LastChangeDate obsolete Edm.DateTime 0 must be filled for compatibility reasons FirstName First Name Edm.String 40 LastName Last Name Edm.String 40 FullName Full Name Edm.String 80 DateOfBirth Date of Birth Edm.DateTime 0 GenderCode Gender Code Edm.String 1 MaritalStatusCode Marital Edm.String 1 Status Code TitleCode Title Code Edm.String SAP AG. All rights reserved. 10

11 CountryCode Country Edm.String 3 Code Only relevant for consumer RegionCode Region Code Edm.String 3 Only relevant for consumer CityName City Name Edm.String 40 Only relevant for consumer PostalCode Postal Code Edm.String 10 Street Street Edm.String 60 Only relevant for consumer HouseNumber House Edm.String 10 Number Only relevant for consumer Address Edm.String 241 Address Only relevant for consumer PhoneNumber Phone Edm.String 30 Number Only relevant for consumer MobilePhoneNumber Mobile Edm.String 30 Phone Number Only relevant for consumer FaxNumber Fax Number Edm.String 30 Only relevant for consumer WebSite Web URI Edm.String IsConsumer Person is Edm.Boolean 0 Consumer IsContact Person is Edm.Boolean 0 Contact LanguageCode Preferred Language Edm.String ProductItem Several product items can be passed per business document. Property Description Edm Core Max Mandatory Key Type Length Id Edm.String 32 ObjectType Object type from external system e.g. SAP_C4C_PRODUCT Edm.String SAP AG. All rights reserved. 11

12 ObjectId Product key from Edm.String 50 external system. ProductName Product name Edm.String 40 ProductDesc Product description Edm.String 512 Amount Amount of product. Edm.Decimal 31,2 Currency information is derived from assigned interaction Quantity Quantity of product Edm.Decimal 22,5 UnitOfMeasuure Unit of product Edm.String Offer Several Offers can be passed per business document Property Description Edm Core Max Mandatory Key Type Length Origin Origin of the Edm.String 30 offer Id Identifier of the Edm.String 10 offer ContentItemId ID of the content Edm.String 5 item of the offer RecommendationScenarioId ID of the recommendation scenario Edm.String AdditionalObjectReference Several additional object references per business document can be passed. Property Description Edm Core Max Mandatory Key Type Length ObjectType Type of the Edm.String 30 object referenced ObjectId ID of the object referenced Edm.String Basic Concepts The OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV supports only the method deep create on the entity type ImportHeader and the dependent entity type BusinessDocument. Other methods, such as create, update or delete are not supported. The field ActionCode controls how a BusinessDocument is processed. See also chapter SAP AG. All rights reserved. 12

13 OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV supports one message of the entity type ImportHeader with multiple lines of the entity type BusinessDocument. Up to 10,000 business documents can be sent at once with the OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV. It is required that always a complete snapshot of the data is provided: It is not supported that only data, which has changed with respect to a previous state is provided. Attribute ExternalTimeStamp of entity BusinessDocument defines the last change or the creation of the business document. Before updating, an interaction time stamp (TIMESTAMP) of interaction in SAP Hybris Marketing and of incoming message are compared (ExternalTimeStamp). Outdated messages, where the field ExternalTimeStamp is bigger than the field TIMESTAMP of the interaction, are ignored since changes are already stored, and the more current interaction carries the complete and most recent snapshot data. The snapshot must also contain all entries for all sub-entity sets, tahat is, ProductItems, Offers, and AdditionalObjectReferences. If for a sub-entity set no entries are provided potentially existing entries are deleted. If the OData service is not accessible (for example no authorization, system not available, too many BusinessDocuments sent) a corresponding HTTP status code is returned. After the OData service has been accepted by Gateway component in SAP Hybris Marketing system always HTTP status code 201 is returned. Potential processing errors are recorded in SAP Hybris Marketing system and can be monitored, restarted and discarded in Integration Errors app. The external key of a BusinessDocument entity is defined by unique combination of the fields SourceSystemId, SourceSystemType, ExternalObjectType, ExternalObjectId. 1.5 The Different Modes As described in the overview chapter, the OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV supports confirmation and request messages. In request mode, messages are processed that import (create, update or delete) interactions. The messages are triggered by changes in the external system. The confirmation mode is used in marketing-driven scenarios to confirm messages that were sent to external systems. The confirmation message mainly contains the key of the business document in the external system. The different modes are defined by attribute ActionCode in entity BusinessDocument. Action code 04 defines creation or update in request mode. Action code 05 defines deletion in request mode. Action code 02 defines the update of an interaction by the external key in confirmation mode. Customer enhancements are only supported when the field ActionCode has the value 04. See the following chapters for more details Request Mode: Create & Update (ActionCode 04) The external key (see table below) of the business document is used to check the existence of an interaction in SAP Hybris Marketing. If an interaction is found it is updated. If no interaction is found an interaction is created. The Attribute Id is optional, and only relevant for marketing-driven processes (see chapter 1.1). If additionally the optional attribute Id is provided an additional search step is performed if no interaction with fitting external key was found. The Attribute Id is used to retrieve an interaction by 2012 SAP AG. All rights reserved. 13

14 its internal key. If an interaction is found it is updated. If no interaction is found an error is raised and the corresponding message can be found in the Integration Errors app. See following table for an overview of mandatory attributes and the definition of the key of the external business document. Entity Property Description Mandatory External Key ImportHeader Id Unique technical identifier of x import run. BusinessDocume nt Timestamp Timestamp of the run SourceSystemType Type of the source system e.g. x x ERP SourceSystemId Identifier of the source system x x Id Key of the interaction that is updated. ContactIdOrigin ID origin of the contact. If the x ContactID is filled the ID Origin from the external system must be set e.g. SAP_C4C_BUPA. ContactId Id of the contact in the x external system. InternalObjectType Interaction type only x mandatory for request mode ExternalObjectType Type of the external object e.g. x x MARKETING_LEAD ExternalId ID of the external object x x ExternalTimeStamp Timestamp of the external x object. Timestamp is used to process messages in the right sequence ActionCode 04 x The main contact of the business document is defined by attribute pair ContactIDOrigin and ContactId. If no contact with this attribute pair (facet) exists in SAP Hybris Marketing a new contact is created. Contact data itself is replicated separately via, for example, OData service CUAN_BUSINESS_PARTNER_IMP_SRV PredecessorId (Marketing-Driven Process) The attribute PredecessorId is only relevant for marketing-driven processes. If it is filled a predecessor lead interaction is determined and the ID of the campaign in which the lead predecessor interaction was created is copied to the current interaction to be created or updated. The external key of the predecessor lead interaction is defined by attributes SourceSystemType, SourceSystemId, ExternalObjectType, and ExternalId. SourceSystemType and SourceSystemId are taken from entity ImportHeader, ExternalID is given by value of PredecessorId in entity BusinessDocument and ExternalObjectType is fixed to value MARKETING_LEAD. If no predecessor lead interaction is found an error is raised which can be seen in Integration Errors app SAP AG. All rights reserved. 14

15 1.5.2 Request Mode: Delete (ActionCode 05) If a business document is deleted in external system then action code 05 has to be used. An interaction is determined according to the rules described in previous chapter If an interaction is found the interaction is not removed from database. A so called obsolete flag is set for the interaction. The interaction can then be deleted in a subsequent step by standard deletion reports. Besides ExternalTimeStamp and the obsolete flag no other interaction data is updated. If no interaction is found an error is raised which is logged and can be seen in Integration Errors app Confirmation Mode: Set External Keys (ActionCode 02) If the field action code has the value 02 the OData service is executed in confirmation message mode. The confirmation mode is only relevant for marketing-driven processes. The main purpose of the confirmation message process step is to update existing interaction with the external business document key. Only a small subset of fields contained in table below are taken into account in confirmation message mode. Entity Property Description Mandatory External Key ImportHeader Id Unique technical identifier of import run. Timestamp Timestamp of the run SourceSystemType Type of the source system e.g. ERP SourceSystemId Identifier of the source system BusinessDocument Id Internal key of the interaction that is to be updated. ExternalObjectType Type of the external object e.g. MARKETING_LEAD ExternalId ID of the external object ExternalTimeStamp Timestamp of the external object. Timestamp is used to process messages in the right sequence ActionCode 02 The Property Id denoting the internal Id of the interaction is used to retrieve an existing interaction. If the interaction cannot be retrieved an error is raised and logged in the Integration Errors app. If the interaction can be retrieved then the mentioned fields above are updated in the interaction. 1.6 Specifics for SAP Hybris Cloud for Customer Integration Some specifics have to be considered for SAP Hybris Cloud for Customer Integration. SAP Hybris Cloud for Customer integration is defined by SourceSystemType = C4C SAP AG. All rights reserved. 15

16 1.6.1 Person and Company Entity (Lead Processing) In general, business partners and business documents are replicated separately and the OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV does only contain references to business partners and not the business partner data itself. The only exception is the lead processing in SAP Hybris Cloud for Customer integration. It is defined by SourceSystemType = C4C and ExternalObjectType = MARKETING_LEAD. Only within this context the entities person and company can be used. In all other cases their usage is forbidden. SAP Hybris Cloud for Customer leads can reference existing business partners, or can be used to introduce and create new business partners when a lead is converted. As long as the business partners are not converted they are not generally visible in SAP Hybris Cloud for Customer, and exist only in the context of the lead. Only generally visible business partners are published by SAP Hybris Cloud for Customer, and can therewith be consumed by OData service CUAN_BUSINESS_PARTNER_IMP_SRV. If a lead contains non-converted business partners their data is also replicated by lead replication service. This data can be mapped to entities person and company of OData service CUAN_BUSINESS_DOCUMENT_IMP_SRV. If person or company data is provided following additional attributes are mandatory in request (ActionCode = 04 ) and confirmation mode (ActionCode = 02 ): Entity Property Description Mandatory (Request) Person Id Id of the person in the external system IdOrigin ID_ORIGIN to identify person from external systems InternalId ID of the person on hybris marketing LastChangeDate obsolete must be filled for compatibility reasons Company Id Id of the company in the external system IdOrigin ID_ORIGIN to identify companies from external systems InternalId ID of the company on hybris marketing LastChangeDate obsolete must be filled for compatibility reasons Mandatory (Confirmation) In request mode it is checked within SAP Hybris Marketing whether a contact can be found identified by Id, and IdOrigin. If a contact is found then the person and/or company data is updated with respect to Id and IdOrigin pair. If no contact can be found and a new contact is created with respect to Id and IdOrigin pair. If both entity types are provided, company and person, a relationship is created. The person is the contact person of the company. Attribute InternaId is only relevant for marketing-driven processes. Person and/or company entity may additionally contain the InternalID attribute. If the InternalId is provided it is assumed that a contact with this InternalId already exists in SAP Hybris Marketing. If no contact can be found an error is raised which are displayed in the Integration Errors app SAP AG. All rights reserved. 16

17 In confirmation mode, only the mandatory attributes are considered. Therefore it is firstly checked whether a contact can be found identified by InternalId. If a contact is found person and company data are added to contact with respect to Id and IdOrigin pair. If no contact can be found an error is raised which can be seen in Integration Errors app Entity Type ProductItem If the field ObjectId is initial the corresponding product item is neglected and no error is raised SAP AG. All rights reserved. 17

18 Important Disclaimers and Legal Information Coding Samples Any software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP intentionally or by SAP's gross negligence. Accessibility The information contained in the SAP documentation represents SAP's current view of accessibility criteria as of the date of publication; it is in no way intended to be a binding guideline on how to ensure accessibility of software products. SAP in particular disclaims any liability in relation to this document. This disclaimer, however, does not apply in cases of willful misconduct or gross negligence of SAP. Furthermore, this document does not result in any direct or indirect contractual obligations of SAP. Gender-Neutral Language As far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as "sales person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun does not exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible. Internet Hyperlinks The SAP documentation may contain hyperlinks to the Internet. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any damages caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. All links are categorized for transparency (see: go.sap.com/registration/contact.html 2017 SAP SE or an SAP affiliate company. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice. Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary. These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. All other product and service names mentioned are the trademarks of their respective companies. Please see for additional trademark information and notices SAP AG. All rights reserved. 18