Creating Packages Programmatically

OneSpan Signfor Dynamics CRMcan automate the preparation ofOneSpan Signpackages via a Custom Button.

Before you can create such a button, you must first create a relationship between the relevant package (esl_package) and the source Entity (e.g. an account).

For more about creating relationships, consult Microsoft TechNet at https://technet.microsoft.com/en-us/library/dn531171.aspx.

After you've satisfied the above prerequisite, you can create a Custom Button in either of the following ways:

And after you've created a Custom Button, you may want to take the automation process further by doing one or more of the following:

Creating a Custom Button on a CRM Form

To create a Custom Button on a CRM form, perform the following steps:

Step 1: Create the Source HTML and JavaScript

The HTML Example section of this guide provides HTML and JavaScript code that creates two HTML buttons, each of which can be used to create a package using data from an account record.

You must first write the required HTML and JavaScript code. This will create the button's visual element as well as its functionality.

The following library parameters are required in the JavaScript function form:

  1. Dynamics 365 provides script to initialize the client context.
  2. <script src="../../ClientGlobalContext.js.aspx" type="text/javascript"></script>
  3. JQuery v 2.1.1 – This version is included with Dynamics 2.1.1.
  4. <script src="../../esl_/scripts/jquery.js" type="text/javascript"></script>
  5. Module to support XrmServiceToolkit. https://www.nuget.org/packages/json2/1.0.2.
  6. <script src="../../esl_/scripts/json.js" type="text/javascript"></script>
  7. XrmServiceToolkit is a JavaScript library that can be used for JavaScript Development under the platform for eSignLive for Microsoft Dynamics CRM 2013/2015 environments. See: https://xrmservicetoolkit.codeplex.com/. The dependencies are: JQuery and json2.
  8. <script src="../../esl_/scripts/XrmServiceToolkit.js" type="text/javascript"></script>

    Step 4 provides many shortcuts to create JavaScript web requests to Dynamics CRM. You can use JavaScript directly, or you can use jQuery.ajax.

    Use the following code to position two buttons at the top of the web resource:

    <ul>
      <li><button id="btnCreate">
      <img src="../../esl_/images/PackageCreateIcon.png" alt="Create Package" /><span>Create</span>
    </button></li>
      <li><button id="btnCreate2">
      <img src="../../esl_/images/PackageCreateIcon.png" alt="Create Package with template" /><span>Create2</span>
    </button></li>
    </ul>
    

    jQuery is used to link each button to the appropriate JavaScript function. After the Web Resource is ready, it can be imported and tested in Dynamics 365.

Step 2: Import the Web Resource into Dynamics 365

After the code from Step 1 is created, it must be imported as a Web Resource into Dynamics 365 in order to be placed on a CRM form.

To import the relevant Web Resource into Dynamics 365:

  1. From the eSignLive for Microsoft Dynamics CRM menu, select Settings > Customizations > Customize the System.
  2. From the ribbon in the Solution window that appears, select Web Resources from the Newdrop-down menu.
  3. In the Web Resource New window, complete the Name field.
  4. In the Type field, either paste the HTML source that you have written, or select a pre-existing file (e.g. HTML Example) and click Choose File.
  5. Click Save and then Publish. The Web Resource becomes available to the entire system.

Step 3: Insert the Web Resource into an Entity Form

After importing the Web Resource, it must be inserted into an Entity form (in this example, an account).

