SAP S4CRM 1811 服務訂單API介紹

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的使用有更詳細的說明文件。

您可以直接透過下面的連結瀏覽這些文件。

文件裡最有用的三部分：

• 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部落格中詳細介紹過，這裡不再重複：

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

而我們仔細觀察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還在不斷的功能增強中，敬請期待。感謝大家的閱讀。

相關閱讀

• SAP的這三款CRM解決方案，您能區分清楚麼

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

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

• 一個SAP顧問在美國的這些年

要獲取更多Jerry的原創文章，請關注公眾號"汪子熙":