Follow

CRM Data Mapping Instructions

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

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


When designing an AssureSign Document Template for submission through DocumentNOW API methods you may add in JotBlocks to the design that may be pre-populated. The mechanism of pre-populating is through Parameters: these are dynamic elements that will be passed to AssureSign at the time of submission. In addition, certain information needed for routing to signatories via email will also require Parameters that the AssureSign system will auto create.

When you attempt to start an AssureSign Document from CRM, you will be presented with a dialog requesting that you enter the data for these parameters. The AssureSign for CRM solution allows you to use the AssureSign Parameter "Tag" attribute to extract data from CRM and prepopulate these elements in the dialog. In order to specify these tags, you must look up the exact entity attribute that you would like to pass.

The AssureSign for CRM solution allows you to link an AssureSign Document to multiple entities, such as Account or Contact. For example:

  • In order to populate an AssureSign Template Parameter with the Account name, you would set the Tag on the Parameter to account.name.
  • To populate an AssureSign Template Parameter with a Contact emailadress, you could set the Tag on a parameter to contact.emailaddress1.

    Note: It is important to enter the actual system name of the entity and fieldname. For example, an out of the box CRM includes the Case entity, which is really incident under the hood. In addition, custom entities and fields you create will be prefaced with new_ or another namespace identifier. The tag should contain the actual system names, and not display or schema names in mixed case.

In all cases you should enter the tag in lower case, with a dot delimiter. Entity attribute names may be easily viewed by accessing Entity information via Customizations in CRM.

For the mapping to occur properly when you have selected an AssureSign Document Template, you must either start the Document from within a given supported Entity (for example, launching with an Account will auto-set the Account relationship) or you must select a given Entity to assign the Document to.

The instructions for configuring relationships with other entities explained that using custom namespaces and altering the naming convention of ID fields will require the tag syntax to be altered provide more explicit instructions to the solution. For more information on the syntax variations that may be used when writing a parameter tag, read our article on Complex CRM Data Mapping Instructions.

Multiline Fields

The tag mechanism allows for a simple dynamic pull of data into a text box for review before submitting. Multiline data (data containing line breaks) has the line breaks stripped when populated into a text box. Therefore, it is possible to indicate in the tag that the data should be loaded into a multiline textarea control by adding a #multiline appender at the end of the tag. For example, to map the multiline description field from contact, you should enter:

contact.description#multiline

It is also possible to merely enter

#multiline

in the tag without a mapping request to instruct the solution code to present a multiline entry field for an unmapped parameter.

Flattening Multiline Fields

If a multine field is mapped into a simple text box, newlines will be stripped. In order to gracefully convert the newlines into another character, use the #flatten modifier. For example:

  • account.address1_composite#flatten:{,} - when address1_composite is pulled, all newlines will be replaced by a comma
  • account.address1_composite#flatten:{ } - when address1_composite is pulled, all newlines will be replaced by a single space

You may specify longer strings of data as well, in addition to single characters.

Date Field Formatting

A small subset of date formats are supported that may be applied to a CRM date field when a value is queried from a related entity. Applying the #formatdate appender alone without a mapping request or onto a CRM field that is not a date will not modify the input. The following appenders will format a date value:

APPENDER EXAMPLE
#formatdate:{mm/dd/yyyy} 09/12/2013
#formatdate:{mm-dd-yyyy} 09-12-2013
#formatdate:{dd/mm/yyyy} 27/11/2012
#formatdate:{mm/dd/yy} 09/12/13
#formatdate:{mm-dd-yy} 09-12-13
#formatdate:{m/d/yyyy} 7/9/2012
#formatdate:{m-d-yyyy} 7-9-2012
#formatdate:{m/d/yy} 7/9/12
#formatdate:{m-d-yy} 7-9-12
#formatdate:{mmm d, yyyy} January 5, 2013
#formatdate:{yyyy/mm/dd} 2014/02/14
#formatdate:{yyyy-mm-dd} 2014-02-14
#formatdate:{utc} will return the value converted by toUTCString()
#formatdate:{locale} will return the value converted by toLocaleString()

Note: when performing a submission of a document through a template map the number formatting is performed through .NET format strings which allows for more customized strings. Refer to MSDN documentation on available date format strings.aspx). The locale and utc custom strings will also work with formatting performed with template maps.

Number Field Formatting

Number formatting is possible for CRM numeric fields when a value is queried from a related entity. Applying the#formatnumber appender alone without a mapping request or onto a CRM field that is not a number will not modify the input. You may specify basic format strings available in the numeral.js library. For example, to format a currency type field to display a dollar sign, commas as thousand separator, and only 2 digits to the right of the decimal, you could use#formatnumber:{$0,0.00} as in the following example:

opportunity.estimatedvalue#formatnumber:{$0,0.00}

Some other examples:

