3036740f-171c-2e10-db9d-f206d2cde48c

DI Construction Kit Anatomy
Series pt. 1: Configuration
Applies to:
SAP Business One – all current versions. For more information, visit the Data Management and Integration
homepage.
Summary
This article explains the DI Construction Kit configuration directory hierarchy, as well as the purpose of the
files within.
Author: Henry Nordström

Company: Profiz Business Solution Oy
Created on: 12 February 2011
Author Bio
Henry Nordström is a Senior Research Fellow at Profiz Business Solution Oy.
SAP COMMUNITY NETWORK SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com | UAC - uac.sap.com
© 2011 SAP AG 1
DI Construction Kit Anatomy Series pt. 1: Configuration
Table of Contents
Introduction ......................................................................................................................................................... 3
The Configuration Folder Hierarchy ................................................................................................................... 3
Etc………… ..................................................................................................................................................... 4
Systems .......................................................................................................................................................... 4
Jobs: Exportjobs, Importjobs and Genericjobs ............................................................................................... 5
Fields Common to All Job Types ................................................................................................................................. 5
Fields Specific For Generic Jobs ................................................................................................................................. 6
Fields Specific for Export ............................................................................................................................................. 6
Fields Specific for Import.............................................................................................................................................. 6
Scripts ............................................................................................................................................................. 7
Templates ....................................................................................................................................................... 8
Changing the Default Locations for The Configuration Folders ......................................................................... 9
Third Party Tools for Modifying the Configurations .......................................................................................... 10
Text Editor ..................................................................................................................................................... 10
Code editor / IDE ........................................................................................................................................... 10
Debugger ...................................................................................................................................................... 10
Conclusion ........................................................................................................................................................ 11
Related Content ................................................................................................................................................ 12
Disclaimer and Liability Notice .......................................................................................................................... 13
© 2011 SAP AG 2
Introduction
In this article, I explain the structure of the DI Construction Kit configuration file hierarchy. I will also slightly
touch on the issues of writing scripts and templates. However, these tasks will be addressed in more detail in
articles that follow.
Currently, most of the configuration in DI Construction Kit is done by modifying files. The directory structure
should be clear enough so that it is easy to understand the purpose of each directory and file. Also, the
structure of the XML configuration files themselves is largely self-explanatory.
In the future, I will be adding some more tool support for modifying the configuration files. For login
parameters, this support already exists: you can easily create new system configuration files or modify
existing ones by clicking the Save button in the login dialog (see image below).
The Configuration Folder Hierarchy

By default, the configuration files of DI Construction Kit are located in a directory named “etc” which is
located under the working directory (For instance, “C:\Program Files\SAP\DI Construction Kit”). The location
of the configuration directory can be changed by modifying the settings in DICKManager.exe.config (for the
windows forms client) and DICKcmd.exe.config (for the commandline client). However, in this article I will
assume that we are using the default setup where the “etc” directory is under the executable directory.
© 2011 SAP AG 3
Etc
This is the “configuration root” directory of DI Construction Kit. Normally, the only file here is the
“nvelocity.properties” file that the NVelocity template engine uses for initialization.
For those familiar with NVelocity, it is worth noticing that the “file.resource.loader.path” variable is overridden
during initialization. DI Construction Kit always sets this variable to be the templates folder of the current
configuration.
By default, all the configuration files are kept under the etc directory hierarchy. This is often very handy, as
you can effectively copy all the system configurations and job definitions by copying a single directory.
Some years ago at SAP TechEd in Munich, Shai Agassi proudly compared the new installation process of SAP
R/3 to a Britney Spears marriage: both only take 45 minutes and in the end you will have an Undo-button. Well, DI
Construction Kit is even better. The whole DI Construction Kit platform can be deployed in a single xcopy/extract
operation and then you can just copy the configuration folders on top of it. Thus, you can basically get DICK up
and running in a new environment in a matter of minutes. Should you need to remove it, just delete the whole
DICK directory and you’re done. There’ll be no trash in your registry or anywhere else for that matter. Compare
this with the installation/configuration time of B1ic/B1if/B1i[your choice of alphabet here].
Systems
Each file in this folder represents a different “system”, meaning a single SAP B1 database located on a
specified server.
The name of the file (without the .xml extension) is the system “handle”. When using the commandline tool
(DICKcmd.exe), this handle is given as a parameter to identify the system to connect to. In the sample
above, the handle is “DEMO”.
Note: When running jobs that require a B1 session, the ConnectionString variable is not used at all. The only time when
this variable is needed is when we are running jobs that do not require a B1 connection (job is defined with
B1Required=false).
In addition to specifying the password directly in the system configuration file, you can use a special syntax
to indicate that the password must be retrieved from another file. For instance: “FILE!!C:\data\pw.txt” would
retrieve the password from the file pw.txt that is located under C:\data. This is not a security feature – it is
© 2011 SAP AG 4
only meant to help maintain a configuration in an environment where you have multiple applications using
the same user id (password of which is subject to change).
Talking about data security, I admit that there is a potential security risk in having the user credentials stored
inside a file in clear text. When running DI Construction Kit in interactive mode, you can just leave the
password out from the system file and give it when logging in. When running the application on the server,
you should make sure that the configuration files are well protected. Still, this is an area where there is room
for improvement. [Anyone willing to contribute a better solution for this ?]
Jobs: Exportjobs, Importjobs and Genericjobs

