SAP S4CRM 1811 服務(wù)訂單API介紹

Jerry在今年2月28日， SAP Customer Management for S/4HANA 1.0 正式問(wèn)世這個(gè)具有紀(jì)念意義的日子，同時(shí)發(fā)布了中英文版的博客進(jìn)行介紹。

英文版 發(fā)在SAP社區(qū)上，至今超過(guò)16000的閱讀量：

而發(fā)布在微信公眾號(hào)上的中文版，也有兩千多的閱讀量：

一轉(zhuǎn)眼大半年就過(guò)去了，如今SAP S4CRM的標(biāo)準(zhǔn)開(kāi)發(fā)，進(jìn)行得怎么樣了呢？在SAP社區(qū)上我寫的那個(gè)英文博客里，有很多國(guó)外的partners在上面留言詢問(wèn)各種各樣的問(wèn)題。由于今年4月份起Jerry就離開(kāi)了S4CRM開(kāi)發(fā)團(tuán)隊(duì)，所以很多問(wèn)題我沒(méi)有辦法回答，于是我邀請(qǐng)了SAP S4CRM的首席產(chǎn)品經(jīng)理Frick Oliver在社區(qū)上回答大家提出的問(wèn)題：

這是Oliver介紹S4CRM的 視頻 ，節(jié)選自SAP官方招聘公眾號(hào)上的一篇文章。大家可以一睹這位德國(guó)老帥哥的風(fēng)采。

今天這篇文章我邀請(qǐng)了SAP成都研究院S4CRM團(tuán)隊(duì)的開(kāi)發(fā)人員宋浩，由他介紹所在團(tuán)隊(duì)設(shè)計(jì)并開(kāi)發(fā)的S4CRM里服務(wù)訂單(Service Order)創(chuàng)建和更新的API。關(guān)于宋浩的背景介紹，大家可以參考他之前的文章： 一個(gè)SAP顧問(wèn)在美國(guó)的這些年 。

在宋浩的文章里，Jerry也植入了一些關(guān)于SAP CRM中間件和SAP Cloud for Customer內(nèi)容介紹，這些內(nèi)容都和SAP基于Netweaver的系統(tǒng)集成這個(gè)主題相關(guān)，希望能對(duì)大家有所幫助。

為什么SAP要成立專門的團(tuán)隊(duì)來(lái)做API開(kāi)發(fā)呢？最簡(jiǎn)單的4個(gè)字答案：系統(tǒng)集成。

Jerry的另一篇文章： SAP S4CRM vs C4C, 諸葛亮和周瑜?  曾經(jīng)比較過(guò)這兩個(gè)產(chǎn)品的方方面面，下圖" 系統(tǒng)集成 "這一行，就是本文要詳細(xì)闡述的內(nèi)容。

如我上圖中高亮強(qiáng)調(diào)的，SAP C4C和其他系統(tǒng)做集成，SAP推薦采用基于Netweaver的PI或者HCI作為中間件，而S4CRM同其他系統(tǒng)的集成方式，就由宋浩給大家做詳細(xì)介紹。

下面是宋浩的正文。

大家好，我是宋浩，今年6月份剛加入SAP這個(gè)大家庭，平日里喜歡旅行，看恐怖片，玩單機(jī)恐怖游戲，從生化危機(jī)，零紅蝶，再到惡靈附身，恐怖元素一直是我閑暇時(shí)光的點(diǎn)綴，歡迎各位道友切磋指導(dǎo)。

S4CRM API是我在SAP經(jīng)歷的第一個(gè)項(xiàng)目，我們就從開(kāi)發(fā)這個(gè)API的初衷說(shuō)起吧。CRM市場(chǎng)這些年瞬息萬(wàn)變，百家爭(zhēng)鳴。亂世必出英雄，我們新一代的產(chǎn)品S4CRM可以說(shuō)是生于亂世，肩扛重任。

要實(shí)現(xiàn)一個(gè)企業(yè)的良好運(yùn)營(yíng)，一個(gè)高效且穩(wěn)定的系統(tǒng)體系是必不可少的。而CRM便是這體系中重要的一員。如果一個(gè)已經(jīng)采用SAP S4CRM的客戶本身還有其他第三方系統(tǒng)，那么如何確保S4CRM與這些外部系統(tǒng)之間高效地運(yùn)行與交互呢？我們的S4CRM API由此應(yīng)運(yùn)而生。