To insert the Web Resource into an Entity form:

  1. From the eSignLive for Microsoft Dynamics CRM menu, select Settings > Customizations > Customize the System.
  2. From the side menu of the Solution window, select the entity form to customize, e.g. Entities > Account > Forms.
  3. Click New > Main Form.
  4. Click the Insert tab. In this example, a One Column tab was inserted before the Summary Section to ensure the buttons appear at the top of the form.
  5. From the Insert tab ribbon, click One Column. A Tab section is created in the Insert pane.
  6. From the ribbon, click Web Resource. The Add Web Resource dialog box appears.
  7. From the Web Resource field, select the web resource file you created in Step 2: Import the Web Resource into Dynamics 365.
  8. Complete the Name and Label fields.
  9. If the HTML Example sample was used, the following buttons are inserted at the top of the form:
    • Clicking Create creates a package. If a primary contact is assigned to the account, it will be added to the package as a signer.
    • Clicking Create2 also creates a package. The code attempts to find a saved template named template01.
  10. NOTE:
    • To decrease the volume of JavaScript, this example uses jQuery. For more information, see jQuery's online documentation.
    • In the above example, the library XrmServiceToolkit.js helps shorten the JavaScript code. This library can be updated.
    • If you want to add animation, or to block the User Interface during the code's execution, use the following code:
    function ShowProcessing (message) {
    
            if (typeof message != "string") {
                message = "Working...";
           }
            var $div = $("#containerLoadingProgress");
            if ($div.length === 0) {
                $div = parent.$("#containerLoadingProgress");
            }
    
            var $message = $div.find("#loadingtext");
            if ($message.length === 0) {
                $message = $("<div />", { "id": "loadingtext", "style": "position:absolute;top:58%;left:50%" });
                $div.append($message);
            }
           $message.text(message);
           $div.show();
       };
    
       function HideProcessing () {
           ///<summary>
           /// Hide the loader after the preocess is over.
           ///</summary>
           var $div = $("#containerLoadingProgress");
           if ($div.length === 0) {
               $div = parent.$("#containerLoadingProgress");
           }
           $div.hide();
        };
    

Creating a Custom Button on the Ribbon

(1) Information about customizing the ribbon can be found in the Customize commands and the ribbon section of Microsoft's online library; (2) you can also use a third-party extension, such as the Ribbon Workbench 2016 extension from develop1: https://www.develop1.net/public/rwb/ribbonworkbench.aspx.

Prerequisites

When you are creating the relevant JavaScript code, the following libraries are recommended to help shorten the code's volume:

  • esl_/scripts/jquery.js
  • esl_/scripts/json.js
  • esl_/scripts/XrmServiceToolkit.js

If you are using the suggested Ribbon Workbench 2016 application, you can create a solution that contains the entity with which to associate the action button.

Action

To create a Custom Button on the ribbon:

  1. From the Ribbon Workbench 2016 menu, click Customization. The following window appears.
  2. From the Toolbox menu, click and drag the Button icon to the Form section of the top menu.
  3. In the Properties: Control pane, complete the fields. The value entered in the Label field is mirrored by the Button icon.
  4. From the Form section of the top menu, click New. The Actions window appears.
  5. Complete the fields with the parameters listed in the prerequisites above. The Custom Javascript Action field can be completed with your company's customized Javascript code.
  6. This field will call parameters to pass to this function.

Adding a Document to a Package

OneSpan Sign supports the following types of documents:

  • Adobe's Portable Document Format (*.pdf)
  • Microsoft Word (*.doc or *.docx)
  • Open Office (*.odt)
  • Text (.txt)
  • Rich Text Format (.rtf)

