appcompass Developer s Guide For: appcompass Data Integration Studio appcompass Business Rules Studio appcompass Visual Studio Editions

Transcription

1 appcompass Developer s Guide For: appcompass Data Integration Studio appcompass Business Rules Studio appcompass Visual Studio Editions Version 5.1 July, 2013 Copyright appstrategy Inc appcompass Developer s Guide - 1

2 Table of Contents 1. Welcome to appcompass Developer s Guide Getting Started Before You Begin Software Installation Activating appcompass Studio License Activating Visual Studio Edition License Activating on a Computer without Internet Access appcompass Concepts & Features Overview Windows Workflow Foundation Workflow Activities appcompass Modules and Connectors Composing & Orchestrating Integration/Business Rules Projects appcompass Studio for Business Users appcompass Visual Studio Editions for Developers appcompass Custom Studio appcompass Express for XCopy Deployment appcompass Enterprise Server for Enterprise Deployment appstrategy Workbench appcompass Add-Ons The Setup Database Project Databases The Samples Project Database Deployment Settings Data Source Settings Sourced Values Expressions and Extension Functions Conditions Data Managers High Performance Options Project Run Details The App Object Designer Hosting/Re-hosting Accessing the Studio Environment Overview Accessing appcompass Studio Accessing Visual Studio Accessing appstrategy Workbench appcompass Studio Overview Overview Features Application Menu Overview Quick Access Toolbar Copyright appstrategy Inc appcompass Developer s Guide - 2

3 Overview of the Ribbon Tabs & Groups appcompass Visual Studio Edition Overview Overview appcompass Activity Modules System Activity Modules Base Activity Modules Utility Activity Modules SQL Activity Modules General Data Access Activity Modules Business Rules Activity Modules Add-On Activity Modules Custom Activity Modules Adding Workflow Activity Modules to the Toolbox Adding Activity Modules to appcompass Studio Toolbox Adding Activity Modules to Visual Studio Toolbox Composing & Orchestrating appcompass Projects Overview Using appcompass Studio Editions Using Visual Studio Editions Creating a New Project Database Overview Creating a New Project Database in appcompass Studio Creating a New Project Database in Visual Studio Creating and Maintaining Deployment Settings Overview Using the Default Deployment Settings Adding and Updating Deployment Settings Creating a New Project Overview Creating a New Project in appcompass Studio Creating a New Project in Visual Studio Property Editors Overview Drop Down Editors Collection Editors Dialog Property Editors SourcedValue Property Editors Other Property Editor Dialogs Custom Query Editor Concatenation Editor Html Editor Copyright appstrategy Inc appcompass Developer s Guide - 3

4 14. Using Data Source Metadata in appcompass Overview Creating Data Source Metadata Metadata Browser Browse Data Source Summary Browse Data Source Entities / Tables Browse Entity Fields / Attributes Working with Data File Definitions Overview Adding and Updating File Definitions Using Conditions in appcompass Projects Overview Control Flow Conditions The Expression Builder Defining Condition Expressions Defining Condition Functions Using Functions in appcompass Projects Overview Internal Functions Extension Functions Using External Assemblies in Functions Overview Adding External Assemblies Reading Data Overview InitializeSource Activity InitializeSourceFromQuery Activity GetNextRecord Activity Looking up Data Overview LookupRecord Activity LookupDataFieldValue Activity LookupPreloadedRecord Activity Using PickLists Overview The LookupPickListRecord Activity The IsPickListValid Activity Mapping Data Field Values Overview The MapFields Activity The Field Map Detail Window Copyright appstrategy Inc appcompass Developer s Guide - 4

5 22.4 Transforming Field Values Writing Data Overview InitializeMssqlTarget Activity Configuring the High Performance Options Setting Data Field values for the Active Record Inserting Data Updating Data The UpsertRecord Activity Deleting Records Executing Stored Procedures Overview ExecuteStoredProcedure Activity Validating appcompass Projects Overview Design Time Validation Design Time Validation on appcompass Studio Design Time Validation on Visual Studio Detailed Validation of appcompass Projects Running Data Integration & Business Rules Projects Overview Running on appcompass Studio Running on Visual Studio Editions Deploying appcompass Projects Overview XCopy Folder Deployment and appcompass Express Copy Project Database to Deployment Server Scheduling Data Integration & Business Rules Jobs Viewing Logs & Statistics Overview Project Run Details Database Log Entries Run Instances Activity Statistics Data Source Statistics View Project Folders appcompass Walkthroughs Read a Source (InitializeSource Activity) Using RelatedEntities to link entities / tables in Source definitions Advanced Topics Overview Copyright appstrategy Inc appcompass Developer s Guide - 5

