Technical Articles
Build your WeChat Work Mobile Micro App With SAP Mobile Services
What is Micro App
An SAP Mobile Services Micro App is the application that you can build & deploy to SAP Business Technology Platform (SAP BTP) and integrating with 3rd social app platform, such as WeChat work, DingTalk, etc.
Now Users are already able to create WeChat Work (or WeCom) type Micro App in SAP Mobile Services (Cloud Foundry). In such an application, users could receive / push different kind of messages from WeChat Work client, and build their own business logic in the SAP BTP application. This provides a way to integrate 3rd party social app platform with SAP systems via SAP Mobile Services.
The full documentation for SAP Mobile Services Micro App can be found in SAP Help Portal: Configuring Micro Apps
This article is an End-to-End solution tutorial for integrating WeChat Work into SAP Mobile Services and will show you how to configure and create your own WeChat Work Micro App in SAP Mobile Services (Cloud Foundry) step by step.
Please also note that currently Micro App feature for now is only available in China.
Before start, you should have your WeChat Work admin account and SAP Mobile Services CF account ready. And I assume you already have basic knowledge about Java, REST API development and basic SAP BTP Cloud Foundry concept.
Step 1. Create your WeChat Work App Configuration
Firstly, you’ll need to create a WeChat Work application in WeChat admin page.
In this admin page, go to “App Management” and create your own App using “+ Create an App”.
Then enter your app logo, app name, select your allowed users (must), descriptions and create the app with button.
- AgentID: This is an auto-generated unique ID for your WeChat Work app in your account. You can get this value from the above screenshot highlighted part 1.
- App Secret: This is the auto-generated app secret for your WeChat Work app. You can get this value from the above screenshot highlighted part 2.
- CorpId: The Corp id for your WeChat Work enterprise id. You can easily get this corp id from the header tab “My Company” of WeChat Work admin page.
- Token and EncodingAESKey: Token and EncodingAESKey are used to allowed your CF application to receive WeChat messages from WeChat Work client. To generate Token and EncodingAESKey, click on “API enabled to receive messages” of Receive messages tab (see highlighted part 3 of above screenshot), then you’ll see following fields.
Generate token and EncodingAESKey manually by clicking “Acquire randomly” buttons (see highlighted part 1 and 2).Note: Regarding the message receiving URL, we’ll deal with it later. Please copy & paste your Token and EncodingAESKey to somewhere else since those information could miss after you click the Back or Cancel button.
Step 2. Create your Mobile Services Application Configuration
Step 3. Create your own business application and Deploy to SAP BTP CF
Now you can create your real business application on Cloud Foundry. You can use many ways here to create your application, e.g. SAP WebIDE, SAP Business Application Studio, or any other IDE you like.
PS: So far the Mobile Services Microapp extension for SAP Business Application Studio is already available, if you want to use SAP Business Application Studio to build Micro app, please see this blog post:
Using SAP Business Application Studio to build WeChat Work Micro App With SAP Mobile Services
This section will only focus on building Micro App using SAP WebIDE.
- com.sap.microapp.messaging.controller: This contains the most important Controller (Portal) for the Java application. As we can see from the above screenshot, there is a default “/OnMessage” controller here, it is used to communicate with WeChat Work Server through Mobile Services , and receives XML WeChat messages sent from WeChat Work Server.The XML format is following the doc of WeChat Work API Doc for message receiving (Chinese doc). A simple WeChat message receive/response format and the the WeChat message consume flow is shown as below.
As example, your end user sent a “ping” text from WeChat Work app, then your CF business application receive the XML payload, parse it and send back a “pong” as response. Other message types rather than text message are all supported in Mobile Services, such as picture, video, voice, etc. Note: You may want to push the result back to your end users and inform them that your business handling is success or not, to do so, return back your customized XML message payload as Response Body in the “/OnMessage” controller. (see step E in the above picture, the response followed the totally same XML format as incoming message in step C)
- com.sap.microapp.messaging.model: This package contains the WeChat Messages model to store the incoming/outcoming XML format Message. (All field names follow the WeChat API Doc)
- com.sap.microapp.messaging.service and com.sap.microapp.messaging.timeoff: The Default business logic is put in com.sap.microapp.messaging.service which consumes the message and pushes an echo string back to the client. In this Demo, I created some own business logic in the com.sap.microapp.messaging.timeoff and some UI index/display pages for TimeOff App so that we are able to create/approve/check leave requests in the Java application by both WeChat chatting and UI. Considering the Rest API development, I provide following request mapping:
- “/welcome” (GET) to provide welcome text just for testing
- “/OnMessage” (POST) to receive WeChat XML message as discussed
- “/leaverequest” (POST/PUT/GET) to provide APIs to create/update/retrieve leave requests. Those APIs are mainly called in my UI page, e.g. call “/timeoff/leaverequest” to create request through Mobile Services:
$.ajax({ url: "/timeoff/leaverequest", contentType: "application/json;charset=UTF-8", data: JSON.stringify(postData), type: "POST", success: function(result){ //... }, error: function(jqXHR, textStatus, errorThrown) {} });
Besides the message receives/response feature, Mobile Services also provides WeChat message push notification feature. To call the push API, use the push API URL mentioned in Step 2 with setting the service key to “X-API-Key” header. Mobile Services supports pushing different kinds of WeChat message to end users, such as simple text, markdown text, text card, WeChat news, etc. And also supporting upload file, picture, video, voice and push the those to users.
To push the WeChat Work notification, you need to build your JSON payload, the example format is like following:
// push simple text to user P000001
{
"notification": {
"wechat": {
"createtime": "2019-12-17T06:24:26.451Z",
"text": {
"content": "hello world!"
},
"msgtype": "text"
}
},
"users": ["P000001"]
}
// upload base64 encoded file and push it to user P000001
{
"notification": {
"wechat": {
"createtime": "2019-12-17T06:52:23.417Z",
"file": {
"media_file_encoded": "data:application/x-zip-compressed;base64,XXXXXXXXXX",
"media_file_name": "abc.zip"
},
"msgtype": "file"
}
},
"users": ["P000001"]
}
Note: The full documentation regarding WeChat push API and WeChat message receiving is already documented in Micro App APIs for WeChat.
Step 4. Config and run your WeChat application
Before running the application, there are still some steps to be processed to get WeChat communication work (as mentioned in Step 1 and Step 2)
And that is why you should call your CF application Rest API “/leaverequest” using request URL like: <Mobile Services Server API>/timeoff/leaverequest
Actually all of those Server API URL can be retrieved from the Micro App application “APIs” tab of Mobile Services Cockpit. Note: For both destinations, the authentication type should be “Forward Authentication”.
If you see that “save is successful”, Congratulations ! you are all set for the integration configuration of SAP Mobile Services and WeChat Work.
Summary
To create and deploy Cloud Foundry application and integrates with SAP Mobile Services Micro App and WeChat Work, you need to:
- Create and configure WeChat Work application in WeChat Work admin page.
- Create and configure SAP Mobile Services Micro App application, including:
- configure Micro App with WeChat application information
- generate service key for WeChat push feature
- create destinations pointing to your Cloud Foundry application
- Create your Cloud Foundry application (e.g. a Spring Boot Java project) which implements:
- the WeChat message receiving controller module
- WeChat notification push modules
- other business logic of your application
Feedback & Support
Please contact the following project owner if you have any questions:
jian-dong.pei@sap.com
Excellent!
Hi Perry,
For other data centers outside China, can I enable Wechat Micro App feature on Mobile Services?
No, it's only available on AliCloud.