Scenario
Just like the Vehicle Identification Number for your car,
your business process needs to uniquely identify the documents in your system.
Unique IDs enable opening forms via links from a Web server or email message.
To prevent new forms from overwriting existing ones you’ll
want to name them on save or submit. Relying on your users to manually enter a
name that is both meaningful and unique is not a good idea. Just like email
subject lines, some users will have meaningful names and some won’t.
Consistency will not be kept if it isn’t enforced and users may overwrite
existing data without paying attention.
Value Proposition
qRules includes commands to support uniquely naming your
form. You can access these commands via rules when your form is opened or
submitted to automatically create a name. Automating the process of creating a
unique name will also speed up the submit process since users won’t have to
type in a name.
Using rules to automate creating unique names for your forms
is a best practice for the following reasons:
·
Prevents users from overwriting existing data by
mistake
·
Enhances comprehension of form content
o
Consistent names are easier for humans to parse
o
Meaningful names can describe the contents of
the form
·
Eases migration of data since unique names can
travel from server to server
·
Better integration with other systems
o
Links to open forms show more meaningful
information about them
o
Forms can be saved to server or database without
fear of overwrites
This document will show you how you can uniquely identify
your form using two techniques. As a bonus, we also show a related technique of
how to randomize entries of a repeating section using Random Numbers.
Requirements
·
qRules v2.3 or above
Generate a GUID
GUID stands for Globally Unique
ID. Wikipedia defines a GUID as
follows: “A globally unique identifier or GUID (pronounced /ˈɡwɪd/)
is a special type of identifier used in software
applications to provide a unique reference number. The value is represented as
a 32 character hexadecimal character string, such as
{21EC2020-3AEA-1069-A2DD-08002B30309D} and usually stored as a 128 bit
integer.”
Benefits:
·
GUIDs are independent – you can create a GUID
without relying on data from your form
·
GUIDs don’t reveal anything about your form
Limitations:
·
GUIDs don’t carry any meaning – you can’t tell
what’s in your form by looking at the GUID
·
GUIDs are hard for humans to handle – they are
longer than credit card numbers and contain alphabet characters (however,
sometimes you don’t want people to know what’s in a form by looking at it’s
title, hence the benefit above)
You can generate a GUID using qRules GenerateGuid command.
Command Overview
GenerateGuid generates a new GUID
in the format specified by the format argument. The command returns the
generated GUID in the Result field of the QdabraRules data source. Format can
be one of the following:
·
N = 32 digits: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
·
D (default) = 32 digits separated by hyphens:
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
·
If you are using the default, you do not need to
specify a format.
·
B = 32 digits separated by hyphens, enclosed in
brackets: {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}
·
P - 32 digits separated by hyphens, enclosed in
parentheses: (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
For example, you can use this
command to create a GUID without hyphens: GenerateGuid
/format=N
Rich Client Form
Follow these steps to create a
sample form that can be used in the InfoPath client:
1.
Inject qRules in your form (if you haven’t
already). Please refer to the qRules User Guide for more information on this.
2.
Open your form in InfoPath Designer (we’ll use
the InfoPath 2007 out-of-box sample Expense Report)
3.
Add an attribute under root node called ID:

4.
Modify the Submit
button changing the Action to ‘Rules
and Custom Code’ define these rules:
a.
Create
Unique Name only runs if @ID
is blank and has one action
i.
Sets qRules Command to GenerateGuid /format=N

b.
Set ID
only runs if qRules Success is TRUE and has one action
i.
Set @ID
to qRules result

Note: if you have other qRules commands executing in your form, it would be wise to add a second condition to this Rule, such that it only executes if Success is TRUE and if @ID is blank (same condition as above)
c.
Stop Rules
if qRules Fails
i.
Rule is checked to stop processing others if it
fails

d.
Set
Caption always runs
i.
Sets qRules command to concat(“SetCaption
/caption=”, @ID)

e.
Other rules that submit the form
i.
If submitting via email: Use @ID for email subject.

ii.
If submitting to a SharePoint library: Use @ID as the file name.

f.
Close form

5.
Disable Save
and Save As (in Tools > Form
Options > Open and Save) to prevent manually overriding the GUID for
form name.
6.
Publish your form and submit a few sample forms
to test the functionality.
Browser Form in SharePoint
Browser forms require InfoPath
Form Services which ships in SharePoint 2007 (MOSS) or SharePoint 2010
Enterprise. Browser forms cannot be run in preview mode – you have to publish. Same
as Rich Client but don’t use Set Caption rule (since it isn’t supported for
browser forms)
1.
Refer to the qRules v2.3 User guide (located in Start > All Programs > Qdabra >
Tools > qRules), section: “Using
qRules in Infopath Forms Services (IPFS)” for steps on how to:
a.
Browser-enable your form template.
b.
Set your qRules-enabled buttons to ALWAYS send data to the server.
c.
Publish your form as an admin-approved template.
d.
Upload the form template to your InfoPath Forms
Server via SharePoint Central Administration.
e.
Activate the form template to your site
collection.
f.
Create or set your SharePoint library to allow
management of content types.
g.
Add the form template in your SharePoint library
as a content type.
Create a Key using Concat()
Unlike GUIDs, Keys are not generated. Instead, you create
them from parts of your form or from InfoPath macros. InfoPath supports the
XPATH macro language, which includes the Concat function. You can use the Concat
function in a rule when you set a field. Concat() can be used to concatenate
fields from your form’s data sources together. You can also add system
information, such as the username and current date and time to ensure
uniqueness.
Benefits:
·
Keys are easy for humans to understand and refer
to
·
Keys carry information and can describe the
form’s contents
Limitations:
·
Keys are more difficult to create. Keys are
defined by the form designer. If the form designer doesn’t do a good job,
duplicate keys can result. That’s why it’s important to use extra information
like username and date time to prevent duplicates.
·
Keys can be long and contain special characters
which will cause problems when making links. Once again, the form designer must
ensure that the size of the key is kept in check using form validation.
What fields make a good key?
It depends on your form. Keys will
become the name of your form so you want to make sure that you choose a name
which is appropriate for the business process. Here’s a list of common fields
used to create a name with notes.
·
Form Template Name – the name of your XSN
o
Use if you are storing all of your forms in a
location where there may be other forms. Examples: a form library in SharePoint
that supports multiple content types, folder on a file server where all XML
forms are archived.
o
Don’t use if the storage location is specific to
that form template.
·
Description – any field in the form that
describes the form
o
Use if the field isn’t too long and plain text
o
Don’t use if the field is long, contains special
characters, or encodes rich text.
·
Username – logged in user or a field in the form
o
Use if the submitter of the form describes the
form. Example: author of a document.
o
Don’t use if you have multiple authors, lots of
workflow, or people who submit on the behalf of others (unless they have the
ability to type in the username).
·
Time Zone
o
Use if you have forms submitted from different
time zones with the possibility duplicate
o
Don’t use if you are using username and users
are always submitting from one timezone with no submit-on-behalf logic
·
Current Date and Time
o
Use to make the form unique. Use qRules to get
milliseconds if you have large quantity of forms being submitted at same time.
o
Don’t use if you have some other unique identifier
(for example, a GUID) that you are concatenating to the key
Example
In the following example, we will
be concatenating the Form Template Name, Username and the Current Date and
Time. Follow these steps to create a sample form that can be used in the InfoPath
client:
1.
Inject qRules in your form (if you haven’t
already). For more, please refer to the qRules User Guide.
2.
Open your form in InfoPath Designer (we’ll use
the InfoPath 2007 out-of-box sample Expense Report)
3.
Add an attribute under root node called Key:

4.
Modify the Submit
button changing the Action to ‘Rules
and Custom Code’ define these rules:
a.
Get Full
Date and Time only runs if @Key
is blank and has one action:
i.
Sets qRules Command to GetFullDateTime
/format=M-d-yyyy_hh:mm:ss.fff
(This command syntax would result to
something like 11-17-2010_05:30:07.015)

b.
Set Key
only runs if qRules Success is TRUE and has one action
i.
Set @Key
to concat("Expense Report - ",
userName(), " - ", Result)

c.
Stop Rules if qRules Fails
i.
Rule is checked to stop processing others if it
fails
d.
Set Caption always runs
i.
Sets qRules command to concat(“SetCaption
/caption=”, @Key)
e.
Other rules that submit the form
i.
If submitting via email: Use @Key for email subject.
ii.
If submitting to a SharePoint library: Use @Key as the file name.
f.
Close form
5.
Disable Save
and Save As (in Tools > Form
Options > Open and Save) to prevent manually overriding the Key for your
form name.
6.
Publish your form and submit a few sample forms
to test the functionality.
Random Numbers
Random numbers aren’t always unique so they aren’t a good
candidate for uniquely naming your form. However, they can be useful within
your form to randomize the order of questions in a survey, for example.
Benefits:
·
Random numbers can be used to reorder content in
your form
·
Random numbers can be whole numbers from 1 on
up, or decimal numbers
Limitations:
·
Random numbers aren’t always unique
·
Random numbers don’t contain any descriptive
information
You can generate a random number using qRules GenerateRandomNumber command.
Command Overview
GenerateRandomNumber generates a random number allowing setting of
upper and/or lower bounds for the random number.
Arguments:
·
max (optional): Exclusive upper bound
·
min (optional):
Inclusive lower bound, must have a maximum number to use
Examples:
·
GenerateRandomNumber
/max=100 /min=20
·
GenerateRandomNumber
/max=100
Randomizing Repeating Content – General Overview
To randomize repeating content in
your form, the repeating group must include a sort ID in your main or secondary
XML data source. You will need to count the number of items and use qRules’ GenerateRandomNumber command to
randomly pick numbers/items from the list.
Step-by-step Example
For our example, we will create a
form that generates a random question – you can expand this form and turn it
into a quiz form or a questionnaire.
1.
Create a blank InfoPath form and inject it with
qRules.
2.
Open your form in InfoPath Designer.
3.
Add the following fields:

4.
Drag the RandomQuestion
node as a repeating table on your canvas and then add a button labeled ‘Generate’.
5.
Go to the Data
tab > Default Values,
right-click on the RandomQuestion repeating
node and select Add another RandomQuestion
below (add at least 5).

6.
For each node, specify the default values of the
SortID (1-5) and the RandomQuestion (use any default
question desired). Leave the Answer
fields blank.
If
you preview your form, you should see something like this:

7.
Add the following rules to your button:
(These are repeated rules that have the same action executing the GenerateRandomNumber qRules command. We repeat the rule 8 times, which seem like the
max, and this isn’t elegant. It would probably be better to use an XML file
with some fields for the logic – set the SortID field to the generated number,
if the result corresponds to a question that has already been answered, run the
command again, set the field again, and so on…)
a.
Rule #1 – no condition, set the value of the
QdabraRules Command field to GenerateRandomNumber /max=6 /min=1

b.
Rule #s 2-8:
Condition: The expression my:Questions/my:RandomQuestion[my:Answer !=
"" and my:SortID =
xdXDocument:GetDOM("QdabraRules")/QdabraRules/Result]
Action: Set the value of the
QdabraRules Command field to
GenerateRandomNumber /max=6 /min=1

8.
Right-click on the RandomQuestion repeating table, and in the properties dialog,
uncheck the box ‘Allow users to insert and delete rows’.

9.
Add a conditional formatting to the RandomQuestion repeating table to not
show rows which SortID is not equal
to the generated number (QdabraRules Result
field) and Answer is blank:

10.
Add a conditional formatting to the Answer textbox so that blank answers
are shaded:

11.
Preview your form and test – keep clicking on
the Generate button, answer some questions,
etc. You’ll get something like this:

Document IDs
A Document ID (DocID) is a number from 1 on up that records
the number of the document. Document IDs are used in server-based systems such
as SharePoint to number documents. When you save your form to a SharePoint
Library or List, SharePoint will automatically assigns a unique integer to your
document or list item.
Benefits:
·
DocIDs are short and easy to reference
Limitations:
·
DocIDs aren’t unique across servers and will
cause migration problems later
·
DocIDs are hard to insert into your form because
the server assigns them. Some developers will query SharePoint to get the
largest ID and then set the ID in their form, but this is not a good practice
since two documents can be submitted simultaneously. So, to prevent duplicates
you have to submit, query for ID, and submit again. To query for ID requires
something unique in the form which means you’ll probably need a GUID or Key
just to make sure you are querying the correct form that you just saved.
Due to the above limitations, we don’t recommend DocIDs for
your form.