Docusign and ColdFusion integration

Question

I am using the following code to call the docusign api. I got the information from this link.

<soap:Body>
    <ns:CreateEnvelopeFromTemplates>
      <ns:TemplateReferences>
        <ns:TemplateReference>
          <ns:TemplateLocation>Server</ns:TemplateLocation>
          <ns:Template>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</ns:Template>
          <ns:RoleAssignments>
            <ns:RoleAssignment>
              <ns:RoleName>Company</ns:RoleName>
              <ns:RecipientID>1</ns:RecipientID>
            </ns:RoleAssignment>
          </ns:RoleAssignments>
        </ns:TemplateReference>
      </ns:TemplateReferences>
      <ns:Recipients>
        <ns:Recipient>
          <ns:ID>1</ns:ID>
          <ns:UserName>Fred Flintstone</ns:UserName>
          <ns:Email>fred.flintstone@...</ns:Email>
          <ns:Type>Signer</ns:Type>
          <ns:RoleName>Caveman</ns:RoleName>
          <ns:RoutingOrder>1</ns:RoutingOrder>
        </ns:Recipient>
      </ns:Recipients>
      <ns:EnvelopeInformation>
        <ns:AccountId>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</ns:AccountId>
        <ns:EmailBlurb>This Envelope was sent through the DocuSign API using ColdFusion</ns:EmailBlurb>
        <ns:Subject>DocuSign it! using ColdFusion</ns:Subject>
      </ns:EnvelopeInformation>
      <ns:ActivateEnvelope>true</ns:ActivateEnvelope>
    </ns:CreateEnvelopeFromTemplates>
  </soap:Body>

I am unable to understand what the RoleAssignment tag under Template is used for. I have gone through the documentation here but did not understand it.

I think this is the only reason I am not getting a response. I commented this portion in my code but I am getting the following output after changing all of the credentials.

An error occurred!
struct
Charset  [empty string]
ErrorDetail  Unknown host: demo.docusign.net
Filecontent  Connection Failure
Header   [empty string]
Mimetype     Unable to determine MIME type of file.
Responseheader  
struct [empty]
Statuscode   Connection Failure. Status code unavailable.
Text     YES

Can anyone please help me out with this?

Answer 1

I don't think the RoleAssignment has anything to do with that particular error. You need to combine the SOAP Header and the SOAP Body from their example. The SOAP Body should be contained with the SOAP Header block.

Notice that their example for the SOAP Header contains the <soap:Body> block. Then their example for the SOAP Body is also surrounded by the <soap:Body> block. They should be combined like this for your <cfhttp> call:

<cfset UserName = "[XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX]XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX" />
<cfset Password = "SuperSecret" />

<cfscript>
  strNonce = ToBase64(createUUID());
</cfscript>

<!--- create the request body XML block --->
<cfsavecontent variable="request_xml">
<cfoutput>
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ns="http://www.docusign.net/API/3.0">
  <soap:Header>
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
        <wsse:UsernameToken wsu:Id="UsernameToken-1" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
            <wsse:Username>#UserName#</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0##PasswordText">#Password#</wsse:Password>
            <wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0##Base64Binary">#strNonce#</wsse:Nonce>
        </wsse:UsernameToken>
    </wsse:Security>
  </soap:Header>  
  <soap:Body>
    <ns:CreateEnvelopeFromTemplates>
      <ns:TemplateReferences>
    <ns:TemplateReference>
      <ns:TemplateLocation>Server</ns:TemplateLocation>
      <ns:Template>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</ns:Template>
      <ns:RoleAssignments>
        <ns:RoleAssignment>
          <ns:RoleName>Company</ns:RoleName>
          <ns:RecipientID>1</ns:RecipientID>
        </ns:RoleAssignment>
      </ns:RoleAssignments>
    </ns:TemplateReference>
      </ns:TemplateReferences>
      <ns:Recipients>
    <ns:Recipient>
      <ns:ID>1</ns:ID>
      <ns:UserName>Fred Flintstone</ns:UserName>
      <ns:Email>fred.flintstone@...</ns:Email>
      <ns:Type>Signer</ns:Type>
      <ns:RoleName>Caveman</ns:RoleName>
      <ns:RoutingOrder>1</ns:RoutingOrder>
    </ns:Recipient>
      </ns:Recipients>
      <ns:EnvelopeInformation>
    <ns:AccountId>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</ns:AccountId>
    <ns:EmailBlurb>This Envelope was sent through the DocuSign API using ColdFusion</ns:EmailBlurb>
    <ns:Subject>DocuSign it! using ColdFusion</ns:Subject>
      </ns:EnvelopeInformation>
      <ns:ActivateEnvelope>true</ns:ActivateEnvelope>
    </ns:CreateEnvelopeFromTemplates>
  </soap:Body>
</soap:Envelope>
</cfoutput>
</cfsavecontent>

(This example was taken directly from their documentation. I only combined the two blocks.)

Then send that request (from their example):

<!--- send the request to the DocuSign service --->
<cfhttp url="https://demo.docusign.net/api/3.0/api.asmx" method="post" result="http_response">

  <!--- make sure you set this correctly for the call you are making --->
  <cfhttpparam type="header" name="SOAPAction" value="http://www.docusign.net/API/3.0/CreateEnvelopeFromTemplates" />
  <cfhttpparam type="header" name="accept-encoding" value="no-compression" />
  <cfhttpparam type="xml" value="#trim(request_xml)#" />
</cfhttp>

And finally handle the response (from their example):

<!--- if we received a successful response --->
<cfif find("200", http_response.statusCode)>
  <cfscript>
    response_xml = xmlParse(http_response.fileContent);

    // use XPath to get the top level element you want from the SOAP response
    result_node = xmlSearch(response_xml, "//*[local-name() = 'CreateEnvelopeFromTemplatesResult']")[1];

    // use dot notation to navigate the XML structure
    envelope_id = result_node.EnvelopeID.xmlText;
  </cfscript>

  <cfoutput>
    EnvelopeID: #envelope_id#
  </cfoutput>
<cfelse>
  <cfoutput>
    An error occurred!
  </cfoutput>
  <cfdump var="#http_response#">
</cfif>

Answer 2

The RoleAssignment tags are used for assigning your recipient to a particular template role. When you send an envelope that uses a template, you are referencing a template that you have created through the DocuSign console (demo.docusign.net). When you created the template, you had to specify at least one template role for the template, which contains a role name, recipient name, and recipient email. The value you use for the role here needs to match the role name you provide in the api call. So if you called your role "Signer1" for instance, you need to have

<ns:RoleName>Signer1</ns:RoleName>

If you named the role "Company" the keep like you have it.

Answer 3

If this is a POST request (submitting data), it looks as though the webservice is not recognising the submission of the actual SOAP XML file.

Are you sending the XML as an XML type as shown in the documentation?

<cfhttpparam type="xml" value="#trim(request_xml)#" />