Live Chat

Syntax Codes and Equations

Syntax Codes

Syntax codes provide a more advanced method for retrieving, chaining, and performing calculations on data from different fields. From creating simple mail merge functionality to performing complex equations using many data fields, syntax codes make this possible.

Field Syntax

Field Syntax can be defined as a “code” within the Ivinex system that is used to get field data from a specific field in a data module by it’s unique name or unique ID.

Default Record Fields: There are a few fields that are automatically generated for every record. As long as there is at least one record in a module, these fields are always available when using field syntax.

  • Created By: [Field: created_by] (The username of the person who created the record.)
  • Created Date: [Field: created_date] (The date the record was created.)
  • Modified By: [Field: modified_by] (The username of the person who last modified the record.)
  • Modified Date: [Field: modified_date] (The date the record was modified.)
  • Record ID: [Field: collection_id] (The ID of the record.)
Warning: When referencing the Record ID using field syntax, you must call it “collection_id” [Field: collection_id]. This is especially useful when attempting to set linked fields using a workflow.

The other fields we can access using Field Syntax depend on the data fields that were built into the module we are attempting to pull data from.

Note: When a field is created for a module, the “Display Text” will be used to name the field in the Ivinex system. However, the Ivinex system will modify the field names that are stored in the database in the following ways:

Field Name Modifications: Automatic modifications to field names within the Ivinex system (Fig. 1).

  • All lowercase.
  • Underscores replace spaces.
  • All non-letter/number punctuation removed.
  • If there are two fields with the same name, the second field will end with a number, starting from 0.
Fig. 1 - Display Name, Field Name, and ID.

Fig. 1 – Display Name, Field Name, and ID.

Now that we know how Ivinex modifies field names, we can use the field names or the field ID’s to get data using field syntax.

Field Name Example: Hello [Field: contact_first_name], today ([Field: contact_birthday]) is your birthday! Here is a coupon code for 10% off your next order.
Field ID Example: Hello [Field: 14005], today ([Field: 14010]) is your birthday! Here is a coupon code for 10% off your next order.
Example Output: Hello Joe, today (11/12/2012) is your birthday! Here is a coupon code for 10% off your next order.

Advanced Field Syntax

When using Field Syntax to get data from the “Linked Record” field type, it’s important to note that the field itself is referencing another field in a different module (Fig. 2).

Fig. 2 - Linked Record Module Relationship

Fig. 2 – Linked Record Module Relationship

Chaining Syntax:

  • : syntax: [Field: linked_field_name:actual_data_field] (most common method).

This method is most commonly used to get field data from a linked record. It is possible to use the chaining syntax multiple times in a row to get data from a field that may be 1, 2, or 3 linked records away. There is no limit on how many times you can use the : syntax in a row.

Note: The : syntax is used in a unique way when setting up email notification templates. See the “Where to use Syntax Codes” section of this tutorial to learn more.
: Syntax Example (one chain): We want to get the phone number of the linked contact for our field “Account Owner”. We would use the name of the field as the first part of the syntax and then add a colon : to get the phone number: [Field: account_owner:phone]. This would return the phone number of the linked contact.
: Syntax Example (multiple chains): We want to get the name of a person in our “contact” module. Our starting point is a module named “support”. Our support module links to our “account” module which then links to our “contact” module. To get the name of the contact we will need to use the chaining syntax multiple times: [Field: first_linked_field:second_linked_field:contact_name_field]. This would return the contact name from the contact module.

When using Field Syntax to get data from the “Radio” and “Select” field types, it is important to note that these field types support multiple options, and each option has a respective ID and “text” value. (Fig. 3).

Fig. 3 - Options with ID's and Text Values

Fig. 3 – Options with ID’s and Text Values

The vertical bar (or “pipe”) syntax:

  • | syntax:Used to specify the type of data to be returned.
    • |0 syntax: [Field: example_field|0] = Will force the ID to be returned.
    • |1 syntax: [Field: example_field|1] = Will force the text value to be returned.
