使用嵌入式签名向DocuSign模板填充自定义合并字段问题排查

你遇到的模板合并字段无法填充的核心问题是混淆了DocuSign信封自定义字段和模板合并字段的用法：你当前给Envelope添加的CustomField是信封级别的元数据字段，用来存储信封相关的自定义信息，并不是用来填充模板里的合并字段的。模板合并字段需要通过TemplateReference中的角色分配来绑定对应的数据。

代码中的具体问题点 #

1. 错误的字段映射方式：你把数据放到了EnvelopeInformation.CustomFields里，但这和模板合并字段没有关联，DocuSign不会用这些值去填充模板里的合并字段。
2. 角色分配缺少字段数据：你创建的TemplateReferenceRoleAssignment只设置了角色名和收件人ID，但没有绑定模板合并字段对应的数据源，导致模板没有数据可以填充。
3. 角色名匹配风险：代码中用'Signer ' + String.valueOf(signerNumber)作为角色名，需要确保DocuSign模板里的角色名和这个完全一致（包括大小写、空格），否则角色映射失败，字段也无法填充。

修正后的代码示例 #

重点修改处理TemplateReference的循环部分，为每个角色分配添加模板字段映射：

seq = 1;
for(DocuSign_Lease_Mapping__c objDocuSignLeaseMapping : lstDocuSignLeaseMapping){
    reference = new DocusignAPI.TemplateReference();
    reference.TemplateLocation = 'Server';
    reference.Template = objDocuSignLeaseMapping.DocuSign_Template_ID__c;
    reference.sequence = seq;
    reference.RoleAssignments = new DocuSignAPI.ArrayOfTemplateReferenceRoleAssignment();
    reference.RoleAssignments.RoleAssignment = new DocuSignAPI.TemplateReferenceRoleAssignment[lstcontact.size()];
    
    // 为每个签名人角色绑定模板合并字段数据
    for(Integer i=0; i<lstcontact.size(); i++){
        Contact signerContact = lstcontact[i];
        Integer signerNum = i+1;
        
        // 1. 创建角色分配对象
        DocuSignAPI.TemplateReferenceRoleAssignment roleAssignment = new DocuSignAPI.TemplateReferenceRoleAssignment();
        roleAssignment.RoleName = 'Signer ' + String.valueOf(signerNum); // 必须和模板里的角色名完全一致
        roleAssignment.RecipientID = String.valueOf(signerNum);
        
        // 2. 创建模板字段映射（对应模板里的合并字段）
        DocuSignAPI.ArrayOfTemplateField templateFields = new DocuSignAPI.ArrayOfTemplateField();
        // 根据你模板里的合并字段数量调整数组长度
        templateFields.TemplateField = new DocuSignAPI.TemplateField[3];
        
        // 示例：模板里的合并字段是 {{SignerName}}、{{SignerEmail}}、{{ApplicationID}}
        DocuSignAPI.TemplateField nameField = new DocuSignAPI.TemplateField();
        nameField.Name = 'SignerName'; // 模板里的合并字段名（必须完全匹配）
        nameField.Value = signerContact.Name;
        
        DocuSignAPI.TemplateField emailField = new DocuSignAPI.TemplateField();
        emailField.Name = 'SignerEmail'; // 模板里的合并字段名
        emailField.Value = signerContact.Email;
        
        DocuSignAPI.TemplateField appIdField = new DocuSignAPI.TemplateField();
        appIdField.Name = 'ApplicationID'; // 模板里的合并字段名
        appIdField.Value = objApplication.Id;
        
        templateFields.TemplateField[0] = nameField;
        templateFields.TemplateField[1] = emailField;
        templateFields.TemplateField[2] = appIdField;
        
        // 3. 将字段映射绑定到角色分配
        roleAssignment.TemplateFields = templateFields;
        
        // 4. 添加到角色分配数组
        reference.RoleAssignments.RoleAssignment[i] = roleAssignment;
    }
    
    templateReferenceArray.TemplateReference[index] = reference;
    index++;
    seq++;
}

关键注意事项 #

• 字段名完全匹配：TemplateField.Name必须和DocuSign模板里的合并字段名100%一致（包括大小写、拼写、特殊字符），比如模板里用{{TenantFullName}}，代码里就不能写成tenantFullName。
• 角色名完全匹配：代码中的roleAssignment.RoleName必须和模板里创建的角色名称完全一致，如果模板里的角色是“Tenant”、“Co-Tenant”，就要把代码里的'Signer ' + String.valueOf(signerNum)改成对应的名称。
• 保留信封自定义字段：如果你确实需要信封级别的自定义字段（比如DSFSSourceObjectId），可以保留EnvelopeInformation.CustomFields的代码，这部分和模板合并字段不冲突。

按照这个修改后，模板里的合并字段就能正确填充对应的数据了。

内容的提问来源于stack exchange，提问作者Prashant Bhure