tc:data

The tc:data tag is used to do both of the following actions:

• Retrieve data from TeamConnect system fields.
• Point the Document Generator to different object records from which to retrieve data by nesting tc:data tags, thereby "navigating" to the system fields you need.

What Can Be Retrieved with tc:data

The tc:data tag can retrieve data from the following areas:

• Main object record
  Use the tc:data tag independently to retrieve single instances of data from TeamConnect system fields of the main object record.
• Sub-objects
  Nest the tc:data tag within one of the following tags:
  • tc:loop tag, to automatically retrieve data from sub-objects.
  • tc:filter tag, to have the user select the sub-object from which to retrieve the data.
    These tags retrieve data from TeamConnect system fields of sub- objects, such as project assignees and categories. For more information, see:
  • tc:loop or tc:filter
  • Filters for Sub-objects and Single Records
• Related objects
  Nest the tc:data tag within one of the following tags:
  • tc:search tag, to automatically retrieve data from related objects.
  • tc:filter tag, to have the user select the related object record from which to retrieve the data.
    These tags retrieve data from TeamConnect system field of related objects (such as involved, appointment, child custom objects, embedded custom objects and child accounts). For more information, see tc:search and tc:filter.
• Objects not related to the main object
  Nest the tc:data tag within the tc:filter tag to retrieve data from objects that are not related to the main object. For more information, see Filters for Non-Related Objects.
• System object related to current object through a system field
  Nest the tc:data tag within another tc:data tag when a system field relates the current object to a system object, in order to retrieve data from the related system object, such as contact. For an example, see Nesting to Navigate.
• Custom object record selected in a custom field
  Nest the tc:data tag within the tc:detail tag to retrieve data from system fields of a record selected in a custom field of type Custom Object. For an example, see Nesting to Navigate.

Points To Remember

When using tc:data, you must know the following concepts:

• The tc:data tag will retrieve data from the specified system field of the current object. When the tc:data tag is not nested, it points to data from the main record for which the document is being generated.
• The tc:data tag requires one tag attribute, select. It can also accept several other tag attributes, which are used to format the data item that the tag retrieves.
• When using tc:data to retrieve data, the object attribute you are retrieving with tc:data cannot be of the data type Object. An object is actually a collection of attributes that identify data, so it cannot itself be inserted into a generated document. If you attempt to do this, the generated document will contain a large amount of nonsensical code. If you need specific information from that object, you should nest tc:data tags in order to navigate to the specific data you need.
  
  Tip: Object Model: Read This First and the additional reference tables it points to indicate the data type of each object attribute in the Data Type column of all tables. You can see which attributes have the data type Object and avoid retrieving them in a template.
   
• If you need to retrieve data from a custom field, use tc:detail. For more information, see tc:detail.

Required tc:data Tag Attribute

Whether using the tc:data tag on its own to retrieve data from the currently selected record, or if nesting the tc:data tag to retrieve data from sub-objects or related objects, the select attribute must always be used with the tc:data tag.

Required tc:data Tag Attribute

Example:

<tc:data select="NumberString" />

The select attribute takes a system field's name as its value. In the example above, NumberString is the object attribute that corresponds to the system field, Number. Therefore, the data retrieved by the Document Generator will be the number of the record selected by the user.

Optional tc:data and tc:detail Tag Attributes

The following attributes are optional attributes that can be used within the tc:data and tc:detail tag. Each optional attribute is applicable to a specific field type (such as number, date, text). These tags control the format of the data that is generated in the document.

Caution: If you try to assign an attribute to a field that is not of the appropriate type, TeamConnect is not able to generate the document and displays an error.

Optional Tag Attributes for tc:data and tc:detail

dateFormat Tag Attribute Values

The following values are the available values for the dateFormat attribute.

Possible Values for dateFormat Tag Attribute

The date and time formats can be combined to create the desired result. For example, you can combine MM/dd/yyyy with h:mm a (dateFormat="yyyy/dd/MM h:mm a") to display the date as 12/08/2001 3:08 PM.

Navigating Within tc:data Tag

In tc:data tags, you can navigate throughout the Object Model to retrieve data from other objects without opening and closing separate tags for each object. If you only want to retrieve one data item from an object, rather than multiple items, it may be easier to write one tag that points to the data you need rather than nesting to navigate.