Job definitions act as “binders” that bind together the scripts that are to be executed, the templates to be
used as well as other necessary parameters such as path information for input/output etc.
As the name implies, export jobs are related to tasks where we want to export data from B1 to a specified file
format, which might be XML but could also be something else, such as CSV or some kind of freeform text
layout.
Likewise, import jobs are related to tasks where we want to import new data into SAP B1. Import jobs are
more limited with file formats, currently they can only handle input in XML format.
Finally, we have the generic jobs that can be pretty much anything, including certain kinds of imports or
exports that the “standard” jobs cannot handle. You have much more freedom with generic jobs, but there
are more issues you need to take care of yourself, instead of letting the toolkit handle it for you.
Fields Common to All Job Types

 Description: The description of the job. This appears as a tooltip text in the windows client.
 B1Required: Indicates if the job requires that you have a B1 session. Valid values: true, false.
 ScriptPath: the name(s) of the script(s) to execute. If there are many files you need to refer, separate
them with semicolons. For instance: “myscript.cs;general.cs”.
 ScriptLanguage: CS for C#, VB for Visual Basic. Python support will be added in the future. Please
note that I have not tested the VB feature as I prefer C# in my own work. However, VB compilation
support is built in to the .NET framework so it should be ok.
 ClassName: The class name of the object that we are instantiating. This is required as you can
define multiple classes in a single source file (and you can have multiple source files)
© 2011 SAP AG 5
Fields Specific For Generic Jobs

 InitAction: The method to be invoked. Export and Import jobs rely on prespeficied method names that
you need to use in your scripts. In generic jobs, you can invoke any method you like.
Fields Specific for Export

 SelectionQuery: an SQL expression that returns a resultset. Otherwise the resultset can return
whatever you wish, but the first column of the resultset must contain the keys you intend to use in the
export (for instance, DocEntries of invoices or itemcodes of item records).
 SelectionQueryType: either B1 or ADO. The choice is yours, but the ADO queries are faster and
have less restrictions.
 ExportTarget: specifies the details on files to be produced.
Note: You can have multiple export targets, each with a different template and different target path, even different
template engine if you wish. Thus you could for example do an export job that produces a bunch of XML invoices
and simultaneously produce a simple text file that summarizes key information about those documents.
 For each Export target, you can define the following:

 IsBatch: true or false. If true, all the results from the template engine will be merged into a single
aggregate document. If false, you will get a separate document for each key processed.
 TemplateEngine: NVelocity or StringTemplate. Although the sample project is done with
StringTemplate, my personal choice would be NVelocity.
 TemplateBatchHeader: Used only when IsBatch is true. This template is processed in the beginning
of the batch (before the individual documents).
 TemplateBody: This template is processed once for each key.
 TemplateBatchFooter: Used only when IsBatch is true. This template is processed in the end of the
