developer’s guide - componentsource manual is organized to allow you to reference information for...

Copyright © appStrategy Inc. 2013 appCompass Developer’s Guide - 1

appCompass

Developer’s Guide

For:

appCompass Data Integration Studio appCompass Business Rules Studio

appCompass Visual Studio Editions

Version 5.1 July, 2013


Table of Contents

1. Welcome to appCompass Developer’s Guide ................................................... 7

2. Getting Started ............................................................................................... 9

2.1 - Before You Begin ......................................................................................... 9 2.2 - Software Installation .................................................................................... 9 2.3 - Activating appCompass Studio License ......................................................... 10 2.4 - Activating Visual Studio Edition License ........................................................ 12 2.5 - Activating on a Computer without Internet Access ......................................... 13

3. appCompass Concepts & Features................................................................. 18

3.1 - Overview .................................................................................................. 18 3.2 - Windows Workflow Foundation .................................................................... 18 3.3 - Workflow Activities .................................................................................... 18 3.4 - appCompass Modules and Connectors .......................................................... 19 3.5 - Composing & Orchestrating Integration/Business Rules Projects ...................... 20 3.6 - appCompass Studio for Business Users ......................................................... 22 3.7 - appCompass Visual Studio Editions for Developers ......................................... 22 3.8 - appCompass Custom Studio ........................................................................ 22 3.9 - appCompass Express for XCopy Deployment ................................................. 23 3.10 - appCompass Enterprise Server for Enterprise Deployment ............................ 24 3.11 - appStrategy Workbench ........................................................................... 24 3.12 - appCompass Add-Ons .............................................................................. 25 3.13 - The Setup Database ................................................................................. 25 3.14 - Project Databases .................................................................................... 26 3.15 - The Samples Project Database .................................................................. 27 3.16 - Deployment Settings ................................................................................ 28 3.17 - Data Source Settings ................................................................................ 28 3.18 - Sourced Values ........................................................................................ 29 3.19 - Expressions and Extension Functions .......................................................... 32 3.20 - Conditions ............................................................................................... 32 3.21 - Data Managers ........................................................................................ 32 3.22 - High Performance Options ......................................................................... 33 3.23 - Project Run Details ................................................................................... 34 3.24 - The App Object ........................................................................................ 35 3.25 - Designer Hosting/Re-hosting ..................................................................... 35

4. Accessing the Studio Environment ................................................................ 36

4.1 - Overview .................................................................................................. 36 4.2 - Accessing appCompass Studio ..................................................................... 36 4.3 - Accessing Visual Studio .............................................................................. 36 4.4 - Accessing appStrategy Workbench ............................................................... 36

5. appCompass Studio Overview ....................................................................... 38

5.1 - Overview .................................................................................................. 38 5.2 - Features ................................................................................................... 40

5.2.1 – Application Menu Overview ................................................................... 40 5.2.2 – Quick Access Toolbar ............................................................................ 41


5.2.3 - Overview of the Ribbon Tabs & Groups ................................................... 42

6. appCompass Visual Studio Edition Overview ................................................ 47

6.1 - Overview .................................................................................................. 47

7. appCompass Activity Modules ....................................................................... 49

7.1 – System Activity Modules ............................................................................ 49 7.2 – Base Activity Modules ................................................................................ 49 7.3 – Utility Activity Modules ............................................................................... 50 7.4 – SQL Activity Modules ................................................................................. 51 7.5 – General Data Access Activity Modules .......................................................... 52 7.6 – Business Rules Activity Modules .................................................................. 53 7.7 – Add-On Activity Modules ............................................................................ 54 7.8 – Custom Activity Modules ............................................................................ 54

8. Adding Workflow Activity Modules to the Toolbox ........................................ 55

8.1 – Adding Activity Modules to appCompass Studio Toolbox ................................. 55 8.2 – Adding Activity Modules to Visual Studio Toolbox .......................................... 56

9. Composing & Orchestrating appCompass Projects ........................................ 60

9.1 - Overview .................................................................................................. 60 9.2 - Using appCompass Studio Editions ............................................................... 60 9.3 - Using Visual Studio Editions ........................................................................ 61

10. Creating a New Project Database ................................................................ 62

10.1 – Overview ................................................................................................ 62 10.2 – Creating a New Project Database in appCompass Studio .............................. 62 10.3 – Creating a New Project Database in Visual Studio ........................................ 63

11. Creating and Maintaining Deployment Settings .......................................... 65

11.1 - Overview ................................................................................................ 65 11.2 - Using the Default Deployment Settings ....................................................... 65 11.3 - Adding and Updating Deployment Settings .................................................. 66

12. Creating a New Project ............................................................................... 67

12.1 – Overview ................................................................................................ 67 12.2 – Creating a New Project in appCompass Studio ............................................ 67 12.3 – Creating a New Project in Visual Studio ...................................................... 69

13. Property Editors .......................................................................................... 70

13.1 – Overview ................................................................................................ 70 13.2 – Drop Down Editors .................................................................................. 71 13.3 – Collection Editors .................................................................................... 72 13.4 – Dialog Property Editors ............................................................................ 73 13.5 – SourcedValue Property Editors .................................................................. 74 13.6 – Other Property Editor Dialogs .................................................................... 78

13.6.1 – Custom Query Editor .......................................................................... 78 13.6.2 – Concatenation Editor .......................................................................... 79 13.6.3 – Html Editor........................................................................................ 80


14. Using Data Source Metadata in appCompass ............................................... 82

14.1 – Overview ................................................................................................ 82 14.2 - Creating Data Source Metadata ............................................................ 82 14.3 – Metadata Browser ............................................................................... 84

14.3.1 – Browse Data Source Summary............................................................. 84 14.3.2 – Browse Data Source Entities / Tables .................................................... 85 14.3.3 – Browse Entity Fields / Attributes .......................................................... 86

15. Working with Data File Definitions .............................................................. 87

15.1 – Overview ................................................................................................ 87 15.2 - Adding and Updating File Definitions .......................................................... 88

16. Using Conditions in appCompass Projects ................................................... 89

16.1 – Overview ................................................................................................ 89 16.2 – Control Flow Conditions ............................................................................ 89 16.3 – The Expression Builder ............................................................................. 91 16.4 – Defining Condition Expressions ................................................................. 92 16.5 – Defining Condition Functions ..................................................................... 95

17. Using Functions in appCompass Projects .................................................... 98

17.1 – Overview ................................................................................................ 98 17.2 – Internal Functions ................................................................................... 98 17.3 – Extension Functions ............................................................................... 101

18. Using External Assemblies in Functions .................................................... 104

18.1 – Overview .............................................................................................. 104 18.2 – Adding External Assemblies .................................................................... 104

19. Reading Data ............................................................................................ 106

19.1 - Overview .............................................................................................. 106 19.2 - InitializeSource Activity .......................................................................... 106 19.3 - InitializeSourceFromQuery Activity ........................................................... 110 19.4 - GetNextRecord Activity ........................................................................... 113

20. Looking up Data ........................................................................................ 114

20.1 - Overview .............................................................................................. 114 20.2 - LookupRecord Activity ............................................................................ 114 20.3 - LookupDataFieldValue Activity ................................................................. 114 20.4 - LookupPreloadedRecord Activity .............................................................. 114

21. Using PickLists .......................................................................................... 115

21.1 - Overview .............................................................................................. 115 21.2 – The LookupPickListRecord Activity ........................................................... 116 21.3 – The IsPickListValid Activity ..................................................................... 116

22. Mapping Data Field Values ........................................................................ 117

22.1 – Overview .............................................................................................. 117 22.2 – The MapFields Activity ............................................................................ 117 22.3 – The Field Map Detail Window .................................................................. 119


22.4 – Transforming Field Values ...................................................................... 120

23. Writing Data ............................................................................................. 122

23.1 Overview ................................................................................................ 122 23.2 - InitializeMssqlTarget Activity ................................................................... 122 23.3 - Configuring the High Performance Options ................................................ 124 23.4 - Setting Data Field values for the Active Record .......................................... 126 23.5 - Inserting Data ....................................................................................... 127 23.6 - Updating Data ....................................................................................... 128 23.7 - The UpsertRecord Activity ....................................................................... 129 23.8 - Deleting Records .................................................................................... 130

24. Executing Stored Procedures .................................................................... 131

24.1 - Overview .............................................................................................. 131 24.2 - ExecuteStoredProcedure Activity .............................................................. 131

25. Validating appCompass Projects ............................................................... 133

25.1 – Overview .............................................................................................. 133 25.2 – Design Time Validation ........................................................................... 133

25.2.1 – Design Time Validation on appCompass Studio .................................... 133 25.2.2 – Design Time Validation on Visual Studio .............................................. 134

25.3 – Detailed Validation of appCompass Projects .............................................. 135

26. Running Data Integration & Business Rules Projects ................................ 137

26.1 - Overview .............................................................................................. 137 26.2 - Running on appCompass Studio ............................................................... 137 26.3 - Running on Visual Studio Editions ............................................................ 137

27. Deploying appCompass Projects ............................................................... 138

27.1 - Overview .............................................................................................. 138 27.2 - XCopy Folder Deployment and appCompass Express .................................. 139 27.3 - Copy Project Database to Deployment Server ............................................ 140

28. Scheduling Data Integration & Business Rules Jobs ................................. 141

29. Viewing Logs & Statistics .......................................................................... 143

29.1 - Overview .............................................................................................. 143 29.2 - Project Run Details ................................................................................. 143 29.3 - Database Log Entries.............................................................................. 144 29.4 - Run Instances ....................................................................................... 144 29.5 - Activity Statistics ................................................................................... 144 29.6 - Data Source Statistics ............................................................................ 144 29.7 - View Project Folders ............................................................................... 144

30. appCompass Walkthroughs ....................................................................... 145

30.1 - Read a Source (InitializeSource Activity) ................................................... 146 30.2 – Using RelatedEntities to link entities / tables in Source definitions ............... 158

31. Advanced Topics ....................................................................................... 162

31.1 – Overview .............................................................................................. 162


31.2 – Viewing and Editing Project Xaml ............................................................ 162 31.2.1 – Viewing Project Xaml in appCompass Studio ........................................ 162 31.2.2 – Viewing Project Xaml in Visual Studio ................................................. 164

31.3 – Creating Your Own Activity Assemblies ..................................................... 166

32. Project Scenarios and Samples ................................................................. 167


1. Welcome to appCompass Developer’s Guide

Welcome to appCompass Developer’s Guide! appCompass offers a next-generation development environment that can be utilized by

business users and developers to tackle simple or complex data integration and business rules projects. appCompass projects are developed using activity modules that can be

utilized in the following development environments:

For Business Users (appCompass Studio):

appCompass Data Integration Studio

appCompass Business Rules Studio

For Developers (Visual Studio):

appCompass - Visual Studio Edition (VSE)

appCompass Business Rules Studio - Visual Studio Edition


No programming is required to use appCompass Studio environments.

For developers, appStrategy offers appCompass Visual Studio editions for Data Integration Studio and Business Rules Studio.

This manual is organized to allow you to reference information for appCompass Studio or for using Visual Studio to develop appCompass projects. If you are

using the appCompass Studio edition, you can skip the sections on Visual Studio. And if you are using a Visual Studio edition, you can skip the sections

on appCompass Studio.

Explore this user guide to learn more about how to work with the appCompass Developer environments:

The Toolbox Using the Designer Navigating the Outline

The Property Grid Built-in Editors

Mapping Data Field Values Loading and Saving Projects Extending appCompass Projects with Extension Functions

Defining Conditions for Use in the Designer Multi-User Considerations


