Creating Transactions from Custom Buttons

Before you can create such a button, you must first create a relationship between the relevant transaction (esl_package) and the source Entity (for example, 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 prerequisites, you can create a Custom Button in either of the following ways:

• Creating a Custom Button on a CRM Form

• Creating a Custom Button on the Ribbon

After you have created a Custom Button, you may want to take the automation process further by doing one or more of the following:

• Adding a Document to a Transaction

• Adding a Convention to a Transaction

• Sending a Transaction Automatically

Creating a Custom Button on a CRM Form

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

• Creating the Source HTML and JavaScript

• Import the Web Resource into Dynamics 365

• Inserting the Web Resource into an Entity Form

Creating 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 transaction 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.

   <script src="../../ClientGlobalContext.js.aspx" type="text/javascript"></script>

2. JQuery v 2.1.1 – This version is included with Dynamics 2.1.1.

   <script src="../../esl_/scripts/jquery.js" type="text/javascript"></script>

3. Module to support XrmServiceToolkit. https://www.nuget.org/packages/json2/1.0.2.

   <script src="../../esl_/scripts/json.js" type="text/javascript"></script>

4. XrmServiceToolkit is a JavaScript library that can be used for JavaScript Development under the platform for OneSpan Sign Embedded Integration for CRM 2013/2015 environments. See: https://xrmservicetoolkit.codeplex.com/. The dependencies are: JQuery and json2.

   <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.

Import the Web Resource into Dynamics 365

After the HTML and JavaScript code 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 OneSpan Sign Embedded Integration for 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.

   

Inserting 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 OneSpan Sign Embedded Integration for 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 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 transaction. If a primary contact is assigned to the account, it will be added to the transaction as a signer.

   • Clicking Create2 also creates a transaction. The code attempts to find a saved template named template01.

    

   • 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.

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.

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 Transaction

OneSpan Sign supports the following document types:

• Adobe's Portable Document Format (*.pdf) — PDFs on which OneSpan Sign can act generally have at least these permissions enabled: (1) Changing the Document; (2) Signing; (3) Filling of form fields.

• Microsoft Word (*.doc or *.docx)

• Open Office (*.odt)

• Text (*.txt)

• Rich Text Format (*.rtf)

In addition, the OneSpan Sign Print Driver supports any document that can be printed from a Windows-based application (e.g., Microsoft Word, Microsoft Excel, Microsoft PowerPoint).

File Size Constraints

• The maximum size of a single document is 16 MB. Smaller documents yield better performance — we recommend under 5 MB per document.

• If your organization uses Salesforce or Microsoft SharePoint connectors, the file size maximum is 5 MB per document.

• If your organization uses Salesforce connectors, the maximum number of documents that can be added to a transaction is ten (10).

• If you enable email delivery while configuring a recipient, attachments larger than 5 MB are not supported.

File Name Constraints

• Document file names should not contain any of the following comma-separated characters: *, /, \, :, <, >, |, ?, ".

• A document's name cannot contain the string esigned.

General File Constraints

• We recommend that you do not use PDF documents that make use of XML Forms Architecture. For more information, see XFA Support.

• Do not upload password-protected or corrupted documents. These will generate an error.

• OneSpan strongly recommends that you scan a PDF for syntax errors (e.g., by using Adobe's Preflight tool), and resolve any errors before you add the document to a transaction.

• PDFs with the NeedAppearances flag set to true are not currently supported.

If you want to add a document to a Transaction, 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 Transaction

If you want to add a Convention to a Transaction, 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 Transaction Automatically

If you want to send a transaction 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);
}