A path to a data item, or object attribute, that exists in a different object is retrieved in a single tag by writing a path to it using the object attributes that serve as relationships between objects. These object attributes are noted in Object Model: Read This First and in the additional reference tables it points to, with arrows (-->).

Follow these guidelines when navigating to an attribute within a tc:data tag:

• Separate each object attribute in the path with a forward slash (/).
• Capitalize the first letter of all object attributes in the path.
• Close the tag to point the Document Generator back to the previous object that it was pointing to.

For example:

<tc:data select="Parent/Contact/ FirstName" />
Retrieves the first name of the Contact selected for the parent record's contact-centric field.

<tc:data select="Project/Name" />
Retrieves the name of the Project record to which a Task record is related.

<tc:data select="MainAssignee/Type/ Name" />
Retrieves the name of the main assignee's role for a record.

<tc:data select="MainAssignee/User/ Contact/FirstName" />
Retrieves the first name of the main assignee for a Project record.

tc:detail

The tc:detail tag retrieves data from a TeamConnect custom field. You can use tc:detail to retrieve custom field values from the currently selected record, or you can nest it, thereby "navigating" to retrieve values from objects that you specify.

Keep the following points in mind when working with this tag:

• To retrieve custom fields of related objects, nest the tc:detail tag within the tc:search or tc:filter tag (for details, see tc:search or tc:filter).
• To retrieve custom fields from a system or custom object to which a custom field links, nest the tc:detail tag within the tc:data tag (for details, see Nesting to Navigate).
• The tc:detail tag uses the same attributes as the tc:data tag for formatting the data retrieved by the tag. See the Optional Tag Attributes for tc:data and tc:detail table for a list of additional attributes.

The following table provides a description of the required attribute of tc:detail.

Required tc:detail Tag Attribute

Example:

<tc:detail select="CLAM_AUTO/Personal Injury" />

In the previous example, Personal Injury is a custom field found in a Claim record in the category Auto. Since this custom field is a check-box, the label of the check-box is the data extracted and inserted into the generated document if the check-box is checked. Additional categories on the same level are other types of claims, for example, General Liability and Home.

In this example, CLAM is the unique code of the custom object Claim. If you are referencing a custom field in the top node (root) of a custom object's category tree, the tree position of the custom field is the unique code of the object.

The options in the resulting drop-down list in Document Generator appear to the end user as follows:

Custom Field Display Formats

By default, data retrieved from each type of custom field appears in a particular format in the generated document. However, you can modify the way certain data types appear using the tag attributes in the Optional Tag Attributes for tc:data and tc:detail table.

The following table indicates how each type of data will be displayed by default.

Custom Field Display Formats in Generated Document

tc:loop

The tc:loop tag is used to navigate to sub-objects of the current object. The tc:loop tag does not retrieve any data by itself. It only specifies the sub-object from which TeamConnect will retrieve data. Essentially, it navigates from the current object to the sub-object that you specify.

When you close the tc:loop tag, you return to the object to which the sub-object belongs. However, while inside the tc:loop tag, you can continue to navigate to other objects by nesting additional tags. You can also nest tc:loop within other tags as needed, such as tc:filter or tc:conditional.

To retrieve data from system fields of the sub-object, you must nest the tc:data tag within the tc:loop tag.

When nesting the tc:data tag within the tc:loop tag, the following data can be retrieved:

• Data from all instances of a sub-object.
  For example, you may want to include all the names and phone numbers of all the Assignees for an auto claim. For details, see Retrieving Data from All Instances of Sub-object.
• Data from only instances of the sub-object that match a criterion that you define.
  For example, you may want to include only the name and phone number of Assignees with a certain role, such as Supervisor. For details, see Retrieving Data with tc:loop Using Qualifiers.

Automatically Selected vs. User-Selected Sub-objects

The tc:loop tag is useful for selecting instances of a sub-object from which data should be retrieved automatically in a document template. However, there are some cases where it is necessary for the user who is generating a document to select a sub-object from which to retrieve data.

For example, your document template may require that the user select an assignee, address, or phone number. In order to provide the user with a list of instances of a sub-object, you would not use tc:loop. Instead, you would use tc:filter to define a filter page where the user would make the appropriate selection. You will learn more about how to do this in Filters for Sub-objects and Single Records.