借助我們開(kāi)發(fā)的服務(wù)訂單領(lǐng)域相關(guān)的S4CRM API，外部系統(tǒng)可以同S4CRM進(jìn)行一系列的服務(wù)流程操作，一個(gè)典型的場(chǎng)景就是，在外部系統(tǒng)調(diào)用S4CRM API，實(shí)現(xiàn)創(chuàng)建和修改服務(wù)訂單或者服務(wù)確認(rèn)(Service Confirmation)等需求。

如何找到我們11月份剛剛發(fā)布的這些API文檔呢？

瀏覽器訪問(wèn)help.sap.com，看到這位美女后，輸入關(guān)鍵字S/4HANA cloud進(jìn)行搜索：

進(jìn)入S/4HANA cloud的產(chǎn)品頁(yè)面，輸入service order - Create, Change, 即可打開(kāi)我們的API幫助文檔。

對(duì)于我輸入的關(guān)鍵字S/4HANA cloud，大家不用覺(jué)得費(fèi)解，因?yàn)閷?duì)于這些API，S/4HANA On-Premise和Cloud共享同一套ABAP代碼實(shí)現(xiàn)。

幫助文檔里詳細(xì)介紹了API請(qǐng)求和響應(yīng)結(jié)構(gòu)里每個(gè)字段的技術(shù)名稱，長(zhǎng)度和業(yè)務(wù)含義。對(duì)于SAP的老司機(jī)來(lái)說(shuō)，拿到這份文檔就可以開(kāi)工了。

另外在SAP Best Practices Explorer網(wǎng)站上，對(duì)于這些API的使用有更詳細(xì)的說(shuō)明文檔。

您可以直接通過(guò)下面的鏈接瀏覽這些文檔。

https://rapid.sap.com/bp/scopeitems/3D2

文檔里最有用的三部分：

• Process flow： 直接在瀏覽器顯示Service Order Management and Monitoring的流程圖：

(圖太大了，一屏顯示不完全)

• **Process flow(BPMN2): **一個(gè)后綴名為npmn的文件，內(nèi)容同Process flow相同，只是以BPMN格式存儲(chǔ)(業(yè)務(wù)流程建模與標(biāo)記,用于構(gòu)建業(yè)務(wù)流程圖的一種建模語(yǔ)言標(biāo)準(zhǔn))。

• Test script： 一個(gè)word格式的使用手冊(cè)。

因?yàn)門est script里包含了使用API的詳細(xì)步驟，這里不再重復(fù)了，咱們來(lái)談?wù)凷4CRM API的實(shí)現(xiàn)細(xì)節(jié)。

在介紹S4CRM API之前，讓我們先來(lái)回顧SAP CRM顧問(wèn)都非常熟悉的SAP CRM中間件的消息流設(shè)計(jì)。

還是拿前面提到的例子來(lái)說(shuō)明，假設(shè)外部系統(tǒng)通過(guò)CRM中間件觸發(fā)CRM端的服務(wù)訂單創(chuàng)建。那么從外部系統(tǒng)向CRM中間件發(fā)送消息，到我們能夠在CRM的數(shù)據(jù)庫(kù)表CRMD_ORDERADM_H里看到一條對(duì)應(yīng)的服務(wù)訂單抬頭記錄，主要經(jīng)歷了下圖標(biāo)注的三個(gè)步驟。

第一步： Inbound Adapter的字段映射

為什么需要這個(gè)字段映射呢？無(wú)論是老的CRM On-Premise還是新的S4CRM，只要涉及到服務(wù)訂單的創(chuàng)建，最終必定會(huì)調(diào)用到函數(shù)CRM_ORDER_MAINTAIN。而下圖中的Data Container，其數(shù)據(jù)格式同CRM_ORDER_MAINTAIN的輸入?yún)?shù)個(gè)數(shù)截然不同，因此必須要經(jīng)過(guò)Inbound Adapter做一個(gè)格式映射，這個(gè)思想和設(shè)計(jì)模式里的Adapter模式是一個(gè)道理。

因?yàn)镃RM中間件里做格式轉(zhuǎn)換的Inbound Adapter需要支持各種業(yè)務(wù)對(duì)象的數(shù)據(jù)同步，比如服務(wù)訂單，物料主數(shù)據(jù)，產(chǎn)品主數(shù)據(jù)等等，因此Adapter用于接收Data Container的輸入?yún)?shù)類型必然是一個(gè)通用類型：

第二步：Validation Service