6 31.2 Viewing and Editing Project Xaml Viewing Project Xaml in appcompass Studio Viewing Project Xaml in Visual Studio Creating Your Own Activity Assemblies Project Scenarios and Samples Copyright appstrategy Inc appcompass Developer s Guide - 6

7 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 Copyright appstrategy Inc appcompass Developer s Guide - 7

8 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 Copyright appstrategy Inc appcompass Developer s Guide - 8

9 2. Getting Started 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 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. Copyright appstrategy Inc appcompass Developer s Guide - 9

10 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: Copyright appstrategy Inc appcompass Developer s Guide - 10

11 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. Copyright appstrategy Inc appcompass Developer s Guide - 11

12 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. Copyright appstrategy Inc appcompass Developer s Guide - 12

13 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: Copyright appstrategy Inc appcompass Developer s Guide - 13

14 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. Copyright appstrategy Inc appcompass Developer s Guide - 14

15 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 Copyright appstrategy Inc appcompass Developer s Guide - 15

16 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 Copyright appstrategy Inc appcompass Developer s Guide - 16

17 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. Copyright appstrategy Inc appcompass Developer s Guide - 17

18 3. appcompass Concepts & Features 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 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 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. Copyright appstrategy Inc appcompass Developer s Guide - 18

19 The process of composing your projects (workflows), involves dragging activities on to the designer and configuring the associated properties 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. Copyright appstrategy Inc appcompass Developer s Guide - 19

20 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: Copyright appstrategy Inc appcompass Developer s Guide - 20

21 Compose projects using Sequence model: Copyright appstrategy Inc appcompass Developer s Guide - 21

22 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 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 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: Copyright appstrategy Inc appcompass Developer s Guide - 22

23 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. Copyright appstrategy Inc appcompass Developer s Guide - 23

24 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 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. Copyright appstrategy Inc appcompass Developer s Guide - 24

25 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 SharePoint 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 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) 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 systemspecific settings. In enterprise deployments, you can move the Setup database to an enterprise database such as Microsoft SQL Server, Oracle, and IBM DB2 etc. Copyright appstrategy Inc appcompass Developer s Guide - 25

26 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. Copyright appstrategy Inc appcompass Developer s Guide - 26

27 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.). Copyright appstrategy Inc appcompass Developer s Guide - 27

28 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 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. Copyright appstrategy Inc appcompass Developer s Guide - 28

29 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 Constant DataField DataFieldExt DateTime Value Identifier The Constant source allows you to enter any value in the value identifier. Example: Constant:John Smith 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. The DataFieldExt extends the DataField source value to point to a data field in a record from any source or target in the project. 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. Copyright appstrategy Inc appcompass Developer s Guide - 29

30 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: Copyright appstrategy Inc appcompass Developer s Guide - 30

31 Sourced Value Editor Window The example below shows the Sourced Value Editor window used for configuring a Sourced Value at design time: Copyright appstrategy Inc appcompass Developer s Guide - 31

32 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 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 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. Copyright appstrategy Inc appcompass Developer s Guide - 32

33 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 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. Copyright appstrategy Inc appcompass Developer s Guide - 33

34 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. Copyright appstrategy Inc appcompass Developer s Guide - 34

35 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 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. Copyright appstrategy Inc appcompass Developer s Guide - 35

36 4. Accessing the Studio Environment 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 Accessing appcompass Studio To access your version of appcompass Studio, double-click on the appcompass icon that was installed on your desktop: 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: 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: Copyright appstrategy Inc appcompass Developer s Guide - 36

37 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. Copyright appstrategy Inc appcompass Developer s Guide - 37

38 5. appcompass Studio Overview 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. 2 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. Copyright appstrategy Inc appcompass Developer s Guide - 38

39 3 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. 4 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. 5 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. Copyright appstrategy Inc appcompass Developer s Guide - 39

40 5.2 - Features Application Menu Overview You can access the main menu by clicking the top left button in appcompass Studio. Copyright appstrategy Inc appcompass Developer s Guide - 40

41 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 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 Copyright appstrategy Inc appcompass Developer s Guide - 41

