Question:
What is DocuWare Control and how can it be utilized?
Solutions:
DocuWare Control allows you to handle the processing of your documents using special commands. Please refer to the guide to configure DocuWare Control;
DocuWare Control with DocuWare Printer
Each DocuWare Control statement has to start with <dwControl:.
- Ensure that all commands are written with the font "DWControl.ttf" in order to be recognized as a valid command.
The DWControl.ttf font will be installed with DocuWare Printer. Alternatively It can be found in "...\DocuWare\Desktop\Printer\DWControl.ttf". - It doesn't matter which color or size the commands are, you may use e.g. white commands on a white background.
- All commands will be removed from the document after they have been processed.
If you use DWControl together with DocuWare Import you need to specify them without dwControl:
- DWControl command for DW Printer:
<dwControl:Field dbName="EMPLOYEE" type="Text" value="Mark Smith"/> - DWControl command for DW Import:
<Field dbName="EMPLOYEE" type="Text" value="Mark Smith"/> - All commands need to be specified in a .dwcontrol file, there in a <Page> section
- Pay attention to the use of upper case and lower case.
- Each .dwcontrol file needs to start with the following line
<ControlStatements xmlns="http://dev.docuware.com/Jobs/Control" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> - See KBA-36502 for further information and examples.
For the full list of DocuWare Control Commands, see Knowledge Center-DocuWare Control. Please refer to the following information for additional examples and key information worth noting:
SelectConfiguration
If you are familiar with DocuWare Printer Configurations, you can easily select one configuration by name. The document will be processed as if the configuration would have been automatically recognized.
<dwControl:SelectConfiguration name="Letter"/>
Note: The SelectConfiguration command cannot be used in combination with other commands. If other commands are found in the document, they will be ignored.
NewDocument
If this command is found on a page of the document, it will become the first page of a new document.
<dwControl:NewDocument />
FileCabinet
In this example, the document shall be stored into a file cabinet called "Invoices & Orders".
<dwControl:FileCabinet name="Invoices & Orders"/>
You can use also the file cabinet GUID instead.
<dwControl:FileCabinet id="12345678-1234-1234-1234-123456789abc"/>
Basket or DocumentTray
To store the document into a basket use the Basket or DocumentTray command.
<dwControl:Basket name="Basket-Sanders"/>
<dwControl:DocumentTray name="Basket-Sanders"/>
Fields
The Field command is meant to fill a metadata or index field of the document being stored. The field is identified by its database column name. Currently, four types of fields are supported, as described in the following sections. The attributes dbName and type are required.
- Text/Memo values
<dwControl:Field dbName="EMPLOYEE" type="Text" value="Mark Smith"/>
<dwControl:Field dbName="MEMO" type="Memo" value="Text"/> - Keyword values
<dwControl:Field dbName="Remark" type="Keyword" value="one"/>
<dwControl:Field dbName="Remark" type="Keyword" value="two"/>
Note: When storing multiple values into a single keyword field, multiple Control commands are needed. - Numeric values
In different cultures, colons or dots and other characters are interpreted differently, thus the culture has to be provided to interpret the value correctly. For example 3.000 in Germany is interpreted as 3000, but as 3 in England. In the given sample, the value would be saved as 31,20.
<dwControl:Field dbName="SALARY" type="Numeric" value="31,2" culture="de-CH" decimalPlaces="2" />
When storing a document to a basket, due to an archaic DocuWare restriction, we need to know the numbers of decimal places of the value, as it should be stored to the basket. In the given sample the value would be saved automatically as 3120 to the basket, when decimalPlaces is 2. Storing the document manually from the basket to the filecabinet would then result in 31,20 again. If decimalValues is not specified, the default is 2. - Date values
<dwControl:Field dbName="EMPLOYMENTDATE" type="Date" value="2010-04-03" culture="en-US" format="yyyy-MM-dd" />
<dwControl:Field dbName="EMPLOYMENTDATE" type="Date" value="03 April 2010" culture="en-US" format="dd MMMM yyyy" />
<dwControl:Field dbName="DATUM" type="Date" value="03.04.2010" culture="de-DE" format="dd.MM.yyyy" />
<dwControl:Field dbName="DATUMZEIT" type="DateTime" value="2010-04-03 7:43P" culture="en-US" format="yyyy-MM-dd h:mmt" />
Form
If you are creating documents without letterheads, you can add them using the Form command. It is related to the page, where it is found only. If multiple Form commands are found on a page, the first one will be used.
As a form or letterhead, you have to use a pdf file. This file can be located on a local resource, defined by the path parameter or it can be part of a Printer Configuration.
Example for usage of a local resource.
<dwControl:Form path="C:\forms\letterhead.pdf" />
Using a Printer Configuration as form repository
In each Printer Configuration, you are allowed to set forms for the first or all other pages. The parameters configName and configId reference such a configuration. The configForm parameter can have the value 1 for first page or 2 for all other pages, to select one of the forms in the referenced configuration. For this configuration, usage rights are required.
For example, if you have a "Letters" configuration, in which a letter head is defined for the first page, you can use it with this command.
<dwControl:Form configName="Letters" configForm="1"/>
Print
If you want to redirect the document to another printer, you can use the Print command. The name of the printer can be specified in the device attribute. The default settings of this printer are used. If you need a specific setting, create an additional instance of the printer with another name and define the needed setting there.
Furthermore, in case you are using the Form command, you can choose, whether the printout shall be with or without form. You can fill true in the value of withoutForm, if you don't want to print the defined form or false otherwise.
<dwControl:Print device="my printer" withoutForm="true" />
If not defined, withoutForm is set to false.
Print to default printer:
<dwControl:Print />
You have the option to print additional documents, as e.g. terms of business at the end of the document. The file has to be in pdf format.
<dwControl:Print device="my printer" additionalFilePath="C:\terms\conditions.pdf" />
Using a Printer Configuration as additional file repository
Similar to the Form command, you can use Printer Configurations to deploy needed files to the executor of DocuWare Control commands.
The additionalFileConfigName references the Printer Configurations, in which an additional print file has to be defined. For this configuration, usage rights are required:
<dwControl:Print device="my invoice printer" additionalFileConfigName="Invoices" />
Sign
If you want to electronically sign the document, you can use the Sign command. Similar to the Form command, you can use Printer Configurations to load the needed information, in this case a certificate.
The certificateConfigName references the Printer Configurations, in which a signature has to be configured. For this configuration, usage rights are required.
<dwControl:Sign certificateConfigName="Sign pdf" />
Special characters
A value has to be surrounded with either single quotation marks 'example' or double quotation marks "example".
Using DWControl with DW Printer special characters don't need to be escaped, however, using DWControl with DW Import special characters do need to be escaped correctly.
Please see the following KBAs for information regarding DocuWare Control with special characters:
- How to use special characters in a .dwcontrol metadata? - KBA-35321
- How to embed umlauts in a DWControl file?- KBA-35278
Forbidden strings in parameter values
Please avoid using these strings within your DocuWare Control parameters:
Do not use DW Control strings "<dwControl:...":
<dwControl:Field dbName="REMARK" type="Text" value="<dwControl:NewDocument/>"/>
Inside single quotation marks, any single quotation mark character is forbidden.
<dwControl:Field dbName="REMARK" type="Text" value='Say:'Hello''/>
Inside double quotation marks, all double quotation marks are forbidden.
<dwControl:Field dbName="REMARK" type="Text" value="Say:"Hello""/>
KBA is applicable for Cloud and On-premise Organizations.