Retrieving Data from All Instances of Sub-object

To retrieve data from all instances of a sub-object, regardless of the type, you only need to use the select attribute with the tc:loop tag and then nest the tc:data tag within the tc:loop tag.

For example, you can use this method to list all Assignees for a project, regardless of the assignee role (type). The Document Generator will print the data you specify for all of the assignees of the project.

Usage of tc:loop - Retrieving Data from All Instances of Sub-object

Example:

<tc:loop select="AssigneeList">
<tc:data select="User/Contact/FirstName" />
<tc:data select="User/Contact/Name" />
<tc:data select="Type/Name" />
<tc:data select="User/Contact/DefaultPhone/PhoneString"/>
</tc:loop>

The select attribute of tc:loop takes a sub-object, such as an assignee or a category, as its value. Data values from the system fields of the sub-object specified by tc:loop are retrieved by tc:data tags nested within tc:loop.

In the example given, the data retrieved by TeamConnect is the first and last name, title, and phone number of all the users who are Assignees. The sub-object Assignee is specified by the tc:loop tag. The first and last name, title, and phone number of all the users are specified by the nested tc:data tags. Notice that this information is really stored in the user's Contact record, so the tags are actually navigating to the Contact record.

Retrieving Data with tc:loop Using Qualifiers

To retrieve data from certain instances of the sub-object that meet a certain criterion, rather than all instances of the sub-object, you must use the qualifier attribute with tc:loop. Again, you must also nest the tc:data tag within the tc:loop tag.

For example, you can use this method to retrieve data only from assignees that have the role Supervisor within a project record. If one or more assignees are found to match your qualifier, their data will be retrieved and inserted in the generated document. The Document Generator will automatically retrieve data only from those records that match the criterion, whether there are zero, one, or multiple records that match.

Caution: The qualifier attribute can only handle one qualifier.

For most sub-objects, the Type attribute is the most useful characteristic for filtering the data that is retrieved. For assignees, the role is actually the Type attribute of the assignee sub-object in the Object Model.

It is possible to use other object attributes from the sub-object, such as a number or text field, but these values are rarely useful for setting a criterion for which sub-objects to retrieve.

The following table indicates the tags and attributes that you would use to set up a tc:loop that retrieves a qualified list of sub-object data in a document template.

Usage of tc:loop - Retrieving Data with Qualifier

 The following table indicates the syntax for the qualifier attribute value.

Qualifier Tag Attribute Syntax

 The following examples show how qualifiers can be used in the tc:loop tag.

Example 1:

<tc:loop select="AssigneeList" qualifier="Type_TreePosition=CLAM_SPRV">
    <tc:data select="User/Contact/FirstName" />
    <tc:data select="User/Contact/Name" />
    <tc:data select="User/Contact/DefaultPhone/ PhoneString" />
</tc:loop>

In the example above, the qualifier attribute takes the unique code of the object and the tree position of the selected item within the sub-object as its value. CLAM is the unique code of the selected object, Claim, and SPRV is the tree position of the project assignee. The data retrieved by TeamConnect is the first and last name, and phone number of only the type of assignee (specifically, assignee role) that is specified by the qualifier attribute.

Example 2:

<tc:loop select="DetailList" qualifier="Category_Parent_Name=Claim">
    <tc:data select="Category/Name" />
</tc:loop>

This is an example of using a text value as a qualifier. In this example, which is for a custom object named Claim, the qualifier attribute makes the Document Generator retrieve only those categories added to the record that have Claim as the parent category. This property means that any categories on the level directly beneath Root which are added to the record are retrieved. However, the category Claim itself is not retrieved.

Also, any categories added to the record that are on the second, third, fourth levels, and so on, beneath the Root are not retrieved, because their Parent category is not Claim. The data being retrieved with the tc:data tag is the name of each category that meets the qualifier.

This property is useful when you want the generated document to include only the major categories of a record and not all of the sub-categories.

Example 3:

<tc:loop select="PhoneList" qualifier="Type_TreePosition=PHON_BUS1">
    <tc:data select="PhoneString" />
</tc:loop>