42 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 Copyright appstrategy Inc appcompass Developer s Guide - 42

43 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. Copyright appstrategy Inc appcompass Developer s Guide - 43

44 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 View Logs 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. 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 Copyright appstrategy Inc appcompass Developer s Guide - 44

45 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 Copyright appstrategy Inc appcompass Developer s Guide - 45

46 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 Copyright appstrategy Inc appcompass Developer s Guide - 46

47 6. appcompass Visual Studio Edition Overview 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. 2 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 Copyright appstrategy Inc appcompass Developer s Guide - 47

48 the process. To add a workflow activity to any part of the designer, drag it from the toolbox and drop it on the designer. 3 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. 4 Ribbon Bar The Ribbon at the top of Visual Studio window buttons for managing the currently loaded appcompass project in the designer. 5 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. Copyright appstrategy Inc appcompass Developer s Guide - 48

49 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 System.Activities execution within appcompass projects. 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. Module Description Assembly 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 Copyright appstrategy Inc appcompass Developer s Guide - 49

50 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. Module Description Assembly Active directory Users Activities for managing Active Directory appcompass.activedirectory.dll Users. Automation File System Module for checking system and other resource utilization, monitoring and other automation functions. Activities used for managing files and directories, access control lists etc. on the file system. appcompass.automation.dll appcompass.filesystem.dll Copyright appstrategy Inc appcompass Developer s Guide - 50

51 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. Module Description Assembly SQL OLEDB Provides SQL OLEDB access to data appcompass.sqloledb.dll sources. SQL ODBC SQL Server SQL Server Compact Edition Oracle IBM DB2 MySQL SQL Azure Provides SQL OLEDB access to data sources. Provides native connectivity to Microsoft SQL Server databases. Provides native connectivity to Microsoft SQL Server Compact Edition databases. Provides native connectivity to Oracle databases Provides native connectivity to IBM DB2 databases. Provides native connectivity to MySQL databases. Provides native connectivity to SQL Azure databases. appcompass.sqlodbc.dll appcompass.mssql.dll appcompass.mssqlce.dll appcompass.oradb.dll appcompass.db2.dll appcompass.mysql.dll appcompass.sqlazure.dll Copyright appstrategy Inc appcompass Developer s Guide - 51

52 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. Module Description Assembly 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 Microsoft Dynamics CRM Online Microsoft Dynamics CRM 2011 Microsoft Dynamics CRM 4 Provides activities for processing xml messages. Activity module for Microsoft Dynamics CRM Online Activity module for Microsoft Dynamics CRM Activity module for Microsoft Dynamics CRM 4. appcompass.xml.msg.dll appcompass.mscrm2011.dll appcompass.mscrm2011.dll appcompass.mscrm2011.dll Salesforce Activity module for Salesforce.com appcompass.sforce.dll Copyright appstrategy Inc appcompass Developer s Guide - 52

53 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. Module Description Assembly 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 Extended activity module for Microsoft Dynamics CRM appcompass.mscrm2011.rules. dll Business Rules Activities for Microsoft Dynamics CRM 4 Business Rules Activities for Active Directory Extended activity module for Microsoft Dynamics CRM 4. Extended activity module for Active Directory Groups, Users, Computers, etc. appcompass.mscrm2011.rules. dll appcompass.activedirectory.r ules.dll Check the appcompass support portal for additional Business Rules activity modules. Copyright appstrategy Inc appcompass Developer s Guide - 53

54 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. Copyright appstrategy Inc appcompass Developer s Guide - 54

55 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: Copyright appstrategy Inc appcompass Developer s Guide - 55

56 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 Copyright appstrategy Inc appcompass Developer s Guide - 56

57 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: Copyright appstrategy Inc appcompass Developer s Guide - 57

58 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: Copyright appstrategy Inc appcompass Developer s Guide - 58

59 Module Description Assembly Core appcompass Core activities. The appcompass.core.dll appcompass Core module is required. Logs Viewers Record These are the activities used for logging. Activities used for viewing values during test runs of your project Activities used for managing record values appcompass.logs.dll appcompass.viewers.dll appcompass.record.dll List Activities for managing ad hoc lists and pick lists appcompass.list.dll Copyright appstrategy Inc appcompass Developer s Guide - 59

60 9. Composing & Orchestrating appcompass Projects 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 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. Copyright appstrategy Inc appcompass Developer s Guide - 60