2. Getting Started

2.1 - Before You Begin Before you begin using appCompass Studio, you should review the Getting Started With the appCompass Product Suite manual, the appCompass Base Activities User Guide, appStrategy Workbench User guide and other supporting documentation to

gain an understanding of the appCompass environment, installation requirements and the day-to-day usage of the system.

2.2 - Software Installation There are no additional requirements for installing appCompass Studio. The installer

includes all the assemblies that can be included in the toolbox by your edition of the product. Review the Getting Started for additional information.


2.3 - Activating appCompass Studio License After installing appCompass Data Integration Studio or appCompass Business Rules

Studio, run the appCompass Studio program by double-clicking on the appCompass icon that was installed on your desktop. The Login window will be displayed as shown below:

Click the Activate License button

The Activate License window will be displayed:


Enter your licenseID and password, and optionally indicate a name for your installation,

then click the “Activate” button. Wait for a few seconds until the “Activate” button is disabled indicating that your license has been activated.

Click the OK button and Project Database Log In window will be displayed. You can then

log in to the Samples Project Database or create a new project database.


2.4 - Activating Visual Studio Edition License After installing appCompass Visual Studio Edition or appCompass Business Rules Studio

for Visual Studio, run the appStrategy Workbench program by double-clicking on the Workbench icon that was installed on your desktop. The Login window will be displayed

as shown below:

Click the Activate License button and follow the on-screen instructions to activate the software license for the software.


2.5 - Activating on a Computer without Internet Access When the machine where you install the software has no internet access, the activation

can be done as follows. Run the appStrategy Workbench application and the login window will be displayed.

Click the button and the following screen will be displayed:


Select License Manager and click the OK button and the License Manager window will be

displayed.

Select the product from the list and click on the “Activate Manually” button.


In the following window, enter the license ID and password and click on the “Generate

Request” button

After a few seconds, the activation request is created, click on “Copy to file” to save the

generated xml. Then, from another computer with Internet access, type https://secure.softwarekey.com/solo/customers/manualrequest.aspx

https://secure.softwarekey.com/solo/customers/manualrequest.aspx


In the web page, upload your file or copy its content then click the related “Submit” Button

You will obtain a response request that you can copy and paste or save into a file


Then on the machine where the software is installed, submit the response in Step3

section:

Click the “Activate” button, after a few seconds your license is activated: a confirmation

message is displayed.


3. appCompass Concepts & Features

3.1 - Overview Before jumping in to start composing and orchestrating your projects with appCompass, it is recommended that you review this section to get a basic idea of the concepts that

drive appCompass. The concepts are not discussed in detail here but are rather presented in a concise manner to help you hit the ground running. In addition to understanding the concepts and features, this section will also introduce you to the most

frequently used terms in appCompass. While appCompass features so many options, only the key common features are included in this section.

3.2 - Windows Workflow Foundation appCompass is based on Microsoft’s Windows Workflow Foundation v4.5 (WF). By utilizing WF, and also Windows Communication Foundation (WCF), appCompass utilizes

the latest technology to deliver a powerful and flexible environment that easily integrates with other systems. Knowledge of Windows Workflow is not required to use appCompass to compose and orchestrate projects. Windows Workflow Foundation is part of the .Net

framework. It is not an additional purchase and does not require special installation considerations.

3.3 - Workflow Activities The actual work performed by appCompass projects are done through the execution of one or more workflow activities. A workflow activity takes input and gives output and contains user-configurable variables and properties. Out-of-the-box, Windows Workflow

Foundation offers several activities – a majority of which are atomic (generic).

appCompass workflow activities are grouped into modules that can be configured to complete a process. The workflow activities that are included in your installation of

appCompass depend on the edition and modules of the system that you have purchased. appCompass activities are able to move and share data between modules and also with external systems. Each module is specific to the features of the application that it

supports – including files, databases, SAAS etc. appCompass users can also extend the system by creating their own workflow activities that can interact with other appCompass

activities.


The process of composing your projects (workflows), involves dragging activities on to

the designer and configuring the associated properties.

3.4 - appCompass Modules and Connectors appCompass activities are packaged in modules related to the job they perform as a group. For example, the Dynamics CRM modules include several activities that are used for composing and orchestrating jobs that target Microsoft Dynamics CRM Online,

Microsoft’s Dynamics CRM 2011 and Microsoft Dynamics CRM 3. appCompass modules also include the connectors available for the module. For example, the Dynamics CRM

2011 module includes connectors for accessing Dynamics CRM 2011 using WCF, FetchXml and FilteredViews.

appCompass modules are self-contained and feature their own user guides. Available documentation for modules includes appCompass for Flat Files User Guide, appCompass

for Dynamics CRM User Guide and others. To use a module, refer to its User Guide.


3.5 - Composing & Orchestrating Integration/Business

Rules Projects

In appCompass, projects are composed and orchestrated as

opposed to being programmed or developed as in legacy integration products. Using

activity modules with powerful activities featuring easy-to-use and reusable editors makes this possible.

Compose Projects Using Flowchart Model:


Compose projects using Sequence model:


3.6 - appCompass Studio for Business Users appCompass Studio refers to appCompass Data Integration Studio or appCompass

Business Rules Studio – the two environments for composing and orchestrating integration and business rules projects for business users.

appCompass Data Integration Studio is a next generation environment for composing integration and migration projects.

appCompass Business Rules Studio is a next generation business rules engine for

composing enterprise-class business rules. Business Rules Studio starts with appCompass Data Integration functionality and adds additional activities for building reusable enterprise rules.

3.7 - appCompass Visual Studio Editions for

Developers appCompass Visual Studio Editions refers to appCompass Data Integration Visual Studio Edition and appCompass Business Rules Visual Studio Edition – the two

environments for composing and orchestrating integration and business rules projects for developers.

3.8 - appCompass Custom Studio

appCompass Custom Studio refers to a custom Studio that “hosts” appCompass

activities. Programming experience is required to create a Custom Studio. An appCompass Enterprise license is required to run a Custom Studio.

A popular starting point for a Custom Studio can be found here: http://blogs.msdn.com/b/mcsuksoldev/archive/2012/03/26/workflow-foundation-wf4-rehosting-

the-workflow-designer.aspx

http://blogs.msdn.com/b/mcsuksoldev/archive/2012/03/26/workflow-foundation-wf4-rehosting-the-workflow-designer.aspx

http://blogs.msdn.com/b/mcsuksoldev/archive/2012/03/26/workflow-foundation-wf4-rehosting-the-workflow-designer.aspx


3.9 - appCompass Express for XCopy Deployment

Data integration jobs can be developed, scheduled and run from the development machine using any edition of appCompass Studio or appCompass VSE. The appCompass Express license is required for each additional machine on which you wish to deploy your

projects. The appCompass Express system includes a copy of appStrategy Workbench for managing the deployment. appCompass Express is very

easy to setup, run, and administer since it supports XCopy deployment.


3.10 - appCompass Enterprise Server for Enterprise

Deployment

appCompass Server is an optional software system that you can purchase and

install on a server computer to run jobs that you compose using appCompass Development products. appCompass Server offers a centralized location for

running jobs in an automated fashion. appCompass Server also includes a WCF interface that allows you to activate

projects from other solutions or stored procedures. appCompass Server requires Microsoft SQL Server, Oracle, IBM DB2 or MySQL database.

3.11 - appStrategy Workbench The appStrategy Workbench application is the administration and maintenance

module for appCompass. All settings for deployments, data sources, and definitions for managing the day-to-day running of the system can be defined in

the Workbench application. All editions of appCompass Development products, appCompass Express and appCompass Server include appStrategy Workbench.


3.12 - appCompass Add-Ons Activity modules which are not part of the appCompass package are called Add-Ons. The

following Add-Ons are currently available.

Add-On/Connector Description

Data Quality Module

Software for composing and executing on data quality initiatives.

Data Cleansing (Auditing, Formatting and Validation).

Matching for Single Customer View (SCV).

Master Data Management. Data Governance

SharePoint

Activity modules and connectors for Microsoft SharePoint (On-premise

and On-line);

Active Directory Activity modules and connectors for Microsoft Active Directory

appCompass SDK Optional Software Development Kit for re-hosting the designer

EDI Activity modules and connectors for EDI (X12/EDIFACT)

3.13 - The Setup Database When you install appCompass, it also automatically installs a Setup database - Setup.sdf. The Setup database is a SQL Server Compact Edition database. You will not have to do anything special with the Setup database. But you need to know that it exists and holds

general configuration information for your appCompass Data Integration Studio installation. The configuration information includes licenses and other general system-

specific settings. In enterprise deployments, you can move the Setup database to an enterprise database such as Microsoft SQL Server, Oracle, and IBM DB2 etc.


3.14 - Project Databases appCompass stores projects in project databases. Your project database can contain a

few, or unlimited number of projects. Depending on the edition of appCompass that you have purchased, you can also maintain several project databases and synchronize data

between project databases. This feature makes it easy for you to maintain separate environments for Development, Test and Production.

Project databases are not just used for storing your job definitions. They also store all the supporting and other data including data source definitions, lists, settings and logs.

appCompass currently allows you to store your project data in Microsoft SQL Server Compact Edition - (CE) or enterprise SQL Databases (Microsoft SQL Server, Oracle, MySQL and IBM DB2). SQL Server CE is used mostly for development and for small and

medium deployments. Since it is an embeddable database, it requires little or no resources to create and maintain – and it is free! The samples supplied with

appCompass are in SQL Server Compact Edition format. appCompass includes utilities that allow you to move your project database from one format to another (VSE and Enterprise editions only).

For enterprise installations where high performance is required for processing millions of transactions, an enterprise database engine is recommended.


3.15 - The Samples Project Database A project database named Samples is installed along with your edition of the

appCompass software product. The Samples database contains several examples that show you how to hit the ground running with appCompass.

In addition, a database named Northwind containing test data is also installed on your computer. Using the Northwind test database, you can run the

Northwind sample projects in the Samples project database. This is because both the Samples project database and the Northwind databases are SQL Server

Compact Edition databases. You will not be required to configure connection strings for the Samples database and the Northwind database. They are

automatically configured for you so you can run the Northwind sample projects. And there is no need to install the SQL Server CE software – it is automatically

included in appCompass.

Before running other sample projects (non-Northwind samples), make sure that you properly configure the required settings (connection strings, authentication

etc.).


3.16 - Deployment Settings

Most software projects consume a lot of time at deployment (configuring registry settings, checking activations, connection strings, file locations, etc.).

To alleviate these problems, appCompass includes Deployment Settings that you

can use to define how your projects will be deployed – even before the projects are composed. For example, you can create deployment settings for

Development, Test and Production. You can also create deployment settings for locations where the projects will be deployed. There is no limit to the number of

deployment settings that you can define.

Based on the deployment settings, the projects that you compose will ‘know’ exactly how to behave and the settings to use for connection strings, urls, file

locations etc. So, to continue with our Development/Test/Production example, while you are developing the project, your project will automatically use the

Development settings. At Test time, the project will use the Test settings and at deployment it will automatically use the Production settings.

3.17 - Data Source Settings

The metadata of the data sources to be used in your projects are captured and maintained in the project database. You can connect once to the data source to

create the metadata. After that, you can utilize the project database to work in environments that do not have direct access to the data source.

When creating a data source, appCompass gathers not only information related to

entities or table metadata, but also any additional information included in the database of applications including pick lists and data mapping information. For

example, when creating data source metadata for Microsoft Dynamics CRM and Salesforce.com, pick list information is automatically included so you can select

them when composing projects.

Since not all data sources expose robust metadata, the system includes options