一般情況下每一個(gè)CRM中間件數(shù)據(jù)同步對(duì)象都有一個(gè)對(duì)應(yīng)的用于做校驗(yàn)的函數(shù)，在調(diào)用實(shí)際的創(chuàng)建/修改API之前，使用該校驗(yàn)函數(shù)執(zhí)行錯(cuò)誤檢測(cè)，實(shí)現(xiàn)Fail Fast，F(xiàn)ail Early的目的。

Fail Fast, Fail Early是大神Jim Shore和Martin Fowler提出的一種軟件開(kāi)發(fā)實(shí)現(xiàn)理念，詳細(xì)介紹參考Martin的 著作 。

例如下圖中的COM_PRODUCT_MAT_VALIDATE就是物料主數(shù)據(jù)同步對(duì)象對(duì)應(yīng)的數(shù)據(jù)校驗(yàn)函數(shù)，該截圖來(lái)自事務(wù)碼SMW01。

第三步：調(diào)用對(duì)應(yīng)的CRM函數(shù)

如果是服務(wù)訂單同步，意味著函數(shù)CRM_ORDER_MAINTAIN的調(diào)用；如果是物料主數(shù)據(jù)，就是COM_PRODUCT_MAINTAIN，以此類推。

從事基于ABAP Netweaver的SAP產(chǎn)品相關(guān)的二次開(kāi)發(fā)的顧問(wèn)們可以享受一個(gè)優(yōu)勢(shì)：很多作用相似的功能API，在不同的SAP產(chǎn)品中實(shí)現(xiàn)理念也類似，這種風(fēng)格的相似性不容易用語(yǔ)言來(lái)描述，簡(jiǎn)單地說(shuō)就是都帶著一股“ SAP味兒 ”。

比如我之前做過(guò)多年的SAP SD開(kāi)發(fā)，創(chuàng)建銷售訂單用的是函數(shù)SD_SALESDOCUMENT_CREATE，而加入SAP S4CRM團(tuán)隊(duì)后使用函數(shù)CRM_ORDER_MAINTAIN創(chuàng)建CRM里的服務(wù)訂單。當(dāng)我瀏覽了后者的參數(shù)定義，試著寫了一些測(cè)試代碼之后，不由得發(fā)出感嘆，“啊，一切都是熟悉的味道?！?

同樣，我們S4CRM API的實(shí)現(xiàn)思路，同剛剛回顧過(guò)的SAP CRM中間件思路一致，也是三大步驟。

1. Validation

2. Mapping

3. Business Processing

除了Validation和Mapping調(diào)換了順序之外，整體思路和CRM中間件的三大步驟完全一致：

接下來(lái)我們看看在S4CRM里開(kāi)發(fā)一個(gè)API的詳細(xì)步驟。

1. 模型

首先需要的是建模，沒(méi)有模型，API何從談起？

工欲善其事必先利其器，所以我們第一步要做的就是根據(jù)具體的服務(wù)場(chǎng)景中的銷售訂單在SAP系統(tǒng)中建立我們的數(shù)據(jù)模型。

使用事務(wù)碼SXMB_IFR，選擇Enterprise Service Builder, 系統(tǒng)會(huì)在本機(jī)尋找Java運(yùn)行環(huán)境，此項(xiàng)為必須項(xiàng)，所以在建模前務(wù)必要安裝JRE。

模型是需要建在相對(duì)應(yīng)的namespace下面的，我這里使用的是SAP S4CRM標(biāo)準(zhǔn)開(kāi)發(fā)用的namespace：

建模有四大元素：

• 數(shù)據(jù)類型(data Type)

• 消息類型(Message Type)

• 錯(cuò)誤消息類型(Fault Message Type)

• 服務(wù)接口(Service Interface)

首先要做的是創(chuàng)建基本數(shù)據(jù)類型，可以參考現(xiàn)有的global的基礎(chǔ)數(shù)據(jù)元素，將API需要使用到的global數(shù)據(jù)元素從global namespace引入到我們自己的namespace里面來(lái)。

舉個(gè)例子，下圖是SalesArea這個(gè)復(fù)合字段，里面包含了“五朵金花”，大多數(shù)基于Netweaver的SAP產(chǎn)品里，對(duì)于SalesArea的建模都沿用了這一最佳實(shí)踐：

實(shí)際我們這里是在做一個(gè)拼裝工作，樂(lè)高(LEGO)大家一定聽(tīng)說(shuō)過(guò)或者玩過(guò)吧。

如下圖所示，我們像拼裝樂(lè)高玩具那樣，把各種數(shù)據(jù)類型拼裝成一個(gè)結(jié)構(gòu)，用于接收外部數(shù)據(jù)(也就是服務(wù)訂單)。