61 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. Copyright appstrategy Inc appcompass Developer s Guide - 61

62 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 DB 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. Copyright appstrategy Inc appcompass Developer s Guide - 62

63 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. Copyright appstrategy Inc appcompass Developer s Guide - 63

64 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 Copyright appstrategy Inc appcompass Developer s Guide - 64

65 11. Creating and Maintaining Deployment Settings 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 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 Default Description/Usage 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 Production If you will be using a Test bed you can use this deployment setting for testing. 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. Copyright appstrategy Inc appcompass Developer s Guide - 65

66 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. Copyright appstrategy Inc appcompass Developer s Guide - 66

67 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 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 Copyright appstrategy Inc appcompass Developer s Guide - 67

68 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. Copyright appstrategy Inc appcompass Developer s Guide - 68

69 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. Copyright appstrategy Inc appcompass Developer s Guide - 69

70 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 Send activity: Copyright appstrategy Inc appcompass Developer s Guide - 70

71 The Send 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 Drop Down Editors appcompass uses drop down property editors to show lists of options from which the user can select one. Copyright appstrategy Inc appcompass Developer s Guide - 71

72 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 Copyright appstrategy Inc appcompass Developer s Guide - 72

73 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). Copyright appstrategy Inc appcompass Developer s Guide - 73

74 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: Copyright appstrategy Inc appcompass Developer s Guide - 74

75 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 Boolean Concatenation ConditionResult Constant DataField DataFieldExt DataSourceFieldName DataSourceListEntryValue Value 0 (False) or 1 (True) Value is a concatenation of project values Result of a condition extension function (returns True or False) Value is exactly as specified Field of any source or target defined in the active activity Field of any source or target defined in the project Name of the selected field in the metadata model 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, SharePointSiteUser and SharePointSiteUserLogin Copyright appstrategy Inc appcompass Developer s Guide - 75

76 DeploymentServerField Date DateTime ExtensionFunction FileContent 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.) A date entry or date-related value A date / time entry or datetime-related value Value from an ExtensionFunction. Value from a file. This option reads the entire contents of the file as the value to use. FilePath FileRecordSubString FolderPath InternalFunction HTML HTMLWithMergeFields LongString Password PickListEntry PickListEntryDescription PrimaryKey ProjectVariable RecordCount Text Gets a file path Gets a sub string from a text file record Gets a folder path This option sets the value based on the performance of a function (see section Function Editor) HTML value HTML value with project fields merged in Gets the value of a long string Get a password value (encrypted) Picklist value Description of specific Picklist value Value is primary key of the selected entity of a data source If the project uses an InitializeProject activity, this Source gets the value of a pre-defined ProjectVariable Value is the count of records in a Source Text value Copyright appstrategy Inc appcompass Developer s Guide - 76

77 TextWithMergeFields WorkflowActivityName WorkflowArgument Text value with project fields merged in Value is the display name of an activity name from the current project Value is an argument passed to the project WorkflowDataManagerName Value is the display name of a selected Source or Target activity WorkflowName WorkflowServerValue WorkflowVariable Value is name of a project in the current project database Gets a specific server value A variable defined in the project Copyright appstrategy Inc appcompass Developer s Guide - 77

78 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 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. Copyright appstrategy Inc appcompass Developer s Guide - 78

79 Concatenation Editor The Concatenation Editor window is displayed for concatenating values. To include project values in the concatenation, click the Insert button. Copyright appstrategy Inc appcompass Developer s Guide - 79

80 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. Copyright appstrategy Inc appcompass Developer s Guide - 80

81 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. Copyright appstrategy Inc appcompass Developer s Guide - 81

82 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 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: Copyright appstrategy Inc appcompass Developer s Guide - 82

83 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. Copyright appstrategy Inc appcompass Developer s Guide - 83

84 14.3 Metadata Browser Once created, you can browse the metadata from your data source at any time. You can also refresh the metadata Browse Data Source Summary Copyright appstrategy Inc appcompass Developer s Guide - 84

85 Browse Data Source Entities / Tables Copyright appstrategy Inc appcompass Developer s Guide - 85

86 Browse Entity Fields / Attributes Copyright appstrategy Inc appcompass Developer s Guide - 86

87 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. Copyright appstrategy Inc appcompass Developer s Guide - 87

88 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. Copyright appstrategy Inc appcompass Developer s Guide - 88