for accessing data sources in a dynamic manner.


3.18 - Sourced Values To deliver a code-free environment where projects can be composed and

deployed quickly, appCompass employs “Sourced Values”. In simple terms, a Sourced Value allows you to quickly select a source for a value and an

identifier for it. To specify a sourced value, you enter the Source, a colon and

then the value identifier (Source Value Identifier). Below are some examples of the many sourced values used in appCompass:

Source Value Identifier Constant The Constant source allows you to enter any value in the value

identifier.

Example: “Constant:John Smith”

DataField The DataField allows you to point to a specific data field in a record

if the source of the specific record is associated as “Source” to the current activity.

Example: “Employees.LastName” points the value of the LastName column in the data Employees record.

DataFieldExt The DataFieldExt extends the DataField source value to point to a data field in a record from any source or target in the project.

DateTime The DateTime sourced value points to a date/time related value. They can also be used to specify other date/time related data.

Example: “DateTimeNow” generates the current date/time.

ExtensionFunction The ExtensionFunction source allows you to select a function that you have defined to return value or perform additional processing.

The above examples give you an idea of how Sourced Values are defined and used in appCompass. There are over fifty (50) Sourced Value types that you can

use to specify data anywhere in your projects.

By providing a rich set of editors and controls to manage Sourced Values, appCompass is able to provide a very powerful and flexible combination that

gives users the fastest and most compact environment for configuring activities and orchestrating processes.


Sourced Values in Property Grid

Below are examples of Sourced Value controls on the property grid at design time:

Sourced Values in Mapping The example below shows Sourced Values in use for mapping. In this case the values are coming from DataField, InternalFunction, ExtensionFunction, Concatenation and even

HTML:


Sourced Value Editor Window

The example below shows the Sourced Value Editor window used for configuring a Sourced Value at design time:


3.19 - Expressions and Extension Functions

Simple expressions and functions can be defined in the appCompass environment to extend the functionality of the project. appCompass Expressions and Extension

Functions can be written in C# and VB and stored in the project database. At design and run time, expressions and extension functions can access external .Net methods,

appCompass methods, variables, arguments and properties in the running process. Expressions and Functions can be entered, validated and saved using the simple appCompass Function Editor. Visual Studio is not required. Expressions and

Extension Functions can be defined by super users; extensive programming experience is not required. Once defined, the expressions and functions are automatically validated

and saved in the project database. No compilation is necessary – the functions are automatically compiled by appCompass.

3.20 - Conditions The branching, looping and other processing decisions to be made by the processes that

you compose will be based on conditions. Activities such as “While”, “If” and others expect conditions as the main property for executing an activity or a sequence of

activities if a condition is true or false. appCompass includes an Expression Editor that can be used to quickly define simple conditions. appCompass Extension Functions can

be defined to handle complex conditions. An Extension Function defined for handling a complex condition must return a Boolean value.

3.21 - Data Managers appCompass Data Managers are a special set of activities that can be initialized as Sources or Targets in the project. Source Data Managers retrieve data from a data

source and make the records and values in them available for other modules in the project. Target Data Managers are used for saving records to a specific data source. The

properties, connectors configuration options, and execution context of Data Managers is based on the parent module of the Data Manager.

Unlike traditional and legacy ETL solutions, appCompass projects can support an unlimited number of Source and Target Data Managers in the same project. And

you can define configuration values using values from unrelated Sources/Targets and even dynamic values. A standard Source can be initialized using an

InitializeSource activity and a standard Target activity can be initialized using an

InitializeTarget activity.

In addition to standard Data Managers (Source & Target), appCompass also supports derived Data Managers such as Lists, Lookups, PreloadedRecords,

PickLists, etc.


appCompass persists the values of the current records of Data Managers so they can be utilized by other activities using the DataField/DataFieldExt Sourced

Values. Some appCompass modules provide additional Data Managers that are specific to the data source. For example, the appCompass modules for Microsoft

SQL Server and Oracle provide the InitializeSourceFromCsv activity. InitializeSourceFromCsv supports ultra-fast loading of a data source directly from

a CSV file, while making the activity function just like any other Source. Several

activity modules also feature an InitializeSourceFromQuery activity which allows loading of records based on a user-defined query.

3.22 - High Performance Options

appCompass includes several options that can be used to optimize the processing of high volume and complex projects. These features are available as

configurable properties that are associated with Sources and Targets defined in the project. Target activities also feature a special property named

“HighPerformanceOptions”. This feature is especially useful when working with SAAS platforms such as Microsoft Dynamics CRM Online, Salesforce.com and

others which are notoriously slow due to utilization of web services. By properly configuring the High Performance property, your projects will run much faster and

can handle much heavier loads.


3.23 - Project Run Details

You can configure your appCompass integration and business rules project to log as much information as possible regarding the process. Several selections are

included for viewing logs and other project runtime data. After running the job or

while it is still running, you can use the Project Run Details window to view all details related to the job, including Activity statistics, Source and Target

statistics, performance logs and error logs.


3.24 - The App Object

The appCompass App object is a subject that belongs in technical discussions. We will not go into a technical deep-dive here but since you are learning about

the concepts, features and terminology of appCompass, we will give it a cursory

look. If you do not have any technical background, it is recommended that you skip this section, since you will be accessing the App object through controls and

editors that shield you from the technical details.

The App object is a class that gives you full access to your processes at design time and runtime. It is automatically added to the Designer as a Variable

assigned to the main Sequence or Flowchart activity when you create a new project. Any project that will be hosting appCompass activities must make the

App object accessible from a top-level sequence activity containing the appCompass activities.

You can access the methods and properties of the App object directly. The

designer will accept conditions directly from the App object. This allows you to enter condition expressions such as App.IsActionResultValid while composing your

project.

appCompass includes several hundred editors to make the designer very easy to

use. Almost all of them rely on the App object to access data, get lists etc. If your project requires complex functions or conditions, you will be utilizing the

data held in the App object and the hundreds of methods to make your job easy. If you will be leveraging the appCompass Base activity or DataManager activity

to extend appCompass, the App object will also be invaluable since it gives you access to project values at design time and run time.

3.25 - Designer Hosting/Re-hosting appCompass comes in several editions including the Studio editions and the Visual Studio editions because the WF4 Designer which it utilizes can be easily re-hosted. You do not

need to know anything about hosting or re-hosting. It is automatically done for you in the appCompass Development product that you choose to use.


4. Accessing the Studio Environment

4.1 - Overview This chapter covers how you access your appCompass development environment. Whether you are using appCompass Studio or Visual Studio, you will need to run the

Integrated Development Environment (IDE) program to access the available features.

4.2 - Accessing appCompass Studio To access your version of appCompass Studio, double-click on the appCompass icon that

was installed on your desktop:

4.3 - Accessing Visual Studio To access Microsoft Visual Studio 2012 or higher as your appCompass development

environment, double-click on the Visual Studio icon that was installed on your desktop:

4.4 - Accessing appStrategy Workbench The appStrategy Workbench application is the administration and maintenance module for appStrategy’s software products. Most selections that you make from your

appCompass Development environment appCompass Studio will access software modules in appStrategy Workbench.

It is through Workbench that you will access options for managing your development process, and also for deploying your integration and business rules projects.

To access appStrategy Workbench, double-click on the icon that was installed on your desktop:


You can also access appStrategy Workbench directly from the Studio property grid window by clicking on the Workbench property icon:

Refer to the appStrategy Workbench User Guide for additional information while working on a selection that references Workbench.


5. appCompass Studio Overview

5.1 - Overview This section covers the appCompass Studio environment. It covers the main components of Studio including the toolbox, the designer, the property grid associated with the active

activity, the ribbon bar and the outline.

Toolbox The Toolbox shows the available workflow activities including the out-of-the-box WF activities and appCompass activities. The activities in the toolbox are grouped into

sections. When new activity assemblies are added to the appCompass bin folder, they are automatically included in the toolbox. The numbers of activity modules that can be included in the toolbox depends on whether you have installed the appCompass Data

Integration product or the appCompass Business Rules product.

Designer The Designer is the work surface for composing appCompass projects. It is the drag/drop environment on which activities are defined and connected to form the flow of

the process. To add a workflow activity to any part of the designer, drag it from the toolbox and drop it on the designer.

1

2

3

4

5

1

2


Property Grid

The Property Grid contains the properties of the currently active activity. It is through

the property grid that activity property values are defined and edited. To view the properties of any activity in the Designer, simply click on it.

Ribbon Bar The Ribbon at the top of appCompass Studio window includes three button tabs (Home, Settings, Deployment) with a number of group options detailed later in this document.

Outline

The outline view displays the activities sequence as a tree view; this is useful when

working on a complex integration project or when the number of activities is high.

5

4

3


5.2 - Features

5.2.1 – Application Menu Overview

You can access the main menu by clicking the top left button in appCompass Studio.


Option Description

Creates a new project

Imports an existing xaml file into the current database.

This can be a xaml file which was originally created by appCompass (e.g. in another project database)

Open a project by selecting from the list of projects in the current database.

Opens the last active project in the previous use of appCompass

Opens the list of all the recently accessed projects in the current

database

Saves changes made to the current project

Saves the current project under different name.

Saves all open projects in the Designer

Exports the currently active project in a XAML file. The xaml file

can then be imported into a different project database.

Closes the currently active project in the Designer

5.2.2 – Quick Access Toolbar

You can also access different features from the Quick Access Toolbar of the ribbon.

Icon Description

Save the currently active project

Save all projects currently open in the Designer

Open an existing project in the project database

Create a new project

To undo the last action or repeat it


5.2.3 - Overview of the Ribbon Tabs & Groups

You can access various features from the ribbon:

The Ribbon is divided into three tabs (Home, Settings and Deployment)

Home

Settings

Deployment

Studio "Home" tab:

Settings

Use the Modules button to select the activity modules to be included in the toolbox


Launch Workbench from Studio

Allows you to view, add or import detailed documentation for the current project in RTF format.

DataSources

Creates a new data source to be used in the project

Deletes a data source

Refreshes a data source (Recreation of metadata model if the data

model has changed)

Displays the list of data sources defined in the project database for

review or editing

Optionally allows you to check-in a data source in the current project

database into another project database.

Optionally allows you to check-out a data source in the current project

database from another project database.


Run

Displays a summary screen of the validation errors for the activities used in the

current project

Schedules the current project as a task in Windows Task Scheduler on the current

machine.

Runs the currently loaded project directly from appCompass Studio

Source Studio

Displays the Expression Builder for the definition of conditions that can be

used directly in control flow activities such as While, if, Switch etc.

Use for defining, modifying or deleting extension functions

Use for defining, modifying or deleting expressions

Use for defining, modifying or deleting condition extension functions

Use for defining, modifying or deleting condition expressions

Optionally displays the XAML generated for the project in the Xaml Viewer. You can also make changes directly to the xaml and it will be reflected in

the Designer.

View Logs

Displays a summary multi-tab window of the Project Run Details showing run instances, activity statistics, logs and other details about project

execution.

Displays the contents of the logs for the current project

Display counts (records read, updated, inserted, etc.) when running the

current project


Studio "Settings" Tab:

The following options allow you to access Workbench features:

Checks-In all data from the current project database to another

project database

Checks-Out all data from the current project database to another

project database

Locks an item (data source or other metadata) in the current project

Unlocks an item (data source or other metadata) in the current project

View, CheckIn or CheckOut projects in the current project database

View, CheckIn or CheckOut file definitions in the current project database

View, CheckIn or CheckOut data formats in the current project

database

View, CheckIn or CheckOut deployment settings in the current project

database