Note: You may not find a need to use the |1 syntax, as the default value returned is the “text” value vs. the ID value. It is possible to use both the : syntax and the | syntax together.
| Syntax Example: We want to get the ID of an option that has been selected by a user. Our field name is “callback”, the type is Radio, and our options are Yes (ID: 4885), and No (ID: 4886). To get the ID of the selected option, we start with the name of the field and then add the vertical bar character | and then a 0[Field: callback|0]. This would return the ID of the selected option.

Fields where the | syntax makes a difference:

  • Radio
  • Select
  • User
  • Linked_Record
Warning: When attempting to set a Linked_Record with a workflow, you must use the |0 syntax as this field type is stored as an ID only.

Table Syntax

Table Syntax enables us to output a table of data (multiple records from a data module) in an email or static field.

The syntax to display a table is the following:

[Table: <Module>|<Fields>|<Style>|<Order By>|<MaxNumRows>]
  • Module: The module (or tab) that you want to show in the table.
  • Fields: Comma separated list of field names (or IDs) to show. If you leave this blank, the default will be displayed.
  • Style: HTML or TEXT.
  • Order By: How you want this sorted.
  • MaxNumRows: The Max number of rows to display.
Example: We have a support ticket record in Ivinex for a customer. We use the activity module to store notes and tasks for this support ticket. We want to send an email to the customer which contains all of the related activity records that apply to this specific support ticket. When we send an email (while looking at the support ticket record), we would include the following Table Syntax: [Table: Activity||HTML|collection_id^desc|]

This means, display a table of Activities, use the default fields, display in HTML format, order by the collection_id in descending order, and display all of them. (The collection ID is the internal ID of each record…it is incremented by one each time another is created, so it’s really the reverse order of the created date).

If you wanted to only display the very last activity, you would type:

[Table: Activity||HTML|collection_id^desc|1]

 

Table Syntax Example

Table Syntax Example

User Syntax

User Syntax is similar to Field Syntax in the way it allows us to get data. The User fields however are not related to a module (that we can create), instead they are related to the individual user fields found in the User Manager.

Available User Information Fields:
Using these will return the information stored in the User Manager for the current logged in user.

  • [User: first_name]
  • [User: last_name]
  • [User: alias]
  • [User: title]
  • [User: email]
  • [User: address]
  • [User: phone]
  • [User: extension]

Following along with our previous Field Syntax example, we will now incorporate User Syntax:

Example: Hello [Field: contact_first_name], today ([Field: contact_birthday]) is your birthday!
Here is a coupon code for 10% off your next order.
Sincerely,
[User: first_name] [User: last_name]
Phone: [User: phone] Ext: [User: extension]
Example Output: Hello Joe, today (11/12/2012) is your birthday!
Here is a coupon code for 10% off your next order.
Sincerely,
Bret Lund
Phone: 123-456-7890 Ext: 777

Equations

The Ivinex platform currently supports the following mathematical symbols:

Here are a few examples of how to construct simple equations in Ivinex:

Note: Equations will only be evaluated when using INTEGER and DECIMAL data types.
Note: Equations are not currently evaluated on import or if an equation input is changed by a workflow.
Addition Example: [Field: shipping_price] + [Field: extra_fee] or [Field: shipping_price] + 4.50
Subtraction Example: [Field: total_price] – [Field: discount] or [Field: total_price] – 9.95
Multiplication Example: [Field: contract_price] * [Field: tax_rate] or [Field: contract_price] * 0.065
Division Example: [Field: total_apples] / [Field: total_people] or [Field: total_apples] / 5
Exponentiation Example: [Field: my_number] ^ [Field: my_other_number] or [Field: some_number] ^ 3
Modulo Example: [Field: my_number] % [Field: my_other_number] or [Field: my_number] % 10

Advanced Equations

More advanced equations are supported in Ivinex.

Example 1: [Field: room_height] * [Field: room_width] * [Field: room_length]
Example 2: ([Field: field_one] * [Field: field_two]) ^ [Field: field_three]

Where to use Syntax Codes

Now that we have learned all about syntax codes, the next step is learning where we can use them.

Email Templates

Using syntax codes within email templates is very helpful when you want to customize or insert user / client specific data (Fig. 4).

Fig 4. - Email Template using Syntax Codes

Fig 4. – Email Template using Syntax Codes

Email Notifications

