Follow

Complex CRM Data Mapping Instructions

Last updated 2017-05-10 14:19:14 UTC

Starting with our solution version 2.0.0.16, a Tag builder interface is available on AssureSign Configuration records in settings. 


Background Information

The AssureSign Solution for CRM allows you to quickly write simple tags on JotBlocks that allow data to be looked up and mapped into template parameters. The solution comes pre-linked to certain entities. For example, the Account and Contact entities are connected to the AssureSign Documents entity through CRM "n:1" relationships. These respective relationships have corresponding lookup fields in the AssureSign Documents entity: asign_accountid and asign_contactid.

The rules for writing tags were intentionally written in as non-complex a manner as could be supported to allow non-technical users to get their systems integrated with AssureSign as quickly as possible.

So, if a new AssureSign Document is launched from within an Account entity, it is very easy to write a JotBlock parameter "tag" to lookup the account name. The tag is written

account.name

The patterm of that expression should be familiar to software or database developers, who would read that as "give me the name property of the account object," or "give me the name field of the account table."

This lookup works because the code was written to make certain assumptions. The lookup is being run from the point of view of the AssureSign Documents entity. The code assumes there must be a field that will allow me to find a related account, and it was written to test whether there was a field named either asign_accountid or new_accountid. Then, the code was written to assume that in the account table there must be an ID field named accountid.

The same works for the built in relationship with the Contact entity. The code assumes there must be a field that will allow me to find a related contact, and it was written to test whether there was a field named either asign_contactid ornew_contactid. Then, the code was written to assume that in the contact table there must be an ID field namedcontactid.

Things get trickier with entities that do not follow those conventions. For example, the built-in CRM entity serviceappointment (which is displayed as "Service Activity") has an ID field named activityid. So, if you create an n:1 relationship on AssureSign Documents with serviceappointment, the code will not work if you simply write a tag such as

serviceappointment.description

If you create the custom relationship with a lookup field in AssureSign Documents named new_serviceappointmentid, the code would be wrong in assuming that the ID field in serviceappointment is named serviceappointmentid, and our simple lookup based on naming convention assumptions does not work. Were we to try to create a table of known entities and their ID fields, we would still have a problem trying to figure out what to do with custom entities and any new built-in entities added to CRM in future releases.

Starting with solution version 2.0.0.13, this advanced syntax also works in names of JotBlocks to allow updates to linked entity fields.

Advanced Syntax

Starting with our solution version 2.0.0.7, entities with unconventional relationship IDs and custom namespace prefixes may be mapped with an advanced version of our tag syntax.

Some examples of premapped entities that will work with no change to the tags:

account.name
contact.emailaddress1

You may add modifiers to the entity name to explicitly indicate the name of the lookup field and the name of the ID field in the entity. The pattern you must enter to use this syntax is:

entityname[lookupIDname>entityID].field

This may be read as "retrieve the field from the entity whose ID entityID matches the lookup field lookupIDname."

So, the simple account and contact examples may also be written:

account[asign_accountid>accountid].name
contact[asign_contactid>contactid].emailaddress1

Since the ID fields in those entities matches the simple syntax of [entityname]id, indicating the name of the ID fields is optional. These could also be written:

account[asign_accountid].name
contact[asign_contactid].emailaddress1

If you configure a new relationship with serviceappointment, and you name the lookup field "my_appointmentid", you could write a tag like this:

serviceappointment[my_appointmentid>activityid].description

This could be read as "retrieve the description of the serviceappointment entity whose activityid field matches the field my_appointmentid in my AssureSign Documents record."

Linked entity lookups may be extended with this advanced syntax, as well. The basic pattern for writing a tag to retrieve a linked entity field is:

linkedentity[relatedentity.linkedentityid].linkedentityfield

This could also be written as follows if needed to resolve the lookup and related entity ID fields:

linkedentity[relatedentity[lookupIDname>relatedentityID].linkedentityid].linkedentityfield

To retrieve an account's primary contact email address when you only have a relationship with account, any of the following will work:

contact[account.primarycontactid].emailaddress1
contact[account[asign_accountid>accountid].primarycontactid].emailaddress1
contact[account[asign_accountid>accountid].[primarycontactid>contactid]].emailaddress1

In the case of the third version, you can see that it is possible to write the extended tag syntax to resolve the contact entity linked to the account as well. In this simple example, it would be pointless to write the more specific syntax, but we have written these out for illustration purposes only.

Appended modifiers, such as #multiline and #formatdate:{yyyy/mm/dd} will continue to work when added to tags. This extended tag pattern will also work when used on tags for template maps. You may not use this extended syntax in order to update immediately related CRM entity fields.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

0 Comments

Article is closed for comments.