View, CheckIn or CheckOut global pick lists in the current project database

Purge log entries from the project database

Purge project run instances

Purge data source statistics

Studio “Deployment" Tab

Run - Deploy

Compiles the current project and creates the xcopy deployment folder

Deploys the project on an appCompass Enterprise Server

Opens the folders used by the system for input and output. The Input and Output folders are the defaults used when a full path is not

specified for file names. Project provides direct access to the directories created by Build XCopy

above


6. appCompass Visual Studio Edition Overview

6.1 - Overview This section covers the appCompass development environment running in Visual Studio 2012 or higher. It covers the main components including the toolbox, the designer, the property grid associated with the active activity and the outline.

Toolbox

The Toolbox shows the available workflow activities including the out-of-the-box WF activities and appCompass activities. The activities in the toolbox are grouped into

sections. Additional appCompass activities can be included in the toolbox from the appCompass bin folder. The numbers of activity modules that can be included in the

toolbox depends on whether you have installed the appCompass Data Integration product or the appCompass Business Rules product.

Designer

The Designer is the work surface for composing appCompass projects. It is the

drag/drop environment on which activities are defined and connected to form the flow of

1

2

3

1

2

4

5


the process. To add a workflow activity to any part of the designer, drag it from the toolbox and drop it on the designer.

Property Grid The Property Grid contains the properties of the currently active activity. It is through the property grid that activity property values are defined and edited. To view the

properties of any activity in the Designer, simply click on it.

Ribbon Bar

The Ribbon at the top of Visual Studio window buttons for managing the currently loaded

appCompass project in the designer.

Outline The outline view displays the activities sequence or flow chart as a tree view; this is useful when working on a complex integration project or when the number of activities is

high.

5

3

4


7. appCompass Activity Modules

The tables below shows the activity modules that are available in the system.

7.1 – System Activity Modules

The table below shows the WF4 activity modules that are utilized in appCompass:

Module Description Assembly

Control Flow Provides activities for controlling flow of

execution within appCompass projects.

System.Activities

Flowchart The Flowchart activities module

contains activities that you can use to

model your project using the Flowchart

model

System.Activities

Primitives The activities in the WF4 Primitives

module allow you to assign values,

delay execution, and invoke methods

System.Activities

7.2 – Base Activity Modules

The base activity modules are included in all versions of appCompass Data Integration Studio and appCompass Business Rules Studio and Visual Studio editions.


Core The appCompass Core activities module

includes activities that are used for initializing

your project, closing the project, executing

functions, calling other projects and more.

appCompass.Core.dll

Logs These are the activities used for logging.

appCompass.Logs.dll

Viewers Activities used for viewing values during test

runs of your project

appCompass.Viewers.dll

Record Activities used for managing record values

appCompass.Record.dll

List Activities for managing ad hoc lists and pick

lists

appCompass.List.dll


7.3 – Utility Activity Modules

The utility activity modules are included in all versions of appCompass Data Integration Studio and appCompass Business Rules Studio and Visual Studio editions.


Active directory

Users

Activities for managing Active Directory

Users.

appCompass.ActiveDirectory.dll

Automation Module for checking system and other

resource utilization, monitoring and

other automation functions.

appCompass.Automation.dll

File System Activities used for managing files and

directories, access control lists etc. on

the file system.

appCompass.FileSystem.dll


7.4 – SQL Activity Modules The SQL activity modules are included in all versions of appCompass Data Integration

Studio and appCompass Business Rules Studio and Visual Studio editions. They provide ODBC, OLEDB and native access to popular SQL database engines.


SQL OLEDB Provides SQL OLEDB access to data

sources.

appCompass.SqlOledb.dll

SQL ODBC Provides SQL OLEDB access to data

sources.

appCompass.SqlOdbc.dll

SQL Server Provides native connectivity to

Microsoft SQL Server databases.

appCompass.Mssql.dll

SQL Server

Compact Edition

Provides native connectivity to

Microsoft SQL Server Compact Edition

databases.

appCompass.MssqlCE.dll

Oracle Provides native connectivity to Oracle

databases

appCompass.Oradb.dll

IBM DB2 Provides native connectivity to IBM

DB2 databases.

appCompass.DB2.dll

MySQL Provides native connectivity to MySQL

databases.

appCompass.MySQL.dll

SQL Azure Provides native connectivity to SQL

Azure databases.

appCompass.SqlAzure.dll


7.5 – General Data Access Activity Modules The general data access activity modules are included in all versions of appCompass

Data Integration Studio and appCompass Business Rules Studio and Visual Studio editions.


Flat Files Provides activities for working with

text, multi-type text, CSV and flat xml

files.

appCompass.FlatFiles.dll

XML Provides activities for working with XML

files

appCompass.Xml.Main.dll

XML Messages Provides activities for processing xml

messages.

appCompass.Xml.Msg.dll

Microsoft Dynamics

CRM Online

Activity module for Microsoft Dynamics

CRM Online

appCompass.Mscrm2011.dll

Microsoft Dynamics

CRM 2011


CRM 2011.


Microsoft Dynamics

CRM 4


CRM 4.


Salesforce Activity module for Salesforce.com appCompass.Sforce.dll


7.6 – Business Rules Activity Modules The business rules activity modules are used only in appCompass business rules

projects. They are included only in appCompass Business Rules Studio and appCompass Business Rules Studio – Visual Studio edition.


Business Rules

Activities for

Microsoft Dynamics

CRM Online

Extended activity module for Microsoft

Dynamics CRM Online

appCompass.Mscrm2011.Rules.

dll

Business Rules

Activities for

Microsoft Dynamics

CRM 2011


Dynamics CRM 2011.


dll

Business Rules

Activities for

Microsoft Dynamics

CRM 4


Dynamics CRM 4.


dll

Business Rules

Activities for Active

Directory

Extended activity module for Active

Directory – Groups, Users, Computers,

etc.

appCompass.ActiveDirectory.R

ules.dll

Check the appCompass support portal for additional Business Rules activity modules.


7.7 – Add-On Activity Modules Add-on modules are purchased and installed separately. Add-on modules include SAP,

Microsoft Dynamics AX, SharePoint etc. Check appStrategy web site for a full list of add-on modules.

7.8 – Custom Activity Modules

You can also include your own activity modules in your appCompass projects. Refer to the Advanced Topics chapter for a general overview of the Custom Activity module sample project.


8. Adding Workflow Activity Modules to the Toolbox

8.1 – Adding Activity Modules to appCompass Studio

Toolbox To include appCompass activity modules in the appCompass Studio toolbox, click the Modules button from the Settings group of the ribbon bar of appCompass Studio and select the activity modules to include or exclude:


8.2 – Adding Activity Modules to Visual Studio Toolbox To include appCompass activity modules in the Visual Studio 2012 (or higher) toolbox,

follow the steps below:

Open any Windows Workflow Application or an appCompass Visual Studio project in Visual Studio 2012 or higher.

Click the right mouse button to display the context menu as shown below. Choose

the Add Tab option.

Add a new Tab named appCompass.Core


Select the appCompass.Core tab in the toolbox. Click the right mouse button

and select Choose Items... from the context menu.

The following window will be displayed:


Click the Browse… button to select the file appCompass.Core.dll from the install directory (C:\Program Files\appStrategy\appCompass 5.0\appCompass\bin). The

activities will be displayed in the tool box as shown below:

You can click the right mouse button on the actives to sort them alphabetically.

Follow the steps above to add other activity modules to the Visual Studio tool box. Below is the list of the base activity modules that you can add to the tool box before adding

other activity assemblies that you will require for your project:



Core appCompass Core activities. The

appCompass Core module is required.

appCompass.Core.dll

Logs These are the activities used for

logging.

appCompass.Logs.dll

Viewers Activities used for viewing values

during test runs of your project

appCompass.Viewers.dll

Record Activities used for managing record

values

appCompass.Record.dll

List Activities for managing ad hoc lists and

pick lists

appCompass.List.dll


9. Composing & Orchestrating appCompass Projects

9.1 - Overview

To compose data integration, migration and business rules projects, you utilize the activity modules that you have installed as in your version of appCompass.

9.2 - Using appCompass Studio Editions

To create your project, run appCompass Data Integration Studio or appCompass Business Rules Studio and drag-and-drop activities from the toolbox on to the designer. There are several sample projects in the Samples database that show examples of

completed projects.


9.3 - Using Visual Studio Editions

To create your project, run Visual Studio 2012 or higher and drag-and-drop activities from the toolbox on to the designer. There are several sample projects in the Samples

database that show examples of completed projects.

You can also use appStrategy Workbench to export appCompass projects to Visual Studio projects.


10. Creating a New Project Database

10.1 – Overview The configuration information, metadata, project xaml and other required data that

support your usage of appCompass are stored in a project database.

The project database can be of type SqlServerCe (compact version of SQLServer installed during the installation of appCompass) or defined in an enterprise database (SQL Server, Oracle, MySQL, IBM DB2, etc.). The type of database supported depends on the version

of appCompass that you have installed. appCompass Professional edition supports only SQL Server Compact Edition project databases.

If your project database will be used concurrently by more than one user at a time, it is recommended that you create the database on an enterprise database

such as Microsoft SQL Server, Oracle, MySQL, or IBM DB2.

10.2 – Creating a New Project Database in

appCompass Studio To create a new project database in appCompass Studio, run the appCompass Studio

product and the login window will be displayed as shown below.

Click the New button and the Create New Project Database window will be displayed.


10.3 – Creating a New Project Database in Visual

Studio

To create a new project database for use in your Visual Studio projects, run the appStrategy Workbench application and the login window will be displayed as shown

below.

Click the New button and the Create New Project Database window will be displayed.


In the “Create New Project Database” window below, enter a unique name for the new

project database, and follow instructions to complete other fields. The database type and connection string are required. Click on the Connection String button to define the

connection string to be used for accessing the project database.

The screenshot above shows the connection string created in case of a base SqlServerCe Click the OK button to proceed with creating the new project database.

Note:

appCompass SQL Server Compact Edition database files (“.sdf” extension) are stored in the following folders: Windows7/8:

C: \ ProgramData \ appStrategy \ Databases \ ProjectDatabases (C: \ Users \ All Users \ appStrategy \ Databases \ ProjectDatabases)

Windows XP/2003/2008: C: \ Documents and Settings \ Application Data \ All Users \ appStrategy \ Databases \

ProjectDatabases


11. Creating and Maintaining Deployment Settings

11.1 - Overview Deployment Settings are used throughout the system to determine the behavior of system operations at design time and also at runtime. This is a powerful feature that

allows you to pre-configure the environments for running the projects that you will be composing and orchestrating.

You can create any number of Deployment Settings in your project database.

11.2 - Using the Default Deployment Settings

When a new project database is created, the system automatically adds the following Deployment Settings into your project database as a starting point:

Deployment Setting Description/Usage Default This is the default Deployment Setting that is assigned when

you do not choose a specific deployment setting.

You can also use this as your main deployment setting if you are working on a small or medium sized project where the same computer will be used for development, testing and

deployment.

The Default deployment setting is required by the system. You will not be able to delete it.

Development If your organization follows the normal Development, Test,

Production cycle, you can use Development when you are developing your projects.

In this case you will set your connection strings, web service login credentials etc. to your development

computer/environment.

Test If you will be using a Test bed you can use this deployment setting for testing.

Production This is the out-of-the-box Deployment Setting for your

production environment. You and add to it or you can create a brand new one to suit your needs.


11.3 - Adding and Updating Deployment Settings

To add, change, or delete a Deployment setting, select “Deployment Settings” from the

“Settings” menu of the appStrategy Workbench application. The following window will be displayed:

When adding a new Deployment Settings record, you must add a unique name for the Deployment Server. Note that DeploymentSettings and DeploymentServer are used interchangeably.

Note that field descriptions are displayed at the bottom of the screen.

To Add a DeploymentSetting, click the “Add” button; enter the field values and click the “Save” button to add the new record to the project database.

To Change or Update a DeploymentSetting, select the specific entry, make changes to

the field values and click the “Save” button to update the values.

To Delete a DeploymenSetting select the specific entry and click the “Remove” button to remove the record from the project database.


12. Creating a New Project

12.1 – Overview The jobs you create for data integration and business rules are organized as specific

projects. Each project includes the workflow representation of the job, conditions, functions and other definitions required to run the job. Projects are stored in the project database. They can also be copied from one project database to another. appCompass

projects can be created, composed and orchestrated directly in appCompass Studio environments and also in Visual Studio 2012 or higher. On deployment machines,

appCompass projects and all associated metadata can be viewed using the appStrategy Workbench application.

12.2 – Creating a New Project in appCompass Studio

To create a new project in appCompass Studio, click the application menu button on the top left corner of the main appCompass window

and select New


The New Project window is displayed:

Enter the required information and click the OK button to create a new project.

Based on the selected options, any required Arguments, Variables or other initial entries will be automatically added.

Once created, you can then compose your project by adding the required

activities on to the Designer.


12.3 – Creating a New Project in Visual Studio To create a new appCompass project in Visual Studio, select Create New Visual Studio

Project from the Visual Studio Tools menu of appStrategy Workbench. The following window will be displayed:

Follow the screen instructions and click the OK button to create the project. In addition to creating the Visual Studio project folder, appStrategy Workbench

also creates the project information in the project database.

The Visual Studio Tools menu of appStrategy Workbench includes additional options for managing appCompass projects in Visual Studio. See the appStrategy

Workbench documentation for details.


13. Property Editors

13.1 – Overview The properties associated with activity assemblies are displayed in the property grid as

shown in the example below for the SendEmail activity:


The SendEmail activity features some of the property editors available in appCompass including the highlighted SourcedValue editor, the Collection editor and several dialog

editors designed to simply the configuration of the activity properties. In this chapter we will discuss the most commonly used property editors in appCompass.

13.2 – Drop Down Editors

appCompass uses drop down property editors to show lists of options from which the

user can select one.


13.3 – Collection Editors appCompass collection editors are used for entry of multiple items of a specific type.

When the collection property button is clicked, the collection editor window is displayed as shown below:

Option Description

Click the Add button to add an entry to the collection. To make

changes, click on the entry to select it and then make the changes.

Use the Up and Down arrow buttons to rearrange the entries.

Use the delete button to remove a specific row

Click the delete all button to remove all entries


13.4 – Dialog Property Editors appCompass utilizes dialog editors throughout the system for entry of property data. An

example is the Data File Definition window which is used for configuring the DataFileDefinition property of the InitializeCsvTargetFile activity (See the appCompass for Flat Files User Guide).


13.5 – SourcedValue Property Editors

SourcedValues are the most commonly used data types in appCompass and as such, SourcedValue property editors are the most commonly used property editors in appCompass.

Sourced Values in Property Grid Below are examples of Sourced Value controls on the property grid at design time:

Sourced Values in Mapping The example below shows Sourced Values in use for mapping. In this case the values

are coming from DataField, InternalFunction, ExtensionFunction, Concatenation and even HTML:


Sourced Value Editor Window

The example below shows the Sourced Value Editor window used for configuring a Sourced Value at design time:

The table below shows the different source and value options for SourcedValues.

Source Value

Boolean

0 (False) or 1 (True)

Concatenation

Value is a concatenation of project values

ConditionResult

Result of a condition extension function (returns True or

False)

Constant Value is exactly as specified

DataField Field of any source or target defined in the active activity

DataFieldExt Field of any source or target defined in the project

DataSourceFieldName Name of the selected field in the metadata model

DataSourceListEntryValue A list entry defined for a data source. For example, this option allows you to associate the value to a SharePoint

list. The various lists available are: SharePointListTemplate, SharePointSiteTemplate, SharePointSiteUser, SharePointSiteGroup,

SharePointSiteRole, SharePointSiteUserEmail and SharePointSiteUserLogin


DeploymentServerField Value defined for the currently active DeploymentServer. DeploymentServer fields allow you to define values that

are specific to each deployment environment. This is especially useful when the value changes from one

deployment environment to another – (for example, file location, connection strings etc.)

Date A date entry or date-related value

DateTime A date / time entry or datetime-related value

ExtensionFunction Value from an ExtensionFunction.

FileContent Value from a file. This option reads the entire contents of the file as the value to use.

FilePath Gets a file path

FileRecordSubString Gets a sub string from a text file record

FolderPath Gets a folder path

InternalFunction This option sets the value based on the performance of a function (see section Function Editor)

HTML HTML value

HTMLWithMergeFields HTML value with project fields merged in

LongString Gets the value of a long string

Password Get a password value (encrypted)

PickListEntry Picklist value

PickListEntryDescription Description of specific Picklist value

PrimaryKey Value is primary key of the selected entity of a data source

ProjectVariable If the project uses an InitializeProject activity, this

Source gets the value of a pre-defined ProjectVariable

RecordCount Value is the count of records in a Source

Text Text value


TextWithMergeFields Text value with project fields merged in

WorkflowActivityName Value is the display name of an activity name from the current project

WorkflowArgument Value is an argument passed to the project

WorkflowDataManagerName Value is the display name of a selected Source or Target

activity

WorkflowName Value is name of a project in the current project database

WorkflowServerValue Gets a specific server value

WorkflowVariable A variable defined in the project


13.6 – Other Property Editor Dialogs

In this section we will review a few of the many dialogs used in appCompass for entering required property values.

13.6.1 – Custom Query Editor

Depending on the module, appCompass displays the appropriate window for entering

custom queries for selecting records. Note: the standard InitializeSource activity does not require a custom query as it is automatically generated. The example below shows the Custom Query Editor for the SQL Server SqlClient connector.


13.6.2 – Concatenation Editor

The Concatenation Editor window is displayed for concatenating values. To include

project values in the concatenation, click the Insert button.


13.6.3 – Html Editor

The Html Editor is displayed for the entry of field values for your project as shown below. The editor allows you to enter HTML or text directly.

Text mode is the default. The top button bar provides options for changing colors,

inserting images, selecting fonts, indentation, alignment etc.

When the selection is HtmlWithMergedFields, you can use the “Insert” button to include project values in the html document.


To enter the html "code mode", click the top right toolbar button

NB: If you have created your html page outside of the editor, you can copy paste

the html directly into the editor and insert project values if needed.


14. Using Data Source Metadata in appCompass

14.1 – Overview

appCompass utilizes metadata of your data bases, files, CRM and ERP data sources to speed up development of your data integration and business rules projects. Most data

source metadata can be created in appCompass during initialization of Source and Target data sources.

During metadata creation, the system connects to the data source to retrieve the metadata which is then stored in your project database for local use during development

of your projects. This feature allows you to continue development of your project even when you are disconnected from the data source.

14.2 - Creating Data Source Metadata To add, change, refresh, or delete a data source, click the DataSource button of the Connector Configuration window of the data source – the following window will be displayed:


To Add a data source, click the “Add” button; the data source creation window described below will be displayed.

To Change or update a data source, select the specific entry, make changes to the field values and click the “Save” button to update the values.

To Delete a data source, select the specific entry and click the “Remove” button to remove the data source from the project database. To Refresh a data source, select the specific entry and click the “Refresh” button to

refresh the data source.

When the Add button is clicked, the sample screen below is displayed for adding a new

SQL Server metadata:

Enter a unique name for your SQL Server data source, select the SQL Server Data

Source Type, and click the OK button to continue with metadata creation.


14.3 – Metadata Browser Once created, you can browse the metadata from your data source at any time. You can

also refresh the metadata.

14.3.1 – Browse Data Source Summary


14.3.2 – Browse Data Source Entities / Tables


14.3.3 – Browse Entity Fields / Attributes


15. Working with Data File Definitions

15.1 – Overview The appCompass Flat Files module includes several activities for working with database

files. The appCompass Flat Files module includes connectors for CSV, Text and Flat Xml files. Refer to the appCompass Flat Files User Guide for more information regarding the Flat Files module.

In this chapter we will review the creation of Data File Definitions which can be used by the appCompass Flat Files module. When working with comma separated (CSV) files, the appCompass.FlatFiles module supports automatic field discovery. When working with

non-delimited text files, you will need to define the fields in the file to use them as part of your data integration and business rules projects. In addition, there are also projects

that require that you predefine CSV file fields.

The File Definitions tool in appStrategy Workbench which can be accessed from your Studio environment, allows you to define and maintain file definitions. Once defined,

these definitions are used in your development environment for selecting file fields and other values to be used at runtime. The definitions are also reusable and thus can be

used in an unlimited number of projects.


15.2 - Adding and Updating File Definitions

To add, change, or delete a File Definition, select “File Definitions” from the “Settings” menu of the Workbench application. The following window will be displayed:

When adding a new FileDefinition, you must add a unique name for the FileDefinition.

To Add a FileDefinition, click the “Add” button; enter the field values and click the “Save”

button to add the new record to the project database. To Change or Update a FileDefinition, select the specific entry, make changes to the field

values and click the “Save” button to update the values. To Delete a FileDefinition, select the specific entry and click the “Remove” button to remove the record from the project database.

Once defined, you can access the File Definition in the appCompass.Flat Files module.


16. Using Conditions in appCompass Projects

16.1 – Overview

There two types of conditions in use in appCompass. The first is the condition required to control the flow of your workflow. The control flow conditions are mostly used by the

Windows Workflow (WF4) designer and runtime. These conditions are required by workflow activities such as DoWhile, If, and While etc. to control the flow of your workflow.

The second type of condition is used by in general by the appCompass system. The

system allows you to use conditions extensively to add flexibility to your processes. For example when defining filters for selecting data from a source, you can use a condition to decide whether to include a filter item or not. Another example involves field maps –

which allows you to use a condition to decide whether to map a data field or not.

In addition to the conditions that you define, appCompass also includes several built-in conditions that you can select on demand.

16.2 – Control Flow Conditions Control flow conditions are mostly defined on the Designer. To define a condition for a

control flow activity (e.g. While), drag the control flow activity on to the designer.


Enter the condition in the textbox provided. If you are running appCompass in Visual

Studio, you can also use intellisense the complete the condition. You can define a more powerful condition by using the appCompass Express Builder.

Access the Expression Builder as follows:

Accessing the Expression Builder in appCompass Studio Click the Expression Builder button from the Source Studio group of the appCompass Studio ribbon bar, and the Expression Builder will be displayed.

Accessing the Expression Builder in Visual Studio Click the Workbench property icon on the property grid. Select Expression

Builder from the Visual Studio Tools menu and the Expression Builder will be displayed.


16.3 – The Expression Builder

Complete the expression to the right of the conditionResult variable. This is the value that will be passed to the workflow activity. Any valid statement can be entered. You

can type a “.” right after the App variable to use intellisense to browse the methods and properties of the App object to be included in the expression. You can also click the

“Insert Parameters” button to include values from the workflow as method parameters in your condition expression.

Copy the expression to the clipboard:

Click on the Copy to Clipboard button to copy the condition to the clipboard

Paste the condition into the Condition property of the workflow activity:

If the condition is valid, it will be accepted by the designer. If the condition is not valid, an error flag and message will be shown.


16.4 – Defining Condition Expressions