In the previous example, the qualifier attribute makes the Document Generator retrieve only the phone numbers for a contact that are of the type Business 1 (BUS1). The tc:data tag retrieves the actual phone number.

Notice that the value for the qualifier attribute is the unique code of the lookup table (PHON), followed by an underscore (_) and the tree position of the phone type being retrieved (BUS1).

tc:date

The tc:date tag retrieves the current system date, at the time the document is generated. By default, the date will be displayed in the following format:

MM/dd/yy

To display the current system date in another format, use the format tag attribute.

You can also nest the tc:user tag, since it works the same regardless of which other tags you have outside of it. The following table describes the possible tag attributes for tc:date.

Usage of tc:date

Example:

<tc:date format="EEE, MMM d, yy"/>

In the example given, the date will be inserted in the generated document and formatted by Day, Month Date, Year, as in Friday, Jun 28, 2002.

tc:user

The tc:user tag retrieves data from the user account of the current user who is generating the document. You can nest tc:data tags to retrieve the necessary data from that user. You can also nest the tc:user tag, since it works the same regardless of which other tags you have outside of it.

This tag points to the YUser object table. See Object Model: Read This First to learn about what data you can retrieve about the current user, either from YUser or from an object that is related to it.

Example:

<tc:user>
    <tc:data select="Contact">
    <tc:data select="FirstName" />
    <tc:data select="Name" />
    <tc:data select="Title" />
    </tc:data>
</tc:user>

In the example given, the data retrieved by TeamConnect is the first name, last name, and job title of the user who generates the document, which is all located in the contact record associated with that user.

tc:file

The tc:file tag retrieves the text of a separate XML file and places that text in the end-user's generated document. The file you are retrieving must be uploaded to a specific directory in TeamConnect's Documents area. This tag can be nested as needed in a document template.

You can use this tag to retrieve content that is being used by many different templates, instead of including the same content directly in each template. This tag is also useful if the text in the XML file should be included only under certain circumstances. You can use this tag in conjunction with the tc:conditional tag to accomplish this.

Usage of tc:file

Example:

<tc:file select="Statutes/CalStatutes.xml" />

The select attribute takes the name of the folder in which the XML file is located and the name of the XML file as its value. In the example given, Statutes is the name of the folder and CalStatutes is the name of the XML file. The content of the CalStatutes file will be included as text in the generated document.

Preparing XML Files Referenced by tc:file

You may wish to retrieve text from a file with a DOC extension (a Microsoft Word™ file) and insert that text into the generated document. However, only an XML file can be extracted with the tc:file tag and inserted into the generated document.

To convert the DOC file into an XML file

1. Open the DOC file with your word processing application (i.e. Microsoft Word™).
2. Format the text exactly as you would like the information to appear in the generated document (enter all returns, indentations, line formatting, font size, and so on).
3. Save the file with an RTF extension and close your word processing application.
4. Find the RTF file you just saved and open it with a text editor such as Microsoft Notepad™.
5. At the very beginning of the document, insert the following tags, with a line return after each, in the following order:
   <?xml version="1.0" encoding="UTF-8"?>
<tc:document version="1.0" mime-type="MimeType" name="TemplateName" xmlns:tc="http://www.w3.org/1999/XSL/Transform">
   For information about the attribute values "MimeType" and "TemplateName" see the Document Tag Attributes table.
   <tc:content>
   Caution: Do not place a line return after tc:content. If the source code does not start immediately after this tag, TeamConnect encounters an error when trying to generate the document.
6. At the very end of the document, insert the following tags, in the following order:
   </tc:content>
</tc:document>
7. Save the file with an XML extension.
8. Open the file in Internet Explorer or an HTML editor to test whether it is well-formed.
9. Create a new folder within the Document Templates folder of the object for which your template is created.
10. Upload the XML file to the folder you just created.
    The contents of the XML file will be included in the generated document as long as the XML file and its folder are in the correct directory in the Documents area of TeamConnect.

tc:conditional

The tc:conditional tag is used to specify a condition that must be met in order for any nested content within the tc:conditional tag, including static text as well as tags, to be included in the generated document. If the condition specified by the tag is met, then anything nested within tc:conditional is generated. If the condition is not met, then the nested content is ignored.

The following points summarize the basics about tc:conditional:

• tc:conditional can be nested within almost any other tags. For example, you can nest it within tc:filter or tc:search. For an example of nesting tc:conditional, see Retrieving Specific Type of Related Object with tc:conditional.
• You can nest tc:conditional tags within each other, if necessary.
• There are two main tag attributes for tc:conditional: compare and test. You must always use either one or the other when you use tc:conditional. However, you cannot use both.
• There are two other tag attributes that you can use in combination with compare or test, which are described in the following table.

The following table describes all of the tag attributes that may be used with tc:conditional.

Tag Attributes of tc:conditional

Using tc:conditional to Compare Custom Field Values

The compare attribute of tc:conditional is useful for comparing a custom field to a value that you specify in the tag. If the custom field has the value that you specify, then the condition is found to be true, and the content nested within the tc:conditional tag is generated.

You can use compare with the following types of custom fields. For each type of custom field, you must provide the value of the compare tag attribute in the specified format.

Tag Attribute Value Formats for Comparing Custom Fields

Example:

<tc:conditional compare="Detail[CLAM]/DetailValue[DrunkDriver],true">
    <tc:file select="Statutes/DrunkDriverStatute.xml" />
</tc:conditional>
<tc:conditional compare="Detail[CLAM]/DetailValue[Speeding],true">
    <tc:file select="Statutes/SpeedingStatute.xml" />
</tc:conditional>

In this example, the custom fields DrunkDriver and Speeding are check-boxes within the project Claim. The values specified for each is true, meaning that if a check-box is checked, then the XML file specified for that field will be included in the generated document. For example, if the DrunkDriver check-box is checked, the XML file DrunkDriverStatute is included in the generated document since the true condition that you specified was met.

Using tc:conditional to Compare Sub-objects

The compare attribute of tc:conditional can also be used to check whether an instance of a certain type of sub-object exists. If the type of sub-object that you specify in the tag has been added to the record, then the condition is found to be true, and the content nested within the tc:conditional tag is generated.

You can use the compare attribute to check any sub-object that has a Type object attribute. For example, Address, Assignee, Phone, and Email all have a Type.

Example:

<tc:conditional compare="System[Assignee],Adjuster">Please contact your claim adjuster for more information.</tc:conditional>

In this example, if the Assignee List in the record contains an assignee of the type Adjuster, then the text inside the tc:conditional tag is generated. Adjuster is an example of the type of assignee.

Using tc:conditional to Test for Object Attribute Values

The test attribute of tc:conditional is used to test whether a condition is true. You can test any system fields (object attributes) belonging to an object, EXCEPT for check-boxes. A condition is true when a value exists for that attribute. For example, you can test whether a custom object record such as Claim has a parent selected in the Parent system field.

You can also test the list of sub-objects added to a record to check whether any instances of that sub-object exist. If at least one instance of the sub-object is found, then the condition is true, and the content nested within the tc:conditional tag is generated. For example, if there is at least one Address added to a Contact, then the condition is true.

Unlike the compare tag attribute, the test attribute does not check the type of the sub-object. Any instance found proves the condition to be true.

Example:

<tc:conditional test="MainAssignee">
Please contact the following associate with any questions you might have about your claim.
    <tc:data select="User">
    <tc:data select="Contact">
    <tc:data select="FirstName" />
    <tc:data select="Name" />
    </tc:data></tc:data>
</tc:conditional>

In this example, the text and tags that are nested within tc:conditional will only be inserted into the generated document if a Main Assignee exists for the Claim record.

Testing for a Category

You can use the test tag attribute to test whether a certain category has been added to a record. This is a useful way to include content in a generated document only when the main object record has a certain category added to it.

Example:

<tc:conditional test="Detail[CLAM_HOME]">
We have the following information about your loss in our records:
    Caused by natural disaster:
    <tc:detail select="CLAM_HOME/NaturalDisaster" /> Date of Loss:
    <tc:detail select="CLAM_HOME/LossDate" format="" /> Summary of Loss from your written statement:
    <tc:detail select="CLAM_HOME/LossSummary" /> Estimated Dollar Amount of Loss:
    <tc:detail select="CLAM_HOME/LossEstimate" numberFormat="#,##0.00" />
</tc:conditional>

In this example, the text and custom fields contained within the tc:conditional tag will only be inserted into the generated document if the category CLAM_HOME has been added (exists) in the Claim record.

