Adobe EchoSign Calculated Fields Guide

Transcription

1 Adobe EchoSign Calculated Fields Guide Version 1.0 Last Updated: May, 2013

2 Table of Contents Table of Contents... 2 Overview... 3 Calculated Fields Use-Cases... 3 Calculated Fields Basics... 3 Calculated Field Expressions...4 Supported Operators... 5 Supported Functions... 6 Calculated Fields Formatting...8 Formatting Calculated Fields as a number... 8 Formatting Calculated Fields as a date... 8 Formatting Examples... 9 Using Expression Builder For Specifying Calculated Fields Calculated Fields Examples

3 Overview There are several use-cases where the fields in a document need to get updated dynamically based on the data entered by the signer at time of signing the agreement. Calculated Fields allow setting up rules within a document (or a document template), before sending it out for signature. These rules get processed when the signer interacts with the document and dynamically update the document based on the fields/values. Calculated Fields can be defined within documents using any of the following mechanism: EchoSign Form Authoring UI EchoSign Text Tags See Adobe EchoSign Text Tag Documentation for more details PDF Form Fields using Adobe Acrobat Calculated Fields Use-Cases Calculated fields can be used for any scenarios where the document needs to be dynamically updated at time of signing. Below are a few sample use-cases where calculated fields can be used. These use-cases are for illustration purpose only. 1. Setting up an Order Form: Calculated Fields can be used to set up an order form in which the signer has the option to select from a list of available items for order and selects the quantity that the signer wants to order. Selection an item from the list automatically updates the form with the price for the selected item. The quantity selected by the signer also results in the total cost of the item being calculated automatically. The form can also incorporate additional calculations for determining total tax due on the order or calculating volume discount based on the business rules for offering discounts to customers. 2. Automatically populating contract term expiration date: For agreements that allow customers to choose the length of term of the contract at time of signing (6 months, 12 months, 24 months, etc), a Calculated Field can be used to automatically populate the end date for the contract based on the selection made by the customer at time of signing the contract. 3. Sign up forms with multiple choices: A Calculated Field can be used to set up sign-up forms (such as membership forms) where the person signing the form can choose from a set of available options. The choices made by the signer can drive other dynamic aspects of the forms such as terms that the signer is agreeing to, the duration of the contract and also the total cost. Calculated Fields Basics Any form field, checkbox field or radio button field in an EchoSign form can be marked as a Calculated Field. At time of signing, the signer cannot directly enter a value into a field designated as a Calculated Field, the value of the field gets automatically calculated based on the rules defined in the form. A Calculated Field definition consists of two parts an Expression and Format Expression Required Defines the formula/rule on how the value of the designated field gets 3