業(yè)務(wù)模型的結(jié)構(gòu)創(chuàng)建好之后，我們需要再拼裝一個(gè)供Message Type引用的整體數(shù)據(jù)類型，其實(shí)就是將Message Header的信息引入進(jìn)來(lái)，相信有經(jīng)驗(yàn)的顧問(wèn)們已經(jīng)知道這個(gè)Message Header里維護(hù)什么信息了。是的，就是一些用來(lái)做傳輸?shù)臉?biāo)識(shí)性信息。

我們可以回顧下SAP CRM中間件Inbound Adapter的輸入?yún)?shù)，同樣具有這個(gè)Message Header：一切都是熟悉的味道。

所有數(shù)據(jù)類型都就位后，我們可以組裝最終的Service Interface模型了，這個(gè)模型才是最終開(kāi)放給外部去調(diào)用的Webservice 對(duì)象。這里我們采用的是異步傳輸?shù)姆绞?，?dāng)然您也可以選擇同步，取決于大家的實(shí)際需求和業(yè)務(wù)場(chǎng)景。

上圖Service Interface的名稱, ServiceOrderRequest_In , 就是出現(xiàn)在SAP幫助文檔里的API技術(shù)名稱。

這些模型創(chuàng)建好之后，再到事務(wù)碼SPROXY里生成Proxy對(duì)象，實(shí)際上就是能夠被ABAP代碼訪問(wèn)到的ABAP DDIC結(jié)構(gòu)。

2. 使用ABAP實(shí)現(xiàn)服務(wù)訂單的創(chuàng)建和修改

前面已經(jīng)提過(guò)，我們首先要做的是對(duì)外部接收進(jìn)來(lái)的數(shù)據(jù)進(jìn)行校驗(yàn)，以期在調(diào)用CRM_ORDER_MAINTAIN之前最大程度的保證數(shù)據(jù)的正確性。

在數(shù)據(jù)校驗(yàn)執(zhí)行完并且沒(méi)有拋出任何校驗(yàn)錯(cuò)誤以后，我們需要將外部接進(jìn)來(lái)的數(shù)據(jù)結(jié)構(gòu)與SAP CRM_ORDER_MAINTAIN里的數(shù)據(jù)結(jié)構(gòu)進(jìn)行字段映射。

實(shí)際在CRM_ORDER_MAINTAIN里面相關(guān)數(shù)據(jù)字段是分散存儲(chǔ)在對(duì)應(yīng)的結(jié)構(gòu)里的。比如抬頭數(shù)據(jù)大部分是存放在ORDERADM_H中，行項(xiàng)目數(shù)據(jù)大部分是放在ORDERADM_I里，狀態(tài)數(shù)據(jù)存放在STATUS里。

基于這種特性，您會(huì)很容易發(fā)現(xiàn)，變化的始終是模型，而CRM_ORDER_MAINTAIN這邊相對(duì)來(lái)說(shuō)是固定不變的。所以我們專門設(shè)計(jì)了一個(gè)類用于完成數(shù)據(jù)映射。在這個(gè)類的設(shè)計(jì)上，我們傾向于以固定不變的一邊為主，每一個(gè)結(jié)構(gòu)創(chuàng)建一個(gè)方法，這樣有利于以后的復(fù)用和維護(hù)，設(shè)計(jì)也相對(duì)清晰和有層次感。

下圖是這個(gè)數(shù)據(jù)映射類的方法列表：

我們以O(shè)RDERADM_H來(lái)舉例說(shuō)明，Inbound端我們將對(duì)應(yīng)的外部數(shù)據(jù)映射到SAP CRM_ORDER_MAINTAIN對(duì)應(yīng)的結(jié)構(gòu)ORDERADM_H上面。

下圖展示的是數(shù)據(jù)映射類如何將外部數(shù)據(jù)中包含的服務(wù)訂單抬頭字段里包含的ID，類型和描述信息映射給CRM_ORDER_MAINTAIN需要的輸入?yún)?shù)格式。其中紅色高亮的部分是訂單ID這個(gè)字段的映射處理。

所有字段映射完成后，我們就可以進(jìn)行業(yè)務(wù)的處理了，調(diào)用CRM_ORDER_MAINTAIN去創(chuàng)建或者更新服務(wù)訂單。

如果是服務(wù)訂單創(chuàng)建場(chǎng)景，訂單的ID是在S4CRM系統(tǒng)自動(dòng)生成的，創(chuàng)建完畢后需要將生成的服務(wù)訂單數(shù)據(jù)讀取出來(lái)，作為API響應(yīng)發(fā)送給外部系統(tǒng)。