You can define expression conditions that can be used just like conditions created in the

Expression Builder. Unlike the Expression Builder which creates an expression that can be pasted into the condition property of a control flow activity, when you define an expression condition, it is saved in the project database so that you can select it to be

used anywhere in the workflow.

To define a Condition Expression, display the Condition Expressions window as follows:

Defining Condition Expressions in appCompass Studio

Click the Condition Expressions button from the Source Studio group of the

appCompass Studio ribbon bar.

Defining Condition Expressions in Visual Studio

Click the Workbench property icon on the property grid. Select Condition Expressions from the Visual Studio Tools menu.


Click on the New button to add a new Expression. The following screen will be

displayed:


Enter a valid name and short description for the expression and click the OK button. The Condition Expression Editor window will be displayed:

Complete the expression to the right of the conditionResult variable. This is the value that will be saved in the project database. Any valid statement can be entered. You can type a “.” right after the App variable to use intellisense to browse the methods and

properties of the App object to be included in the expression. You can also click the “Insert Parameters” button to include values from the workflow as method parameters in

your condition expression. Click the Save button to save the Condition Expression in the project database.


16.5 – Defining Condition Functions

You can define more powerful conditions for your projects by using Condition Functions

instead of condition expressions by using Condition Functions. Condition Functions allow you to define complete functions with arguments and full access to all workflow activities, variables, arguments and other items in your project.

To define a Condition Function, display the Condition Functions Editor window as

follows:

Defining Condition Functions in appCompass Studio

Click the Condition Functions button from the Source Studio group of the

appCompass Studio ribbon bar.

Defining Condition Functions in Visual Studio

Click the Workbench property icon on the property grid. Select Condition Functions from the Visual Studio Tools menu.


Click the New button to add a new Condition Function. The following screen will be displayed:


Enter a valid name, short description for the function, function arguments if applicable and click the OK button. The Condition Function Editor window will be displayed:

Enter C# or VB statements to complete the function. You can use the built-in intellisense

to browse the App object to select methods and properties to include in the function, and click the “Insert Parameters” button to include values from the workflow as method

parameters. At any time, you can also use the Validate button to validate the function. To include external assemblies in the function, click the External Assemblies button.

Once selected, you can then access methods in the assembly.

Click the Save button to save Condition Function in the project database.


17. Using Functions in appCompass Projects

17.1 – Overview You can utilize functions to set values in your appCompass project. appCompass

includes several internal functions. In addition, you can define your own functions using the Extension Function Editor.

17.2 – Internal Functions

appCompass includes several internal functions that you can use to set field values or to perform transformation. Internal functions are built into the system and do not require

any code to use them. For example, to set a property value on the property grid using an internal function,

select InternalFunction and then click on the button to select the internal function and specify values for the function arguments if required.

Below are the available internal functions:

Function Name Description

GetValueFromDelimitedString

Gets a value from a string delimited by a single

character using 0-origin index

ConcatenateStrings Concatenates strings.

GetEmptyString Gets an empty string

StringInsert Inserts a string at a specified index position in the

source string (0 origin)

StringPadLeft Pads a string on the left with a specified character

StringPadRight

Pads a string on the right with a specified character

StringReplace Replaces all occurrences of an old string value with

new string value.


StringReplaceWithEmptyString Replaces all occurrences of an old string value with

an empty string value

StringToLower Converts a string to lowercase

StringToUpper Converts a string to UPPERCASE

StringFirstLetterToUpper

Converts the first letter of a string to UPPERCASE

StringRemove Removes characters in a string starting an index

position (0 origin)

StringTrimAll Removes all whitespace from a string

StringTrim Removes a specified character from a string

StringTrimEnd Removes all trailing occurrences of a specified

character from a string

StringTrimStart Removes all leading occurrences of a specified

character from a string

StringSubstring Gets a substring from a string starting at an index

position (0 origin)

StringSubstringOfLength Gets a substring of a specified length from a string

starting at an index position (0 origin)

StringRegex Within the source input string, replaces strings that

match a regular expression pattern with a specified

replacement string.

GetYearWeekNumber Gets the number of the week in the year

GetDateToday Gets today's date

GetDateYesterday Gets yesterday's date

GetDateTomorrow Gets tomorrow's date

GetDateThisDayNextYear Gets this day next year (date)

GetDateThisDayLastYear Gets this day last year (date)

GetDateThisDayNextMonth Gets this day next month

GetDateThisDayLastMonth Gets this day last month

GetDateThisYearStart Gets this year's start date


GetDateThisYearEnd Gets this year's end date

GetDateThisMonthStart Gets this month's start date

GetDateThisMonthEnd Gets this month's end date

GetDateThisDayNextWeek Gets this day next week

GetDateThisDayLastWeek Gets this day last week

GetDateTimeNow Gets the current Date/Time

GetYearFromDate Gets the Year (integer) from the date

GetMonthFromDate Gets the Month (integer) from the date

GetDayFromDate Gets the Day (integer) from the date"

SetTimeForDateTime Uses the hours and minutes specified for a date to

set the time for the DateTime value

GetNumberOfDaysBetweenDates Calculates the integer number of days between two

dates

GetNumberOfHoursBetweenDate

Times

Calculates the number of hours between two

date/time values

AddDaysToDate Adds (or subtracts) the specified number of days to

a date

AddMonthsToDate Adds (or subtracts) the specified number of months

to a date

AddYearsToDate Adds (or subtracts) the specified number of years to

a date

GetUniqueKey Gets an RNGCryptoServiceProvider-based unique

key

GetGuidKey Gets a GUID-base unique key

GetTimeStampKey Gets a TimeStamp key


17.3 – Extension Functions Extension functions provide a powerful optional feature for extending appCompass

projects in an unlimited number of ways. appCompass provides several options for executing extension functions. Extension functions allow you to write code that is managed by, stored in and compiled by appCompass. It provides a hassle-free

environment for connecting platforms to any platform, data source or legacy system by using very little code C# or VB code. Most of the interface methods that you will need

for sharing data with appCompass are already in the App object which is automatically included as a variable in your project. In most cases, your code will simply be making

calls to the App object.

Once created, the extension function can be used to perform any task or to set values in your project.

To define an Extension Function, display the Extension Functions window as follows:

Defining Extension Functions in appCompass Studio

Click the Extension Functions button from the Source Studio group of the appCompass Studio ribbon bar.

Defining Extension Functions in Visual Studio Click the Workbench property icon on the property grid. Select Extension

Functions from the Visual Studio Tools menu.


The following screen will be displayed:

Click the New button to add a new Extension Function. The following screen will be displayed:


Enter a valid name, short description for the function, function arguments if applicable and click the OK button. The Extension Function Editor window will be displayed:

Enter C# or VB statements to complete the function. You can browse the App object using intellisense to select methods and properties to include in the function. Click the Insert Parameters button to include values from the project as method parameters. At

any time, you can also use the Validate button to validate the function.

Click the Save button to save the extension function in the project database.


18. Using External Assemblies in Functions

18.1 – Overview appCompass provides a non-technical option for adding external assemblies to the

Extension Functions and Condition Functions that you create for your projects using appCompass Studio or Visual Studio. For Visual Studio users, a more powerful option which is discussed in the chapter on Creating Your Own Activity Assemblies allows

you to reference external assemblies as you would when you develop other .Net assemblies. In your own activity assemblies you get full control of not only the

appCompass environment but the familiar .Net environment also.

18.2 – Adding External Assemblies To add an external assembly for use in your extension function or condition function, display the Function Editor as described in the previous chapter.


Right click on the external assemblies list box in the function editor window as shown above. Select Add Assembly from the context menu to browse the file system and

select the assembly to add. Once assemblies are added, you can then access methods and objects in the assemblies

in your function.

To remove an assembly from the function, right click on the assembly on the assemblies list box to display the context menu. Select Remove Assembly from the context menu

to remove the selected assembly.


19. Reading Data

19.1 - Overview

Your appCompass projects may require reading data from files, data bases, SAAS applications and other sources. appCompass activity modules include activities for

initializing Sources for reading data. For example, the appCompass SQL Server module features the InitializeMssqlSource and InitializeMssqlSourceFromQuery activities. Once

initialized, you can use the GetNextMssqlRecord activity to read the next record from the result set in the Source.

19.2 - InitializeSource Activity

The appCompass InitializeSource activity is used for initializing the Source. For example, to read data from Microsoft SQL Server, you will need to initialize the Source of

the data, select the connector to use and define filters for specifying the records to read. At design time, you can also get a count and view the records defined by the Source that

you have defined.

For example, to define the Source for reading SQL Server data source, drag the

InitializeMssqlSource activity on to the designer and configure the properties as follows:


Property

Description

Connector Select the connector to be used in this Source for reading SQL Server

records.

Follow the on-screen instructions to select the Connector Type,

Connection Option and other values. The connector types include; appCompass.Data.Sql.SqlClient,

appCompass.Data.Sql.Oledb, appCompass.Data.Sql.Odbc

PrimaryEntity Select the primary SQL Server table from the list.


RelatedEntities Use this property to include related tables in the result

AutoLoad This property is defaulted to FirstRecord which loads the first record

from the list of records that meet the filter criteria. Other options include AllRecords which allows you to utilize preloaded records for

tables with a small number of records. AllRecords option is especially useful if you will be performing a lot of lookups from the table.

AutoRecordCount Whether to automatically count the number of records.

DataFields Select the data fields to be returned from SQL Server. If no data fields

are specified, all fields are returned.

FilterItems You can optionally use this property to define the criteria for selecting

the entity records to be included in the result set.

SortItems You can optionally use this property to define how the records in the Source are to be sorted.


RecordCount Displays a count of the records that meet the criteria defined by the

FilterItems property. If no filter is defined, the count of the total number of records in the table is displayed. This is a design time feature that gives you the number of records in the list.

Records Displays a list of the records that meet the criteria defined by the FilterItems property. If no filter is defined, browsing starts at the first record in the list. This is a design time property for viewing table

records before running your project.


19.3 - InitializeSourceFromQuery Activity

In addition to the standard Source initialization activity defined in the previous section,

you can also optionally use a query to define the Source to be used for reading records if the appCompass module includes the InitializeSourceFromQuery activity. For example, to use a query to read data from SQL Server, use the

InitializeMssqlSourceFromQuery activity:

For example, to define the Source for reading SQL Server data source, drag the appropriate InitializeSourceFromQuery activity on to the designer and configure the

properties as follows:


Property

Description Connector Select the connector to be used In this Source for reading SQL Server

records.

Follow the on-screen instructions to select the Connector Type, Connection Option and other values.

Query Enter the query to be used for selecting the records:


AutoLoad This property is defaulted to FirstRecord which loads the first record from

the list of records that meet the criteria. Other options include AllRecords which allows you to utilize preloaded records for entities with a small number of records. AllRecords option is especially useful with you will be

performing a lot of lookups from the entity.

AutoRecordCount Whether to automatically count the number of records.

RecordCount Displays a count of the records that meet the criteria defined by the FilterItems property. If no filter is defined, the count of the total number of

records in the entity is displayed. This is a design time feature that gives you the number of records in the list.

Records Displays a list of the records that meet the criteria defined by the

FilterItems property. If no filter is defined, browsing starts at the first record in the list. This is a design time property for viewing entity records

before running your project.


19.4 - GetNextRecord Activity

To read the next record from an open connection in appCompass, you use the

GetNextRecord activity from the appropriate activity module. For example, to read the next record from a SQL Server data source, drag and drop the

GetNextMssqlRecord activity on to the designer. The only property required is the Source.


20. Looking up Data

20.1 - Overview