89 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 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. Copyright appstrategy Inc appcompass Developer s Guide - 89

90 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. Copyright appstrategy Inc appcompass Developer s Guide - 90

91 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. Copyright appstrategy Inc appcompass Developer s Guide - 91

92 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. Copyright appstrategy Inc appcompass Developer s Guide - 92

93 Click on the New button to add a new Expression. The following screen will be displayed: Copyright appstrategy Inc appcompass Developer s Guide - 93

94 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. Copyright appstrategy Inc appcompass Developer s Guide - 94

95 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. Copyright appstrategy Inc appcompass Developer s Guide - 95

96 Click the New button to add a new Condition Function. The following screen will be displayed: Copyright appstrategy Inc appcompass Developer s Guide - 96

97 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. Copyright appstrategy Inc appcompass Developer s Guide - 97

98 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 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 GetValueFromDelimitedString ConcatenateStrings GetEmptyString StringInsert StringPadLeft StringPadRight StringReplace Description Gets a value from a string delimited by a single character using 0-origin index Concatenates strings. Gets an empty string Inserts a string at a specified index position in the source string (0 origin) Pads a string on the left with a specified character Pads a string on the right with a specified character Replaces all occurrences of an old string value with new string value. Copyright appstrategy Inc appcompass Developer s Guide - 98

99 StringReplaceWithEmptyString StringToLower StringToUpper StringFirstLetterToUpper StringRemove StringTrimAll StringTrim StringTrimEnd StringTrimStart StringSubstring StringSubstringOfLength StringRegex Replaces all occurrences of an old string value with an empty string value Converts a string to lowercase Converts a string to UPPERCASE Converts the first letter of a string to UPPERCASE Removes characters in a string starting an index position (0 origin) Removes all whitespace from a string Removes a specified character from a string Removes all trailing occurrences of a specified character from a string Removes all leading occurrences of a specified character from a string Gets a substring from a string starting at an index position (0 origin) Gets a substring of a specified length from a string starting at an index position (0 origin) Within the source input string, replaces strings that match a regular expression pattern with a specified replacement string. GetYearWeekNumber GetDateToday Gets the number of the week in the year Gets today's date GetDateYesterday GetDateTomorrow GetDateThisDayNextYear GetDateThisDayLastYear GetDateThisDayNextMonth GetDateThisDayLastMonth GetDateThisYearStart Gets yesterday's date Gets tomorrow's date Gets this day next year (date) Gets this day last year (date) Gets this day next month Gets this day last month Gets this year's start date Copyright appstrategy Inc appcompass Developer s Guide - 99

100 GetDateThisYearEnd GetDateThisMonthStart GetDateThisMonthEnd GetDateThisDayNextWeek GetDateThisDayLastWeek GetDateTimeNow GetYearFromDate GetMonthFromDate GetDayFromDate SetTimeForDateTime Gets this year's end date Gets this month's start date Gets this month's end date Gets this day next week Gets this day last week Gets the current Date/Time Gets the Year (integer) from the date Gets the Month (integer) from the date Gets the Day (integer) from the date" 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 AddDaysToDate AddMonthsToDate AddYearsToDate Calculates the number of hours between two date/time values Adds (or subtracts) the specified number of days to a date Adds (or subtracts) the specified number of months to a date Adds (or subtracts) the specified number of years to a date GetUniqueKey GetGuidKey GetTimeStampKey Gets an RNGCryptoServiceProvider-based unique key Gets a GUID-base unique key Gets a TimeStamp key Copyright appstrategy Inc appcompass Developer s Guide - 100

101 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. Copyright appstrategy Inc appcompass Developer s Guide - 101

102 The following screen will be displayed: Click the New button to add a new Extension Function. The following screen will be displayed: Copyright appstrategy Inc appcompass Developer s Guide - 102

103 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. Copyright appstrategy Inc appcompass Developer s Guide - 103

104 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 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. Copyright appstrategy Inc appcompass Developer s Guide - 104

105 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. Copyright appstrategy Inc appcompass Developer s Guide - 105

106 19. Reading Data 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 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: Copyright appstrategy Inc appcompass Developer s Guide - 106

107 Property Connector Description Select the connector to be used in this Source for reading SQL Server records. PrimaryEntity 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 Select the primary SQL Server table from the list. Copyright appstrategy Inc appcompass Developer s Guide - 107