Please be aware of the following:

  • The maximum size of a single document is 16 MB. The only exceptions concern our Salesforce and Microsoft SharePoint connectors, whose maximum is 5 MB per document. Smaller documents yield better performance — we recommend under 5 MB per document.
  • If you enable email delivery while configuring a recipient, documents that are larger than 5 MB will not be added as attachments to the email.
  • OneSpan will not provide Technical Support for a transaction or transaction template that has more than 10 documents.
  • Document file names should not contain any of the following comma-separated characters: *, /, \, :, <, >, |, ?, ".
  • A document's name cannot contain the string esigned.
  • Uploading password-protected or corrupted documents will trigger an error.
  • PDFs added to a transaction must not have syntax errors. We strongly recommend that you scan a PDF for syntax errors before you add it to a transaction (e.g., by using Adobe's Preflight tool).
  • PDFs with the NeedAppearances flag set to true are not currently supported.

If you want to add a document to a package, the following code can be: (1) added to the sample; (2) invoked when required.

////  Use this function to retrieve a list of notes for the current record.
////
////  parameters:
////     packageId :  package to link to
////     note :  json object
////             {
////               id: "guid of the note",
////               name: "text to display, should be the filename"
////             }
function queryCrmRelatedDocuments(id) {
    var select =
        "?$top=100&$select=AnnotationId,Subject,FileName,FileSize,ModifiedOn,OwnerId,ObjectId&$expand=OwnerId,ObjectId";
    select += "&$filter=ObjectId/Id eq guid'" + id + "' and IsDocument eq true";

    var list = [];

    XrmServiceToolkit.Rest.RetrieveMultiple("AnnotationSet",
        select,
        function(results) {
            $(results).each(function(index, data) {
                    list.push({
                        "name": data.FileName,
                        "id": data.AnnotationId
                    });

                    //Now the list is populated, you can call  'addNoteToPackage'
                },
                function(e) {
                    //Handle errors
                },
                function() {
                    /// handle when done, like hiding "busy" animation
                },
                true);
        });
}



////  Use this function to bind an existing note/attachment to a package.
////
////  parameters:
////     packageId :  package to link to
////     note :  json object
////             {
////               id: "guid of the note",
////               name: "text to display, should be the filename"
////             }
function addNoteToPackage(packageId, note) {
    var document0 = {
        esl_name: note.name,
        esl_description: note.name,
        esl_documentorder: 0,
        esl_filename: "note://" + note.id
    };

    XrmServiceToolkit.Rest.Create(
        document0,
        "esl_documentSet",
        function (result) {
            XrmServiceToolkit.Rest.Associate(
                packageId,
                "esl_packageSet",
                result.documentId,
                "esl_documentSet",
                "esl_package_document",
                function () {
                    ///Handle success
                },
                function (e0) {
                    ///Handle any errors, for example >>  alert(e0.message);
                },
                false);

        },
        function (e0) {
            ///Handle any errors, for example >>  alert(e0.message);
        },
        false);
}

Adding a Convention to a Package

If you want to add a Convention to a package, the following code can be: (1) added to the sample; (2) invoked when required.

////  Use this function retrieve a convention of CRM.
////
////  parameters:
////     name :  name of convention to lookup
////     successCallback :  function(data) {} which expect to receive a convention data
////             {
////               id: convention id,
////               name: name of the convention,
////             }
function getConventionByName(name, successCallback) {

    XrmServiceToolkit.Rest.RetrieveMultiple(
        "esl_conventionSet",
        "?$top=1&$select=esl_conventionId,esl_name&$filter=esl_name eq '" + name + "'",
        function (result) {

            var convention = {
                id: result[0].esl_conventionId,
                name: result[0].esl_name
            };

            // Handle success
            successCallback(convention);
        },
        function(e) {
            //Handle any errors
        },
        function () { },
        true);
}

Then adding the convention to the package using this function:

////  Use this function to bind an existing note/attachment to a package.
////
////  parameters:
////     packageId :  package to link to
////     note :  json object
////             {
////               id: "guid of the note",
////               name: "text to display, should be the filename"
////             }
function addConventionToPackage(packageId, conventionId) {
    XrmServiceToolkit.Rest.Associate(
        conventionId,
        "esl_conventionSet",
        packageId,
        "esl_packageSet",
        "esl_convention_package",
        function () {
            ///Handle success
        },
        function (e0) {
            ///Handle any errors, for example >>  alert(e0.message);
        },
        false);
}

Sending a Package Automatically

If you want to send a package automatically, the following code can be: (1) added to the sample; (2) invoked when required.

function SendPackage (packageId) {

   var crmObject = {
        esl_request: "SendPackage",
        esl_parameter1: packageId  // the package Id is required
    };

    XrmServiceToolkit.Rest.Create(crmObject,
        "esl_plugincommandSet",
        function (data) {
            //Handle succerss
            //  'data' would contain an json object of type 'esl_plugincommand'
        },
        function (e) {
            //Handle error 'e'
        },
        true);
}
Was this information helpful?
X