Configuring Relationships with Other CRM Entities

Last updated 2017-06-06 18:58:32 UTC

It is possible to configure the AssureSign solution to be present on other entities than those preconfigured in the solution, including custom entities. There are special configurations that should be made so that automatically mapping entity fields to template parameters works.

Relationships with Documents

  • To add a relationship to the AssureSign Document entity, go to Customizations>Customize the System, and expand the AssureSign Document entity.
  • Add a N:1 Relationship, noting the following:
    • The easiest configuration is to configure the Lookup Field so the name is entered with the new_ namespace prefix followed by id, for example, new_[entityname]id. If you are mapping to a built in or custom CRM entity,you would use the actual name, and not what is displayed in the Primary Entity list.
    • Alternatively, beginning with version of our solution, it is possible to alter the Lookup Field naming convention should it be required, such as if you are required to add your fields with another customer namespace. However, to enable fields to be looked up from the entity at runtime, you will be required to enter some more advanced tag syntax to instruct the code to find your entity.

For example, if you have added a custom entity with display name Employee but under the hood it is really called new_employee, then all references to it should use the real name new_employee; in this case, when adding the N:1 relationship, using the first "easiest configuration" instructions, the name of the Lookup Field should be entered as new_new_employeeid. Then, when you enter a tag, assuming the primary key field in new_employee is new_employeeid, you could add a tag value to a template parameter on a JotBlock using the simplest language possible:


An alternative approach may be followed if you must use some other namespace or naming convention. For example, say you have created a custom entity called custom_employee, the ID field in that entity is called custom_employeenumber, and you decided to name the lookup field custom_employeeid (I don't know why you would do that, but lets just say you're that kind of person). In this case, the solution cannot "guess" at what your ID fields are, so the text in the parameter tag will have to be more explicit:


This syntax is read by the solution as follows:

get the custom_storename field from the custom_store entity where the lookup field custom_employeeid matches the custom_storenumber field

The simpler example could be written using the same extended syntax:


Why would you write it that way, though, when the first simpler way works? Exactly! Write the tag as simply as possible. However, if your business requirements are such that you are required to follow some other naming conventions, you will need to construct the tags using more complex text.

  • Publish your changes as you go, and then edit the Main form in the AssureSignDocument entity. You should now be able to drag in a pick control for your added entity.

  • Open the properties of the newly added control, and add an Event Handler on the Events tab for the OnChange Event:
    • Select the Library asign_AssureSignDoc.js
    • Add the function AssureSignDoc.retagTemplateList
    • Select "Pass execution context as first parameter"

  • Publish your changes

For the simple example given whereby a custom Employee entity has been configured as described (where the actual name of the entity is new_employee), then a parameter tag could be configured to be prefilled by setting the Custom Tag on the JotBlock or workflow parameter to new_employee.[fieldname]. For example, if you have a field on the new_employee entity whose name (not display name) is new_employeebadgenumber, then you could map that field to a parameter by setting the Custom Tag to new_employee.new_employeebadgenumber



Note: entity and field names should be entered lower case

In your template to be used through CRM, add a JotBlock that is populated by a parameter. To apply the fieldnew_employeebadgenumber set the tag to new_employee.new_employeebadgenumber (the actual name of the entity and the actual name of the field).

What happens at runtime? When you pick a template, the parameters are pulled back from AssureSign. Each parameter's tag is checked. When new_employee.new_employeebadgenumber is found the code looks for a field named new_new_employeeid on the AssureSign Document entity (adding new_ at the front and id at the end). If it finds that field, it performs a query on the entity new_employee having the ID new_employeeid, and the value ofnew_employeebadgenumber is requested.

Relationships with Envelopes

Just as new relationships may be created with the AssureSign Document entity, new relationships may be added to the AssureSign Envelope entity.

The relationship on an AssureSign Envelope will not drive auto-population of data. However, when launching an AssureSign Document from within an AssureSign envelope that has been manually created, the Document form contains code that will attempt to mirror the relationships on the Envelope to the Document. In order to do this successfully, any newly added lookup fields on Documents and Envelopes should be given the same name.

So, for example, if an Envelope is launched from an Account, when a new Document is added through the Document grid on the Envelope form, the Document form will load the Account record within the Document's Account lookup field.

If a new relationship has been added to both Document and Envelope, named custom_employee, and the lookup field in both Document and Envelope for the custom entity is custom_employeeid, then when an envelope is linked to an Employee record and a new Document is added through the Document grid on the Envelope form, the Document form will load the Employee record within the Document's Employee lookup field. The field will need to be present on the AssureSign Document record for the mapping to occur successfully.