NUMBER APPENDER PRODUCES
10000 #formatnumber:{0,0.0000} 10,000.0000
10000.23 #formatnumber:{0,0} 10,000
-10000 #formatnumber:{(0,0.0000)} (10,000.0000)
1 #formatnumber:{0o} 1st
52 #formatnumber:{0o} 52nd
1000.234 #formatnumber:{$0,0.00} $1,000.23
1000.2 #formatnumber:{0,0[.]00 $} 1,000.20 $
1001 #formatnumber:{$ 0,0[.]00} $ 1,001
-1000.234 #formatnumber:{($0,0)} ($1,000)
-1000.234 #formatnumber:{$0.00} -$1000.23
1230974 #formatnumber:{($ 0.00 a)} $ 1.23 m
1460 #formatnumber:{0 a} 1 k
1 #formatnumber:{0%} 100%
0.974878234 #formatnumber:{0.000%} 97.488%

The following currency symbols are supported:
£, €, ¥, ₪, $

Appenders for Option Set and Two Options field types

Not specifying a modifier on an Option Set or Two Options field will extract the text. To explicitly indicate what to map into a parameter, add one of the modifiers:

  • #formatoptiontext to allow pull of an options text
  • #formatoptionvalue to pull the value, not the display text

For example:

  • contact[account.primarycontactid].preferredcontactmethodcode#formatoptionvalue
  • contact[account.primarycontactid].preferredcontactmethodcode#formatoptiontext

If you are using the build in form to manually launch a document, you may want to present the options in a select control to allow the user to be able to pick from the options.  In this case, you may use the modifier:

#options:[] 

with sets of name/value pairs within the brackets.  For example, in order to map in the preferredcontactmethod field from a contact and allow the user to select a different value to pass into the parameter, you would use this syntax:

contact.preferredcontactmethodcode#formatoptionvalue#options:[{"n":"Any","v":1},{"n":"Email","v":2},{"n":"Phone","v":3},{"n":"Fax","v":4},{"n":"Mail","v":5}]

That will do the following:

  • use the value for the parameter (because of #formatoptionvalue) 
  • present a list to select from to the user
  • preselect whatever value is currently set on the contact

It is possible to present a select list to the user for a field that is not mapped in from a related entity.  For example, the following will present a list of 3 items ("Item 1","Item 2","Item 3"), and the text will be passed in to the parameter:

#formatoptiontext#options:[{"n":"Item 1","v":1},{"n":"Item 2","v":2},{"n":"Item 3","v":3}]

Combining Appenders

It is also possible to combine appenders, though this has limited usefulness, such as

contact.createdon#multiline#formatdate:{mmm d, yyyy}

You may not combine #formatnumber and #formatdate.

Accessing the owner user's entity values

To access the fields of the user owner of the AssureSign document being sent, you may use the owner shortcut convention as the name of the entity with field names from the user entity. For example, the following will work:

  • owner.domainname (the output will depend on whether this is online or on-premises)
  • owner.firstname
  • owner.lastname
  • owner.internalemailaddress

Linked entity fields

Introduced in version 1.0.0.15

To populate fields with linked entities (an entity related to an entity connected to the document at any length) you may use the following convention

linkedentity[relatedentity.linkedentityid].linkedentityfield

The entity related to the document must be the innermost entity within the brackets, and as many links as are reasonably supported may be resolved. The field to be populated should be the last element after the dot, and the entity containing it must start the phrase.

Some examples:

  • When an account has been selected, to get the account's primary contact email address, the following could be used

    • contact[account.primarycontactid].emailaddress1
  • A more complex (less useful) item is the email address of the user who created the contact that is the primary contact on the related account:

    • systemuser[contact[account.primarycontactid].createdby].internalemailaddress

It is also possible to lookup entity information from more complex lookup field's that might not be easily queried by using a "this" entity shortcut that refers to the AssureSign Document entity record itself. For example, if you were to try to add multiple systemuser relationships to the entity it would be impossible to use the simplified immediate relationship syntax. As an example, say that you add 4 user lookups and name their fields signer1id, signer2id, signer3id, and signer4id. Then, the following could be used in parameter tags to populate their email addresses:

  • systemuser[this.signer1id].internalemailaddress
  • systemuser[this.signer2id].internalemailaddress
  • systemuser[this.signer3id].internalemailaddress
  • systemuser[this.signer4id].internalemailaddress

(Note: as of version 1.0.0.15, wiring such a complex control to retagTemplateList will not be able to resolve the entity. Such mappings will require selecting all entities in advance of selecting a template.)

For more information on the syntax variations that may be required when writing a parameter tag to query linked entity fields, read our article on Complex CRM Data Mapping Instructions.

Hide a field

It is possible to hide a parameter that is optional in the form presented in CRM.  Set the tag value to:

hide

This tag will be ignored if the parameter is required.  

For an example of using this modifier, if you have configured the parameters for setting the password and password prompt to not be required, and if you do not need these displayed to document submitters using the form in CRM, enter "hide" in the tag and they will not be displayed on the form.

Tags in templates used in workflows

Some of the above formatting and syntax will be limited when used in CRM workflows. Please refer to Constraints with CRM Data Mapping used in workflows.

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

0 Comments

Article is closed for comments.