移动平台第三方系统集成方案V2.0

       最近收到很多客户和伙伴的反馈，希望能够在第三方系统中，集成金蝶云星空的业务审批，例如查看业务审批列表，接受待办消息推送，点击待办消息进行审批等。尤其是在钉钉环境中，对业务审批的集成更为迫切（由于钉钉出入口ip的限制，金蝶公有云环境无法直接接入钉钉）。基于这个考虑，我们推出了移动平台第三方系统集成方案，详细介绍如下：

1.  接入流程与使用场景，如图所示：
   
   

    a、 开发者在金蝶云星空后台进行相关配置，并实现相关的接口；
    b、 客户提交工作流后，待办消息会由金蝶云星空系统，自动推送到指定的接口；
    c 、开发者获得推送的消息后，对消息的处理（如推送到钉钉等）；
    d、 客户接收到推送的消息，点击进入开发者设计的中转页面，并通过单点登录的方式进入金蝶云系统进行；

    e、如果不需要接受消息推送，那么只需要实现单点登录即可；

    f、适用版本：8.0 及以上补丁

    g、对应的单据，需要再Administrator登录==》移动平台单据启用设置===》启用移动审批；

    h、Administrator登录==》参数设置==》基础管理===》移动平台==》发送第三方消息==开启

2. 单点登录实现：
    2.1参数设置：
    登录金蝶云星空后台，打开表单-第三方系统登录授权，点击新增，如下图：

    
      点击获取应用ID，按步骤操作，操作完成后，如下图所示，其中 应用名称和密钥可修改；集成用户不需要选择，然后点击保存：

     
 2.2 代码实现：
    开发者需要根据上述应用id，密钥，以及当前登录用户名，来生成单点登录的链接，并在中转页面中进行跳转，c#代码示例如下：

private void GotoCloud()

      {

        string url = GetUrl();  

        this.Response.Redirect(url);

      }

      private string GetUrl()

      {

        //数据中心Id

        string acctId = "5d1af48d463f54"; 

        //用户名

        string username = "db"; 

        //第三方系统登录授权的应用Id;

        string appId = "204740_5ecB67CG1oCZW9/JSYQOybwFTMw62omL";

        //第三方系统登录授权的应用密钥;

        string appSecret = "090de81733b5466cb90bdb2cc6e76b19"; 

        int lcId = 2052; //语言标识 中文：2052，繁体：3067，英文：1033        

        long timestamp = CurrentTimeMillis() / 1000; //时间戳        

        string[] arr = new string[] { acctId, username, appId, appSecret, timestamp.ToString() };

        //签名

        string sign = GetSignature(arr);    

        //base64编码       

        string sign64 = GetBase64String(appId,username,appSecret,sign,timestamp);

        //金蝶云星空后台设置的系统公网地址 

        string serverUrl = "http://172.17.1.121/k3cloud"; 

        //登录成功后打开的表单Id，业务审批列表：Mob_XWfListEdit; 业务审批详情：Mob_DistributionWfBill;

        string formId = "MOB_CoreConsole";

        //移动单据列表则用formtype = "mobilelist"  

        string formType = "mobile"; 

        //单据详情主键，如果打开的是业务审批详情，需要传入的是待办任务id

        string pkId = ""; 

        string url = GetUrl(serverUrl, acctId, lcId, sign64, formId, formType, pkId);

        return url;

      }

      private string GetUrl(string serverUrl, string acctId, int lcId, string sign64, string formId, string formType, string pkId)

      { 

        string url = string.Format(@"{0}/xmobile/cloud.html?entryrole=oo&acctid={1}&lcid={2}&sign={3}&formid={4}&formtype={5}&pkid={6}", serverUrl,  acctId, lcId, sign64, formId, formType, pkId);        

        return url;

      }

      private string GetBase64String(string appId, string username, string appSecret, string sign, long timestamp)

      {

        //下面json中的参数严格区分大小写，请保持一致

        string signInfo = "{'appId':'" + appId + "','username':'" + System.Web.HttpUtility.UrlEncode(username) +  "','sign':'" + sign + "','timestamp':" + timestamp + "}";      

        byte[] bytes = Encoding.UTF8.GetBytes(signInfo);

        return Convert.ToBase64String(bytes);

      } 

   private string GetSignature(string[] arr)

      {

        //1. 将数组进行排序

        //2. 将数组拼接成一个字符串进行sha加密

        Array.Sort(arr, StringComparer.Ordinal);

        var arrString = string.Join("", arr);

        var sha = System.Security.Cryptography.SHA256.Create();

        var shaArr = sha.ComputeHash(Encoding.UTF8.GetBytes(arrString));

        StringBuilder enText = new StringBuilder();

        foreach (var b in shaArr)

        {

            enText.AppendFormat("{0:x2}", b);

        }

        return enText.ToString();

      }

      private long CurrentTimeMillis()

      {

        var janist1970 = new DateTime(1970,1,1,0,0,0,DateTimeKind.Utc); 

        return (long)((DateTime.UtcNow - janist1970).TotalMilliseconds);

      }

3. 消息推送设置（如果不需要接受消息推送，本部分可以略过）：
    3.1 登录金蝶云星空后台，打开表单-第三方平台集成配置，按下图设置：

选择金蝶云星空轻应用：

     3.2 登录金蝶云星空后台，打开参数设置--基础管理—移动平台，按下图设置：
     
           

4. 消息推送实现：
    4.1 消息推送实现类的编写：
        开发者需要实现接口Kingdee.BOS.Mobile.Contract.IOtherPlatformMessage中的方法Send，并完成具体的业务逻辑，接口定义如下：   

      /// <summary>

      /// 第三方平台消息接口

      /// </summary>

      [ServiceContract]

      [RpcServiceError]

      public interface IOtherPlatformMessage

      {

          [OperationContract]

          [FaultContract(typeof(ServiceFault))]

          MobileResponse Send(Context ctx, MobileMessage message);

      }

    参数及返回值的定义：

    接口实现示例：

    public class OtherPlatformMessage : IOtherPlatformMessage

      {

          public MobileResponse Send(Context ctx, MobileMessage message)

          {

              //具体的业务逻辑

              var response = new MobileResponse();

              response.Errcode = 0;

              response.Errmsg = "Test";

              return response;

           }

        } 

    4.2注意事项：
        a、message中的users为消息接收者的金蝶云星空的用户id列表；当消息类型为待办转已办时候，该用户id可能为：PUSH_ALL_USERS，表示该待办消息的所有接受者(只有待办任务终止、撤销、完成的时候，才会发送PUSH_ALL_USERS)，钉钉目前不支持待办转义办，所以不需要考虑PUSH_ALL_USERS的情况；
        b、开发者需要自己维护：第三方系统与金蝶云星空系统的用户映射列表，需要根据映射关系找到第三方系统中的用户并处理；
        c、message中的sourceid是待办任务id，status是枚举消息类型，status为todo=1表示发送待办消息；status为done=2，表示待办转已办消息；
        d、message不提供url，消息打开的链接需要开发者，根据单点登录的方案自助生成，详见下文； 
        e、该消息为异步发送，由于执行速度的问题，如果需要根据待办任务id，查询金蝶云星空系统中待办任务及流程相关数据，可能会遇到相关数据查询不到情况；若遇到该问题，可以做一个间隔重试的操作。