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

您能夠直接經過下面的連接瀏覽這些文檔。

https://rapid.sap.com/bp/scop...

文檔裏最有用的三部分：

• 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...

而咱們仔細觀察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...

咱們成都S4CRM團隊負責開發的API還在不斷的功能加強中，敬請期待。感謝你們的閱讀。

相關閱讀

• SAP的這三款CRM解決方案，您能區分清楚麼
• Hello World, S/4HANA for Customer Management 1.0
• SAP S4CRM vs C4C, 諸葛亮和周瑜?
• 一個SAP顧問在美國的這些年

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