108 RelatedEntities AutoLoad Use this property to include related tables in the result 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 SortItems You can optionally use this property to define the criteria for selecting the entity records to be included in the result set. You can optionally use this property to define how the records in the Source are to be sorted. Copyright appstrategy Inc appcompass Developer s Guide - 108

109 RecordCount Records 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. 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. Copyright appstrategy Inc appcompass Developer s Guide - 109

110 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: Copyright appstrategy Inc appcompass Developer s Guide - 110

111 Property Connector Description 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: Copyright appstrategy Inc appcompass Developer s Guide - 111

112 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 Records 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. 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. Copyright appstrategy Inc appcompass Developer s Guide - 112

113 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. Copyright appstrategy Inc appcompass Developer s Guide - 113

114 20. Looking up Data 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 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 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 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. Copyright appstrategy Inc appcompass Developer s Guide - 114

115 21. Using PickLists 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. Copyright appstrategy Inc appcompass Developer s Guide - 115

116 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 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. Copyright appstrategy Inc appcompass Developer s Guide - 116

117 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 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: Copyright appstrategy Inc appcompass Developer s Guide - 117

118 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. Copyright appstrategy Inc appcompass Developer s Guide - 118

119 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. Copyright appstrategy Inc appcompass Developer s Guide - 119

120 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 ApplyKeyValue ApplyPicklist Base64Decode Base64Encode Concatenate Convert ConvertHtmlToPlainText CurrencyFrom CurrencyTo Description Returns the value of the key to a table or entity in the target field according to specified filters Returns the value or description of a picklist by filtering a value or description Decode content stored in base64 (ex: File attachment in Dynamics CRM annotation entity) Encode content for storage in base64 (see above) Concatenates multiple values (using the concatenation editor) into one field Convert a text field into numeric format Converts an encoded html content into a text value Returns a value of type integer or decimal from a currency in (CRM4/2011) 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 DateTimeUnixTimeToDateTim e Converts a Unix date format into a windows date / time value DateTimeToUnixTime Converts a date / time value windows to Unix date/time DateTimeddmmyyyytoyyyym Converts a date DD / MM / YYYY date to YYYYMMDD mdd DateTimemmddyyyytoyyyym mdd 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 Copyright appstrategy Inc appcompass Developer s Guide - 120

121 SetValue SetValueToNull SetValueToEmptyString StringLowerCase StringPadLeft StringPadLeftWithValue StringPadRight StringPadRightWithValue StringProper StringRegEx StringSubstring StringTrim StringTrimLeft StringTrimRight StringUpperCaseAll StringUpperCaseFirstLetter Unformat Sets the value of a target field Assigns the value NULL to a target field Assigns an empty string to the target field Switches all characters of a value to lower case Pads the target field with are certain number of spaces to the left Pads target field to the left with value Pads target field to the right Pads target field to the right with value Transforms a string to proper casing (first character in uppercase ) Assigns a new value to the target field by using Regex can extract a portion of a string Removes spaces at the beginning and end of the target field Removes leading spaces from the target field Removes trailing spaces from the target field Converts all characters in target field to upper case Convers the first letter of a target field to upper case Removes formatting from a target field Copyright appstrategy Inc appcompass Developer s Guide - 121

122 23. Writing Data 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 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: Copyright appstrategy Inc appcompass Developer s Guide - 122

123 Property Connector Description 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. Copyright appstrategy Inc appcompass Developer s Guide - 123

124 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 Disabled Enabled Description This is the default setting. Optimized settings are not utilized when writing records to the target. 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. Copyright appstrategy Inc appcompass Developer s Guide - 124

125 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. Copyright appstrategy Inc appcompass Developer s Guide - 125

126 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. Copyright appstrategy Inc appcompass Developer s Guide - 126

127 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. Copyright appstrategy Inc appcompass Developer s Guide - 127

128 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. Copyright appstrategy Inc appcompass Developer s Guide - 128

129 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. Copyright appstrategy Inc appcompass Developer s Guide - 129

130 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. Copyright appstrategy Inc appcompass Developer s Guide - 130

131 24. Executing Stored Procedures 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 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. Copyright appstrategy Inc appcompass Developer s Guide - 131