When sending out an email, the Ivinex system also allows you to request notifications when the email has been opened. The notifications can be generic, or we can select a custom notification (email template) that is sent back to us.

Note: An email notification is triggered when an email is opened. Because the email notification is triggered after the first email, it cannot use field syntax the same way as the original email.
Example: We want to pull data into an email notification template. Because email notifications are created AFTER the original email has been opened, we must specify the module first and then the field name for the Field Syntax to work correctly [Field: Module: field_name]. Or in some cases, we must specify the module, then the next module, and finally the field name [Field: Module: Module: field_name]
Fig. 5 - Notification Email Location

Fig. 5 – Notification Email Location

Workflow Actions

Email Workflow

Example: We want to automatically send an email to the account owner when the account status has changed. The email needs to contain the account name and the new status. In our workflow action we use Field Syntax to pull data into the email: Email To: [Field: account_owner: email] Subject: [Field: account_name] status changed to [Field: status].  
Warning 1: The Send Email workflow action MUST include a from email address or the action will fail. Warning 2: Make sure to setup a system email account before sending any workflow emails. If you do not, the email may not send and if it does, it will not be from your email account. This email will be flagged as spam.
Fig. 6 - Using Field Syntax in Workflow Actions

Fig. 6 – Using Field Syntax in Workflow Actions

Advanced Record Update

Example: Let’s say we created an accounts module and a products module. The accounts module is related to the products module in a one to many relationship (one account with many products). We then decide to add linked record fields to the product module that are supposed to show data from the account module fields. We have the “Automatically set if linked” check box selected for all the new linked record fields, but the new fields are not yet aware of the linked status (even though the product IS linked to the accounts module (Shows up in “Related Accounts”). We decide to build a timer workflow that will update all the new linked record fields with the RELATED account data.

In this special case, we must use the Record ID (collection_id) of the related account in the field syntax: [Field: Account: collection_id]. We first setup a filter to check for fields that are not yet linked (Fig. 6.1). We then setup the workflow action to use the module name and the collection_id (record ID). When the timer workflow runs, it will find the related account BY its RECORD ID and set the linked fields.

Fig 6.1 - Filter checking for linked record fields that are not linked.

Fig 6.1 – Filter checking for linked record fields that are not linked.

 

Fig 6.2 - Using module name and collection_id field syntax.

Fig 6.2 – Using module name and collection_id field syntax.

Filters

Field data can be pulled into a filter using Field Syntax (Fig. 7).

Fig. 7 - Using Field Syntax in a Filter

Fig. 7 – Using Field Syntax in a Filter

Display Conditions

Example: We want to show a static field that says “Email does not match!” when our field “Confirm Email” does not match our field “Email Address”. We create a display condition that uses the following rules:  Confirm Email NOT Equal to blank, and Confirm Email NOT Equal to [Field: email_address].
Note: When using display conditions, you cannot currently use field syntax that includes the ID of a field. You must use syntax that uses the name of the field. Example: [Field: email_address] works, [Field: 12953] does not work. This should be fixed in the near future.
Fig. 8 - Using Field Syntax in Display Conditions

Fig. 8 – Using Field Syntax in Display Conditions

Equation (Field Option)

Example: We want to create an equation that multiplies the “Price” field by the “Quantity” field and outputs the result into the “Total Cost” field. In the “Total Cost” Field Display Options window, we would add the following equation (using Field Syntax) into the Equation field option: [Field: price] * [Field: quantity]
Fig. 8 - Using Syntax Codes in Equation Field Options.

Fig. 8 – Using Syntax Codes in Equation Field Option.

Static Field

Example: We want to use a linked record field type to set the “Account Owner” for our accounts module. After selecting the “Account Owner”, we want to also display other information about the “Account Owner”. Using a static field we enter in the following Field Syntax into the “Text To Display” area: Name: [Field: account_owner: first_name] [Field: account_owner: last_name] Phone: [Field: account_owner: phone] Cell: [Field: account_owner: cell_phone]
Fig. 9 - Field Syntax in Static Field "Text To Display" Area.

Fig. 9 – Field Syntax in Static Field “Text To Display” Area.

Revisions

Tags: , , , , , , , ,

No comments yet.

Leave a Reply

%d bloggers like this: