IBM Datacap

Version 9 Release 0

Custom Actions Development Guide



SC27-6373-00
IBM Datacap
Version 9 Release 0

Custom Actions Development Guide



SC27-6373-00
 Note
Before using this information and the product it supports, read the information in “Notices” on page 9.

This edition applies to Version 8 Release 1 of Datacap (product number 5725-C15) and to all subsequent releases
and modifications until otherwise indicated in new editions.
© Copyright IBM Corporation 2014.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
ibm.com and related resources. . . . . v RRX XML file structure for custom actions . . . . 5
How to send your comments . . . . . . . . . v rrx attributes . . . . . . . . . . . . . 6
Contacting IBM . . . . . . . . . . . . . vi com attributes . . . . . . . . . . . . 6
method attributes . . . . . . . . . . . . 6
Create custom actions . . . . . . . . 1 p attributes . . . . . . . . . . . . . . 6
Optional formatting tags . . . . . . . . . 6
Prerequisites . . . . . . . . . . . . . . 1
Sample rrx file . . . . . . . . . . . . . 7
Installing the project components . . . . . . . 1
Create an actions library . . . . . . . . . . 2
Creating a project by using the Datacap Custom Notices . . . . . . . . . . . . . . . 9
Action Library template . . . . . . . . . 2 Trademarks . . . . . . . . . . . . . . 11
Object model within the Datacap runtime Privacy policy considerations . . . . . . . . 11
environment . . . . . . . . . . . . . . 3
Deploying the DLL on other Datacap computers . . 5 Index . . . . . . . . . . . . . . . 13

© Copyright IBM Corp. 2014 iii

iv IBM Datacap: Custom Actions Development Guide
ibm.com and related resources
Product support and documentation are available from ibm.com®.

Support and assistance

Product support is available on the Web. Click Support from the product Web site
at:
Datacap
http://www.ibm.com/support/entry/portal/Software/
Enterprise_Content_Management/Datacap_Taskmaster_Capture

Knowledge Center

You can view the product documentation on ibm.com. See Knowledge Center at
http://www.ibm.com/support/knowledgecenter/SSZRWV_9.0.0/.

PDF publications

You can view the PDF files online using the Adobe Acrobat Reader for your
operating system. If you do not have the Acrobat Reader installed, you can
download it from the Adobe Web site at http://www.adobe.com.

See the following PDF publications Web site:

Product Web site

Datacap http://www.ibm.com/support/
docview.wss?uid=swg27035774

How to send your comments

Your feedback is important in helping to provide the most accurate and highest
quality information.

You can use any of the following methods to provide comments:

v Add comments by using the Comments pane at the bottom of every topic in
Knowledge Center.
v Send your comments by clicking the Feedback link at the bottom of any topic in
Knowledge Center.
v Send your comments by using the online readers' comment form at
http://www.ibm.com/software/data/rcf/.
v Send your comments by e-mail to [email protected]. Include the name of
the product, the version number of the product, and the name and publication
number of the information (if applicable). If you are commenting on specific
text, please include the location of the text (for example, a title, a table number,
or a page number).

© Copyright IBM Corp. 2014 v

 Consumability survey

Tell us how you feel about the value of quality content by taking the Importance of
High Quality Technical Information survey at the following link:
http://www.ibm.com/survey/oid/wsb.dll/s/ag2c1. If you want to help IBM
make this product easier to install and use, take the Consumability Survey at the
following link: http://www.ibm.com/software/data/info/consumability-survey/.

Contacting IBM
To contact IBM customer service in the United States or Canada, call
1-800-IBM-SERV (1-800-426-7378).

To learn about available service options, call one of the following numbers:
v In the United States: 1-888-426-4343
v In Canada: 1-800-465-9600

For more information about how to contact IBM, see the Contact IBM Web site at
http://www.ibm.com/contact/us/.

vi IBM Datacap: Custom Actions Development Guide

Create custom actions
When you cannot do an application function by using standard actions, you can
write custom actions to fulfill your processing needs.

You can create custom actions for your Datacap applications by using Microsoft
Visual Studio 2010. Action libraries are written in C# .NET, implemented as COM
DLLs. The libraries are made available to your Datacap applications through a
datacap.rrx file that describes the public interface of the library. You add the
actions that you create to your Datacap installation to make them available for use
in your Datacap applications. The custom actions are provided in Datacap Studio.
You can add these actions to rulesets in the same manner as standard actions.

The following users can create custom actions for their Datacap applications:
v Datacap application support staff that does custom implementations
v Reseller application support staff that does custom implementations
v Customer IT staff responsible for Datacap implementations

To create custom actions, you must be experienced with the following disciplines:
v Datacap Studio
v Datacap document hierarchies (DCO)
v Microsoft Visual Studio
v C# programming
v XML

Prerequisites
You must ensure that the required software is installed and running on your
Datacap system before you can create custom actions.

To develop custom actions in the Microsoft Visual Studio development

environment, the following software must be installed and running on your
system:
v Datacap (complete installation). The instructions for developing custom actions
assume that you installed Datacap to the C:\Datacap folder.
v Microsoft Visual Studio 2010

You must all meet the following requirements:

v Verify that meet the Datacap prerequisites described in Installation and
configuration prerequisites.
v Successfully process a batch from start to finish in any Datacap application to
make troubleshooting easier and clarify the sources of potential problems.

Installing the project components

Datacap provides two Microsoft Visual Studio action templates to help you create
custom actions.

The TM 9.0 NET 2.0 Action Library Template.zip and TM 9.0 NET 4.0 Action
Library Template.zip templates allow you to create new custom action DLLs that

© Copyright IBM Corp. 2014 1

 use either .NET 2.0 or .NET 4.0. You can install both of these templates to be able
to pick the desired template in Microsoft Visual Studio at project creation time.

You can download these templates from the Datacap Development Kit page on
IBM® developerWorks® at http://www.ibm.com/developerworks/industry/
library/ind-datacap-taskmaster/.

To install the project components:

1. Copy the TM 9.0 NET 4.0 Action Library Template.zip and TM 9.0 NET 2.0
Action Library Template.zip files into your Visual Studio\Templates folder.
2. In this example, you use the folder C:\Users\<userid>\My Documents\Visual
Studio 2010\Templates\ProjectTemplates\Visual C#.

Create an actions library

You can use the Datacap Custom Action Library template to create a new actions
library.

You use the Datacap Custom Action Library template to create a new project for
your actions. The template creates the action framework which you can expand to
add more custom actions. The framework also contains a sample action with code
that illustrates how to access DCO objects, update the DCO, write to the log, and
so on.

Ensure that you installed the action template by copying TM 9.0 NET 4.0 Action
Library Template.zip, TM 9.0 NET 2.0 Action Library Template.zip, etc. to
C:\Users\<userid>\My Documents\Visual Studio 2010\Templates\
ProjectTemplates\Visual C#. For instructions, see “Installing the project
components” on page 1.

For instructions on deploying your custom actions, see “Deploying the DLL on
other Datacap computers” on page 5.

Creating a project by using the Datacap Custom Action

Library template
Use Microsoft Visual Studio to create a project that is based on the Datacap
Custom Action Library .NET 4 template.

If you need a library that is compatible with .NET 2, use the .NET 2 template
instead of .NET 4.

To start a new project by using the project template:

1. Start Visual Studio by right-clicking the icon and selecting Run as
administrator.
2. Click File > New > Project and select Visual C#.
3. Select .NET Framework 4. Then, select the Datacap Custom Action
Library.NET 4 template.
4. Enter the project action library name and working folder and click OK.
5. Open Actions.cs and expand the Sample Actions region. Implement your
actions in this Actions class.
a. Delete or modify the examples and properties that are provided.
b. Use Write.log to write to the *rrs.log file in the batch folder for
troubleshooting or auditing.

2 IBM Datacap: Custom Actions Development Guide

 6. Open the Resource file that ends with .rrx and update the method and
property declarations to match your Action class members.
7. Open the Resource file help.xml and update the actions help text. The .RRX
help text is displayed when thehelp.xml text is not available for any action.
8. Make sure Solution Configuration is set to Debug and then build the
solution.
9. If any of the Resources cannot be found, right-click on project and select
Properties. Then, add c:\Datacap\dcshared\NET to the Reference Paths tab.
10. Copy the updated DLL file to \Datacap\RRS. Do not register the DLL.

Object model within the Datacap runtime environment

Rulerunner (RRS) sets up certain objects before you run a ruleset. These objects
become available to your actions.

The following diagram shows the Datacap objects that are populated by
Rulerunner and accessible from any actions in the COM DLL.

Your COM DLL must declare an interface for each of the five objects that are
shown and must implement a set property for each. The code to declare an
interface is included in the Datacap Custom Action Library template in the source
file RRSExpected.cs.

Create custom actions 3

 RRS

TDCOLib.IDCO TDCOLib.IDCO DcrroLib.IRRState

ID 20100027.001 ID 20100027.001 Props <B id= ... /B>
<P n= ... ...(/P>
Type MyApp Type MyApp Etc.
XML <B id= ... /B> XML <B id= ... /B> Victim B
<V n= T ype ... <V n= T ype ...
etc. etc. XML <Stack>
<ruleset id= ... >
etc. etc. etc.
Runtime DCO etc.
Rulerunner State object

DclogXLib.IDCLog PILOTCTRLLib.IBPilotCtrl
Enabled True BatchDir C:\Datacap\...
Filename C:\Datacap\... Filename C:\Datacap\...
Write() Write() Vscan
etc. etc.
Log object Pilot Properties object

1 2 3 4 5

DCO RRLog CurrentDCO BatchPilot RRState

COM DLL

1 Rulerunner populates the initial runtime DCO. Actions are responsible for
updating the DCO XML as necessary. In vScanSample, the myact_scan()
action adds page information to the runtime DCO for each image in the
application images folder. When the ruleset completes, Rulerunner writes
the DCO object to the batches folder in the profile.xml file.
Runtime DCO XML before Scan():
<?xml-stylesheet type="text/xsl" href="..\..\dco.xsl"?>
<B id="20100029.004">
<V n="TYPE">MyApp</V>
<V n="victim">yes</V>
</B>
Runtime DCO XML after Scan():
<?xml-stylesheet type="text/xsl" href="..\..\dco.xsl"?>
<B id="20100029.004">
<V n="TYPE">MyApp</V>
<V n="victim">yes</V>
<P id="P1"
<V n="TYPE">Other</V>
<V n="IMAGEFILE">tm000001.tif</V>
</P>
</B>
2 Rulerunner writes information to the profilerrs.log file in the batches

4 IBM Datacap: Custom Actions Development Guide

 folder throughout ruleset execution. When control passes to the COM DLL,
the action can write to the log file by calling RRLog.Write().
3 When Rulerunner moves to the next object in the DCO, it calls the
DatacapRRCurrentDCO property of the action library. In the sample
actions, this object populates CurrentDCO.
4 The pilot properties object is used primarily by a client application that
initiates the rule execution to pass execution parameters such as batch
directory, input DCO file to Rulerunner. Actions in the COM DLL can also
access the pilot properties object if necessary.
5 The Rulerunner State object is used primarily by the client application and
Rulerunner. For example, the client initializes the State object with certain
execution parameters before it calls Rulerunner. Rulerunner uses the State
object to build the execution stack. The object is also available to actions in
the COM DLL. For example, actions can pass error information back to
Rulerunner and the client application that uses the State.Error subobject.

The .NET action template provides access to the dcSmart object. One of the
methods available in this class is MetaWord. MetaWord takes a string as a
parameter and returns a string. MetaWord allows your custom actions to accept
smart parameters. Passing a parameter string to MetaWord resolves any smart
parameters in your input string. It also returns the result that can be processed by
your C# code. If the input parameter does not contain any smart parameters, it
returns the original input string.

Important: Custom actions cannot decrypt built-in Datacap secure values from the
.app file, like database connection strings, passwords, or Advanced Values. For
example, MetaWord, when called on @APPVAR(*/lookupdb:cs) returns the secured
string [secured]011da7544c0b852139730dd582683b8c82a80466dfcd817[/secured].
Custom actions cannot decrypt the secured string.

Deploying the DLL on other Datacap computers

You can copy and register the sample DLL on other Datacap computers to deploy
your custom actions on those computers.

To deploy the DLL on other Datacap computers:

1. Copy the DLL to the C:\Datacap\RRS folder on the target computer. You do not
have to place the RRX in the RRS directory because the RRX is embedded in
the DLL.
2. Do not register the DLL.

RRX XML file structure for custom actions

The syntax for constructing the RRX file makes the actions in the COM DLL
available to Datacap applications.
<?xml version=’1.0’ ?>
<rrx namespace="namespace" [v="version"]>
<com ref="namespace.classname" [qi="COM_object_description"]>
<method name="method_name" [qi="method_description"]>
[<lvl>level_help_text</lvl>]
[<ret>returns_help_text</ret>]
[<h>details_help_text
[<e>example_text</e>]
</h>]
[<p name="param_name" type="param_type" [qi="param_description"]/>

Create custom actions 5

 [<ap>params_help_text*</ap>]]
.
</method>
.
.
</com>
</rrx>

The <ap> tag is not typically used because you can insert the help text into the
parameter definition by using the qi attribute. However, <ap> tags are still needed
if there are no parameters so you can explicitly state that there are no parameters.
For an example, see the convert.rrx file, in c:\datacap\rrs.

rrx attributes
The rrx attributes in the RRX XML file structure for COM actions are namespace
and version.
namespace
The namespace that is displayed in the Datacap Studio Actions Library pane
(required)
v Version number (optional)

com attributes
The com attributes in the RRX XML file structure for COM actions are ref and qi.
ref
<namespace>.<class_name> as specified in the actions library (required)
qi Description that is displayed in the Datacap Studio Action Library information
window (optional)

method attributes
The method attributes in the RRX XML file structure for COM actions are name and
qi.
name
Method (action) name (required)
qi Description that is displayed in the Datacap Studio Action Library information
window (optional)

p attributes
The p attributes in the RRX XML file structure for COM actions are name, type, and
qi.
name
Parameter name (required)
type
Parameter type (required)

Optional formatting tags

You can use the optional formatting tags in the RRX XML file structure for COM
actions to change selected text to bold face type.

You can use the following formatting tags in any of the field in the help text:
<b></b>

6 IBM Datacap: Custom Actions Development Guide

 Changes the text between the start/end tags to bold. This tag adds a space after
the bold text. For example,
Hello <b>Fred</b>.

is output as
Hello Fred .

Sample rrx file

The sample rrx file defines a namespace in the Datacap Studio Actions Library.
This file also specifies the folder in which to search for images to scan, and runs
the scan task.

The following sample defines the myactions namespace that includes the methods;
myact_set_folder and myact_scan.
v myact_set_folder Contains the parameter folderpath of type string.
v myact_scan Contains no parameters but includes more help text options.
<?xml version=’1.0’ ?>
<rrx namespace="myactions" v="7.5.1">
<com ref="MyAction.CDCMyAction" qi="Sample actions">
<method name="myact_set_folder" qi="Specifies the folder to search">
<p name="folderpath" type="string" qi="path to folder"/>
</method>
<method name="myact_scan" qi="Poll the specified folder for image files">
<lvl>Batch level Open event only.</lvl>
<ret>False if failed; otherwise True.</ret>
<h>Details go here<br/>
<e>Example script goes here<br/></e>
</h>
</method>
</com>
</rrx>

The resulting Datacap Studio help text for each action is:

Method myact_set_folder Method myact_scan

Specifies the folder to search Poll the specified folder for image files.
Syntax Syntax

bool myact_set_folder (string folderpath) bool myact_scan ()

Parameters Details

string folderpath - path to folder Details go here

Example

Example Script goes here

Level

Batch level Open event only

Returns

False if failed; otherwise True.

Requirement: All action methods must return a Boolean so the bool return value
is not specified in the RRX but is displayed by default.

Create custom actions 7

8 IBM Datacap: Custom Actions Development Guide
Notices
This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not grant you
any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing

Legal and Intellectual Property Law
IBM Japan Ltd.
1623-14, Shimotsuruma, Yamato-shi
Kanagawa 242-8502 Japan

The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply
to you.

This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.

© Copyright IBM Corp. 2014 9

 IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:

IBM Corporation
J46A/G4
555 Bailey Avenue
San Jose, CA 95141-1003
U.S.A.

Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.

The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.

This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.

Any performance data contained herein was determined in a controlled

environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of

those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.

All statements regarding IBM's future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which

illustrate programming techniques on various operating platforms. You may copy,

10 IBM Datacap: Custom Actions Development Guide

 modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs.

Trademarks
The following terms are trademarks of the International Business Machines
Corporation in the United States, other countries, or both: http://www.ibm.com/
legal/copytrade.shtml

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Oracle and/or its affiliates.

Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered
trademarks or trademarks of Adobe Systems Incorporated in the United States,
and/or other countries.

Linux is a registered trademark of Linus Torvalds in the United States, other

countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other
countries.

Other product and service names might be trademarks of IBM or other companies.

Privacy policy considerations

IBM Software products, including software as a service solutions, (“Software
Offerings”) may use cookies or other technologies to collect product usage
information, to help improve the end user experience, to tailor interactions with
the end user or for other purposes. In many cases no personally identifiable
information is collected by the Software Offerings. Some of our Software Offerings
can help enable you to collect personally identifiable information. If this Software
Offering uses cookies to collect personally identifiable information, specific
information about this offering’s use of cookies is set forth below.

The Software Offering uses session and persistent cookies that collect each user's
user name, for purposes of session management, enhanced user usability, single
sign-on configuration. Session cookies cannot be disabled. Persistent cookies can be
disabled, but disabling them will also eliminate the functionality they enable.

If the configurations deployed for this Software Offering provide you as customer
the ability to collect personally identifiable information from end users via cookies
and other technologies, you should seek your own legal advice about any laws
applicable to such data collection, including any requirements for notice and
consent.

For more information about the use of various technologies, including cookies, for
these purposes, See IBM’s Privacy Policy at http://www.ibm.com/privacy and
IBM’s Online Privacy Statement at http://www.ibm.com/privacy/details the

Notices 11
 section entitled “Cookies, Web Beacons and Other Technologies” and the “IBM
Software Products and Software-as-a-Service Privacy Statement” at
http://www.ibm.com/software/info/product-privacy.

12 IBM Datacap: Custom Actions Development Guide

Index
A custom actions (continued)
running validation actions
S
action libraries deploying DLL on other ScanValidations.sln
creating for custom actions 2 computers 5 running validation actions
RRX XML file structure for COM starting projects 2 deploying DLL on other
actions computers 5
com attributes 6
method attributes 6
optional formatting tags 6 D V
p attributes 6, 7 Datacap applications
creating custom actions for 1 validation actions
rrx attributes 6
Datacap object model running for custom actions
RRX XML file structure for custom
using with custom actions 3 deploying DLL on other
actions
computers 5
syntax 5
actions
creating custom actions 1 M
actions projects method attributes
creating for custom actions 2 description 6
starting for custom actions 2 RRX XML file structure for COM
applications actions 6
creating custom actions for 1

C O
optional formatting tags
com attributes description 6
description 6 RRX XML file structure for COM
RRX XML file structure for COM actions 6
actions 6
custom action libraries
creating 2
RRX XML file structure for COM P
actions p attributes
com attributes 6 description 6, 7
method attributes 6 RRX XML file structure for COM
optional formatting tags 6 actions 6, 7
p attributes 6, 7 prerequisites
rrx attributes 6 custom actions 1
RRX XML file structure for custom installing for custom actions 1
actions project components
syntax 5 installing for custom actions 1
custom actions projects
actions libraries 2 creating 2
creating 1 starting 2
creating actions libraries 2
creating projects 2
Datacap object model 3 R
installing prerequisites 1 rrx attributes
installing project components 1 description 6
prerequisites 1 RRX XML file structure for COM
project components 1 actions 6
RRX XML file structure for COM RRX XML file structure for COM actions
actions com attributes 6
com attributes 6 method attributes 6
method attributes 6 optional formatting tags 6
optional formatting tags 6 p attributes 6, 7
p attributes 6, 7 rrx attributes 6
rrx attributes 6
RRX XML file structure for custom
actions
syntax 5

© Copyright IBM Corp. 2014 13

14 IBM Datacap: Custom Actions Development Guide



Product Number: 5725-C15

SC27-6373-00