tc:block

The tc:block tag is used to group tc:conditional tags. The tc:conditional tags on their own can each have nested content that is only included in the generated document when the condition is true.

However, when nested within a tc:block tag, multiple tc:conditional tags are handled differently.

The advantage of tc:block is to generate the same content, such as retrieving another XML file, when at least one of a group of conditions are met. For example, if one or more of five check-boxes is checked, then retrieve an XML file. Each tc:conditional tag that is nested within tc:block must have exactly the same content nested within it, so that no matter which condition is found to be true, the Document Generator generates the same content.

When tc:conditional tags are nested within tc:block, the Document Generator reads through each tc:conditional tag and checks the condition. As soon as it encounters a tc:conditional tag with a true condition, it generates that tag's nested content. It then ignores the rest of the tc:conditional tags in the block.

The following points will help you use tc:block:

• If you have several tc:conditional tags to include in a document template but they have different content that they will generate, then do NOT nest them within a tc:block tag. The purpose of using tc:block is to allow the same content to be generated, no matter which condition is met.
• You cannot nest any tags within a tc:block tag except for tc:conditional tags. Other tags can be nested within those tc:conditional tags, but they cannot be nested directly within the tc:block tag.
• Like tc:conditional, you can nest tc:block as needed within other tags.
  Example:
  <tc:block>
     <tc:conditional compare="Detail[CLAM]/ DetailValue[DrunkDriver],true">
          <tc:file select="Statutes/RecklessStatute.xml" />
     </tc:conditional>
     <tc:conditional compare="Detail[CLAM]/DetailValue[Speeding],true">
          <tc:file select="Statutes/RecklessStatute.xml" />
     </tc:conditional>
</tc:block>

In this example, the custom fields Drunk Driver and Speeding are specified. The conditions for these check-boxes are each set to true.

Note: The tag nested within each tc:conditional tag is exactly the same. If only one of these fields is checked, then the XML file named RecklessStatute.xml will be retrieved and included in the generated document.

tc:compute

The tc:compute tag can add, subtract, multiply, or divide two numeric values, depending on the mathematical operator specified.

When using tc:compute, you must know the following concepts:

• Each value can be either a system field, custom field, or value specified within the template, but they must both be numerical values. Otherwise, TeamConnect will display an error and the document will not generate properly.
• You can nest tc:compute as needed within other tags.
• In order to specify which two values to compute, you nest tags within tc:compute that point to numerical values.
• The tc:compute tag can be described as "Field1 (+, -, *, /) Field2". For example, for subtracting, the second nested field is subtracted from the first nested field. For dividing, the first field is divided by the second field.

The following table describes the tag attributes for tc:compute.

Usage of tc:compute

Example:

<tc:compute method="-" format="###0.00">
    <tc:detail select="CLAM/ClaimEstimate" />
    <tc:detail select="CLAM/ClaimPaid" />
</tc:compute>

In the example given, the compute method specified is subtraction "-". CLAM/ClaimEstimate and CLAM/ClaimPaid are number fields for the project Claim. Since CLAM/ClaimEstimate is specified first, CLAM/ClaimPaid will be subtracted from CLAM/ClaimEstimate to give the resulting value in the generated document.

To compute a value from one TeamConnect system or custom field and a value specified within the template, use tc:operand in conjunction with tc:compute. See tc:operand for details.

tc:operand

The tc:operand tag can be nested within tc:compute to specify a static value to compute with a value from a number field.

Example:

<tc:compute method="*" format="###0.00">
    <tc:detail select="CLAM/ClaimEstimate" />
    <tc:operand value=".2" />
</tc:compute>

This example calculates a value by multiplying the value in the Claim Estimate field by .2. The purpose of this example is to find a percentage of a value in TeamConnect and insert this percentage value into a generated document.

tc:search

The tc:search tag is used to automatically retrieve data from related objects of the current object. When you want to retrieve data from related objects automatically, rather than having the user select the related objects from which data should be retrieved, use tc:search.

For example, if you are creating a document template for Policy and you want to automatically retrieve data from its child Claim records, you would use tc:search to find the desired Claim records and get data from them.

You can retrieve data from the following related objects by using tc:search to navigate to them:

• A system object that is directly related to the current object, such as its involved or history.
  Note: Documents are not directly related to an object. Therefore, you will not be able to retrieve information or content about a document using tc:search. You will need to use tc:filter instead. For information, see Filters for Non-Related Objects.
• A child custom object of the current custom object.
• An embedded object of the current custom object.
• Child accounts of the current account.

Points To Remember

When using tc:search, you must know the following points:

• Unlike tc:filter, when you use tc:search you cannot guarantee that data will be retrieved from only one record. The Document Generator is "searching" for records according to your tag, similar to a search screen in the user interface.
• If you use tc:search without any tc:conditional tags, then the data will be retrieved from all instances of a related object and included in the generated document. For example, you may want to include the all of the claims filed against a particular policy.
• By nesting the tc:conditional tag within tc:search, you can specify a criterion for the related object records from which to automatically retrieve data.
• You can nest tc:search within other tags as needed to navigate to the appropriate object. For example, after navigating to the Contact object through the contact-centric field in a custom object (by using tc:data), you can use tc:search to get that contact's History records.

When NOT to Use tc:search

You must not use tc:search when:

• You want the user to select which related object record(s) from which data will be retrieved. Instead, use tc:filter.
• You want to retrieve data from a record that is not related to the main object record in any way. Instead, use tc:filter so that the user can select the record.
• You want to retrieve data or content from a document record. Instead, use tc:filter to select a non-related record.
• You want to retrieve data from sub-objects. Instead, use tc:loop (to automatically identify the sub-objects) or tc:filter (to have the user select the sub-objects).

The following table describes the tag attributes for tc:search.

tc:search Tag Attributes

The following example illustrates how tc:search can be used.

Example 1:

<tc:search link="Project" isForChild="yes" qualifier="Application_ProjObjectDefinition_UniqueCode=CLAM">
Claim Information (Child of Policy)
    Claim Name: <tc:data select="Name" />
    Claim Number: <tc:data select="NumberString" />
</tc:search>

In the example above, tc:search is retrieving only child object records for Claim, since Policy may have other child custom objects besides Claim.

Rather than including data from all related object records that are identified by tc:search, you may want to include only data from those records that meet certain criteria. For example, instead of the names of all the Involved Contacts added to a policy, you may want to include only the names of Involved Contacts that have a certain category, such as Additional Driver.

Example 2:

<tc:data select="Parent">
Parent (Policy) Information
    Number: <tc:data select="NumberString" />
    Name: <tc:data select="Name" />
    Policy Holder: <tc:data select="Contact"><tc:data select="FirstName" /> <tc:data select="Name" /></tc:data>
    Additional Drivers: <tc:search link="Involved"><tc:conditional test="Detail[PLIV_ADDR]"><tc:data select="Contact">
    <tc:data select="FirstName" />
    <tc:data select="Name" />
    </tc:data></tc:conditional></tc:search>
</tc:data>

In this example, the document template is for the Claim object. The template retrieves data from the Involved of the parent of Claim, which is Policy. First, the template navigates to the parent object.

Once the template is pointing at Policy, tc:search is used to identify the Involved records. The tc:conditional tag is then used to retrieve data only from those Involved records with the Additional Driver category (role) added to them.

tc:filter

You can define a filter for the document template so that when the user launches the Document Generator, a filter page opens. The user can then select a record, such as a claimant (an Involved), from a drop-down list. Data from this record can then be retrieved in the content of the document.

In the content section of a document template, tc:filter is used to switch focus from the current object record to the record that will be selected by the user in a filter page. Once this object is selected as the current object, you can retrieve data from it using other tags.

For example, if your document template is for a custom object named Claim, you may use tc:filter to retrieve data from involved, appointment, task, history, child objects, or any other objects that are related to Claim and which have been selected by the user in filter pages.

In the header section, you will need to specify how the filter page will appear in the end-user interface of the Document Generator. You will learn more about this in Defining Filter Pages.

When to Use tc:filter

Use tc:filter in the content section when you want to retrieve data from any of the following records or sub-objects which have been selected by the user in filter pages:

• A related object. The related object can be any of the following:
  • Child custom objects
  • Embedded objects
  • Child accounts (if the main object is an account)
  • Related system objects (for example, a project's involved, appointment, or history records), except document.
• An object that is not directly related to the main object.
  For example, the main object of your template is Policy, whose child object is Claim. You may want the user to select the involved parties of the related Claims.
• A sub-object.
  For example, you may want the user to select an Address, Assignee, or Email Address. You can define filter pages that enable users to select these sub-objects.
• An object that is not related to the main or current object, such as Documents.
  For example, you can use tc:filter to retrieve data from a Contact that the user selects, when that Contact is not related to the main object record.

When NOT to Use tc:filter

You would not use tc:filter in the content section under the following circumstances:

• When you do not want the user to select the related records or sub-objects. If this is the case, use tc:search or tc:loop to automatically identify the records and retrieve the correct data.
• When the relationship from the main object to the desired object is found in a custom field.
  For example, if Party and Claim are custom objects and there is a custom field in Claim of type Custom Object that is used for selecting a Party record, then you would navigate to the Party record using tc:detail.
• When the relationship from the main object to the desired object is directly found in a system field.
  For example, from a Claim record, its parent Policy record is found in the system field Parent. Therefore, tc:data is the tag used to get to the data in the Policy record.\
  You would use tc:filter, however, if you want the user to select an object that is related to the record selected in the system field. For example, if you wanted to use records selected by the user from the Involved records of the Policy mentioned above, this would require the use of tc:filter.
• When you want to retrieve data from a sub-object and you do not want the user to select an instance of the sub-object.
  For example, if you want to navigate to the Contact record of Assignees and automatically list the names of all assignees from their Contact records (instead of having the user select an Assignee), then you would use tc:loop.

Points To Remember

When using tc:filter, you must know the following concepts:

• The tc:filter tag does not actually retrieve data and insert it in the generated document. tc:filter is used for navigating to the correct object in TeamConnect to identify the data you need. In order to retrieve data from that object, you use other Document Generator tags, such as tc:data and tc:detail.
• You can nest other tags within tc:filter as needed in order to navigate to the desired objects.
• You must always define the filter using a tc:filter tag in the header of the document template. In the content section, you use tc:filter again to reference the filter you defined that identifies the record(s) from which you want to retrieve data. You will learn more about this in Defining Filter Pages.
• The filter that you define in the header section of the document template can allow the user to select one or multiple related object records.
• Use tc:filter when you need to retrieve data from a sub-object that is selected by the user. Then, in the header section, use the tc:filter tag to define that filter as a filter page.
• You can refer to the following for samples of document templates using tc:filter:
  • Automatically Retrieving Data from Related Objects.
  • Including Information When Certain Conditions Are Met.

The following table describes the attributes of the tc:filter tag when you are using it in the content section of the document template.

tc:filter Tag Attribute

 Example:

<tc:filter select="InvolvedParty">
    <tc:data select="Contact">
    <tc:data select="FirstName" />
    <tc:data select="Name" />
    </tc:data>
</tc:filter>

In the example given, the data retrieved by TeamConnect will be the first and last name of the Contact, who is an Involved Party of the Claim record. The user will choose which Involved Party's data should be retrieved when invoking the Document Generator. InvolvedParty is the filter chosen. The filter that you select here is defined in the header section of the document template.

You can find more examples using tc:filter in Document Template Samples.

tc:input

The tc:input tag retrieves text that is entered by the user who invokes the Document Generator. The user will enter text within fields that you will create by defining them in the header section of the document template. The information retrieved by the tc:input tag is not data within any TeamConnect records.

When using the tc:input tag in the content section of the document template, you reference a corresponding tc:input tag in the header section of the document template where you define the input page.

You can nest tc:input where needed in the content section. It is not affected by the outer tags where it is nested.

The following table indicates how to use tc:input in the content section to retrieve the selection made by the user in the input page.

Usage of tc:input

Example:

<tc:input select="UserInitials" />

In the example given, UserInitials is the input field chosen. When the document is generated, the text that the user entered in this field in the input page will be inserted in place of this tag.

The input field is defined in the document template's header section. For details about defining input pages, see Defining Pages for User Input. See also the example letter in the Document Generator Template Page Two image for examples of using tc:input.

You must now build the header section and document tags of the template around this source code, as described in Using Document Template Headers and Completing the Document Template.