上圖紅色區(qū)域代表調(diào)用CRM_ORDER_MAINTAIN創(chuàng)建服務(wù)訂單的代碼，藍(lán)色區(qū)域代表調(diào)用CRM_ORDER_READ將創(chuàng)建好的訂單明細(xì)從內(nèi)存中讀取出來(lái)，準(zhǔn)備進(jìn)行Outbound處理，即字段映射和映射后的數(shù)據(jù)發(fā)送至外部系統(tǒng)。

發(fā)送響應(yīng)之前的字段映射，將SAP內(nèi)部結(jié)構(gòu)上的數(shù)據(jù)映射到外部結(jié)構(gòu)上的處理邏輯如下圖：

字段映射完畢之后，調(diào)用函數(shù)/AIF/SEND_WITH_PROXY將映射好的結(jié)構(gòu)發(fā)送出去。發(fā)送的目標(biāo)系統(tǒng)通過(guò)Logical Port指定，其值包含在下圖第15行高亮的變量里。

關(guān)于Logical Port在Web Service消費(fèi)場(chǎng)景中的用途，Jerry已經(jīng)在他的SAP博客中詳細(xì)介紹過(guò)，這里不再重復(fù)：

https://blogs.sap.com/2014/05/20/step-by-step-to-create-consume-and-trace-web-service-in-abap-system/

而我們仔細(xì)觀察Logical Port的獲取，這個(gè)值是通過(guò)好幾個(gè)參數(shù)共同決定的。

IF_CONF_API_SRO_CONSTANTS=>COMM-SCENARIO_ID:

這個(gè)字段是一個(gè)常量，值為SAP_COM_0424:

SAP_COM_0424代表的communication scenario的配置步驟，可以從我之前介紹的SAP Best Practices Explorer網(wǎng)站下載。

這個(gè)communication scenario就是SAP針對(duì)實(shí)際系統(tǒng)集成場(chǎng)景抽象出來(lái)的一種開(kāi)箱即用的模型，通過(guò)少量簡(jiǎn)單的配置就能實(shí)現(xiàn)和其他系統(tǒng)做集成。

比如在SAP Cloud for Customer里同樣存在communication scenario的概念，用法也類似：

最后，我模擬外部系統(tǒng)調(diào)用S4CRM API來(lái)創(chuàng)建服務(wù)訂單，給大家一個(gè)更直觀的感受。

我使用SOAP UI這個(gè)軟件來(lái)發(fā)起請(qǐng)求。下圖可以看到我們出發(fā)了一個(gè)請(qǐng)求，創(chuàng)建一個(gè)事務(wù)類型為SVO1的服務(wù)訂單:

SOAP UI里成功調(diào)用Web Service之后，到S4CRM系統(tǒng)查看我們剛才創(chuàng)建的服務(wù)訂單明細(xì)：

最后大家或許會(huì)好奇真正執(zhí)行發(fā)送動(dòng)作的函數(shù)/AIF/SEND_WITH_PROXY。

我們還是先來(lái)回憶SAP CRM中間件，比如CRM向ERP發(fā)送數(shù)據(jù)這個(gè)場(chǎng)景，最后實(shí)質(zhì)是執(zhí)行的RFC調(diào)用：

而S4CRM API使用的/AIF/SEND_WITH_PROXY，這個(gè)函數(shù)的前綴AIF代表Application Interface Framework, 是SAP Netweaver上的一個(gè)Addon，一個(gè)輕量級(jí)的數(shù)據(jù)集成中間件的解決方案。

關(guān)于AIF的更多介紹，大家可以閱讀下面這篇SAP博客：

https://blogs.sap.com/2012/04/03/sap-aif-so-what-is-it-all-about/

我們成都S4CRM團(tuán)隊(duì)負(fù)責(zé)開(kāi)發(fā)的API還在不斷的功能增強(qiáng)中，敬請(qǐng)期待。感謝大家的閱讀。

相關(guān)閱讀

• SAP的這三款CRM解決方案，您能區(qū)分清楚么

• Hello World, S/4HANA for Customer Management 1.0

• SAP S4CRM vs C4C, 諸葛亮和周瑜?

• 一個(gè)SAP顧問(wèn)在美國(guó)的這些年

要獲取更多Jerry的原創(chuàng)文章，請(qǐng)關(guān)注公眾號(hào)"汪子熙":