Jerry在今年2月28日，SAP Customer Management for S/4HANA 1.0正式問世這個具有紀念意義的日子，同時發佈了中英文版的博客進行介紹。
英文版發在SAP社區上，至今超過16000的閱讀量：
而發佈在微信上的中文版，也有兩千多的閱讀量：
一轉眼大半年就過去了，如今SAP S4CRM的標準開發，進行得怎麼樣了呢？在SAP社區上我寫的那個英文博客裏，有很多國外的partners在上面留言詢問各種各樣的問題。由於今年4月份起Jerry就離開了S4CRM開發團隊，所以很多問題我沒有辦法回答，於是我邀請了SAP S4CRM的首席產品經理Frick Oliver在社區上回答大家提出的問題：
這是Oliver介紹S4CRM的視頻，節選自SAP官方招聘公衆號上的一篇文章。大家可以一睹這位德國老帥哥的風采。
今天這篇文章我邀請了SAP成都研究院S4CRM團隊的開發人員宋浩，由他介紹所在團隊設計並開發的S4CRM裏服務訂單(Service Order)創建和更新的API。關於宋浩的背景介紹，大家可以參考他之前的文章：一個SAP顧問在美國的這些年。
在宋浩的文章裏，Jerry也植入了一些關於SAP CRM中間件和SAP Cloud for Customer內容介紹，這些內容都和SAP基於Netweaver的系統集成這個主題相關，希望能對大家有所幫助。
爲什麼SAP要成立專門的團隊來做API開發呢？最簡單的4個字答案：系統集成。
Jerry的另一篇文章：SAP S4CRM vs C4C, 諸葛亮和周瑜? 曾經比較過這兩個產品的方方面面，下圖"系統集成"這一行，就是本文要詳細闡述的內容。
如我上圖中高亮強調的，SAP C4C和其他系統做集成，SAP推薦採用基於Netweaver的PI或者HCI作爲中間件，而S4CRM同其他系統的集成方式，就由宋浩給大家做詳細介紹。
下面是宋浩的正文。
大家好，我是宋浩，今年6月份剛加入SAP這個大家庭，平日裏喜歡旅行，看恐怖片，玩單機恐怖遊戲，從生化危機，零紅蝶，再到惡靈附身，恐怖元素一直是我閒暇時光的點綴，歡迎各位道友切磋指導。
S4CRM API是我在SAP經歷的第一個項目，我們就從開發這個API的初衷說起吧。CRM市場這些年瞬息萬變，百家爭鳴。亂世必出英雄，我們新一代的產品S4CRM可以說是生於亂世，肩扛重任。
要實現一個企業的良好運營，一個高效且穩定的系統體系是必不可少的。而CRM便是這體系中重要的一員。如果一個已經採用SAP S4CRM的客戶本身還有其他第三方系統，那麼如何確保S4CRM與這些外部系統之間高效地運行與交互呢？我們的S4CRM API由此應運而生。
藉助我們開發的服務訂單領域相關的S4CRM API，外部系統可以同S4CRM進行一系列的服務流程操作，一個典型的場景就是，在外部系統調用S4CRM API，實現創建和修改服務訂單或者服務確認(Service Confirmation)等需求。
如何找到我們11月份剛剛發佈的這些API文檔呢？
瀏覽器訪問help.sap.com，看到這位美女後，輸入關鍵字S/4HANA cloud進行搜索：
進入S/4HANA cloud的產品頁面，輸入service order - Create, Change, 即可打開我們的API幫助文檔。
對於我輸入的關鍵字S/4HANA cloud，大家不用覺得費解，因爲對於這些API，S/4HANA On-Premise和Cloud共享同一套ABAP代碼實現。
幫助文檔裏詳細介紹了API請求和響應結構裏每個字段的技術名稱，長度和業務含義。對於SAP的老司機來說，拿到這份文檔就可以開工了。
另外在SAP Best Practices Explorer網站上，對於這些API的使用有更詳細的說明文檔。
您可以直接通過下面的鏈接瀏覽這些文檔。
https://rapid.sap.com/bp/scopeitems/3D2
文檔裏最有用的三部分：
- **Process flow：**直接在瀏覽器顯示Service Order Management and Monitoring的流程圖：
(圖太大了，一屏顯示不完全)
- **Process flow(BPMN2): **一個後綴名爲npmn的文件，內容同Process flow相同，只是以BPMN格式存儲(業務流程建模與標記,用於構建業務流程圖的一種建模語言標準)。
- **Test script：**一個word格式的使用手冊。
因爲Test script裏包含了使用API的詳細步驟，這裏不再重複了，咱們來談談S4CRM API的實現細節。
在介紹S4CRM API之前，讓我們先來回顧SAP CRM顧問都非常熟悉的SAP CRM中間件的消息流設計。
還是拿前面提到的例子來說明，假設外部系統通過CRM中間件觸發CRM端的服務訂單創建。那麼從外部系統向CRM中間件發送消息，到我們能夠在CRM的數據庫表CRMD_ORDERADM_H裏看到一條對應的服務訂單擡頭記錄，主要經歷了下圖標註的三個步驟。
第一步： Inbound Adapter的字段映射
爲什麼需要這個字段映射呢？無論是老的CRM On-Premise還是新的S4CRM，只要涉及到服務訂單的創建，最終必定會調用到函數CRM_ORDER_MAINTAIN。而下圖中的Data Container，其數據格式同CRM_ORDER_MAINTAIN的輸入參數個數截然不同，因此必須要經過Inbound Adapter做一個格式映射，這個思想和設計模式裏的Adapter模式是一個道理。
因爲CRM中間件裏做格式轉換的Inbound Adapter需要支持各種業務對象的數據同步，比如服務訂單，物料主數據，產品主數據等等，因此Adapter用於接收Data Container的輸入參數類型必然是一個通用類型：
第二步：Validation Service
一般情況下每一個CRM中間件數據同步對象都有一個對應的用於做校驗的函數，在調用實際的創建/修改API之前，使用該校驗函數執行錯誤檢測，實現Fail Fast，Fail Early的目的。
Fail Fast, Fail Early是大神Jim Shore和Martin Fowler提出的一種軟件開發實現理念，詳細介紹參考Martin的著作。
例如下圖中的COM_PRODUCT_MAT_VALIDATE就是物料主數據同步對象對應的數據校驗函數，該截圖來自事務碼SMW01。
第三步：調用對應的CRM函數
如果是服務訂單同步，意味着函數CRM_ORDER_MAINTAIN的調用；如果是物料主數據，就是COM_PRODUCT_MAINTAIN，以此類推。
從事基於ABAP Netweaver的SAP產品相關的二次開發的顧問們可以享受一個優勢：很多作用相似的功能API，在不同的SAP產品中實現理念也類似，這種風格的相似性不容易用語言來描述，簡單地說就是都帶着一股“SAP味兒”。
比如我之前做過多年的SAP SD開發，創建銷售訂單用的是函數SD_SALESDOCUMENT_CREATE，而加入SAP S4CRM團隊後使用函數CRM_ORDER_MAINTAIN創建CRM裏的服務訂單。當我瀏覽了後者的參數定義，試着寫了一些測試代碼之後，不由得發出感嘆，“啊，一切都是熟悉的味道。”
同樣，我們S4CRM API的實現思路，同剛剛回顧過的SAP CRM中間件思路一致，也是三大步驟。
1. Validation
2. Mapping
3. Business Processing
除了Validation和Mapping調換了順序之外，整體思路和CRM中間件的三大步驟完全一致：
接下來我們看看在S4CRM裏開發一個API的詳細步驟。
1. 模型
首先需要的是建模，沒有模型，API何從談起？
工慾善其事必先利其器，所以我們第一步要做的就是根據具體的服務場景中的銷售訂單在SAP系統中建立我們的數據模型。
使用事務碼SXMB_IFR，選擇Enterprise Service Builder, 系統會在本機尋找Java運行環境，此項爲必須項，所以在建模前務必要安裝JRE。
模型是需要建在相對應的namespace下面的，我這裏使用的是SAP S4CRM標準開發用的namespace：
建模有四大元素：
-
數據類型(data Type)
-
消息類型(Message Type)
-
錯誤消息類型(Fault Message Type)
-
服務接口(Service Interface)
首先要做的是創建基本數據類型，可以參考現有的global的基礎數據元素，將API需要使用到的global數據元素從global namespace引入到我們自己的namespace裏面來。
舉個例子，下圖是SalesArea這個複合字段，裏面包含了“五朵金花”，大多數基於Netweaver的SAP產品裏，對於SalesArea的建模都沿用了這一最佳實踐：
實際我們這裏是在做一個拼裝工作，樂高(LEGO)大家一定聽說過或者玩過吧。
如下圖所示，我們像拼裝樂高玩具那樣，把各種數據類型拼裝成一個結構，用於接收外部數據(也就是服務訂單)。
業務模型的結構創建好之後，我們需要再拼裝一個供Message Type引用的整體數據類型，其實就是將Message Header的信息引入進來，相信有經驗的顧問們已經知道這個Message Header裏維護什麼信息了。是的，就是一些用來做傳輸的標識性信息。
我們可以回顧下SAP CRM中間件Inbound Adapter的輸入參數，同樣具有這個Message Header：一切都是熟悉的味道。
所有數據類型都就位後，我們可以組裝最終的Service Interface模型了，這個模型纔是最終開放給外部去調用的Webservice 對象。這裏我們採用的是異步傳輸的方式，當然您也可以選擇同步，取決於大家的實際需求和業務場景。
上圖Service Interface的名稱,ServiceOrderRequest_In, 就是出現在SAP幫助文檔裏的API技術名稱。
這些模型創建好之後，再到事務碼SPROXY裏生成Proxy對象，實際上就是能夠被ABAP代碼訪問到的ABAP DDIC結構。
2. 使用ABAP實現服務訂單的創建和修改
前面已經提過，我們首先要做的是對外部接收進來的數據進行校驗，以期在調用CRM_ORDER_MAINTAIN之前最大程度的保證數據的正確性。
在數據校驗執行完並且沒有拋出任何校驗錯誤以後，我們需要將外部接進來的數據結構與SAP CRM_ORDER_MAINTAIN裏的數據結構進行字段映射。
實際在CRM_ORDER_MAINTAIN裏面相關數據字段是分散存儲在對應的結構裏的。比如擡頭數據大部分是存放在ORDERADM_H中，行項目數據大部分是放在ORDERADM_I裏，狀態數據存放在STATUS裏。
基於這種特性，您會很容易發現，變化的始終是模型，而CRM_ORDER_MAINTAIN這邊相對來說是固定不變的。所以我們專門設計了一個類用於完成數據映射。在這個類的設計上，我們傾向於以固定不變的一邊爲主，每一個結構創建一個方法，這樣有利於以後的複用和維護，設計也相對清晰和有層次感。
下圖是這個數據映射類的方法列表：
我們以ORDERADM_H來舉例說明，Inbound端我們將對應的外部數據映射到SAP CRM_ORDER_MAINTAIN對應的結構ORDERADM_H上面。
下圖展示的是數據映射類如何將外部數據中包含的服務訂單擡頭字段裏包含的ID，類型和描述信息映射給CRM_ORDER_MAINTAIN需要的輸入參數格式。其中紅色高亮的部分是訂單ID這個字段的映射處理。
所有字段映射完成後，我們就可以進行業務的處理了，調用CRM_ORDER_MAINTAIN去創建或者更新服務訂單。
如果是服務訂單創建場景，訂單的ID是在S4CRM系統自動生成的，創建完畢後需要將生成的服務訂單數據讀取出來，作爲API響應發送給外部系統。
上圖紅色區域代表調用CRM_ORDER_MAINTAIN創建服務訂單的代碼，藍色區域代表調用CRM_ORDER_READ將創建好的訂單明細從內存中讀取出來，準備進行Outbound處理，即字段映射和映射後的數據發送至外部系統。
發送響應之前的字段映射，將SAP內部結構上的數據映射到外部結構上的處理邏輯如下圖：
字段映射完畢之後，調用函數/AIF/SEND_WITH_PROXY將映射好的結構發送出去。發送的目標系統通過Logical Port指定，其值包含在下圖第15行高亮的變量裏。
關於Logical Port在Web Service消費場景中的用途，Jerry已經在他的SAP博客中詳細介紹過，這裏不再重複：
而我們仔細觀察Logical Port的獲取，這個值是通過好幾個參數共同決定的。
IF_CONF_API_SRO_CONSTANTS=>COMM-SCENARIO_ID:
這個字段是一個常量，值爲SAP_COM_0424:
SAP_COM_0424代表的communication scenario的配置步驟，可以從我之前介紹的SAP Best Practices Explorer網站下載。
這個communication scenario就是SAP針對實際系統集成場景抽象出來的一種開箱即用的模型，通過少量簡單的配置就能實現和其他系統做集成。
比如在SAP Cloud for Customer裏同樣存在communication scenario的概念，用法也類似：
最後，我模擬外部系統調用S4CRM API來創建服務訂單，給大家一個更直觀的感受。
我使用SOAP UI這個軟件來發起請求。下圖可以看到我們出發了一個請求，創建一個事務類型爲SVO1的服務訂單:
SOAP UI裏成功調用Web Service之後，到S4CRM系統查看我們剛纔創建的服務訂單明細：
最後大家或許會好奇真正執行發送動作的函數/AIF/SEND_WITH_PROXY。
我們還是先來回憶SAP CRM中間件，比如CRM向ERP發送數據這個場景，最後實質是執行的RFC調用：
而S4CRM API使用的/AIF/SEND_WITH_PROXY，這個函數的前綴AIF代表Application Interface Framework, 是SAP Netweaver上的一個Addon，一個輕量級的數據集成中間件的解決方案。
關於AIF的更多介紹，大家可以閱讀下面這篇SAP博客：
https://blogs.sap.com/2012/04/03/sap-aif-so-what-is-it-all-about/
我們成都S4CRM團隊負責開發的API還在不斷的功能增強中，敬請期待。感謝大家的閱讀。
相關閱讀
要獲取更多Jerry的原創文章，請關注公衆號"汪子熙":