appCompass includes activities for looking up data from data sources. Lookups provide a convenient means of reading a specific record from the data source. You can also use the Lookup activities to verify existence of a record in the data source.

20.2 - LookupRecord Activity

The LookupRecord activity returns a specific record from a data source. It uses the same properties as the as the InitializeSource activity discussed in the previous

chapter. For example, the appCompass SQL Serve module features the LookupMssqlRecord.

20.3 - LookupDataFieldValue Activity

Some appCompass activity modules feature the LookupDataFieldValue activity which

reads a single data field from the data source. For example, the SQL Server module features the LookupMssqlDataFieldValue activity data source. It also requires only a

single data field as the filter.

20.4 - LookupPreloadedRecord Activity

The appCompass InitializeSource activities can be configured to load records into

memory. If an activity module supports preloading of records, a record can be loaded from the list by using a LookupPreloadedRecord activity. For example, to lookup a preloaded SQL Server record, use the LookupPreloadedMssqlRecord activity.


21. Using PickLists

21.1 - Overview

appCompass includes activities for managing data source picklists defined in the Workbench application.

The activities are in the appCompass.List module (see appCompass Base Activities User Guide):

- LookupPickListRecord

- IsPickListValueValid PickLists can be entered manually or generated automatically when data source

metadata is created. For example, when a Microsoft Dynamics CRM data source is created, the system automatically creates the picklists for all entities.


21.2 – The LookupPickListRecord Activity

The LookupPickListRecord activity which is part of the appCompass List module, allows you to load the values of a picklist into a record. The record values (key/description) can then be used in the running project just like other values.

21.3 – The IsPickListValid Activity

The IsPickListValid activity which is part of the appCompass List module, checks whether a value belongs to a picklist. The value can be the key or description of the

picklist. The activity returns Valid or Invalid and can be tested with an App property as in App.IsActionResultValid.


22. Mapping Data Field Values

22.1 – Overview Mapping in appCompass is unlike mapping in legacy ETL tools. In appCompass, mapping

is another option for setting record values before each record is saved. You can compose projects that do not utilize any mapping to set record values as you can use extension functions and other options to set data field values. In addition, you can also use the

SetValues, TransformValues, ClearRecord and CopyRecord activities from the appCompass.Record module to set record values. However, the MapAndSetFields

activities are the most commonly used method of setting record field values in appCompass projects.

22.2 – The MapFields Activity

Most modules in appCompass include a MapFields activity for mapping. For example, to map Dynamics CRM entity attributes, drag and drop the MapAndSetFields activity on to

the designer. Below is the property grid for the activity:


Select a Source and Target then click on the FieldMaps property button. The Field Mapping window will be displayed:

The MapFields window shows the fields in the entity. Fields required by Microsoft

Dynamics CRM are flagged. Use a Source / Value combination to populate the field values. You only need to map the fields that you wish to include and the required fields. Over fifty built-in Source/Value options are available including DataField (to set the field

from the Source if one was selected) and ExtensionFunction (to set the field from a function). A Transform option can be selected to transform a mapped field before it is

included in the record. You can utilize any number of MapAndSetFields activities to set values in any number of Targets in your appCompass projects.


22.3 – The Field Map Detail Window The Field Map Detail Window shows the fields in the Field Mapping Window in a detailed

format. To display a row in the Field Mapping window in a detail window, double-click on the row. The following window will be displayed:

You can make changes to the field values and click the OK button to update the row in

the Field Mapping window.


22.4 – Transforming Field Values

The Field Mapping window and the Field Map Detail window both include an option to

transform the data field value. The following are transformation options are available:

Name Description

ApplyKeyValue Returns the value of the key to a table or entity in

the target field according to specified filters

ApplyPicklist Returns the value or description of a picklist by filtering a value or description

Base64Decode Decode content stored in base64 (ex: File attachment in Dynamics CRM – annotation entity)

Base64Encode Encode content for storage in base64 (see above)

Concatenate Concatenates multiple values (using the

concatenation editor) into one field

Convert Convert a text field into numeric format

ConvertHtmlToPlainText Converts an encoded html content into a text value

CurrencyFrom Returns a value of type integer or decimal from a

currency in (CRM4/2011)

CurrencyTo Turns a value of type decimal or integer in currency

(CRM4/2011)

DateTimeAddTimeSpan Adds a number of days / hours / minutes / seconds to a given date / time value

DateTimeSubstractTimeSpan Subtract a number of days / hours / minutes / seconds to a given date / time value

DateTimeUnixTimeToDateTime

Converts a Unix date format into a windows date / time value

DateTimeToUnixTime Converts a date / time value windows to Unix date/time

DateTimeddmmyyyytoyyyymmdd

Converts a date DD / MM / YYYY date to YYYYMMDD

DateTimemmddyyyytoyyyymmdd

Converts a date in MM / DD / YYYY date to YYYYMMDD

Expression Use a custom expression to transform a value

ExtensionFunction Use a custom extension function to transform a

value

NumericAddValue adds value to the target field

NumericDivideByValue to divide a value by the target field

NumericMultiplyValue Multiply the target field by a value

NumericSubstractValue Subtract a value from the target field

None No transformation to apply

ReplaceFieldValue Replaces a string value in the target field


SetValue Sets the value of a target field

SetValueToNull Assigns the value NULL to a target field

SetValueToEmptyString Assigns an empty string to the target field

StringLowerCase Switches all characters of a value to lower case

StringPadLeft Pads the target field with are certain number of

spaces to the left

StringPadLeftWithValue Pads target field to the left with value

StringPadRight Pads target field to the right

StringPadRightWithValue Pads target field to the right with value

StringProper Transforms a string to proper casing (first character in uppercase )

StringRegEx Assigns a new value to the target field by using Regex

StringSubstring can extract a portion of a string

StringTrim Removes spaces at the beginning and end of the target field

StringTrimLeft Removes leading spaces from the target field

StringTrimRight Removes trailing spaces from the target field

StringUpperCaseAll Converts all characters in target field to upper case

StringUpperCaseFirstLetter Convers the first letter of a target field to upper

case

Unformat Removes formatting from a target field


23. Writing Data

23.1 - Overview Your integration and business rules projects will be writing data to files, databases and SAAS, and other targets. appCompass includes activities for writing data in SQL Server.

23.2 - InitializeMssqlTarget Activity

To write data to an appCompass target, you will need to initialize the Target of the data, select the connector to use and define other properties using the InitializeTarget activity.

For example, to write data to Microsoft SQL Server, drag and drop the

InitializeMssqlTarget activity on to the designer.

Configure the properties as follows:


Property

Description

Connector Select the connector to be used In this Target for writing SQL Server records.

Follow the on-screen instructions to select the Connector Type,

Connection Option and other values.

HighPerformance Option

By default the HighPerformance property is set to Disabled. Click the property button to enable high performance processing. The default

value of “Disabled” works fine for SQL Server projects.

High performance processing is discussed in detail in the next section.


23.3 - Configuring the High Performance Options

You can set the HighPerformanceOption property of the InitializeTarget activity to optimize writing of data. When the HighPerformanceOption property button is pressed,

the following window is displayed:

Follow the on-screen instructions and the field descriptions below to set the

HighPerformOption:

High Performance Option Select the option to use from the list below:

Option

Description

Disabled This is the default setting. Optimized settings are not

utilized when writing records to the target.

Enabled Enables basic optimization for writing records. This is the most commonly used option for optimizing performance.

EnabledForStaging This option saves the records in the RecordStaging table

from where you can employ multiple projects utilizing multi-threading to process the records. You can also use

this option for testing purposes – when you do not want to write directly to the target.


Include

Use the checkboxes to select the type of transactions to include as part of high performance processing – Deletes, Inserts, and Updates.

Cache Size / Number of Threads Set the cache size and number of threads to use for processing the records. You can use

the default values or test other values depending on your system configuration (CPU, memory, etc.). By caching the records and using multiple threads, appCompass

optimizes the writing of records to the target.

OnRecordActionCompletionFunction

You can specify the function to run after each record is processed. This field is optional.

BatchCompletion

You can specify the function to run after processing each batch of records. This field is optional.


23.4 - Setting Data Field values for the Active Record

Before writing records in the target data source, the values of the data fields of the active record must be set.

The table below shows the activities that can be used to set the data field values of the

active record:

Activity Module Notes

MapAndSetFields Supported in

appCompass activity modules such as SQL

Server, Dynamics CRM etc.

Any number of MapAndSetFields

activities can be used to set data field values.

Field mapping was described in detail in the previous chapter.

SetValues appCompass.Record

Any number of SetValues activities can be used to set data field values

ClearRecord appCompass.Record Clears the active record

CopyRecord appCompass.Record Copies field values from another Source or Target record to the active record

TransformValues appCompass.Record Transforms data field values in the active record

MapFields appCompass.Core Use the MapFields activity for

bulk imports. This activity takes a source and a target and automatically reads all the

records into the target.


23.5 - Inserting Data

Once the data field values in the active record have been set, you can save the new record in the target by using the InsertRecord activity. For example, to insert record

into SQL Server, drag and drop the InsertMssqlRecord activity on to the designer.

Unless you are defining the field values directly in this activity by using the DataFieldValues property, the only required property is the Target. All other properties

are optional. The ErrorLogSource and ErrorLogValues properties are used when you want to perform extensive logging.

At run time the InsertMssqlRecord activity saves the record in SQL Server.


23.6 - Updating Data

Existing records can be updated using the UpdateRecord activity. For example, to update a SQL Server record, drag and drop the UpdateMssqlRecord activity on to the

designer.

Unless you are defining the field values directly in this activity by using the

DataFieldValues property, the only required properties are is the Target and RecordKey or CompositeKey. All other properties are optional. The ErrorLogSource and ErrorLogValues properties are used when you want to perform extensive logging.

At run time the UpdateMssqlRecord updates the record in SQL Server.


23.7 - The UpsertRecord Activity

The UpsertRecord activity combines the InsertRecord and UpdateRecord activities.

For example, to use the UpsertRecord activity from the SQL Server module, drag and drop the UpsertMssqlRecord activity on to the designer.

At run time, if the record exists, it is updated. If the record does not exist at run time, it is inserted into the SQL Server table.


23.8 - Deleting Records

The DeleteRecord activity is used for deleting records from a target. For example, to

delete a record from SQL Server, drag and drop the DeleteMssqlRecord activity on to the designer. To delete a record, the record key is required.

The only required properties are is the Target and RecordKey. All other properties are

optional. The ErrorLogSource and ErrorLogValues properties are used when you want to perform extensive logging.

At run time, if the record exists, it is deleted from the SQL Server table.


24. Executing Stored Procedures

24.1 - Overview

appCompass supports the execution of stored procedures. For database engines that support stored procedures, appCompass includes the ExecuteStoredProcedure activity

for executing stored procedures. If the stored procedure returns records, the records and the fields they contain can be read from the database and utilized in appCompass

just like any other records and fields.

24.2 - ExecuteStoredProcedure Activity

For example, to execute a stored procedure in SQL Server, drag and drop the

ExecuteMssqlStoredProcedure activity on to the designer and configure the properties.


Property Description

Connector Click to property button to configure the connector to select the data source

and other connection values.

StoredProcedureType Select the type of stored procedure indicating the type of result returned.

StoredProcedure The name of the stored procedure

StoredProcedureFields This collection property specifies the data fields in the stored procedure. Only

the field name and field type is required when defining the field. The field

name must match the column name used in the stored procedure.

StoredProcedureParams If the stored procedure uses parameters, specify them with this collection

property.

AutoLoad Use FirstRecord to read the first record from the stored procedure or

