Dataform Tutorial - Data Management From A - Z

The Customer Type lookup should use a lookup group of CustomerType_xxx and contain the following lookup values:

 Table 2 

Lookups consist of a Lookup Group, and Lookup values themselves, which contain at a minimum a Code and Decode value.  Note that the code and decode values do not have to match, you may want to do something similar in the case of a long decode value.  To add or configure a lookup, perform the following steps.

1. Go to System Administration  | Lookup Admin.

2. From here you can add a new Lookup Group, or Add / Edit the Lookup values of an existing Group.

3. To add a new Lookup Group, Click on Manage Groups and then Click Add.

4. Complete the Group Name field and add a description if you have many similar groups, to avoid confusion when using Lookups.
5. Click Save.  To go back to the Lookup Admin Screen and start adding Lookup values to the group, click the Back button.
6. To add lookup values to a group, Click the Add button, select the Group you would like to add codes to and complete the Code and Decode fields on the Lookup detail record.   If this is a pre-existing group, it is a good idea to first Search for the Group in question, and review the existing Lookup Values (Code and Decode) to make sure you don't create duplicates.  Remember to check the 'Include Inactive' checkbox when searching, as inactive values are hidden from the list by default.
7. The Code value of a Lookup is the actual data value that is stored in the database when a record is saved. 
8. It is a best practice to remove any extraneous spaces and special characters from the Code value when creating a new lookup record and to use PascalCase formatting - that is the first letter of each individual word is capitalized.  This is different from CamelCase formatting as seen in the Field Name on the screenshot below, as CamelCase may begin with lowercase lettering.
9. The Decode value of a Lookup is what is displayed on the dataform page when you view ClientSpace in your browser,  Code and Decode are often the same, but aren't required to be.
   
   For more information on adding and configuring lookups, see Adding Or Configuring Lookups.

Add the CustomerInfo_xxx dataform by going to System Administration  | Dataform Admin | Add Dataform and setting the following options in the Add Dataform dialog:

Table 3 

Press 'Save' when you are done.  The system saves your changes and creates a new SQL Table using the values you provided.  This table is a shell for the fields you will place on the dataform where the information will actually be stored.  At this time the system will also add a set of standard fields to the table, such as CreateDate, CreatedByUserID, DateUpdated, UpdatedByUserID, the PrimaryKey of the table (in this case pkCustomerInfo_xxxID) and so on...    

Lets add the fields described in Table 1 as they are presented from the top down.  First create a CustomerData fieldset.  This will add bounding box to the page, making the data more organized.  Next add the fields inside the Customer data fieldset as described in  Table 1 being careful to follow datatype field naming conventions:

 **  Make sure you configure the Related Data for the zipcode datatype as outlined in the following document: Configuring the ZipCode Datatype.

 Now that you have a Customer Data dataform, let's give it a home.  Templates are used by the system to create custom Table of Contents and collections of dataforms that can be used when Workspaces are generated.  In our example, a workspace will equal a client account, so we will have one Customer Data Form with many associated other dataforms.  We will start by first creating a template Workspace. 

Go to System Administration  | Template Maintenance | Add Template.   A Create Template dialog will prompt for a Name and Group.

Name the Template Customers_xxx and select the Clients group, then click 'Save'

The system will open a blank workspace, presenting you with some TOC icons as seen below

Lets start configuring our template - start by clicking the wrench to open the Workspace Maintenance control panel and click on Workspace Settings

You can see in this dialog that the Template name is Customers_xxx and that it belongs to the Clients group.  Access level should be 'Private' and 'Use as a Template' should be checked.

Let's start by making our TOC more attractive.  Click on the Left Nav tab and change the 'Icons Color' setting from black to 3D. 

While we are here, let's also change the background color of the TOC to something more appealing. Click on the color picker for 'Background' and choose a color that you like - keep in mind that we will need to be able to see the TOC document links, so don't make your TOC too dark.

Click 'Save' to see your results.  You will be prompted with a message, just click 'Ok'.

Nothing happened, right?  That's because the TOC settings of a workspace are loaded when you open the workspace. 

To see you changes take effect, click the wrench at the top of the TOC again, this time select 'Table of Contents Maintenance', it has an icon like this

You will be presented with a blank TOC (no dataforms yet), but at the bottom of the Table of Contents window you will see a refresh button  click this to see your TOC changes take effect.

Now let's add the Customer Info dataform to the TOC.  Click the 'Back' button at the bottom of the TOC Maintenance, then click 'Data Management' to add your dataform - the icon looks like this .

Click the 'Add' button, then in the Dataform Search dialog, choose the Customer Info_xxx dataform by double clicking it in the list.

You have added the dataform to the workspace, but it will not appear on the TOC until you click the 'Add to TOC' button, then refresh the TOC again.

As this is going to be our landing page for the Template, we need to also set this dataform as the Workspace Creation Dataform under Workspace Settings.

Go to Workspace Maintenance  | Workspace Settings and select Customer Info_xxx in the Workspace Creation Dataform dropdown.

Click 'Save'

 Multiforms are built the same way you built the Customer Info form, but with a few crucial differences.  Creating a multiform requires your to check the 'Can have multiple' checkbox on form creation, and also requires you configure display columns for the multiform list that will be presented when using the dataform.  As you just created a dataform, you are now somewhat of an expert, so we won't review the entire process here, we'll just give you the specs and let you figure it out.  Let's begin with the Lookup Specs - this dataform is a little more complicated and so has 3 different lookups that will need to be configured:

 And now for the Dataform Specs:

 And finally the dataform fields

Don't forget to configure the display columns for the multiform list, you need at least one column configured, which columns should be displayed are at your discretion  - if you have questions about this or any other step in the process, refer to Dataforms - Workspace Building Blocks for more information.

Repeat Exercise Four in Module one and add your Order Form_xxx dataform to the Template TOC.  It should appear just below the Customer Info_xxx page in the Left Navigation bar.

Review

Now it's time to check your work.  Go to the Report List in ClientSpace and run the Dataform Specification report for your newly created Work Order form.  Compare your work to the following Dataform Exercise Validation.

How did you do?  Are your fields all in the right places, did you remember to follow field naming conventions?  If any of the fields don't match, delete and recreate them to match the spec before proceeding to the next Assignment: Advanced Dataform Configuration. 

In this exercise we are going to simulate what happens when you have to modify your data model to better handle the real information needs of the project.  In this situation, we caught the design flaw before the dataform was being used, so there is no actual stored information that would need to be moved.  We will need to move the Parts fieldset and the associated fields into a separate Parts Order_xxx dataform which will then become a child form of the Work Order form, creating a foreign key relationship between the two forms.  In the context of relational databases, a foreign key is a field (or collection of fields) in one table that uniquely identifies a row of another table  In other words, a foreign key is a column or a combination of columns that is used to establish and enforce a link between two tables. The table containing the foreign key is called the child table, and the table containing the primary key is called the parent table. 

Before beginning you should read the KnowledgeSpace article Configuring Parent Form Datatypes to brush up on how to create these related dataforms.  In this scenario the Work Order would be the parent form and the Order Parts form would be the child form.  You can use the Dataform validation at the end of the previous Exercise as your guideline when moving the parts fieldset to a different form. 

• Add a new multiform called Parts Order_xxx, making sure that 'Search on Load', 'Show Tasks' and 'Allow Cloning' are checked.

• Add all of the associated fields including the Parts Info Fieldset from the Work Orders form utilizing the same specification that we used before. 
• Column and Row placement may need to be adjusted and don't forget to specify the display columns for the multiform list..
• Finally you will add a Parent Form field called Order ID for the Order Form_xxx dataform to the Parts Order_xxx form, creating the foreign key relationship between the underlying dataform tables.  
  • Remember to use appropriate  field naming conventions as this is a foreign key field.  This information is thoroughly covered in Configuring Parent Form Datatypes under Field Name.++ 
• Once all the fields have been added, be sure to delete the parts related fields from the Work Order form. 

Generate a Workspace from the Template

In the next exercises we will be performing more advanced dataform configuration, including setting up business logic and rules for your dataforms.  While business logic can be configured on a template workspace, it will not fire from the template workspaces, so we need to create a client workspace from the template.  Start by going to Organizations and clicking 'Add'.  You will be presented with a dialog that allows you to fill out company information and 'Save' the new Organization record.

Once your organization is saved, click the 'Workspaces' tab and select 'Create Workspace'.  If there are multiple template workspaces available to you then you should be presented with a dialog box that asks you to choose the Template and Workspace Name.  Choose the  Customers_xxx template you created above, fill out the  and click 'Save'.  This should generate a Client workspace, presenting you the CustomerInfo_xxx dataform to fill out.  Complete this dataform and then click 'Save' and you will see the familiar TOC and dataform list you created on your template.  From this point in the tutorial on, the changes you make should me made from the Dataform Quick Admin  of Dataforms on this Client Workspace so you can check your work.

Review 

Now it's time to check your work.  Go to the Report List in ClientSpace and run the Dataform Specification report for your newly created Parts Order_xxx form.  Compare your work to the following Dataform Exercise Validation.

Before you begin it is a good idea to review the KnowledgeSpace document Configuring Custom Header Links which covers all of the options available when configuring custom links.  For purposes of this exercise we will be covering how to configure a custom Dataform link.  We will be creating a link to the parts order dataform from the header of the Order Form_xxx dataform.  While configuring the link we will set a trigger to insure the Parts Order_xxx form is only available if the Order Form_xxx 'Requires Parts' field is set to 'Yes'.    We will then remove the Child Form Link from the upper left to complete the exercise.

Start by going to Admin Settings | Dataform Admin | Custom Links and Clicking 'Add'.

You will be presented with an interface like this:

For now let's just concern ourselves with the fields we will be using for this exercise.  For a more detailed discussion of the Link Configuration dialog, read Configuring Custom Header Links. 

• Table Name - Order Form_xxx (this is the name of the dataform you will be linking to)
• Link Group - Link 1 (where in the header will the link display?)
• Display Value - Parts Order (This is what will actually display in the header of the Order Form)
• Display Action - Workspace dataform (what do you want to link to?)
• Sort Order - 10 (when there are multiple links, where does this link fall?)
• Target Dataform - Parts Order_xxx
• Display when adding - checked (this controls whether the link is available prior to the Order form record being saved.  We may want to uncheck this later, but we will check this so we can test the link configuration on the template without having to save an Order Form)

Make sure that the Configured link is working as expected by going to the Template workspace, and click 'Add' under Order Form - because the 'Display this link when adding' box is checked, you should see the link displayed in the header.  If not, check your work and correct any issues, then when this is working uncheck the 'Display this link when Adding' checkbox before proceeding to the next step. 

Now lets configure the condition under which the link will display.

Link Display conditions: 

• Field Source - Form Data (this means the trigger condition is on the form we are configuring the link for)
• Trigger Field - luRequiresParts (the trigger field we want to use)
• Trigger Value - Yes (only display the link when the field is set to this)
• Label - Parts (this is not really necessary to fill out as we will not have complex display conditions, but it is a best practice to fill this out every time)

In order to make sure this functionality is working, you will need to be able to save a work order form.  Go to the NetWise Test workspace and, following the instructions for adding TOC items above, add the Customer Info and Order Form dataforms to the workspace. 

Make sure that the Configured link is working as expected by going to the Order Form dataform and click 'Add',  set the 'Requires Parts' field to 'Yes' and click Apply, does the Parts Order link display?  Change Requires Parts to 'No', does the link disappear?

Now that this is working successfully, let's get rid of the Child Form Link on the Order Form,  from the order form click QuickAdmin   and choose 'Form Properties'.

Under Form Properties, check the 'Suppress Child Form Dropdown' checkbox and click 'Save'.

When you return back to the Order Form, the dataform link in the upper left corner should disappear.

Review 

Now it's time to check your work.  Compare your link configuration work to the following Dataform Exercise Validation. 

The Labor Info fieldset of our Order Form_xxx is looking pretty crowded and unorganized.  Having the Type of Work, Labor Billing and Text area fields on the form makes sense, but having all of the different amount fields on the form (Per Hour, Fee Amount, Piece Count and Amount Per Piece) does not make sense.  If this is an hourly type of job, why would you want to see the piece count?  Thankfully we can clean this up using configurable field display.    Before you begin it is a good idea to review the KnowledgeSpace document Configuring Dynamic Field Display which covers all of the options available when configuring dynamic field display.  For purposes of this exercise we will be covering how to configure dynamic display on a field.  We will walk through configuring one of the fields on the form, then you will be left to configure the rest of the amount fields based on what you have learned.  Let's start by creating dynamic field display behavior for the Per Hour field.

From the Order Form_xxx, access the Quick Admin  tool and select Field Display Rules. 

Click 'Add' and you will be presented with a dialog like this:

What we want to do is display the Per Hour field if the Labor Billing field equals 'Hourly' (the Code value of the lookup), otherwise we want to hide it and we should probably clear it as well so there is no confusion if a billing type change occurs:

Table Name - Order Form_xxx

Field Source - This table (we are going to look at the current form to find a trigger event)

Pipeline - Default (custom should only be used if custom business logic has been written by the NetWise development staff)

When this field - Labor Billing

*equals this value - Hourly

*this field - PerHour

*will - Display

Make sure the 'Clear Field On Disable/Hide is checked.  These field display configurations are actually very easy to understand.  Check your work on the NetWise Test workspace before proceeding with the other field display configurations. 

Configure the Fee Amount, Piece Count and Amount Per Piece fields to only display if the appropriate Billing Type Code value is selected. 

Review 

Now it's time to check your work.  Compare your field display configuration work to the following Dataform Exercise Validation. 

How did you do?  Did you remember to use the Code value when referencing your lookup?  I modified the field layout slightly as you can see in the example to make the dataform flow better with all of the hidden fields, but this is more for esthetics than anything else.    Now that we can turn fields on and off, let's make sure that the appropriate fields are being used to store your data in the next module on Rules Management. 

Our next exercise will teach you how to configure a set of simple business rules on the Order Form to insure that once we have chosen a Labor Billing Type, that the associated amount field is always being filled out.  Before you begin it is a good idea to review the KnowledgeSpace document Configuring Rules and Business Logic  which covers all of the options available when configuring business rules.  For purposes of this exercise we will be covering how to configure the _RequireFieldOnThisForm rule on the Per Hour field.  This is a Hard Error rule meaning that on save the Per Hour field will be checked and if it has not been completed, an error will be triggered stopping the save until the field is complete.  Once again we will walk through configuring one of the business rules on the form, then you will be left to configure the rest of the amount field rules based on what you have learned.  Let's start by setting required field behavior for the Per Hour field.

From the Order Form_xxx, access the Quick Admin  tool and select Business Rules. 

Click 'Add' and you will be presented with a dialog like this:

Complete the following values:

• Table Name - gen_OrderForm_xxx
• Method Name - _RequireFieldOnThisForm
• Rule Title - Require Per Hour (this is simply what displays in the rules list, so it should be short and descriptive)
• Rule Type - HardError (this will be selected for you based on what Method you choose)
• Execution Order - 10 (read the documentation on this, but this is essentially what order your rules fire in - this can dramatically effect behavior on complex business rules)
• Pipeline - Default (custom should only be used if custom business logic has been written by the NetWise development staff)
• Trigger Field - luLaborBilling
• Trigger Value - Hourly (Code value)
• Description - Description of the rule
• sFieldName - PerHour (this is the field you want to require, based on the trigger.)

Click 'Save' to complete the rule.  Check your work on the NetWise Test workspace before proceeding with the other rules  configurations.  Configure the Fee Amount, Piece Count and Amount Per Piece fields to be required if the appropriate Billing Type code value is selected. 

Now that you have the form validating, lets set up some automation to make customer orders easier to track.

Our final exercise will teach you how to configure an Order ID field and setup a simple business rule on the Order Form to set the OrderID equal to the primary key of the dataform.  This will provide a tangible Order number that can be used as a reference on our Parts Order form. This is a Biz Logic rule meaning that on save the OrderID field will automatically be filled.  By now you have acquired all of the requisite skills to perform these tasks, so the requirements documentation for this last exercise will be minimal.

From the Order Form_xxx, access the Quick Admin  tool and select Form Fields.

Add a field called Order ID to the top of the dataform using the following settings:

• Element Type - Text
• Read Only- Checked

Click 'Save' to add this field to the dataform.  Once added, use Form Properties for the Order Form Dataform to set the Order ID as the default Attribute of the form.

Now lets create our business rule to automatically fill this field for us on Save:

From the Order Form_xxx, access the Quick Admin  tool and select Business Rules.

Create a new business rule using the following parameters:

• Table Name - Order Form
• Method Name - _SetFieldFromKey
• Execution Order - 10
• TargetField - OrderID

Once you have this configured, check your work by making a change to the Order Form and clicking 'Save' - do you see the appropriate Order ID in the field?  Now go to the parts order form - what appears in the Order ID field?

Review 

Now it's time to check your work.  Compare your field rules configuration work to the following Dataform Exercise Validation.

How did you do?  Did you remember to use the Code value when referencing your lookup?  How did you order the rules?