132 Property Connector StoredProcedureType StoredProcedure StoredProcedureFields Description Click to property button to configure the connector to select the data source and other connection values. Select the type of stored procedure indicating the type of result returned. The name of the stored procedure 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 AutoLoad TestRunParameters RecordCount Records If the stored procedure uses parameters, specify them with this collection property. Use FirstRecord to read the first record from the stored procedure or AllRecords to read all records. Design time property to get stored procedure parameter values. Design time property to get the record count if the stored procedure returns records. Design time property to view the records if the stored procedure returns records. Copyright appstrategy Inc appcompass Developer s Guide - 132

133 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 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 Design Time Validation on appcompass Studio At design time, appcompass Studio flags all activity errors on the designer as shown below: Copyright appstrategy Inc appcompass Developer s Guide - 133

134 Design Time Validation on Visual Studio At design time, appcompass flags all activity errors on the Visual Studio designer as shown below: Copyright appstrategy Inc appcompass Developer s Guide - 134

135 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: Copyright appstrategy Inc appcompass Developer s Guide - 135

136 Copyright appstrategy Inc appcompass Developer s Guide - 136

137 26. Running Data Integration & Business Rules Projects 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 Running on appcompass Studio You can run your Data Integration and Business Rules jobs directly from your appcompass Studio environment as follows. Development Environment appcompass Data Integration Studio appcompass Business Rules Studio Visual Studio 2012 or Higher Run Option Click the Run button Click the Run button Click Start button Running on Visual Studio Editions You can run your Data Integration and Business Rules jobs directly from Visual Studio your Studio environment. Development Environment appcompass Data Integration Studio appcompass Business Rules Studio Visual Studio 2012 or Higher Run Option Click the Run button Click the Run button Click Start button Copyright appstrategy Inc appcompass Developer s Guide - 137

138 27. Deploying appcompass Projects 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. Copyright appstrategy Inc appcompass Developer s Guide - 138

139 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. Copyright appstrategy Inc appcompass Developer s Guide - 139

140 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. Copyright appstrategy Inc appcompass Developer s Guide - 140

141 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; Copyright appstrategy Inc appcompass Developer s Guide - 141

142 Enter the required fields and click the Schedule button to schedule the job. Copyright appstrategy Inc appcompass Developer s Guide - 142

143 29. Viewing Logs & Statistics 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 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. Copyright appstrategy Inc appcompass Developer s Guide - 143

144 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 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 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 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 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. Copyright appstrategy Inc appcompass Developer s Guide - 144

145 30. appcompass Walkthroughs Copyright appstrategy Inc appcompass Developer s Guide - 145

146 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 Copyright appstrategy Inc appcompass Developer s Guide - 146

147 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: Copyright appstrategy Inc appcompass Developer s Guide - 147

148 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: Copyright appstrategy Inc appcompass Developer s Guide - 148

149 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 Copyright appstrategy Inc appcompass Developer s Guide - 149

150 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. Copyright appstrategy Inc appcompass Developer s Guide - 150

151 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 Copyright appstrategy Inc appcompass Developer s Guide - 151

152 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. Copyright appstrategy Inc appcompass Developer s Guide - 152

153 Add a Sequence activity from the Control Flow module to the While activity as shown below: Copyright appstrategy Inc appcompass Developer s Guide - 153

154 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. Copyright appstrategy Inc appcompass Developer s Guide - 154

155 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. Copyright appstrategy Inc appcompass Developer s Guide - 155

156 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 Copyright appstrategy Inc appcompass Developer s Guide - 156

157 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. Copyright appstrategy Inc appcompass Developer s Guide - 157

158 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: Copyright appstrategy Inc appcompass Developer s Guide - 158

159 Enter collection item property values as follows: Name DataField JoinType Entity ReferencedKeyname Description Join field name in the defined primary entity property Join type (Inner, LeftOuter, RightOuter, FullOuter) Related (joined) entity (or table) name 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 Copyright appstrategy Inc appcompass Developer s Guide - 159

160 Copyright appstrategy Inc appcompass Developer s Guide - 160

161 Copyright appstrategy Inc appcompass Developer s Guide - 161

162 31. Advanced Topics 31.1 Overview This chapter covers topics that benefit developers who want to extend appcompass to tackle very complex projects 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 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: Copyright appstrategy Inc appcompass Developer s Guide - 162

163 Copyright appstrategy Inc appcompass Developer s Guide - 163

164 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: Copyright appstrategy Inc appcompass Developer s Guide - 164

165 Copyright appstrategy Inc appcompass Developer s Guide - 165