batch.
 TemplateEncoding: Encoding of the templates mentioned above
 TargetEncoding: Encoding of the file to be produced.
 TargetFolder: Path where the resulting files are to be stored
 ErrorFolder: Not currently used.
 Prefix: The prefix for the names of the files
 Suffix: The suffix for the names of the files.
When IsBatch is false, you can specify the “body” of the filename from within the script by setting the
FileNameBody property of the DICKContext object.
Fields Specific for Import

 SourceFolder: The folder from which the files to be imported will be retrieved. By default, this is the
inbox directory inside the application working directory.
 FileFilter: The search pattern that is applied to the source folder. For instance: “*.xml”
 SourceEncoding: The encoding of the source files
 SuccessFolder: The folder into which the successfully processed files will be moved
 FailureFolder: The folder into which the files that were not processed successfully will be moved.
 ImportTarget: You can define one or more targets.
For each ImportTarget:

 ClassName: The class from which the default method will be invoked.
 StartToken, EndToken: In case we do not want to process the whole document but only a part of it,
we can identify the start and end of the part to be processed with these tokens. Please note: these
tokens are just simple strings, currently this feature does not support regular expressions or other
wildcard expressions.
© 2011 SAP AG 6
Scripts
The scripts folder contains all the C# and VB scripts that the jobs use. This is where the actual business logic
is defined. Although Python is currently only supported in the interactive Python console, I usually store my
own Python scripts in this folder along with the other scripts.
I will soon publish another article that concentrates on developing scripts for DI Construction Kit. Here, I will
only give a very small sample of the code so that you get the idea how we can produce the data that is
consumed by the template engine. Consider the following code snippet:
public DICKContext GetExportContext(string key)
{
DICKContext ctx=new DICKContext();
engine.LogDebug("Building context for export");
Documents doc=(Documents)Session.GetBusinessObject(BoObjectTypes.oInvoices);
int docentry=int.Parse(key);
doc.GetByKey(docentry);
ctx.Add("engine",B1Engine.GetInstance());
ctx.Add("doc",B1Wrapper.Wrap(doc)); // Handle to the document header
ctx.Add("rows",B1Wrapper.Browse(doc.Lines)); // Handle to the document lines
BusinessPartnersbp;
bp=(BusinessPartners)Session.GetBusinessObject(BoObjectTypes.oBusinessPartners);
bp.GetByKey(doc.CardCode);
ctx.Add("bp",B1Wrapper.Wrap(bp)); //Handle to the BusinessPartner
ctx.Add("addressinfo",B1Wrapper.Wrap(doc.AddressExtension)); // Retrieved in DI 8.8
fashion
SalesPersons
sp=(SalesPersons)Session.GetBusinessObject(BoObjectTypes.oSalesPersons);
sp.GetByKey(doc.SalesPersonCode);
ctx.Add("salesperson",B1Wrapper.Wrap(sp)); //Handle to the SalesPerson
PaymentTermsTypes pt;
pt=(PaymentTermsTypes)Session.GetBusinessObject(BoObjectTypes.oPaymentTermsTypes);
pt.GetByKey(doc.PaymentGroupCode);
ctx.Add("paymentterms",B1Wrapper.Wrap(pt)); //Handle to PaymentTerms
ctx.Add("FileNameBody",doc.DocNum); //The mid part of the exported file is Doc No.
return ctx;
Do not let the simplicity of the snippet deceive you: this is no toy code. The script above is all you need to
write in order to implement an export interface for sales invoices. Replace the single
BoObjectTypes.oInvoices reference with another type of document and you have the code for exporting
sales orders, purchase orders, deliveries etc. All this is done in less than 25 lines of code. Cool, huh?
This goes to show that although you can’t completely avoid writing code in DI Construction Kit, you can get
away with very little code. Simultaneously, you have full control on what data you expose to the template
engine. You don’t have to rely on fields that someone else decided to include in the export. If a new DI API
version contains new fields, all you need to do is recompile DI Construction Kit against the new API and the
new fields are immediately available. If you need information that is not available in DI API, that’s no problem
either. Just add your own method to retrieve that information from a database, file or even from a web
service if you need to.
© 2011 SAP AG 7
Templates
Currently, DI Construction Kit supports two flavors of template engine: NVelocity and StringTemplate. While
StringTemplate is a more “orthodox” template engine and may perform a bit better, I personally prefer
NVelocity. Anyway, both engines are fully supported and the choice is yours.
Just to demonstrate how we can access the data that we prepared in the previous chapter, here’s a small
NVelocity template snippet:
<Invoice>
<Customer>
<CustomerCode>$bp.Get("CardCode")</CustomerCode>
<CustomerName>$bp.GetXmlEncoded("CardName")</CustomerName>
<BuyerAddress>
<Street>$addressinfo.Get("BillToStreetU")</Street>
<City>$addressinfo.Get("BillToCityU")</City>
<ZipCode>$addressinfo.Get("BillToZipCodeU")</ZipCode>
<CountryCode>$addressinfo.Get("BCU")</CountryCode>
</BuyerAddress>
</Customer>
<InvoiceNumber>$doc.Get("DocNum")</InvoiceNumber>
<InvoiceDate>$doc.Get("DocDate","date")</InvoiceDate>
<OrderReference>$doc.Get("NumAtCard")</OrderReference>
<VatAmount>$doc.Get("VatSum","currency")</VatAmount>
<InvoiceTotal>$doc.Get("DocTotal","currency")</InvoiceTotal>
<PaymentTerms>
<PaymentTermsName>$paymentterms.Get("PaymentTermsGroupName")</PaymentTermsName>
<InvoiceDueDate>$doc.Get("DocDueDate","date")</InvoiceDueDate>
</PaymentTerms>
#foreach ($row in $rows)
<InvoiceRow>
<ItemCode>$row.Get("ItemCode")</ItemCode>
<ItemName>$row.GetXmlEncoded("ItemDescription")</ItemName>
<Quantity>$row.Get("Quantity")</Quantity>
<UnitPrice>$row.Get("Price","currency")</UnitPrice>
<RowIdentifier>$row.Get("LineNum")</RowIdentifier>
<RowFreeText>$row.Get("FreeText")</RowFreeText>
<RowDiscountPercent>$row.Get("DiscountPercent")</RowDiscountPercent>
<RowVatRatePercent>$row.Get("TaxPercentagePerRow")</RowVatRatePercent>
<RowVatAmount>$row.Get("TaxTotal","currency")</RowVatAmount>
<RowVatExcludedAmount>$row.Get("LineTotal","currency")</RowVatExcludedAmount>
</InvoiceRow>
#end
</Invoice>
This snippet produces an XML document when rendered by the template engine.
Note: We could just as well produce a file in some other format. For instance, we could produce a comma-separated file
by removing the XML tags and replaced them with semicolons.
If you have any experience with the B1i framework, I’m sure you will appreciate the ease of working with
templates instead of fighting with XSLT transformation stylesheets.
Both template engines are very well documented. You will find lots of material for them in the web. Here are
just a couple of pointers to get you started:
http://velocity.apache.org/engine/devel/vtl-reference-guide.html
http://www.antlr.org/wiki/display/ST/StringTemplate+3.0+Printable+Documentation
© 2011 SAP AG 8
Changing the Default Locations for The Configuration Folders

As mentioned above, the location of the configuration directory can be changed by modifying the settings in
DICKManager.exe.config (for the windows forms client) and DICKcmd.exe.config (for the commandline
client) as follows:
basedirectory  default is working directory (affects etc default)
logdirectory  default is working directory \ logs
configurationdirectory  default is working directory \ etc
systemdirectory  default is working directory \ systems
templatedirectory  default is working directory \ templates
The following sample shows how to change the location of the whole configuration folder hierarchy to a
server share.
<?xml version="1.0"?>
<configuration>
<startup>
<supportedRuntime version="v2.0.50727"/>
</startup>
<appSettings>
<add key="basedirectory" value="\\DICKSERVER\CONFIGSHARE\">
</appSettings>
</configuration>
Using this setting, the application will assume that the path to etc is \\DICKSERVER\CONFIGSHARE\etc
You can also do more fine-grained settings, for example just change the template directory to a different
place on your local workstation:
<?xml version="1.0"?>
<configuration>
<startup>
<supportedRuntime version="v2.0.50727"/>
</startup>
<appSettings>
<add key="templatedirectory" value="C:\My_Common_Templates\">
</appSettings>
</configuration>
© 2011 SAP AG 9
Third Party Tools for Modifying the Configurations

Text Editor
The choice of editor for modifying the configuration is pretty much a question of taste. There are lots of great
programmer’s editors out there and most developers have a very strong opinion on which one they want to
use. For me, the choice is UltraEdit (www.ultraedit.com).
As a lot of the configuration is done directly in the customer’s environment, so you cannot always expect to
have your favorite editor installed on the host. Thus, it would be handy to have a decent text editor that is
free of charge. Notepad is free, but lacks seriously on the feature side. As a compromise, I usually install
Crimson Editor (www.crimsoneditor.com) on the customer’s site. It is free of charge, robust, fast to install and
has a pretty impressive set of features.
Code editor / IDE

Text editors do the job nicely for other configuration files and templates, but they are a bit limited when
working with the scripts. People used to modern development IDEs usually expect such things as
IntelliSense and a decent debugging experience.
The great thing about DI Construction Kit is that you can actually reference DICK.Core.dll, DICK.B1.dll as
well as DI APIin a Visual Studio C#/VB project, then add your own DICK scripts to the project and with some
magic done behind the curtains, you will get IntelliSense. I will write another article laying down the details on
how to do this in practice.
Debugger
In addition to IntelliSense, the Visual Studio trick will also give you an end-to-end debugging experience. You
can debug the solution so that the debugger will step through both the code from the toolkit as well as the
code in your scripts.
Sooner or later, you will need to do some debugging in the customer’s environment. A real production
environment often produces situations that you need to debug but cannot reproduce in your development
environment. DI Construction Kit does have a logging feature that is often enough for resolving the issue at
hand. Still, it would make problem resolution much easier if you had access to a real debugger. The problem
is that you cannot normally expect to have Visual Studio installed on the customer’s site.
© 2011 SAP AG 10
Once again, this is where the Open Source community comes to the rescue. While SharpDevelop 3.2 is not
quite as refined as Visual Studio, it is still an excellent IDE that has everything you need for a good
development/debugging experience on a customer’s site [see the image below].
Conclusion
In this article, I have described the basic principles of configuring DI Construction Kit as well as scratched the
surface on developing scripts and templates. I hope that this article helps you to get started with DICK
development. I sincerely hope that you enjoy the experience.
© 2011 SAP AG 11
Related Content
Apache Velocity Project
StringTemplate 3.0 Printable Documentation
Open Source Projects for the .NET Platform
For more information, visit the Data Management and Integration homepage.
© 2011 SAP AG 12
Disclaimer and Liability Notice

This document may discuss sample coding or other information that does not include SAP official interfaces and therefore is not
supported by SAP. Changes made based on this information are not supported and can be overwritten during an upgrade.
SAP will not be held liable for any damages caused by using or misusing the information, code or methods suggested in this document,
and anyone using these methods does so at his/her own risk.
SAP offers no guarantees and assumes no responsibility or liability of any type with respect to the content of this technical article or
code sample, including any liability resulting from incompatibility between the content within this document and the materials and
services offered by SAP. You agree that you will not hold, or seek to hold, SAP responsible or liable with respect to the content of this
document.
© 2011 SAP AG 13

3036740f-171c-2e10-db9d-f206d2cde48c

Enviado por

Dados do documento

Descrição original:

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

3036740f-171c-2e10-db9d-f206d2cde48c

Enviado por

Direitos autorais:

Formatos disponíveis

DI Construction Kit Anatomy

Series pt. 1: Configuration

Author: Henry Nordström

The Configuration Folder Hierarchy

Jobs: Exportjobs, Importjobs and Genericjobs

Fields Common to All Job Types

Fields Specific For Generic Jobs

Fields Specific for Export

 For each Export target, you can define the following:

Fields Specific for Import

For each ImportTarget:

Changing the Default Locations for The Configuration Folders

Third Party Tools for Modifying the Configurations

Code editor / IDE

Disclaimer and Liability Notice

Você também pode gostar