Datacap Fields at Document Level

In a recent Datacap project, I was facing a challenge where I wasn’t able to implement Document Level fields. It was really a simple task. The customer had a standard form with 10 pages (fixed) where they wanted to manually index some fields at the Document level. Only first two pages in the document had any real data.

Typically, Datacap solutions almost always have page-level fields and page-level end-user indexing. All validation within Verify task is typically performed at the page level. This is all neat and makes sense. But what about common fields that are same across all pages in the document? For example, Document Category, Document Type, Document Date, etc. Ideally, you wouldn’t want those “shared” fields to be re-indexed for every page. You wouldn’t even want those to be displayed when a page is selected in the tree view. It would be very counter-intuitive to have to re-enter those fields for every page or even one page

How do you solve this issue? Interestingly enough, Datacap Studio allows you to define fields at any level, including Document Level. However, when you call the “CreateFelds” built-in action, it will NOT create the fields at any level besides Page or Field.

This means you can “define” the fields at any level but they won’t actually be created in a run time batch and therefore, will not really be useable.

The Datacap CreateFields() Action used to be part of the DCO Actions library but now it is part of the ApplicationObjects actions library starting from version 9.x. The documentation about this custom action used to be vague at best. But now it clearly indicates that the custom action can only create fields at the page level.

So the question still stands. How do you solve this issue? Well, I don’t give up easy. With trial and error, I was able to work around this issue.

The Workaround

You create your very own Datacap Custom Action to use in lieu of Datacap’s built in CreateFields Custom Action. For instance, call it CreateDocumentFields or CreateDCOFields or something similar. I am going to assume here that you have the basic knowledge of how to to write Datacap Custom Actions using C# and .NET. Datacap actually provides a Custom Action template. Stay tuned and I will write another post about that.

1. First thing first, define the custom action signature.

Again, this article is NOT about how to start or create custom action, instead, its about how to write a particular custom action. I have to assume that you already have a Visual Studio solution to add a new Datacap Custom Action to your already existing Custom Actions library.

public bool CreateDocumentFields()
{
}

2. The next step is to add the Definition of the new Custom Action to .RRX file within your Visual Studio solution

<method name="CreateDocumentFields" qi="Create Fields at Document level">
</method>

3. The nextstep is to add the required code to CreateDocumentFields()

        public bool CreateDocumentFields()
        {
            try
            {
                //Check to make sure that the the action is being executed at the Document Level, if not, stop
                if (CurrentDCO.ObjectType() != 1)
                {
                    WriteLog("The Custom Action CreateDocumentFields() can only run at Document Level" );
                    return false;
                }

                //Load Setup DCO
                XmlDocument xDoc = new XmlDocument();
                xDoc.LoadXml(CurrentDCO.SetupObject().XML);

                //Load the Document Level Fields defined within Setup DCO (using Datacap Studio)
                XmlNode xDCONode = null;
                xDCONode = xDoc.SelectSingleNode(@"//S/D[@type='" + CurrentDCO.Type + "']");

                //At this point, the xDCONode should have all the fields definded at the document level
                if (xDCONode != null)
                {
                    //Loop through the fields to only find "Field" objects. 
                    foreach (XmlNode docFieldNode in xDCONode.ChildNodes)
                    {
                        if (docFieldNode.Name.Equals("F"))
                        {
                            string fieldName = docFieldNode.Attributes["type"].Value;
                            
                            //Make sure the field doesn't already exist. 
                            DCO dcoField = CurrentDCO.FindChild(fieldName);

                            //Create the Document Level field since it doesn't alraedy exist. 
                            if (dcoField == null)
                            {
                                dcoField = CurrentDCO.AddChild(3, fieldName, -1);

                                //Every field must have the following required variables. Add the variables with default values. 
                                dcoField.AddVariable("TYPE", fieldName);
                                dcoField.AddVariable("STATUS", "0");
                                dcoField.AddVariable("Position", "0,0,0,0");
                            }

                            // Get the setup definition of the field to obtain the list of additional variables that have been defined 
                            //   in Datacap Studio for the field.
                            XmlNode fieldNode = xDoc.SelectSingleNode(@"//S/F[@type='" + fieldName + "']");

                            if (fieldNode != null)
                            {
                                //Loop through all predeinfed custom variables for the field and add them
                                foreach (XmlNode vNode in fieldNode.ChildNodes)
                                {
                                    if (vNode.Name.Equals("V"))
                                    {
                                        string varName = vNode.Attributes["n"].Value;
                                        if (!varName.Equals("rules"))
                                            dcoField.AddVariable(varName, vNode.InnerText);
                                    }
                                }
                            }
                        }
                    }
                }
            }
            catch (Exception ex)
            {
                WriteLog("CreateDocumentFields error: " + ex);
                return false;
            }

            return true;
        }

The custom action above can be modified to cater to your specific needs. If you would like to add support for creating custom fields at batch level, the custom action can easily be updated to do just that.

4. The final step is to compile your project and deploy it to the rules folder.

The deployment of the custom action simply involves copying the DLL to the DCO\rules directory. Once deployed, the custom action is ready to be used.

Hit me up with any questions and I will be glad to help!