AllRecords to read all records.

TestRunParameters Design time property to get stored procedure parameter values.

RecordCount Design time property to get the record count if the stored procedure returns

records.

Records Design time property to view the records if the stored procedure returns

records.


25. Validating appCompass Projects

25.1 – Overview One of the key features of appCompass is that the system provides several options for

validating activities on the designer, functions, expressions, data source metadata and other items used in the development of your data integration and business rules projects.

25.2 – Design Time Validation Whether you are using appCompass Studio or Visual Studio, at design time, appCompass

flags all activity errors on the designer. You can mouse over the error flag to view the error message. As each error is corrected, the error flag is removed.

25.2.1 – Design Time Validation on appCompass Studio

At design time, appCompass Studio flags all activity errors on the designer as shown below:


25.2.2 – Design Time Validation on Visual Studio

At design time, appCompass flags all activity errors on the Visual Studio designer as

shown below:


25.3 – Detailed Validation of appCompass Projects At any time, you can perform a detailed validation of your appCompass data integration

and business rules project. To perform a detailed project validation, display the Project Validation window as follows:

Detailed Project Validation in appCompass Studio

Click the Validate button from the Run group of the appCompass Studio ribbon

bar.

Detailed Project Validation in Visual Studio

Click the Workbench property icon on the property grid. Select Validate Project from the Visual Studio Tools menu.

The Validate Project window is displayed showing several tabs that list items in the project and showing all errors:


26. Running Data Integration & Business Rules

Projects

26.1 - Overview Data integration and business rules jobs are run just like any other jobs using appCompass. Your

Dynamics CRM integration project most likely includes activities from other modules such as the

SQL Server module, the Flat Files module and other modules.

26.2 - Running on appCompass Studio

You can run your Data Integration and Business Rules jobs directly from your appCompass Studio

environment as follows.

Development Environment Run Option

appCompass Data Integration Studio Click the Run button

appCompass Business Rules Studio Click the Run button

Visual Studio 2012 or Higher Click Start button

26.3 - Running on Visual Studio Editions

You can run your Data Integration and Business Rules jobs directly from Visual Studio your Studio

environment.

Development Environment Run Option

appCompass Data Integration Studio Click the Run button

appCompass Business Rules Studio Click the Run button

Visual Studio 2012 or Higher Click Start button


27. Deploying appCompass Projects

27.1 - Overview

Once you are done with composing and orchestrating your project you can run it directly

on any computer that has a valid license – regardless of the type of product installed. The most cost-effective deployment product for deploying your projects is appCompass Express since it allows you to execute from an XCopy folder. You can also deploy to an

enterprise server running appCompass Enterprise server software.


27.2 - XCopy Folder Deployment and appCompass

Express

An xcopy folder is an install folder created by Workbench that is ready to run on

any computer with an appCompass license. The ideal deployment product for running and managing your xcopy deployment is appCompass Express.

To create an XCopy folder, select “Build XCopy Deployment” from the Deploy/Run menu of the Workbench application. You can also run this option from your Studio

product if it is available. The following window will be displayed:

Follow the on-screen instructions and click the “OK” button to create the XCopy folder. The XCopy folder will include everything you will need (including a fresh project

database), to run your projects on any computer with .Net 4.0 or above installed. All that is required is a valid license.


27.3 - Copy Project Database to Deployment Server

If you have installed an appCompass Enterprise server, you can also deploy your project database for use on the server by copying it directly from your current database (preferably your Test database).

To copy your project database to a deployment server, select “Copy Project Database to

Deployment Server” from the Deploy/Run menu of the Workbench application. You can also run this option from your Studio product if it is available. The following window will

be displayed:

Follow the on-screen instructions and click the “OK” button to copy the project database to the selected deployment server.


28. Scheduling Data Integration & Business

Rules Jobs To schedule a data integration or business rules job, display the job scheduling window as follows:

Scheduling Jobs in appCompass Studio

Click the Validate button from the Run group of the appCompass Studio ribbon

bar.

Scheduling Jobs in Visual Studio

Click the Workbench property icon on the property grid. Click Schedule Job from the Deploy/Run menu.

The Job Scheduling window is displayed as shown below;


Enter the required fields and click the Schedule button to schedule the job.


29. Viewing Logs & Statistics

29.1 - Overview

The appStrategy Workbench application Workbench includes tools that you can use to

view Logs and Statistics stored in the project database as you run your jobs. The viewers can be accessed from the “Logs/Statistics” menu of the Workbench application. They are also accessible from the appCompass Studio environments.

29.2 - Project Run Details

You can configure your integration and business rules projects to capture as much information as possible regarding the process. After running the job or while it is still

running, you can use the Project Run Details window to view all details related to the job, including Activity statistics, Source and Target statistics and system logs. The Project

Run Details gives you a centralized report showing all details about instances of the project.

In addition, the Project Run Details also allows you to view details on child jobs launched by each job.


29.3 - Database Log Entries

Database Log Entries captured during the course of running your jobs can be viewed

using the Database Log Entries of the Logs/Statistics menu. Log entries can be selected by date range and other criteria.

29.4 - Run Instances

Each run instance of a project makes an entry in the Run Instance table. This selection

shows a summary of the run instances for the project selected by date range.

29.5 - Activity Statistics

This selection allows you the view the statistics for each activity for each instance of the

project. Entries can be viewed by specifying a date range.

29.6 - Data Source Statistics

This selection shows statistics on data sources that have been used by projects in the

project database. Entries can be viewed by specifying a date range.

29.7 - View Project Folders

This selection allows you to view the project folders for the active project database. During processing, if your projects are using the input and output folders, this option gives you a quick way to go to the locations.


30. appCompass Walkthroughs


30.1 - Read a Source (InitializeSource Activity) appCompass activity modules include activities for reading records from data sources.

For example, the activity InitializeMscrm4Source in the Dynamics CRM4 module reads records from a Microsoft Dynamics CRM 4 data source. The Dynamics CRM2011 module

includes InitializeMscrm2011Source used for reading records from Dynamics CRM 2011 Online or Dynamics CRM 2011 On Premise data source. Other examples of Source activities include InitializeMssqlSource, InitializeOradb, InitializeDB2Source etc.

The following example illustrates the usage of a Microsoft Dynamics CRM 2011

InitializeMscrm2011Source activity in an integration project. To read data from a CRM2011 entity, use the corresponding activities in the Dynamics

CRM 2011 activity module in the toolbar

Select InitializeMscrm2011Source activity and drag it on to the Designer


The red error flag indicates that one or more activity properties are in error. Mouse-over the red dot to view the error messages. Configure the properties of

the activities as shown below:

First configure the Connector property by clicking on the button and the following screen will be displayed:


Select the Connector Type (Online for CRM2011 online, FetchXml for using the web services (On-premise), WCF to use the WCF connector (On-premise or

Online), and FilteredViews to use SQL for On-premise). Follow the screen instructions to complete the entries and click the OK button.

Upon configuring the connector and selecting an entity, the red error warning

disappears. You can then use properties such as RecordCount and Records to get

a count of the records or to view the selected records.

RecordCount:

Records: Displays the records that meet the criteria:


You can also specify the data fields to load from the data source using the DataFields property. When not specified, all data fields are loaded


Use the FilterItems property to specify the criteria for loading records from the

data source. When not specified, all records are loaded.

Click the FilterItems collection property button to display the window below:

Click the Add button to add a filter. You can add multiple filters by using AND or OR.

The Value property of a FilterItem which is used in conjunction with the operator is a Sourced Value which means that the value can come from a variety of sources.

By default an InitializeSource loads the first record of the source (Property "AutoLoad"

set to FirstRecord). Other records can be read by using the GetNextRecord activity.

In an appCompass project, typically, this source is read in a loop to process records in the list. You can use the While, DoWhile, or ForEach activity from the Control Flow

category to process the records in a loop.

In cases where you need to load a specific record as opposed to are list of records, use

the LookUpRecord activity.


In general, to control the loop, the While activity is used along with a condition. In our example, as the source is read, perform processing, drag a While activity on to the Designer


appCompass exposes a function to indicate that an activity’s action result is valid. It is used in the example below to loop through records.


Add a Sequence activity from the Control Flow module to the While activity as shown

below:


Then drag two new activities ( ViewRunTimeRecords and GetNextMscrm2011Record) on

to the designer as shown below and configure them.

Then add the CloseProject activity to the project. Every project must be properly closed with the CloseProject activity.


To execute the project, click the "Run" button on the Run Group of the Home tab.

Check the “Run as new process” box to run the project as a new process. In that case you can continue working while the job is running.

Click the “Run” button to run the project.

If you are using the Visual Studio edition, click the Visual Studio “Start” button.


The job is launched

Since this is a simple project that reads and views records, the Viewer will display the

first record. Click the Next button to move to the next record…


Click the "End Run" button of the viewer to stop the project execution (the "Continue" button continues processing but does not redisplay the corresponding Viewer)

After running a project, use the Project Run Details window to display statistics and logs

related to the project execution.

If you are running the Visual Studio edition, click the Workbench property icon to display Workbench. Select Project Run Details from the Logs/Statistics menu.


30.2 – Using RelatedEntities to link entities / tables in Source definitions

In most Source initialization activities (InitializeSource), it is possible to link multiple

entities or tables using the RelatedEntities property.

Add RelatedEntities collection entries:


Enter collection item property values as follows:

Name Description

DataField Join field name in the defined primary entity property

JoinType Join type (Inner, LeftOuter, RightOuter, FullOuter)

Entity Related (joined) entity (or table) name

ReferencedKeyname Name of the related field in the related entity

When a join is defined in this collection, the fields of the entity / linked table are

displayed for selection fields in the collection DataFields / FilterItems activity


31. Advanced Topics

31.1 – Overview

This chapter covers topics that benefit developers who want to extend appCompass to tackle very complex projects. .

31.2 – Viewing and Editing Project Xaml

As you drag and drop activities on to the designer, the associated xaml is automatically created by the system. You do not have to maintain or edit xaml manually. But

appCompass Studio and Visual Studio both include options that allow you to make changes to the project xaml. After editing the xaml, your changes will be automatically

reflected on the designer.

31.2.1 – Viewing Project Xaml in appCompass Studio

To view and edit project xaml in appCompass Studio, click the View Markup button

from the Source Studio group of the appCompass Studio ribbon bar.

The appCompass Markup Viewer window will be displayed:


31.2.2 – Viewing Project Xaml in Visual Studio

To view and edit project xaml in Visual Studio, right-click on the xaml file in the solution

explorer to display the context menu.

Select View Code from the context menu. The xaml file will be displayed in Visual Studio for viewing and editing:


31.3 – Creating Your Own Activity Assemblies

Most of your custom requirements can be met by defining integrated extension functions and conditions. But if your project requires the ability to include these capabilities as options in the appCompass toolbox, appCompass allows you to include your own custom

activity modules.

To develop and include your custom activity module in appCompass, follow the steps below:

Review the appCompass.Custom sample project which is included in the

appCompass installation folder. You can follow this example to build your

activities assembly.

Add any properties you wish to expose to the Base activity classes.

Add your validation code to the ValidateActivity method.

Add your execution code to the ExecuteActivity method.

Review the appCompass.Custom.Design sample project which is included in

the appCompass installation folder. You can follow the example to build

the presentation assembly for your activities module.

Test your custom assembly.

Copy the custom assembly and the design assembly to the appCompass bin

folder. Add the custom assembly to the toolbox and start using it just like

other activity modules.


32. Project Scenarios and Samples

The Samples database includes several examples that you can use as a training guide as you learn how to create data integration and business projects.