4 calculated. EchoSign evaluates the Expression at time of signing and the resulting value is displayed in the field. Format Optional The resulting value of the Calculated Field can also be formatted as a date, number or currency by specifying a Format. Calculated Fields can be defined using EchoSign Text Tags, using the EchoSign Web UI or using PDF Form Fields. When using the EchoSign Text Tags or PDF Form Fields to define Calculated Fields, the Expression for the calculation is defined using a new directive called: calc. Formatting of the calculated field can be specified using a directive called: format. For example: {{somecalculatedfield_es_:signer1:calc(someexpn):format(formattype, someformat)}} This shows Text Tags being used to define a field within a document assigned to the first signer called somecalculatedfield. The value of this field gets calculated based on the formula specified in someexpn. The type of the resulting value is specified by the parameter formattype and formatted based on the format defined someformat. The EchoSign Web UI provides a fully functional Expression Builder for defining the formula for Calculated Field. See Section on Using Expression Builder For Specifying Calculated Fields for more details on the Web UI. Calculated Field Expressions The Expression defines the formula/rule for determining the value of the calculated field. An Expression can consist of one or more of the following elements: Literal Specifies an actual value that gets used as part of the Expression; these can be string values, numbers or dates. For example: {{hellofield_es_:signer:calc( Hello )}} - This will set the value of the field called hellofield to be Hello. {{numfield_es_:signer:calc(10)}} This will set the value of the field called numfield to 10. Strings that need to be included in an Expression must be surrounded in quotes (either double (") or single (')). If the resulting value needs to include a quote (either a single quote or a double quote), this can be achieved by using a back slash (\) to escape the quote. Operators Note: For all examples going forward only the Expression will be shown, the complete syntax for the text tag will not be shown. Operators are used to perform one or more operations as part of the Expression. For example: This will result in the value of 10 being populated in the Calculated Field. 5/22/ This will result in the value of 5/19/2013 being populated in the 4

5 Fields Functions Calculated Field. Section Supported Operators lists all the Operators supported within Expressions. Any existing fields within the document can be used for defining an Expression by referring to the field by its name. The fields can be EchoSign fields (such as: Signature Date Field, Signer Name, Signer Company, etc) or fields defined within the document or other calculated fields. For example: price * quantity This expression references two other fields within the document called price and quantity. The result of the multiplication of the values of these two fields will be populated in the Calculated Field. signername & employee of & signercompany This expression references two fields within the document signername and signercompany which get pre-populated by EchoSign if available and concatenates them together. If the signer s name is Casey Jones and the signer s company is Acme Corp, this expression will result in a value of Casey Jones employee of Acme Corp being populated in the Calculated Field. If a field name contains a space, the field name must be placed within a square bracket ([]) to be able to reference it in an Expression. For example: [field name with spaces] will reference a field in the document called field name with spaces. Expressions can also include one or more Functions from the EchoSign supported list. The specified Functions get evaluated at time of agreement signing and the resulting value gets displayed in the Calculated Field. For example: dateadd(d, signeddate, 3) This expression uses the dateadd function and specifies adding 3 days to the date on which this agreement gets signed. So if the document gets signed on 5/22/2013, the resulting value of the expression will be 5/25/2013. Section Supported Functions lists all the Functions supported within Expressions. Supported Operators The following Operators are supported when specifying Expressions within a Calculated Field. Operator Description + Add two numbers together. - Subtracts two numbers. / Divides two numbers. * Multiplies two numbers together. & Concatenate two strings together. = Equals. Compares two values and returns true if the two values are equal and false if they are not.!= Not Equals. Compares two values and returns true if the two values are not equal and 5

6 false if they are. < Less Than. Compares two values and returns Boolean (true or false) if the first value is less than the second value. >= Greater than or Equals. Compares two values and returns Boolean (true or false) if the first value is greater than or equal to the second value. <= Less Than or Equals. Compares two values and returns Boolean (true or false) if the first value is less than or equal to the second value. > Greater than. Compares two values and returns Boolean (true or false) if the first value is greater than the second value. % Modulo Operator. Returns the remainder of the division between two numbers. ^ Exponent Operator. Returns the exponential value of the specified numbers. Supported Functions The following Functions are supported when specifying Expressions within a Calculated Field. Function Category Description abs(number1) Math Returns the absolute value of the number number1. roundup(number1) Math Round up the number number1. rounddown(number1) Math Round down the number number1. round(number1) Math Round the number number1 to nearest integer. min(number1,number2) Math Returns the smaller of the two numbers number1 and number2. max(number1,number2) Math Returns the larger of the two numbers number1 and number2. datepart(part, date) Date Returns the part of the date specified by the first argument as an integer. For example: datepart(m, 5/22/2013) will return the 5 the month part of the date. Table below shows the acceptable values for part attribute. dateadd(part, date, addition) Date Adds the specified number of parts (e.g. "d" for day, "m" for month, or "y" for year) to a date to calculate a future date. You may use numbers or field names. For example: dateadd("m", "Jan 1, 2000", 3) would return a date of Apr 1, In this example, the formula adds 3 months to the date specified. datediff(part, date1, date2) Date Returns the number of parts (e.g. "d" for days, "h" for hours, or "n" for minutes) between two dates. You may use numbers or field names. For example: datediff("d", "Jan 1, 2000", "Jan 2, 2000") 6

7 would return a value of 1 to represent 1 day between January 1st and January 2nd. daysin(part, date) Date Returns the number of days contained in the part (e.g. "d" for day, "m" for month, or "y" for year) for the date specified. You may use numbers or field names. For example: daysin("m", "Feb 1, 2000") would return a value 29 for the days in February 2000 and daysin("y", "02/01/2001") would return 365 for the days in date(string) Date Convert a string value such as "1/1/2000" into a date object which can be used in other functions. now() Date Return the date and time when the formula was evaluated most often when the signature page gets loaded. if(logical_test, value_if_true, value_if_false) Logic Evaluates "logical_test". The logical_test can be another expression. If it is TRUE, it returns the value specified in the "value_if_true". If it is FALSE it returns the value of "value_if_false". Both the value_if_true and value_if_false attributes can also be expressions. For example: if (1>0, "Correct", "Incorrect") would return "Correct". and(logical1, logical2,...) Logic Return true only if all the logical arguments evaluate to TRUE. Otherwise it returns false. For example: and (1>0, 2>1) would return "true" and (1>0, 2=1) would return "false". or(logical1, logical2,...) Logic Returns true if any of the logical arguments (logical1, logical2,...) is evaluated to TRUE. If all the logical arguments are evaluated to FALSE it returns false. For example: or (1>0, 2>1) will return "true". or (1>0, 2=1) will return "false". not(logical) Logic Returns the opposite value of "logical". So if "logical" is evaluated as FALSE it returns true. If it is evaluated as TRUE, it returns false. For example: not (1>0) would return "false". Accepted values for portions of dates The following values can be used in date related functions when specifying the portion of the date on which the function should operate. Part y q Portion of the date to which the function will apply Year Quarter 7

8 m d h n s Month Day Hour Minute Second Calculated Fields Formatting In addition to specifying the Expression for a Calculated Field the output value can also be formatted. The output can be formatted as Text (the default) or formatted as a number or a date. When used with Text Tags the format directive takes two arguments: FormatType Format Specifies the type of value the Calculated Field represents. Accepted values for this parameter are: number and date. Specifies the structure of the output value to be placed in the calculated field. Formatting Calculated Fields as a number The following characters can be used to specify the formatting of an output in the form of a number. Format Character _ Description (Underscore.) Represents any digit placeholder. 9 Represents any digit placeholder.. Location of a mandatory decimal point (or locale-appropriate symbol). 0 Located to the left or right of a mandatory decimal point. Pads with zeros. ( ) If number is less than zero, puts parentheses around the mask. + Places a plus sign before positive number; a minus sign before negative number. - Places a space before positive number; a minus sign before negative number., Separates every third decimal place with a comma (or locale-appropriate separator character). $ Places a dollar sign (or locale-appropriate symbol) before formatted number. When specified it must be the first character for the format string. % Converts the number value in the field into a percentage. Multiplies it by 100 and puts the % sign at the end. When specified it must be the last character of the format string. Formatting Calculated Fields as a date The following characters can be used to specify the formatting of an output in the form of a date. Format Description Example 8

9 Character s The seconds of the minute between "0" to "59" ss The seconds of the minute with leading zero if required. "00" to "59" n The minute of the hour between "0" or "59" nn The minute of the hour with leading zero if required. "00" or "59" h The hour of the day between "1" to "12" hh The hour of the day with leading zero if required. "01" to "12" H The hour of the day between "0" to "23" HH The hour of the day with leading zero if required. "00" to "23" d The day of the month between 1 and 31. "1" to "31" dd The day of the month with leading zero if required. "01" to "31" ddd Abbreviated day name. "Mon" to "Sun" dddd The full day name. "Monday" to "Sunday" m The month of the year between "1" to "12" mm The month of the year with leading zero if required. "01" to "12" mmm Abbreviated month name. "Jan" to "Dec" mmmm The full month name. "January" to "December" yy The year as a two-digit number. "99" or "08" yyyy The full four digit year. "1999" or "2008" t Displays the first character of the A.M./P.M. designator. "A" or "P" tt Displays the A.M./P.M. designator. "AM" or "PM" Formatting Examples 1. {{myfield_es_:calc(otherdatefield + 3):format(date, "mmm dd, yyyy")}} - A Calculated Field formatted as a date. The output will be something like May 22, {{mytax_es_:calc(total * taxrate):format(number, "$,.00") }} - A Calculated Field formatted as a number. The output will be something like $1,

10 Using Expression Builder For Specifying Calculated Fields Calculated Fields can be specified through the EchoSign Web Form Authoring UI. The steps below will guide you through the steps of defining a Calculated Field once you have gone to the Form Authoring UI. 1. Step 1: Drag-and-drop a field in the document. Double click on the field that you just added to bring up the field properties dialog. Give the field an appropriate name. Change the Field Type attribute using the drop-down list to be of type Calculated Value. This indicates that the field value will be determined based on a calculation at time of signing. 2. Step 2: Type the calculation expression in the text field called Formula or click on the function button to bring up the Expression Builder. 3. Step 3: Use the Expression Builder to define the expression for the calculated field (see Figure below). The Expression Area shows the formula that will be used to calculate the value of the field. You can type the formula into the Expression Area or use the UI to construct the formula. The Expression Builder provides the list of all the available Functions, list of existing Form Fields in the document and supported Operators to allow easily constructing the expressions. You can add a Field or a Function into the formula by double clicking on the item in the List Area in the Expression Builder. You can also add any Operators to the expression by clicking on the specific 10

11 operator in the Operators List. 4. Step 4: Once you have finished defining the Expression, you can check the syntax of the Expression by clicking the Check Syntax button and save the changes. 5. Step 5: Set the format for the Calculated Fields using the drop down list from the Formula section. 11

12 6. Step 6: Finally select from the list of available formats or select Custom formatting to define a custom formatting for the field. Calculated Fields Examples {{shipstate_es_:signer1:calc([billingstate]):showif(sameas=unchecked)}} A field in the document assigned to the first signer that will only be displayed when another field (a check box) called sameas is unchecked. The value of the field is automatically populated with the value of the field billingstate that the signer has entered in the document. {{total_es_:signer1:calc(q1*pr1):format(number, $,0.00 ):align(right)}} A field in the document assigned to the first signer. Its value gets automatically calculated as the product of the values in fields q1 and pr1. The resulting value is formatted as currency and displayed with a dollar ($) symbol in front of the resulting value and containing two decimal points. The resulting value is also aligned right aligned within the field. {{price_es_:signer:calc(if(pn1= W1,9.99,if(pn1= W2,5.99,if(pn1= W3,24.99,0))))}} A field in the document called price which gets calculated based on the value selected by the signer in another fields pn1 in the document. In this example if field pn1 equals W1 the value displayed in the price field is 9.99, if field pn1 equals W2 the value displayed in the price field is 5.99 and so on. If none of the values match the value of the field pn1 the value displayed in price is 0. Using this mechanism Calculated Fields can be used to automatically populate the price of an item based on the selection that a user has made during signing. 12