EngageCX Modeler 13.0 Users Guide

Repository

Connect to EngageCX Platform

The Modeler tool is set up so that you can connect with your EngageCX Platform account and fully utilize existing project files created by your organization, on your local computer. Accessing the EngageCX Platform files is possible through the EngageCX Drive tool. To access and connect to EngageCX Platform through EngageCX Drive follow the steps below:

1. Access the Repository tab in the Ribbon.
2. Select the EngageCX Drive button under the Drive group.
3. You will be redirected to EngageCX Drive where you will have to enter the Enterprise Website URL and account credentials to connect. For more details, please access the EngageCX Drive documentation.

Document Operations

Whenever you want to edit a document and share the changes with your team, access the Repository tab in the Modeler Ribbon, connect to EngageCX Platform, then utilize the options available in the Document Operations group as needed. Here's how you can utilize the options:

Get the latest server version

1. Access EngageCX Drive and open the diagram you want to edit in Modeler.
2. Navigate to the Repository tab in the ribbon.
3. Select the Get Latest Version button from the Document Operations group.
4. You will see a visual indication while the Modeler communicates with the EngageCX Repository to retrieve all the data. Once completed, your diagram will be updated.

Undo the pending changes

1. Access EngageCX Drive and open the diagram you want to edit in Modeler.
2. Navigate to the Repository tab in the ribbon.
3. Select the Undo Changes button from the Document Operations group.
4. If you are undoing the changes of a file you have edited, you will receive a message requesting confirmation to reload and lose the changes you have made to the file. Select Yes to proceed with losing changes and reloading the Server Version. If you select No, your changes will still be present in the Modeler and stored in the local working folder.

Check In a Document

1. Access EngageCX Drive and open the diagram you want to edit in Modeler.
2. Navigate to the Repository tab in the ribbon.
3. Select the Check In button from the Document Operations group.
4. From the Commit Changes dialog, add any comments needed for this new version and then select Check In.

Check Out a Document

1. Access EngageCX Drive and open the diagram you want to edit in Modeler.
2. Navigate to the Repository tab in the ribbon.
3. Select the Check Out button from the Document Operations group.
4. In the newly checked out document, make all of the required changes and select Save. Then, you must Check In the changes in order to update the document in the repository.

Design the Output Structure

When building your diagrams, a key component is understanding the different ways to design the structure of your output.

XML Output

Creating Elements, Attributes, and Text Values

Creating Prior to Mapping

1. In the Output Object, right click on the object you would like to add content to and select from available options to Add Attribute,Add Element and Add Text.
2. The Insert Dialog will be displayed depending upon the type of object you have selected. You will need to specify a name for your object. It is important to remember that your provided name must conform to XML standards. For example, the name cannot contain spaces, etc.
3. You can also change the assigned namespace prefix and provide a namespace url. Using namespaces is sometimes necessary to distinguish between identifiers like this element which may have the same name but containing information from another source.
4. When you are satisfied with your setup, select Insert and you will notice in the output object that your object has been created.
5. By repeating steps 1 through 4, you can create content structure including child attributes or text values for the element you have created.
6. You can now proceed to mapping data from input data sources to your designed XML structure.

Creating Attributes By Mapping

1. Drag and drop a Data Connector from any data source into the Output XML. An attribute will automatically be created in the output object.

Creating Repeating Elements

Dragging and Dropping Data Set Connectors

1. Select the dark blue Data Set Connector in your input data source and drag and drop directly into your output object.
2. A Repeating Element is created in your output XML. This object will also have a dark blue Data Set Connector with an established Data Connection from your drag and drop action.

Right Clicking in the Output Object

1. Select the element you would like to add a child Repeating Element to in the output object. From the resulting contextual menu, select Add Element Sequence.
2. The Insert Element Sequence Dialog will now be displayed. You can now add a name for your new Repeating Element Sequence as well as specify a namespace and namespace url.
3. Select Insert when you are satisfied with your additions and your new Repeating Element Sequence will be added into the output object.
4. Use the dark blue Data Set Connectors to drag and drop to the dark blue Data Set Connector in the output object to establish data mappings. This will ensure a new element is created for every occurrence of your input data set.

Split-By Output Elements

1. Select the element from the output diagram, based on which you want to split the output by and right-click on it.
2. Click Split by this Element from the contextual menu.
3. In the diagram, you can notice an icon next to the corresponding data point that suggests the trigger data point. You can use Split By feature only once for the current output.
4. Once you're ready, click Export or Preview from the Home tab in the Ribbon and you will see that the output is split based on each entry enclosed in the selected data point.

BI In-Memory Database Output

An IMDB (In-Memory Database) - is a database that is stored in the computer’s main memory. It is a faster database than a disk database, because accessing the data from the main memory is more effective as the time to retrieve data and querying is eliminated. The IMDBs are used in applications where the time for response is essential.

Creating Tables and Adding Data

1. An empty BI In-Memory Database output object will possess a single element called Database. Right click on the Database element and select Add Table. You will need to define the tables present in your In-Memory Database.
2. In the Create Table Dialog, specify a name for your table and choose an available command type. Commands types include appending for adding content to an existing table, updating for updating an existing table, or ignoring when a table with the same name is present. This option will be executed when the In-Memory Database is deployed to a BI Server with existing information. If the table is not present, a new table will simply be created.
3. Select Insert when you are finished to add the Table into the output structure. The table will be represented with a repeating icon as well as posses an input Data Set Connector.
4. You can create further structure by right clicking on the Table in the output object and selecting Create Field.
5. In the Create Field Dialog, specify a name and a value type for your field. Remember the type will be important for your output in determining what types of widgets can display this data.
6. Select the Insert button and notice that your field will be added into the output object. The name and the value type will be displayed.
7. Map your input data source to the Table by connecting the dark blue Data Set Connectors. Then map individual data points using the light blue Data Connectors.
8. Additionally, you can simply drag and drop data points into the output object and a Field will be automatically created for you. The data value type will be assumed from the data source and displayed. You can modify this by double clicking on the Field to access the Properties Pane.
9. Select the Preview button in the Home Tab to view your In-Memory Database output including the Tables you've created and the associated columns (fields) within.

Table Relationships

When you are creating an In-Memory Database output diagram, it is important to remember that you are structuring a database and you may need to define relationships that exist between the tables that you are creating. Establishing relationships is an important step for Analyst Analysis as information that resides in different tables needs to be linked by a foreign key. Follow the instructions below to create relationships between your created database tables.

1. First, follow necessary instructions to create the tables in your output In-Memory Database.
2. Right click on the Database output object in the output and select Properties from the contextual menu or you can simply double click on the Database output object to launch the Properties Pane.
3. Select the Edit button in the Properties Pane to set up your relationships.
4. In the Table Relationship dialog, you will need to map your foreign key relationships between one the source tables column and the destination table's column that you specify. Select Save when you are finished creating your relationships.
5. You can repeat steps four and five to add as many relationships that you require. Additionally, if adding additional tables in your output, you can always access the Properties Pane as noted in step two to establish more relationships.

Define a Primary Key

1. Right click on the Table you have created in the In-Memory Database Output Object and select Properties or double click on the Table to launch the Properties Pane.
2. In the Properties Pane, you will notice an option to Define a Primary Key on creation of the table. You can select from available columns using the drop down menu. This drop down menu will be populated with the available columns that you have added into your output object.
3. Once you have selected a Primary Key additional options will be displayed for when you are updating an already deployed In-Memory Database. Remember a Primary Key is a unique identifier for the row and you will need to specify from the available options how updating will be controlled. Use the descriptions provided to select the intended behavior.
4. Select Enter on the keyboard to preserve your changes and return to the Design Surface for further design.

Data Operations Output

When working with Data Operations, we refer to this as Data Operations Output object. This output type is used for creating database tables and appending to or replacing current tables in a database by collections of CRUD operations, such as UPDATE, INSERT or DELETE. With this goal in mind, it is important to understand the different ways that you can structure your output to meet these needs. In this section, you can find information on creating and structuring data operations object. You might notice that if you attempt to create any data connection from your input data source to your output data object, you will not be able to succeed. This is because the first step that needs to be accomplished is actually setting up the structure of your Data Operations Output. To do so, you will need to follow the instructions below.

1. Right click on Operations in the Data Operations Output object and select Add Data Operation from the contextual menu. You will be creating a particular structure to be used in this output.
2. In the Insert Data Operation dialog, you will need to specify which connection to use for this output and make additional configurations through pre and post processing SQL commands as needed. Select from the available connections (Database, Salesforce, Creatio or Dynamics CRM connections) in the drop-down list.
3. Provide the name of the collection data which can be the table name.
4. Select the Type of the database operation that you need to perform.
5. In case you have selected Update or Delete as the type of the data operation, you need to create a condition when these two operations will be allowed to execute. For example, you can type in a column based on which values the operation will perform.
6. Next, you will need to select Add Field to set up the target columns to which the configured operation will apply.
7. Once ready, select Save. The object will be displayed in the design surface, but you need to draw the connections manually from the input data file to the data operations object.

Excel Output

EngageCX Modeler provides Excel output format that allows aggregation of multiple data sources into an Excel spreadsheet. The diagram with an Excel Output configuration is an .ede file that can be further used under the Workflow editor, when generating .xslx files.

The structure of a spreadsheet document consists of the <workbook> element that contains <sheet> objects - that reference the worksheets in the workbook.

Adding Worksheets

Creating Prior to Mapping

1. If you want to create a new sheet under the same workbook, right-click on the Workbook element in the Excel output tree.
2. Select Add Sheet from the contextual menu.
3. Click on the new created sheet to provide a name for it under the Properties pane in the left. By default, the name of any worksheet would be: Sheet.
4. You can now proceed to map data from input data sources to your designed Excel table structure.

Creating Attributes By Mapping

1. Drag and drop a Data Connector from any data source into the Excel Output to populate the attributes with the values extracted from the data source. An attribute will automatically be created in the output object.

Configuring Worksheets

After inserting a <worksheet> element on the Excel Output object, you can either add a row for defining a finite number of rows within the Excel table format or a repeating row to define a sequence of rows, depending on the values found in the input file (e.g. CSV, XML, Text Files, etc.).

Adding a New Row to a Worksheet

1. Right-click on the <Worksheet> element in the Excel Output tree to expand its options.
2. Select Add Row from the contextual menu to insert a child to your worksheet. You can repeat this step as many times as you need to introduce a finite number of rows.
3. Click on the <Row> element in the tree and the Properties pane will be enabled in the left side. Provide the index on the vertical axis where the row should be inserted in an Excel table format.
4. To populate the row, you can right-click on the <row> element and expand its contextual menu.
   • Select Add Cell to insert a cell to the current row. Click on the <cell> element in the tree to configure its properties in the Properties pane.
     • Name: Provide a name for the current cell.
     • Index: Provide an index value where this cell will be positioned in the row.
     • Type: Choose the type of values that this cell should accept. (e.g. String, Boolean, etc. )
   • Select Add Formula to configure a more complex expression that obeys Excel rules.
     • Name: Provide a name for the current cell.
     • Index: Provide an index value where this cell will be positioned in the row.
     • Type: Choose the type of values that this cell should accept. (e.g. String, Boolean, etc. )
     • Formula: Provide an expression that obeys Excel rules (e.g. SUM(A1,B1)).
5. You can now proceed to map data from input data sources to your designed table-row structure.

Adding a Repeating Row to a Worksheet

1. Right-click on the <Worksheet> element in the Excel Output tree to expand its options.
2. Select Add Row Sequence from the contextual menu to insert a repeating row to your worksheet. The sequence will have the same number of rows with the values in the rows mapped to the input file.
3. Click on the <RowSequence> element in the tree and the Properties pane will be enabled in the left side. Provide the index on the vertical axis where the repeating row should start in an Excel table format.
4. Enable the Write Headers option to display the headers of the columns.
5. To populate the repeating row, you can right-click on the <rowsequence> element and expand its contextual menu.
   • Select Add Cell to insert a cell to the current row. Click on the <cell> element in the tree to configure its properties in the Properties pane.
     • Name: Provide a name for the current cell.
     • Index: Provide an index value where this cell will be positioned in the row.
     • Type: Choose the type of values that this cell should accept. (e.g. String, Boolean, etc. )
   • Select Add Formula to configure a more complex expression that obeys Excel rules.
     • Name: Provide a name for the current cell.
     • Index: Provide an index value where this cell will be positioned in the row.
     • Type: Choose the type of values that this cell should accept. (e.g. String, Boolean, etc. )
     • Formula: Provide an expression that obeys Excel rules (e.g. SUM(A1,B1)).
6. You can now proceed to map data from input data sources to your designed table-row structure.

Output Structure Options

Renaming Objects

1. Select the object you would like to rename in the output object.
2. Double click to launch the Properties Pane, or right click on the selected object and choose Properties.
3. In the Properties Pane, specify a new name for your selected object and hit Enter.

Repositioning Objects

1. In the output object, determine which object you wish to move.
2. Next, click and hold the object you wish to move. An indicator will display where releasing is allowed or disallowed. Also directional arrows will provide an indication of where the object will be placed when you release.
3. Release the mouse button when you are satisfied with the placement.

Working with Data Connections

Data Source Connections

Connect to a Database

1. Start by selecting the Data Sources button in the Home Tab.
2. Select the Database tab in the Data Source Pane opened, then select New Connection button.
3. In the Database Connection Dialog, you will need to set up the configurations as needed.
   • Specify a Connection Name to be used.
   • Select from available Provider Types: Microsoft Access Database File, Microsoft ODBC Data Source, Microsoft SQL Server, Oracle Database, Custom Provider.
   • Depending upon your provider you may need to specify different configurations, such as: Server name, Database name, TNS Name, and more.
   • You will also need to provide the Username and Password to log on to the database.
4. When your configurations are complete, select Test Connection. You will receive a notification of success or failure. If the connection has failed, you should revisit your configuration settings and retest.
5. To access and customize the connection string (not required), select Advanced. You will be presented with the Advanced Connection Dialog where you can structure your own connection string.
6. When you are satisfied with a Successful Connection, select Save. Your Database Connection will now be displayed in the Databases Pane. You can now proceed with your diagram design using the different database objects available.

Salesforce Connection

1. Start by selecting the Data Sources button in the Home Tab.
2. Select the Database tab in the Data Source Pane opened, then click on the New Connection hyperlink.
3. In the Salesforce Connection dialog, you will need to set up the configurations as needed.
   • Specify a unique Connection Name to be used.
   • Enter the login URL of your Salesforce org to be used (for example, https://login.salesforce.com/services/Soap/c/32.0)
   • You will also need to provide the Username nd Password to log on to Salesforce.
   • Copy and paste the security token generated by Salesforce.
4. Once you have provided all of the necessary information select Connect and the connection will be added to the Data Sources Pane.

Microsoft Dynamics

1. Start by selecting the Data Sources button in the Home Tab.
2. Select the Microsoft Dynamics tab in the Data Source Pane opened, then click on the New Connection hyperlink.
3. In the Microsoft Dynamic Connection Dialog, you will need to set up the configurations as needed.
   • Specify a unique Connection Name to be used.
   • Enter the Microsoft Dynamic URL
   • You will also need to provide the Username and Password credentials to log on to the Microsoft Dynamic connection.
4. Once you have provided all of the necessary information select Connect and the connection will be added to the Data Sources Pane.

EngageCX Server Connection

1. Start by selecting the Data Sources button in the Home Tab.
2. Select the EngageCX Server tab in the Data Source Pane opened, then click on the New Connection hyperlink.
3. In the EngageCX Server Connection Dialog, you will need to set up the configurations as needed.
   • Specify a unique Connection Name to be used.
   • Enter the URL of the EngageCX server.
   • You will also need to provide the Username and Password credentials to log on to the EngageCX Server.
   • Optionally, provide the environment name.
4. Once you have provided all of the necessary information, select Connect and the connection will be added to the Data Source Pane.

Edit EngageCX Server Query

You can double-click on an object-collection from the Design Surface and create a customized query for obtaining limited results, in case the data collected from the EngageCX server is too large. A new dialog will be opened, where you can do several configurations related to the object you are currently editing.

1. In the Edit EOS Query dialog, you can change the Name of the object you are referring.
2. Switch between connections of the same object diagram in case you have installed EngageCX Platform on several machines.
3. Select Reload Data Source if you want to synchronize the current query with the data source which may result in removal of the invalid properties from the query.
4. Click Select Columns/Properties to choose only the columns which you intend to use in your query. Besides choosing from the columns in your table, you have also the possibility to use the submission forms. These tables/forms can be selected from the drop-down list on the toolbar under the Ribbon.
5. You can use filters in order to narrow the results from the data source. Click Edit Filters and then use the Add filter button to introduce as many filters as you need. You can visit Configure Filters section for more details.
6. Once you're ready creating your query, click Apply.
7. Select Results to view the filtered results.

Document DB

1. Start by selecting the Data Sources button in the Home Tab.
2. Select the Document DB tab in the Data Source Pane opened, then click on the New Connection hyperlink.
3. In the Document DB Connection Dialog, you will need to set up the configurations as needed.
   • Specify a unique Connection Name to be used.
   • Enter the Document DB Server URL that hosts the DB solution that you want to connect to.
   • Provide the primary key of the Document DB Server.
4. Once you have provided all of the necessary information, select Connect and the connection will be added to the Data Source Pane.

Creatio

1. Start by selecting the Data Sources button in the Home Tab.
2. Select the Creatio tab in the Data Source Pane opened, then click on the New Connection hyperlink.
3. In the Creatio Connection dialog, you will need to set up the configurations as needed.
   • Specify a unique Connection Name to be used.
   • Enter the Creatio Server URL that hosts the Creatio solution that you want to connect to. (e.g. http://< server_name >/< Creatio application_name >/0/ServiceModel/EntityDataService.svc/)
   • Specify a REST authentication service that manages user authentication. (e.g. http://< server_name >/< Creatio application_name >/ServiceModel/AuthService.svc/Login)
   • You will also need to provide the User Name and Password credentials to log on to the Creatio connection.
   • Select the Authentication Type between the two available options Basic or Cookie.
4. Once you have provided all of the necessary information, select Connect and the connection will be added to the Data Source Pane.

Edit Creatio Query

You can double-click on an object-collection from the Design Surface and create a customized query for obtaining limited results, in case the data collected from the Creatio server is too large. A new dialog will be opened, where you can do several configurations related to the object you are currently editing.

1. In the Edit Creatio Query dialog, you can change the Name of the object you are referring.
2. Switch between connections of the same object diagram.
3. Select Reload Data Source if you want to synchronize the current query with the data source which may result in removal of invalid properties from the query.
4. Click Select Columns to choose only the columns which you intend to use in your query. Besides choosing from the columns in your selected table, you have also the possibility to use the columns within associated one-to-one tables. These columns can be manually selected from the Select Columns dialog, in which Select all functionality will not be applied for them.
5. In case you select a one-to-one relationship table, you can click Edit to choose exclusively from its corresponding columns.
6. You can use filters in order to narrow the results from the data source. Click Edit Filters and then use the Add filter button to introduce as many filters as you need.
7. Once you're ready creating your query, click Apply.
8. Select Results to view the filtered results.

For more information regarding the Creatio Connection usage in Enterprise Portal, access the following link.

Configure Filters

When you want to see only a part of the rows in a table from a data source, EngageCX offers you the possibility to configure some filters by restricting the amount of data through a specified criteria. In Modeler, there are two types of filters:

• Standard Filters

  The standard filters restrict the information by only showing the rows where the values for a field meet some condition.

  1. In Edit Filters dialog, select Add filter.
  2. Create the filter condition:
     • Source - select the field based on which the filter will be configured; here you have the opportunity to set also filters on a One-to-One relationship tables.
     • Path - in case you have selected, in the previous field, a one-to-one relationship table, you should specify the path to the field source.
     • Function - choose the function to test the selected attribute from the available options in the drop-down list.
     • Default Value - assign a default value of the selected field for which the filter will test true.
     • Operator - if you have many filters, you can select a logical operator as the order of how they will be evaluated (And - all of them must be valid or Or - at least one filter must be valid).
  3. Once you're ready, click Apply to save the changes.

• Grouped Filters

  In case that many filters are applied to your data, you can choose how they should be grouped by making use of the buttons (Group With Next, Ungroup) on the top-right corner of the dialog. In this way, the filters are combined and they are assessed together as a single statement.

  1. In Edit Filters dialog, configure the filters you want to treat as nested, such that the filters are nearest to their group mates.
  2. Select the first filter in the group that you intend to create.
  3. The Grouping related buttons will become active on the top-right corner of the dialog and click Group With Next. On the outer-left region of the nested filters, there will be a parenthesis embracing the ones included in the group.
  4. Repeat the steps, until you have all the filters that you need configured.
  5. If you change your mind and there is one or many filters that you need to get out of the group, you should click Ungroup.
  6. Once you're ready, click Apply to save the changes.

REST API Connection

Follow the steps below to learn how to configure a REST API data source.

1. Start by selecting the Data Sources button in the Home Tab.
2. Select the REST API tab in the Data Source Pane opened, then click on the New Connection hyperlink.
3. In the REST API Connection dialog, you will need to set up the configurations as needed by filling out the form fields:
   • Specify a unique Connection Name to be used;
   • Enter the REST API URL;
   • Provide the Schema Path (by default, for EngageCX API Inspector is doc/v2/userapi);
     • Optionally, select Browse to upload a Schema File (JSON file) from your computer, in case there is no documentation on your server.
   • Choose the Authentication Type. The only supported type at the moment, for EngageCX API Inspector, is Basic. The type of authentication depends on the types that are implemented by the REST API server you intend to connect.
   • You will also need to provide the Username and Password credentials to log on to the REST API connection.
4. Once you have provided all of the necessary information select Connect and the connection will be added to the Data Sources Pane.

Connections Options

Using the Data Source Pane

Once you have added a Data Connection in Modeler, you will need to be able to access its content in the Data Source Pane.

Accessing Data Connection Objects

1. Select the arrows to the left of the connection and objects to expand or collapse information.
2. You can expand available Tables, Views, and Stored Procedures, to include them directly in your diagrams by dragging and dropping into the Design Surface.
3. In addition, you can also expand Tables to view the columns that are present within.

Edit, Reload or Delete a Data Connection

Edit a Connection

1. In the Data Source Pane, select the Options button located at the right of your connection.
2. Select Edit from the contextual menu to launch the Data Connection Dialog.
3. The Connection Dialog will now be presented so you can make adjustments to your configuration.
4. When making edits, select Test Connection to establish your edits are accurate, and select Save when complete to return to your design.

Reload a Connection

1. In the Pane, select the Options button located at the right of your connection.
2. Select Reload from the available options.
3. The Modeler will now communicate with the connection to update the display with the most recent schema and content.

Delete a Connection

1. In the Data Source Pane, select the Options button located at the right of your connection.
2. Select Delete from the resulting options menu.
3. You will receive a notification to confirm you wish to delete the Connection. Select OK to proceed or Cancel to abort the option to delete.
4. The Connection will now be removed from the Data Source Pane.

Working with Data Connection Tables

One of the most commonly used input data sources is tables.

Inserting a Table

1. In the Database Pane, expand the Tables present in your database connection to view available tables.
2. Select the table you would like to add to the Design Surface, hold the mouse button, and drag and drop the Table into the Design Surface. Release the mouse button and a Table Object will be created in the Design Surface. The database table will provide a Data Set Connector for all rows in the table and individual Data Connectors for all available columns present.
3. Next, establish Data Connections by dragging and dropping the table's Data Connectors to the output object or other Objects in the Design Surface.

View Table Data

Right Click Option

1. In the Design Surface, right click on the desired Table Object and select View Data from the resulting contextual menu.
2. The View Data Dialog will now be launched. A generic query will be launched and it will display a limited number of rows in the Results Window. You can select Show More to retrieve more data from the database table.

Data Pane Option

1. In the Data Sources Pane, expand the Tables present in your database connection to view available tables.
2. Select the Options button located at the right of your Database Table and select View Data.
3. The View Data dialog will now be launched. A generic query will be launched and it will display the resulting of rows in the Results Window. You can select Show More to retrieve more data from the database table.

Working with Database Tables Options

Defining a Foreign Key

You can define foreign keys to establish table relationships directly in the Modeler. Follow the instructions provided below to define a foreign key relationship with multiple tables.

1. First, understand the tables and the relationship you wish to define.
2. Right click on table to define a foreign key for in the Design Surface and select Properties. Additionally, you can simply double click on the Table Object to launch the Properties Pane.
3. In the Properties Pane, expand the Foreign Key Group and select Define.

4. The Foreign Key Dialog will now be displayed.

   • Select the Foreign Key Field from the drop-down menu of available columns in that table.
   • Select the Parent Table from a menu of available tables in your diagram.
   • Select the Parent Table Field from a drop-down menu of available columns in the parent table.

5. Select Apply to commit your changes. The Properties Pane will now display the Foreign Key information you have defined. In addition, the Design Surface will also display the Foreign Key relationship between the tables with a connection and a key icon.

Enable Caching

You can enable caching for your table to improve performance. This action will store the table results in memory so if the data needs to be accessed multiple times for usage, a full extraction will not be required every time. To enable caching for your table, use the following instructions.

1. In the Design Surface, double click on the Table Object or right click and select Properties from the resulting contextual menu.
2. The Properties Pane will now be visible. There will be a check box option to Enable Caching present in the Properties Pane. Select this option to Enable Caching for your database table.

Using Views

A Database View is a subset of the database designed to be display specified data in a particular fashion. Views can be created in a variety of fashions by the Database Administrator and if you have available Database Views, you can include them directly into your diagrams for usage. Follow the instructions below for including Database Views in your diagram.

1. In the Databases Pane, expand your Database Connection. Available Database Views will be listed in the Views Group. Expand this group to access your Views.
2. Drag and drop the View you would like to include in your diagram directly into the Design Surface and release. This will create a View Object in the Design Surface for your View. Notice the View Object will be present with all of the available returned columns that you can include in your output.
3. Now that your Database View is accessible in the Design Surface, drag the Data Connectors to the output object to include the data you wish to be present in the output.
4. Next, select the Preview button in the Home Tab of the Ribbon to test your results and ensure your View is returning the data as you intend.

Using Stored Procedures

A Stored Procedure is a subroutine designed in relational databases for reusable access. Often logic for data retrieval can be centralized in Stored Procedures for calling from other processes and maintained in only one location. A Stored Procedure is designed in a variety of ways, and if your database possesses these, they will be available to you to include in your data diagrams.

1. In the Databases Pane, expand your Database Connection. Available Stored Procedures will be listed in the Stored Procedures Group. Expand this group to access your Stored Procedures in this database.
2. To include a Stored Procedure in your diagram, select and drag and drop the Stored Procedure into the Design Surface. A Procedure Object will be created in the Design Surface and for Stored Procedures this will be displayed in gray. You will notice that within the Object, the available items to include in your output as a result of the Stored Procedure are located to the right side of the Object. Additionally, if the Stored Procedure requires input values for processing, these will be located to the left as input Data Connectors.
3. You will need to establish Data Connections to specify where the input will come from as well as drag and drop the returned data points into the output object to include in your output.
4. Lastly, select the Preview button in the Home Tab of the Ribbon to view your output and ensure your Stored Procedure is returning your data as expected.

Other Data Input Options

You can include data from other non-database sources such as XML Files, CSV Files, Web Services, and more.

XML

If you have data residing in an XML File that you would like to include in your output design, use the sections below to explore how to insert XML Data Sources as well as explore other available options.

Inserting an XML Data Source

1. Select the XML File button located in the Insert Tab of the Ribbon.
2. The Insert XML Dialog will now be displayed. To begin select Browse in the file URL field and navigate to your input XML File to use.
3. Your selected file will be displayed after choosing. You can now select the Embed File Bytes option to embed the XML Source bytes in the diagram and additionally if the XML Input File has an associated Schema, you can select the Browse button below the XSD option to navigate and select your XSD schema.
4. Select Insert when you have finished your selections. The XML File's contents will now be added into the Design Surface as an orange colored XML Object. The structure of the XML will be present in the XML Object including dark blue Data Set Connectors for repeating elements and light blue Data Connectors for attributes and text values.
5. You can now proceed with your diagram design utilizing the input data source. Drag and drop Data Set and Data Connectors into the output object to create repeating content and unique data points as required in your output. When you want to include all child elements or attributes for any element in your input source, hold down the Control Key on your keyboard when dragging over an element from the XML Source.
6. Select the Preview button in the Home Tab to view your data to ensure the data collected from the XML File is being retrieved appropriately.

Use a Parameter to Override XML Source Path

1. Follow all of the necessary steps to insert an XML Data Source into your diagram.
2. Next, add a parameter into your diagram by selecting the Parameter button in the Objects Group of the Home Tab.
3. Double click on the Parameter Object to launch the Properties Pane.
4. Specify a name for the parameter and the value type. Add a value that you would like to use as default as well as for testing purposes. When testing the overriding of the source for the XML Data Source, you may wish to access the Properties Pane again to edit this value and modify for testing. You can do so at any point by double clicking on the Parameter Object in the Design Surface. In our example, we want to use a string value and set to a test file we know the path for to test the collection of the XML Input.
5. Map the Parameter Object to the XML Data Source Object by dragging and dropping the Data Connector for the parameter to the Override Path Data Connector.
6. Test your output by selecting the Preview button in the Home Tab. The path specified in the input Parameter should be used to collect the correct XML Data Source File.
7. It is recommended that you repeat step six after changing the Parameter Value to another known input source for testing purposes.

JSON

If you have data residing in a JSON File that you would like to include in your output design, use the sections below to explore how to insert JSON Data Sources as well as explore other available options.

Inserting a JSON Data Source

1. Select the JSON File button in the Insert Tab of the Ribbon.
2. The Insert JSON Data Source dialog will now be displayed. Select the Browse button to navigate to your computer and select your input JSON File. The file path will be displayed in the dialog.
   1. You can select the Embed file bytes option to embed the JSON File into the diagram. This is optional and can be used if the JSON File is static and does not change.
3. Optionally, select the Browse button in the Schema File box to navigate to your computer and select an input schema (e.g. .xsd file) that uses a JSON file. The file path will be displayed in the dialog.
   1. Select Embed schema bytes to embed the JSON schema in the current diagram. This is optional.
4. When you are satisfied with your configurations, select Insert to add the JSON File into the Data Diagram. You will notice a orange JSON Data Source Object added into the Design Surface for your JSON File. This will include all available column information as output Data Connectors as well as an input Data Connector to override the source file path dynamically.
5. You can now interact with the JSON Object to drag and drop Data Connectors to your output object or other JSON Object to create Data Connections.
6. Lastly, select the Preview button in the Home Tab to ensure your output data is retrieving from the JSON File as expected.

CSV

A Comma-Separated Values file stores tabular data in plain text. These files normally consist of records with fields that are separated by tabs or commas. These can also be used as data sources when working in the Modeler to design your Data Diagrams.

Inserting an CSV Data Source

1. Select the CSV File button in the Insert Tab of the Ribbon.
2. The Insert CSV Dialog will now be displayed. Select the Browse button to navigate to and select your input CSV File. The file path will be displayed in the dialog.
3. You can select the Embed File Bytes option to embed the CSV File into the diagram. This is optional and can be used if the CSV File is static and does not change.
4. Expand the Options Group. You can specify other options regarding your CSV File in this menu. Available options include:
   • Enable Caching - used to cache CSV content for performance improvement when referenced many times.
   • Contains Column Name - check this box if you input CSV File contains column names.
   • Automatically Determine Value Types - check this box if you would like the Modeler to automatically determine value types for data in your CSV File.
   • Discard Last Rows - specify this value if you have rows in your input CSV File after content that you wish to discard.
   • Specify Comma Separator - add the character used as a separator in your CSV File.
   • Select Encoding Type - Use the drop down menu to switch between Unicode and ANSI and Multibyte encoding options. For ANSI and Multibyte you can also select an available Charset.
5. Expand the Advanced Group. Select the Enable Values Coercion option to utilize conversion of empty and invalid values to a value you specify or leave null. The Modeler will find empty or invalid values in your input data source and map according to the values that you provide in the available fields. This is a valuable feature to automate the conversion of a CSV File that may contain empty cells that would impact calculations in your Data Diagram.
6. When you are satisfied with your configurations, select Insert to add the CSV File into the Data Diagram. You will notice a dark green CSV Object is added into the Design Surface for your CSV File. This will include all available column information as output Data Connectors as well as an input Data Connector to override the source file path dynamically.
7. You can now interact with the CSV Object to drag and drop Data Connectors to your output object or other CSV Object to create Data Connections.
8. Lastly, select the Preview button in the Home Tab to ensure your output data is retrieving from the CSV File as expected.

Editing CSV File Settings

1. In the Design Surface, right click on the CSV File Object and select Properties. You can also simply double click on the Object. Either option will launch the Properties Pane.
2. In the Properties Pane, you will have access to all options used when inserting a CSV File. These options include browsing to select a different file, enable caching and embedding options, changing encoding, enabling values coercion, and much more.
3. You can also make edits to the properties by right clicking on the CSV File Object and selecting the Edit option from the contextual menu.
4. After making any necessary adjustments in the Properties Pane, you will need to select Apply located at the bottom of the pane. Your changes will then be saved and you will be returned to the Design Surface.

Excel Spreadsheets

1. Select the Excel File button in the Insert Tab of the Ribbon.
2. The Insert Excel Dialog will now be displayed. Select the Browse button to navigate to and select your input Excel Spreadsheet. The file path will be displayed in the dialog.
3. You can select which sheets you would like to include in your diagram. You will have the ability to select if the sheet contains column names, and if you would like the Modeler to automatically determine the value types in your spreadsheet. If you do note want to Modeler to automatically determine the value types in your spreadsheet all of the values will be treated as string values.
4. Once you have had all the configurations needed select insert and the Excel Object will be shown in the Design Surface. You will notice a light blue Excel Spreadsheet Object is added into the Design Surface for your Excel Spreadsheet. This will include all available column information as output Data Connectors as well as an input Data Connector to override the source file path dynamically.
5. You can now interact with the Excel Spreadsheet Object to drag and drop Data Connectors to your output object or other Excel Spreadsheet Object to create Data Connections.
6. Lastly, select the Preview button in the Home Tab to ensure your output data is retrieving from the Excel Spreadsheet as expected.

Text

TXT Files are files that are commonly used for storage of information that has no special formatting. These files normally consist of plain text structured as a sequence of lines delimited by end-of-file markers. These file types can also be used as data sources when working in the Modeler to design your Data Diagrams.

1. Select the Text File button in the Insert Tab of the Ribbon.
2. The Insert TXT Dialog will now be displayed. Select the Browse button to navigate to and select your input Text File. The file path will be displayed in the dialog.
3. You can select the Embed File Bytes option to embed the TXT File into the diagram. This is optional and can be used if the Text File is static and does not change.

4. Expand the Options Group. You can specify other options regarding your TXT File in this menu. Available options include:

   • Select Encoding Type - Use the drop down menu to switch between Unicode and ANSI & Multibyte encoding options. For ANSI & Multibyte you can also select an available Charset.

   • Select charset - Use the drop down menu to select a character set from the available ones. Note: This option is only available if the Encoding Type is set to be ANSI & Multibyte.
     
     Currently we support the following character sets:

   • ISO8859: ISO8859-1 (Western European), ISO8859-2 (Eastern European), ISO8859-4 (Baltic), ISO8859-5 (Cyrilic), ISO8859-6 (Arabic), ISO8859-7 (Greek), ISO8859-8 (Hebrew), ISO8859-11 (Thai)

   • WINDOWS: WINDOWS-1250 (Central European), WINDOWS-1252 (Western European), WINDOWS-1253 (Greek), WINDOWS-1254 (Turkish), WINDOWS-1255 (Hebrew)

5. Once ready, select Insert to add the TXT File into the Data Diagram. You will notice a light blue Text Object is added into the Design Surface for your TXT File. This will include the available information as a "Content" field with an output Data Connector. Unlike the CSV file, this Diagram Object cannot have the path overwritten dynamically, so it does not have an input Data Connector.

6. You can now interact with the TXT Object to drag and drop the Data Connector to your output object or other Text Object to create Data Connections.
7. Lastly, select the Preview button in the Home Tab to ensure your output data is retrieving from the TXT File as expected.

Subdiagrams

Using Subdiagrams is a helpful way to segment the functionality that you design for reuse in other diagrams. It is a helpful tool when using a common procedure designed in a diagram across many other diagrams because modifications only need to be made in one location and subsequently the other diagrams will inherit the adjustments. To insert a Subdiagram, use the following steps.

1. Begin by ensuring proper design of your Subdiagram. You will need to know the location where the diagram is saved and have a good understanding of its usage and functionality.
2. Next, in your new diagram, select the Subdiagram button in the Other Data Sources Group of the Insert Tab.
3. In the resulting Insert Subdiagram Dialog, select Browse to navigate and select your Subdiagram to be inserted.
4. Select Embed File Bytes to embed the Subdiagram in the current diagram. This is optional.
5. Select the Insert button at the bottom of the dialog to inset the Subdiagram. The Subdiagram will be present as a DAX Object in the Design Surface. You will notice that the output results will be present as available Data Connectors.
6. Establish Data Connections by dragging and dropping desired data points into the output object or other diagram objects.
7. The result of this diagram will call upon the Subdiagram to execute its aggregation as you have designed. The returned content will be mapped to your output or objects as you have designed. You can preview the output to ensure your Subdiagram is behaving as intended by selecting the Preview button in the Home Tab.

Plugings

You can include previously constructed libraries in your diagrams using the following instructions.

1. In the Ribbon, select Plugins in the Insert Tab.
2. Select Browse in the resulting Insert Plugins Dialog. Browse for the dll of your choosing and select.In this example, we will use the ExternalFunctionSample.dll that can be found in the Library Samples directory when installing the EngageCX Studio.
3. The available Plugin Methods will be listed in the Dialog. You can expand the Methods and view Input Parameters and Output Parameters that will result from the function's usage.
4. Select the Method you would like to insert into your diagram and a check mark will be displayed to note your selection. Select the Insert button at the bottom of the Dialog to insert into your diagram. An External Function Object will now be created in the Design Surface. You will notice that input parameters and output parameters will be displayed with available Data Connectors for mapping.
5. You can now map data to and from the External Function Object by dragging and dropping Data Connectors.
6. Preview your output to ensure the function is returning the correct information by selecting the Preview button in the Home Tab.

File Collection

The Modeler can be used to obtain data from a large collection of files located in a central directory. To utilize this feature, your files will need to be of the same type and structure.

Set up Input

To set up your diagram to collect data from a File Collection, use the steps provided below. Remember that your files need to be of the same type and structure in order to use this feature.

1. In the Insert Tab of the Ribbon, select File Collection from the Other Data Sources Group.
2. In the Source Field, specify the file path to the directory of where your collection of files is located. In our example, we will use a directory containing 3 input XML files to retrieve data from.
3. Next, in the File Pattern field, specify the file pattern the Modeler will search for. You can use wildcards in your file names to specify an ambiguous pattern.
4. You can select the Search in subdirectories check box if there are subdirectories containing files that you would like to include in this collection.
5. Select Insert when your setup is complete, and a File Collection Object will be inserted into the Design Surface. Notice that the File Collection Object contains input Data Connectors if you wish to override the specified source and file pattern dynamically from other inputs like parameters or database content.
6. Establish a Data Set Connection from the File Collection to the output by dragging and dropping the dark blue Data Set Connector to the output object. This will create a repeating object in the output for each file retrieved.
7. Now it is necessary to add a sample input source to include which data points you wish to use. Add one of the files with the same structure as a sample.
8. Connect the file output Data Connector from the File Collection Object to the XML Data Source input connector for Override Path. For each XML collected this will be used as the source for the input XML File.
9. Drag and drop Data Connectors from the XML Data Source Object to the output object to include the data you wish to retrieve from the source files.
10. Once ready, select the Preview button in the Home Tab to view your output and ensure the File Collection setup is working appropriately.

Edit Properties

If you would like to edit the File Collection properties at any point after inserting, follow the instructions provided below.

1. Right click on the File Collection Object in the Design Surface and select Properties from the contextual menu. You can also simply double click on the File Collection Object. Both of these options will launch the Properties Pane.
2. In the Properties Pane, you will have access to the same configurations you used to insert the File Collection Object. Use the Properties Pane to edit the source, file pattern, and specification to look in subdirectories.

Dynamically Set Source and File Pattern

While you can statically specify the source directory and file pattern to use for a File Collection Object, there may be times when you wish to drive this process in a more dynamic approach like passing these values in from your application. The steps provided below highlight overriding the source directory and the file pattern used to determine where and what the File Collection Object will retrieve data for in your diagram.

1. Make sure you have followed all of the necessary steps to set up a File Collection Object in your diagram.
2. The File Collection Object possesses two input Data Connectors. You can use these to override these values from other dynamic sources such as database columns. In this example we will configure parameters to overwrite these values from an application.
3. In the Home Tab, select the Parameter button to add an input parameter into your diagram.
4. In the Design Surface, double click on the Parameter Object to launch the Properties Pane.
   • Specify a name.
   • Select the value type.
   • Set the default value of the parameter.
   • Remember, you can always access this menu by double clicking to change the default value for testing the behavior of your parameter. The value will actually be overwritten from your application at run time.
5. Next, repeat steps 3 and 4 to add an additional Parameter for the file pattern. Again, this value can be determined from information collected from the user in the application and passed to the diagram.
6. Connect the light blue Data Connectors for both parameters to the source and file pattern Data Connectors in the File Collection Object.
7. Select the Preview button in the Home Tab to see if the File Collection uses the parameters effectively. Remember that the default values set for the Parameters will be used to determine the source folder and the file pattern to use when collecting the files.
8. It is recommended that you now set up another test directory with sample files and modify your parameters to collect from this location and repeat step eight.
9. Additionally, you can reference the Data Aggregation Server Documentation to learn more in the programming manual about testing the parameter functionality from an application you create.

Web Services

The Modeler can be used to aggregate data from Web Services.

To insert and configure a Web Service as a data source in your diagram, use the instructions provided below.

1. In the Insert Tab of the Ribbon, select the Web Service button to insert a Web Service Object into your diagram. This will launch the Insert Web Service dialog.
2. First, you must know the Web Service Description Language (WSDL) URL for the Web Service. This URL will point to the WSDL Description which contains the provided functionalities for the Web Service. The Modeler will use this to collect this necessary information for further configuration. Place your WSDL URL in the available field. For our example, we will use a sample Web Service that calculates temperature from Fahrenheit to Celsius.
3. When you add your Web Service WSDL URL, select the Collect button. The Modeler will retrieve the available methods from the WSDL and display for you in the dialog.
4. To insert one of the available methods, select in the dialog to reveal a button to insert into the diagram. Select the Insert button to the right to insert into your diagram.
5. A Web Service Object will now be inserted into the Design Surface. You will notice that the Web Service may require input parameters to represent information it must receive. These are present as light blue Data Connectors. In addition, you will see available output Data Connectors to map the results to your output data or to other diagram objects.
6. Next, connect your source for input data to the input Data Connector in the Web Service Object.
7. Map the output Data Set and Data Connectors to your output object or other diagram objects as needed. In this example, the constant value "75" will be passed to the Web Service where it will be converted to Celsius and the returned Celsius value will be included in the output XML.
8. Once ready, select the Preview button in the Home Tab to view the results of the data collection.

Data Set Commands

Join

A Join Command is useful for combining two or more input data sources based upon a condition that you specify. An example of Join Command usage would be if customer data was stored in two separate tables in a database. One table holds information about the customer address information and another holds transactional history information. Both are contain an identifying column called ID that is not an established foreign key.

Using a Join Command can allow the retrieval of the transactional data from the first table, and for each customer, also search the address table to compare ID's and when found, include the address information specified. This operation joins specified transactional and address information for each customer when the ID fields are equivalent.

Use Command

The Join Command can be inserted into your Data Diagrams when you would like to join data from multiple data sources based upon a condition. To insert and use a Join Command follow the instructions provided below.

1. First, you will need to add the Diagram Objects to Join into the Design Surface.
2. In the Insert Tab of the Ribbon, select the Join button from the Data Set group to add a Join Command Object into the Design Surface. The Join Command Object will now be placed in the Design Surface. Reposition for usability in your diagram.
3. Use the Data Set Connectors to connect both the parent and the child data sources to the Join Command. You can add more data sources by right clicking on the Join Command and selecting Add Join Child.
4. You will need to use available functions to build the conditional test to be used as the condition. The result will yield a true or false value which will be used to join. Connect the output of your logical test to the condition Data Connector.
5. Next, include the joined data set to your output object by dragging and dropping the Data Set Connector from the Join Command to the output object. Then, drag and drop the data points you wish to include from each input data source to your output object.
6. Lastly, select the Preview button in the Home Tab to ensure that your Join Command is providing the correct results.

Command Options

By default, the inserted Join Command is specified as an Inner Join. You can modify the Join Command to be a Left Join or Inner Join by following the instructions provided below.

Inner Join - returns all rows when there is at least one match in both sources.
Left Join - returns all rows from the parent data source and the matched rows from the child source.

1. Right click on the Join Command Object in the Design Surface and select Properties from the resulting contextual menu or simply double click on the Join Command Object.
2. The Properties Pane will now be displayed. For your Join Command, you can now select the Join Type from the drop down menu.
3. The Join Command will be updated in the Design Surface to display the type of Join. For Inner Join, the default Join will be displayed.

Group By

The Group By Command can be used to select records from a data source that generate distinct values for a specified field. This option can be particularly useful when you want to retrieve data for a particular group of fields sharing the same values of your choosing. In this section, you can find helpful information on when you would use a Group By Command and how you can insert them into your Data Diagrams.

An example of using a Group By Command in your Data Diagram would be if all sales data for a given year was stored in a table. This table could possess multiple occurrences for every product offered. If your requirement is to count how many of each product were sold in that given year, you can use a Group By Command to first group the data for every product, then use a Count Function to count the occurrences of every individual product value in the table. An example of such usage would reflect an output such as the following:

product="hats" count="234"
product="gloves" count="400"
product="pants" count="1320"

Use Command

To utilize the Group By Command in your data diagram, use the helpful steps and example provided below.

1. Begin by adding the input data source you wish to retrieve data from in the Design Surface.
2. Select the Group-by button located in the Insert Tab of the Ribbon. The Group By Object will now be added into the Design Surface. Reposition this object for your design needs.
3. Connect the dark blue Data Set Connectors from the input data source to the Group By Object. Then, connect the light blue Data Connectors for the group rule. The Group By Command will use the input data point you specify for the group rule to determine the grouping behavior to return a singular unique occurrence for each value.
4. Next, you will need to use the result of the Group By Command for your design needs. As an example, we will use a Filter Command and the Count Set Function to uniquely sum both male and female employees. Here we will filter the data set for the key for each group, then use the Count Set Function to return the count for each unique group key. Data Connections are all established by dragging and dropping Data Connectors.
5. Select the Preview button in the Home Tab to preview the XML output to determine if our diagram is performing as expected.

Filter

A Filter Command is used for when you need to filter a data set based upon a certain condition. This type of Object can be incredibly useful for filtering your input data source to reflect the output only necessary for your output data needs.

An example of using a Filter Command to meet the filtering needs of a particular Data Diagram design would be if a particular data source held key data on all sales data. Let's assume such a data set possessed a field called Territory which held values related to what territory each sale was made in. For certain reporting needs, we would only need to access the information present for one Territory at a time. In this situation we could use a Filter Command to test when the Territory field holds the value of our desired territory and obtain only the data related to that specified value.

Use Command

Use the instructions provided below to insert and configure a Filter Command in your data diagram.

1. Begin by adding the input data object that you would like to filter into the Design Surface.
2. Insert the Filter Command, by selecting the Filter button located in the Data Set Group of the Insert Tab in the Ribbon. The Filter Command will now be present in the Design Surface. You should reposition for your design needs in the Design Surface.
3. Create Data Connections from the input data source to the Filter Command and from the Filter Command to the output object. This is accomplished by dragging and dropping the blue Data Set Connectors.
4. Next, you will need to create a logic test for your filter rule. You can use the available functions to set up a rule in your diagram. A logical equals function will test when the external parameter value equals that of the SalesOrderID column value and filter the data set to only provide the data for that Sales Order. Insert an equals function from the Logical Menu in the Functions Group of the Insert Tab. Next, create Data Connections by dragging and dropping the Data Connectors to the equals function and the result to the Filter Rule input Data Connector.
5. Include any data points in the output object by dragging and dropping from the input data source.
6. Lastly, select the Preview button in the Home Tab to view your output and ensure that the Filter Command is working as designed. In our example, we have set the input parameter default value to be '43659' to test for a known Sales Order ID. When previewing all orders will be filtered to only return the data related to this Sales Order ID.

Sort

A Sort Command be a useful addition to your Data Diagram when you are looking to sort your included output data based upon a specified sort rule. Such design can be important when designing data sources to be used by reports needing the data to be sorted without needing to sort the data through the report template. In this section, you can find helpful information on inserting and configuring a Sort Command in your Data Diagram to meet your sorting needs.

Use Command

1. Begin by adding the input data source you would like to sort into the Design Surface.
2. In the Insert Tab of the Ribbon, choose the Sort button and specify the sort order which you would like to use. The Sort Object will be placed into the Design Surface. Reposition this object in a location that suites your design needs.
3. Drag and drop the dark blue Data Set Connectors to the Sort Object and from the Sort Object to the output object.
4. Use the light blue Data Connectors to add the data point you wish to sort the set by. Connect this item to the sort rule Data Connector.
5. Now drag and drop the data points from the input Table Object to the Output Diagram Object to include in the output.
6. Select the Preview button in the Home Tab to view your output and ensure that the sorting is working as intended.

Functions

You will need to use Functions in your Data Diagrams to test and transform your data. These helpful tools allow you to create expressions for testing and fine tune the data that resides in your data sources to produce the optimized data for your needs. In this section, you will find helpful information on the available functions that you can choose from.

General use of Functions

1. Begin by understanding the a Function typically performs a job that depends upon input Data Connectors that you must establish with other data sources and output Data Connectors containing the results of the Function's operation. Functions are normally placed between objects in your diagram for easier mapping so make sure enough space is allocated to insert your Function.
2. Understand what type of operation you would like to accomplish.
3. In the Insert Tab, select the Function Group button to meet your desired needs, and select from an available list of functions for that group.
4. Your Function will now be inserted into the Design Surface. Drag and drop the Function Object to a location where you can easily map data to and from the Object and map the data desired from your input source to the function's input Data Connectors.
5. You can now include the results to other objects including your output object by dragging the Function's output Data Connector to your desired location. In our example, we'll insert another Function (from the aggregate group - Sum Set) to sum the set of all products ordered to get an order total and map the results to that function. This diagram will be a multiplied value for each product order, then sum all of those values in the data set to provide a total sum of all products in that order. This demonstrates that a functions output may often need to be mapped to another function's input Data Connector for further usage before including in your output.

Constant

You will often need to use Constants to define values for your testing that are static. Constants can be a variety of different types such as integer, string, and date and hold the value that you specify.

We'll take an example based upon our sample database Table source. If we wanted to filter the data set such that only values of UnitPrice greater than 50 are to be included in our output data, we would need to declare a Constant of integer value type and set the value to 50. Once inserted into the Data Diagram, simply double click on Function object to access the Properties Pane.

Math Functions

Math Functions can be very useful to perform operations on your input data but are also used for comparison and value finding objectives. These helpful functions allow you to perform such operations as addition, subtraction, finding maximum or minimum values, and more. In this section, you can find information on the available Math Function and how they can assist you in meeting your Data Diagram design needs.

Max

This Function can be useful when you are in need of comparing two or more values and returning the maximum value of the two. As an example, we only want to display prices in our output as 20 and above. We will use the Max() function to test UnitPrice against a Constant that is set to 20. Here you will see that for every UnitPrice, whichever value is greater, 20 or the UnitPrice value, will be displayed.

By default, the Max() Function has two input value connectors. You can add additional parameters by right clicking and selecting Add Parameter from the Application Bar. Below you can find a sample diagram and it's resulting output.

Min

This Function can be useful when you are in need of comparing two or more values and returning the minimum value of the two. As an example, we only want to display prices in our output as 20 and below. We will use the Min() function to test UnitPrice against a Constant that is set to 20. Here you will see that for every UnitPrice, whichever value is less, 20 or the UnitPrice value, will be displayed.

By default, the Min() Function has two input value connectors. You can add additional parameters by right clicking and selecting Add Parameter from the Application Bar. Below you can find a sample diagram and it's resulting output.

Average

The Average function is useful when you would like to calculate the average of two or more input values. As an example, let's imagine that the previous two years, a standard discount has been given of 2 and 3 dollars. Given that each order has its own discount value, we can compute an average discount, per product, to determine what the average discount has been per order. In this example, we'll use Constants to portray the previous two year discount values. By default, the Average Function has two input value connectors. You can add additional parameters by right clicking and selecting Add Parameter from the Application Bar. Here we have done so to add a third parameter. Below you can find a sample diagram and it's resulting output.

Sum

The Sum function is useful when you would like to find the Sum of two or more values. As an example, we may know that for every order placed, there is a standard processing fee of 2 dollars. This would mean that we would need to include a sum of both the UnitPrice value and a constant with value of 2 to get the finalized UnitPrice which includes the standard processing fee.

By default, the Sum Function has two input value connectors. You can add additional parameters by right clicking and selecting Add Parameter from the Application Bar. Below you can find a sample diagram and it's resulting output.

Subtract

The Subtract function is useful for when you would like to subtract two or more values. As an example, we want to find the final price after applying a discount. We use a Subtract function to first specify the UnitPrice field as a parameter and then the Discount field as a parameter. The result will yield a final price of the order after subtracting the discount.

By default, the Subtract Function has two input value connectors. You can add additional parameters by right clicking and selecting Add Parameter from the Application Bar. Below you can find a sample diagram and it's resulting output.

Multiply

The Multiply function is used to find the product of two values. As an example, if you wanted to find the total order amount, you would be in need of multiplying the UnitPrice field by the Quantity field to obtain the total order amount.

By default, the Multiply Function has two input value connectors. You can add additional parameters by right clicking and selecting Add Parameter from the Application Bar. Below you can find a sample diagram and it's resulting output.

Divide

The Divide function is used to find the divide one data value by another. An example of such usage would be if, for shipping purposes, every order quantity had to be divided by 2 and displayed in the output XML for printing purposes. When inserting a Divide function, you can specify both the dividend and the divisor. In our example, we have specified our dividend to be the Quantity field and the divisor to be a Constant assigned the value of 2. Below you can find the example diagram demonstrating this, as well as the corresponding output data.

Modulus

The Modulus function can be useful in examples where any negative value must be returned as a positive value. An example of such usage is if we incurred a penalty which required a 10 dollar payout per UnitPrice for every order placed. In some cases we may see that the overall UnitPrice may dip below zero as a negative number. To also obtain just the value as a positive figure, we will use the Modulus function. The Modulus function simply has one input Data Connector where you will include the value to use. In this example, we've subtracted 10 first, and with the result, used the Modulus function.

Ceiling

The Ceiling function can be useful if you are looking to obtain the smallest following integer in relation to an input value. As an example, if we are looking to obtain the next integer price point in relation to our UnitPrice per order, we can use the Ceiling Function to find the smallest following integer. This function, when inserted, only possesses one input Data Connector. For this example, we will use the UnitPrice field from our table with our Ceiling Function.

Floor

The Floor function can be useful if you are looking to obtain the largest previous integer in relation to an input value. As an example, if we are looking to obtain the previous integer price point in relation to our UnitPrice per order, we can use the Floor Function to find the largest previous integer. This function, when inserted, only possesses one input Data Connector. For this example, we will use the UnitPrice field from our table with our Floor Function.

Aggregate Functions

Aggregate Functions are useful for performing calculations by iterating through a data set and computing the chosen function of your choice. These types of functions are used in example such as summing every field of an entire database table, finding the minimum value for a particular attribute present in a repeating node set in XML, and much more. In this section, you can find helpful information on each Aggregate Function available to you.

Max Set

The Max Set function is used to iterate over a specified input data set to compute the maximum value found for a specified input parameter. As an example, a report needs to find the specific value of the largest order that was placed. For this, we'll use the Max Set function to iterate through our database table, and compute the maximum value for the Quantity field. Notice how the Data Set Connector is used to map the entire table data set and the Quantity field is connected to the function's input parameter Data Connector.

Min Set

The Min Set function is used to iterate over a specified input data set to compute the minimum value found for a specified input parameter. As an example, a report needs to find the specific value of the smallest unit price that was offered for every order. For this, we'll use the Min Set function to iterate through our database table, and compute the minimum value for the UnitPrice field. Notice how the Data Set Connector is used to map the entire table data set and the UnitPrice field is connected to the function's input parameter Data Connector.

Average Set

The Average Set function is used to calculate the average of the values present for a specified input parameter in a data set. For this example, we want to retrieve what the average discount that was applied was for all orders. In order to accomplish this goal, we will use the Average Set function, Map the table and function Data Set Connectors, and map the Discount field as the input parameter.

Sum Set

The Sum Set function is used for situations where you would like to compute the sum value for all values present for a specified data point. As an example, we want to find the total combined sales for every order in our database table. We first are going to use a Math Function to help us compute the total sale per product by multiplying the UnitPrice by the Quantity. Then, we will use this value as our input parameter for our Sum Set Function. This will sum all of these values as computed for the entire data set.

Count Set

The Count Set function is used when you wish to return the computed count of records in a data set. As an example, we need to know the total number of orders placed. In order to accomplish this, we will use a Count Set function and use a Data Set Connection to map our orders table as the input set to count by the Count Set function. Next, the result will be mapped to an output data source.

Conversion Functions

Conversion Functions are useful when you are attempting to change the data type of a specified input data field. In this section, you can find useful information on when using these functions in your Data Diagrams as well as descriptions of each function.

To Bool

A Boolean data type is used to return either True or False. This function converts all data types, with the exception of the DateTime format, to Boolean values. All numbers other than "0" are converted into "true" and "0" is converted into "false". String values other than "true" convert into "false".

To Byte

You can use this function to convert a numerical value to byte format.

To Short

The Short data type can be used to represent a whole number which may take less storage and having a smaller range. The To Short function will convert Boolean or numerical values to short values.

To Int

For situations where the Integer data type is required, the To Int function can be used to convert both Boolean or numerical values to integer values.

To Long

For needs that require a larger integer values data types, you can use the To Long function to convert Boolean or Numerical values to Long value types.

To ushort

The ushort data type is a 16-bit integer from 0 to 65,535. Select this function to convert values to the ushort data type.

uint

The uint data type is for four byte unsigned integers ranging from 0 to 4,294,967,295, inclusive. Use the To uint function to convert current values into this data type.

ulong

The ulong data type is for unsigned 64 bit integers ranging between 0 to 18,446,744,073,709,551,615. Use the To ulong function to convert current values into this data type.

Float

The Float data type is stored as four bytes and is a single precision floating point number. To convert any current values to the Float data type, use the To Float function.

To Double

The Double data type is used for double-precision floating point numbers. To convert any current values to the Double data type, use the To Double function.

To DateTime

The DateTime data type is used to represent an instance in time, usually for data and time specifically. To convert any data type into date format, use the To DateTime function.

To Number

Use To Number to convert data types to the Number data type.

To String

The String data type is used for a sequence of characters. To convert all data types into the string data type, use the To String function.

Database

Database Functions are specifically related to database operations you may require. You can access these functions by selecting the Database button in the Functions Group of the Insert Tab.

Is Null

The Is Null function will test a provided database column to see if the column contains a Null value. The result of this function will be a Boolean value of true or false. This function can be useful for cleansing data to replace Null Values with a placeholder value for calculations, for example.

Logic Functions

Logical Functions are useful when using functions for logical comparisons. Situations such as testing two data points for equal values, testing data points for the greater value, and for other logical needs such as "and" and "or". In this section, you will find helpful information on each of the available Logical Functions.

Not

The Not Functions is used for situations where we want to find the negation of a input Boolean parameter. An example of such usage would be if a database contained information about employees and their work hours. In a monthly report, we need to list all of the logged departments that employees worked for with the exception of the Sales Department hours. Logically, this example would list as "find all of the work history records where the department does not equal sales". In the Modeler, we will need to use a diagram that tests if two values are equal, then proceeds to find the negation of this value using the Not Function. For this, in Diagram 2, you can notice that the equals function is used to first test for department values equal to sales. The result is used as a the input parameter for the Not Function, and the result will be used as the input parameter for the Filter function. This will filter the data set to only provide records where the department is Not equal to Sales. See the help section on the Not Equal Function for a more ideal approach to addressing this example scenario.

Equal

The Equal Function is used to test if two values are equivalent. This function can be useful for comparing two or more data fields for equality. The result of this function will be a Boolean value of true or false. An example of this function's usage is highlighted also in the example for Not Functions. In this example, we test an input field from a database table to see if it equals a constant given the value "Sales". This function will test each Department field for the value "Sales" and return true or false which will be used by another function. You should be aware that by right clicking the Equal Function in the Design Surface, you can access the Application Bar to add additional input parameters to be used by your function.

Not Equal

You can use the Not Equal function to return the value of true if two input parameters are not equal to each other. Let's take the same scenario as described in using the Not Function. A database contains information about employees and their work hours. In a monthly report, we need to list all of the logged departments that employees worked for with the exception of the Sales Department hours. We can use the Not Equal function to test for all department values that are not equal to the string "Sales". Here, we will insert a Not Equal function, specify the Department field as our first parameter and the constant "Sales" as the second. The result will be used to as our Filter function input parameter (a Boolean value).

Greater or Equal

The Greater or Equal function is used in situations where you wish to test for values that are greater than or equal to another specified value. An example of this function's usage would be returning only records from an employee work history table where the hours worked is greater than 1000. In this example, we'll use a Greater or Equal function to test the Hours Worked field with a constant set to 1000. Notice how Data Connections are made to map the input data points to as both input parameters in the function. The result is mapped to be used as the input parameter in the Filter Command.

Greater

The Greater function is used to compare the first input parameter with a second and returns the value true if the first parameter (op1) is greater than the second (op2). For this example, we will use the scenario where we would like to obtain only records from a database table where the work hours are greater than 1000 (but not including 1000). This is where the Greater Function will prove useful. We will simply need to insert into the Design Surface, then use both the Hours Worked field and numerical constant (1000) as input parameters op1 and op2. We will use the result as an input parameter for our Filter function.

Less or Equal

The Less or Equal function is used in situations where you wish to test for values that are less than or equal to another specified value. An example of this function's usage would be returning only records from an employee work history table where the hours worked is less than 1000. In this example, we'll use a Less or Equal function to test the Hours Worked field with a constant set to 1000. Notice how Data Connections are made to map the input data points as both input parameters in the function. The result is mapped to be used as the input parameter in the Filter function.

Less

The Less function is used to compare the first input parameter with a second and returns the value true if the first parameter (op1) is less than the second (op2). For this example, we will use the scenario where we would like to obtain only records from a database table where the work hours are less than 1000 (but not including 1000). This is where the Less Function will prove useful. We will simply need to insert into the Design Surface, then use both the Hours Worked field and numerical constant (1000) as input parameters op1 and op2. We will use the result as an input parameter for our Filter function.

And

The And Function is very useful for combining logical operations specifying when certain logical tests must be satisfied. This function take Boolean values as parameters, and you can right click on the Function Object to access the Application Bar where an option resides to Add Parameters. In this example, we'll use the And Function to set up two logical tests that must be satisfied in order to obtain our data. We want to filter our data set to retrieve values only when the Hours Worked field is less than 1000 And when the Department field is equal to "Accounting". The And Function will ensure both of these Boolean results must be true in order to return a true value to the Filter function.

Or

The Or Function is useful to combine logical tests where the result will be true if either of the specified Boolean input parameters are true. To demonstrate this usage, we've used a scenario where we would like to filter our employee work history table to only retrieve data where the Department field is equal to "Accounting" Or when the Department field is equal to "Sales". To accomplish this goal, we set up two Equal Functions to test for these values, and pass the results to the Or Function using their Boolean values as input parameters op1 and op2. If either of the logical tests is true, the record will be used in the output data source.

Geography

Geography Functions are specifically related to operations you may require to perform on the input to produce optimized data for map charts in BI Dashboards driven by the EngageCX BI Server. In this section, you will find helpful information on each of the available Geographical Functions.

To Geo Country

The To Geo Country function is used to adjust an input country code to match the value found in a referenced database. Because country definitions can vary in languages used, this function will compare to a common database to translate a country code to a common country value that can be interpreted by the EngageCX BI Server.

To Geo Region

The To Geo Region function is used to locate the country and return the closest match for the given location. First the provided plugin, AdjustGeoLocation, must be inserted into the diagram.

String Functions

String Functions are used for working with the data of the string data type. These functions allow you to perform operations such as concatenating, obtaining substrings, replacing, and more. In this section, you will find helpful information on the String Functions that available to you as you design your Data Diagrams.

Concatenate

The Concatenate function is used to concatenate two or more input values into the resulting string. You can add additional parameters for concatenation by right clicking on the function to access the Application Bar. Here you can select Add Parameter. As an example, we will use a database table that contains employee information. We will use the Concatenate function to combine both the FirstName and Lastname fields to create a full name. Additionally, a constant is added to create a ", " string to be placed between the values and an additional parameter was added by right clicking on the function. The fields and constant are mapped to the function's input parameter data connectors, and the result data connector is mapped to the element sequence in the output data source.

Contains

The Contains function is useful for testing string inputs for the presence of a specified string value. If the input string contains the specified string, the function will return true. If this test fails, the function will return false.

An example of using the Contains function would be filtering the data set to provide only employees from the sales department. We can use the Contains function to test the Title field to see if it Contains the string "Sales". To do so, we've added the Contains function and specified a constant with value "Sales". The Title field is mapped to the input data connector for content, and the "Sales" constant is mapped to the input data connector for substring. The result output data connector is mapped to the filter-rule input data connector in our filter function.

Substring

The Substring function is useful for obtaining a string value from an input string data source. This function has input data connectors for the input string, the starting position of the substring, and the size (how many characters from the starting position).

An example highlighting this usage is if we wanted to only obtain the birth year from a date field specifying birth date. In this example, we first add a conversion function to convert the field to a string. Next we add constants for both the position and the size. These values are set for 0 (position) and 4 (size) to obtain the first four characters from our input string. The To String function result is mapped to the string input data connector and the constants are mapped to both corresponding data connectors for position and size. The result output data connector is mapped to our element sequence in the output XML.

Replace

The Replace function is useful for finding a string within an input string value and replacing with another specified string. The function contains input data connectors for the input string, the string to search for, and the string that will replace the found value.

To demonstrate this usage, we take an example where due to corporate structuring, our reports need to now reflect any job titles for "Sales Representative" as "Sales Agent". We first created two constants, one for the search string of "Representative" and another for "Agent" which will replace the found value. After inserting the Replace function, the Title field is mapped to the input string data connector, the "Representative" constant is mapped to the tofindString data connector, and the "Agent" constant is mapped to the replaceString data connector. The result output data connector is mapped to the element sequence in the output XML.

Starts with

The Starts With function is useful for testing an input string to return true if it starts with a specified string. This function has input data connectors for the input string and the substring to be used for search.

To demonstrate this usage, we will use a scenario where we only wish to obtain data on our employees whose last name Starts With a 'P'. After inserting the Starts With function, we set a string constant with a value of 'P' and map this to the substring input data connector of the function. Next we map the LastName field to the input data connector for our function. This function is used as the input for the Filter used to filter the data set.

Ends with

The Ends With function is useful for testing an input string to return true if it ends with a specified string. This function has input data connectors for the input string and the substring to be used for search.

To demonstrate this usage, we will use a scenario where we only wish to obtain data on our employees whose title is that of a "Representative" regardless of what department. After inserting the Ends With function, we set a string constant with a value of "Representative" and map this to the substring input data connector of the function. Next we map the Title field to the input data connector for our function. This function is used as the input for the Filter used to filter the data set.

Length

The Length function is used to obtain the number of characters present in a specified input string. The function has an input data connector for the input string and an output data connector to map the result to the data output.

To demonstrate the usage of this function, we will use the LastName field as the input string and map the result output data connector to the element sequence in the output XML.

Is Empty

The Is Empty function is used to test if the string input value is empty, and if so, will return the Boolean value true. Otherwise, the function will return false. This function only requires the input string to be mapped to the string input data connector. The result can be used for filtering and other test functions. In this example, we show how the Is Empty function is used to test for any employees that are missing the LastName field in their record.

Is Not Empty

The Is Not Empty function is used to test if the string input value is not empty, and if so, will return the Boolean value true. Otherwise, the function will return false. The function only requires the input string to be mapped to the string input data connector. The result can be used for filtering and other test functions. In this example, we use the Is Not Empty function to ensure that any data presented in our output does not contain empty values for LastName.

Date and Time Functions

Date and Time functions are useful for when you are working with data related specifically to dates and times.

Now

The Now Function is used to return the current date and time, according to the local machine.

UTC Now

The UTC Now function is used to return the current date and time, according to the local machine's time, the selected time zone and the Daylight Saving if applicable.

Add Date

The Add Date function is used to add date values to input date values. It is important to note that this function requires an input date data connector as well as a ticks data connector. Both connectors must be of the datetime date type.

Date Difference

The Diff Date is used to return the number of ticks between the two specified input date values.

Day

The Day function is used to return the day from a given input datetime input data field.

Month

The Month function is used to return the month from a given input datetime input data field.

Year

The Year function is used to return the year from a given input datetime input data field.

Add Days

The Add Days function is used to add a specified number of days to an input date parameter.

Add Months

The Add Months function is used to add a specified number of months to an input date parameter.

Add Years

The Add Years function is used to add a specified number of years to an input date parameter.

To String

This function is useful for converting datetime input data values into strings in your output data source. The To String function uses two input parameter data connectors. One is for the input date to be used, and the other must be a specified string format (such as YYYY-DDDDD).

Other Functions

The functions found in the Miscellaneous group are not fitting for other category groups of functions. In this section, you can find helpful information about these functions and how to use them in your Data Diagrams.

If-Else

The If-Else function is available if you would like to use a logical condition to test your data and then specify results for both when the condition is met and when the condition is not met. Depending upon the condition, a value will be returned for true and false appropriately. To demonstrate the usage of this function, we will use an example with a specified need to display our records in our output report only as work departments "Accounting Department" and "Non-Accounting". In order to make this transformation successfully, we will use an If-Else function. This function will test for when the Department field is equal to "Accounting". If true, we will specify the value to be a constant "Accounting Department". If the result of our condition is false, we will return the value "Non-Accounting". Notice that the If-Else function requires three input Data Connectors. One connector is for the Boolean value of the test condition and the other two are the specified input values for both true and false returns.

Position

The Position function is useful when you would like to return the position of the current iterated record in the referenced data source. As an example, if we wanted to only include work hours from our work history database table for the Accounting department, yet we still needed to reference the position of these reported records for other needs. We can simply insert the Position function into our Data Diagram to retrieve this value.

In this example, we've used the Equal Function to test for when the Department field is equal to "Accounting" and use this return Boolean value as the input for our Filter. Next, we've inserted the Position Function. This function has an input Data Set Connector that the table must be connected to return the position related to this data set. The output data connector is mapped to the element sequence in our output data source using the Filter.

SQL Queries

SQL Queries can be useful for condensing the design space in your diagram. Some of the objectives offered through the Modeler functions, can easily be written in a SQL Query. The sections below will provide you with helpful information on learning more about integrating SQL Queries into your Data Diagrams.

Inserting SQL Query

1. In the Ribbon, select the Query button from the Insert Tab.
2. Select the type of Query you want to add from the contextual menu. This will launch the Insert Query Dialog, where you have to fill in the following fields:
   • Name: give the new query a name.
   • Connection: choose from the available Database Connections which the query will use.
   • Enable Caching: toggle on this option for caching query results; this option is not required but may be used for performance improvements.
3. Begin to write your SQL Query in the provided Query Construction Window. You will notice that an auto-populate feature will assist you in constructing your query from available database objects.
4. The Modeler will evaluate your syntax and provide useful feedback if there is an issue. If the syntax is correct with no errors, you will see the results from the query in the Results Menu.
5. When you are satisfied with your Query, select Insert to add into the Design Surface. A SQL Query will be displayed as a dark blue element.
6. Now that the SQL Query is present in the Design Surface, you can proceed to establish Data Connections to include the results in your output. Dragging and dropping the Data Connectors from one Object to the next maps the data from the SQL Query Object to the Output Object.
7. Select Preview button in the Home Tab of the Ribbon to view your Query results in the output data.

Editing SQL Query

1. Double click on your SQL Object in the Design Surface to launch the Edit Query Dialog.
2. In the dialog you will be able to edit your Query in the Query Construction Window, check your syntax, preview your Query Results and configure parameters, if necessary.
3. When you are satisfied with your Query configurations, make sure you select Save to update your changes and return to the Design Surface.

Editing EngageCX Server Query

1. Double click on your EOS Object in the Design Surface to launch the Edit EOS Query dialog.

2. When you are satisfied with your query configurations, make sure you select Save to update your changes and return to the Design Surface.

View Data Results

1. Right click on the SQL Query Object and select View Data from the resulting contextual menu.
2. This action will launch the View Data Dialog. Here you will be able to only view your Query results. You can modify the query from the Query Construction Window, to test and view other queries, however, you will not be able to save any changes made. In order to make any changes to the query in the Diagram you will need to follow the steps in Editing SQL Queries.

Parameters in SQL Query

1. First, set up your parameter for the Diagram by selecting the Parameter button in the Home Tab. A Parameter Object will now be created in the Design Surface.
2. Double click on this object to access the Properties Pane. Here you can specify:
   • Name: provide a name for your parameter.
   • Value Type: select the data type of your parameter value from the drop-down list.
   • Default Value: choose a initial value for your parameter according to your data type previously selected.
3. Select the Query button in the Insert Tab and choose one query type from the drop-down list to launch the Insert Query Dialog, where you have to fill in the following fields:
   • Name: give the new query a name.
   • Connection: choose from the available Database Connections which the query will use.
   • Enable Caching: toggle on this option for caching query results; this option is not required but may be used for performance improvements.
4. Begin to construct your Query in the Query Construction Window. To include a parameter in your SQL Query, use the syntax ${parametername} as a placeholder for your external parameter.
5. Select Edit Parameters to configure the parameters you have added. Here you can define the parameter type as well as a default value to use within your Query. Remember, the value of the external parameter will always overwrite this value and it will be used in your diagram later. Once ready, select Save.
6. If you receive an error, use the information displayed to revisit your Query Construction. If the syntax is correct with no errors, you will see the results from the query in the Results Menu.
7. When you are satisfied with your Query, select Insert to add into the Design Surface. Your Query will be displayed as a dark blue Query Object in the Design Surface and you will also notice that a light blue Data Connector is displayed on the left side of the Query Object. This is the Data Connector for your input parameter.
8. Next, connect your diagram parameter to the input parameter Data Connector in the SQL Query Object. Then establish your Data Connections from the SQL Query Object to the output object. The results of this action will be the SQL Query that will use the diagram parameter to select the ContactID as the parameter defines and return this information to the XML Output.
9. Select the Preview button in the Home Tab to test your Query results in the output data source.

Scripts

The Modeler tool supports the design and usage of both JavaScript and C# scripts directly in your diagram. Read the sections below to learn more about creating and using Scripts in your diagrams.

Inserting a New Script

Follow the instructions provided below to insert and use a Script into your data diagram:

1. In the Insert tab, select Script button under the Ribbon.
2. Select the language for your Script from the contextual menu to create a new script or you can import and already created one.
3. To write a new Script, use the Script Construction Window. A simple example will be displayed to assist you in your design.
4. Select Edit Parameters from the Ribbon to display how many parameters you have defined in your Script. You may wish to test your Script for results and will first need to define the values for the parameters for testing. Provide sample values in the provided Default Value fields. Select Save when complete.
5. Select the Run Script button for testing your Script with the defined input parameter values. The result of your Script will be displayed. If there are any errors in the script they will be displayed.
6. When you are satisfied with your results, select Insert to add the Script into the Design Surface.
7. Establish Data Connections from an input data source to your Script input parameters then connect the Result Data Connector to your desired Diagram Object or output.
8. Select the Preview button in the Home Tab to view your results and ensure your Script is providing the results you intend.

Editing Script

To edit your Script after inserting, follow the instructions provided below:

1. In the Design Surface, right click on the Script object and select Properties from the resulting contextual menu.
2. The Scripts Pane will now be displayed for you to reconfigure your inserted Script. Select Options button for the script and choose Edit Script option to make modifications in the Script Construction Window and select the Run button for testing your code as well as previewing your results.
3. When you are satisfied with your edits and testing, select Save to preserve your changes and return to the Design Surface.

Common Tools

Some tools in the Modeler are common to many different options. This section highlights the usage of these common tools that you will frequently be using when creating your Data Diagrams.

Previewing

It is highly recommended to consistently preview your results when making adjustments and additions to your Data Diagrams. You can access the Preview button any time in the Home tab of the Ribbon.

In the Results View dialog you can preview your results to ensure that the diagram is returning the data you had designed it to. The dialog will display a limited sample of your output data, but you can select Show more button to obtain more rows or Show all to view the entire result. When you are finished reviewing your sample output, you can switch back to Design View.

Properties Pane

The Properties Pane allows you to make modifications to important Diagram Objects within your Data Diagrams. In the Properties Pane you can perform such operations as changing data types, names and assigning values.

Accessing the Properties Pane

• Double click on an Object in the Design Surface.
• Select the object you want to adjust and choose Show Properties from the View tab.
• Right-click on an Object in the Design Surface and select Properties from the resulting contextual menu.

You can navigate through the objects in your Data Diagram by using the Navigation Bar located at the bottom of the pane in order to select the desired object with ease.

Changing Properties

Available properties vary from one object to another, but the same steps apply to all when it comes to adjusting the properties of the desired object.

1. Open the Properties Pane.
2. From the Navigation Bar at the bottom of the Properties Pane, make sure you select the correct object.
3. Once you are viewing the right properties, make the necessary adjustments by modifying the values and then press Enter to save the changes.

Once you are satisfied with your modifications, you can collapse the pane by selecting X button at the top-right corner of the Pane.

Appendix

Set up the Studio

System Requirements

EngageCX Modeler can be installed on Windows operating systems. Here is a helpful list to assist you in preparing for your Modeler installation.

Minimum Requirements	Optimal Requirements
Hardware
Processor: Intel Core i5 @2GHZ	Processor: Intel Core i7 @ 3GHZ
Memory: 4GB of RAM	Memory: 8GB of RAM
Hard Disk: 10 GB disk space	Hard Disk: 10 GB of disk space
Operating System
Windows Vista SP2	Windows 8 x64 and up
Prerequisites
Net Framework 4.5 or later	Net Framework 4.5 or later

When you have confirmed the above components are present on your installation machine, proceed to the Installing section.

Installing

EngageCX Modeler is available to you in an executable (.exe) installer which contains several applications called EngageCX Studio. This allows you to simply double click on the installer file and follow the on screen instructions provided to you by the Setup Wizard. Below are some helpful points to assist you along the way with the installation:

1. The installer will open with the welcome screen that indicates the setup wizard is ready to begin and guide you through the installation. When you are ready to begin, select Next.
2. Accept the end-user licensing agreement by checking the box and selecting Next button.
3. Specify the directory you wish to install EngageCX Studio in. EngageCX recommends using the default installation folder C:\Program Files\EngageCX\EngageCX Studio 2018(64 bit)\, then select Next.
4. Now, you will need to decide which product to install. EngageCX Studio provides a suite of products which can be chosen during this step of the installation. Each tool is provided with a short description of its functionality.
5. Next, the Setup Wizard will perform the necessary installation and provide a progress bar for your information.
6. When the setup is successfully completed, the Setup Wizard will provide a notification of completion. You can uncheck the Launch Publisher option if you do not wish to launch the Publisher after installation finishes. When you are ready to complete the installation, select Finish.

Updating your Build

When updating your build using either the production links from our website or the evaluation builds provided by our support team, the steps to update are the same.

1. The first step to follow when updating your EngageCX Studio build is to uninstall the old build from the machine. Otherwise, the installer will open and you will see a note saying that there is another version already installed.
2. Use the link provided to download the correct version that you need.
3. Follow the on-screen instructions. These will be the same as the ones highlighted on the Installing page.
4. Once the build is updated, you can continue to create and design your diagrams as before.

Trial Limitations

If you are new to Modeler and you are using a trial basis, you may have questions about the limitations your trial license may present. Below is a full list of the Trial limitations for the Modeler. If you have any questions you can reach out to support@ecrion.com or directly to your account manager.

Output

All the data from the output files (exported from the Preview dialog) are scrambled.

Databases

Only the EngageCX Adventure Works Database can be used.

Terminology

Data Source

The Modeler will easily allow you to connect to different data sources. For the purpose of discussing the usage of the Modeler, we will refer to a data source as the different structure or fields for which you will be pulling your data from (database tables, SQL queries, CSV, XML and more). Using the Modeler, you will be able to connect to multiple data sources, to aggregate and transform your data for use with document production, dashboard generation or even moving data to another location.

Data Diagram

Whether you are designing a data source to drive a Dashboard created in the Modeler, a data source to be used with your Document Template for document production or even designing the creation of a new table through a data transformation and ingestion output, you will be designing what we will be calling a Data Diagram.

A Data Diagram uses the combination of multiple Data Sources, associating Data Connections, available Functions, and a desired output object to obtain data, perform operations on and produce a well structured data source for your usage. This Data Diagram will visually represent the source of each data point in your output data object and also show any transformation performed on the data using functions. The displayed data points can be expanded to see the tree view of all your data. The diagram object will preserve the collapsed or expanded state for the previous selection of data items.

This Data Diagram will be used by EngageCX's Data Aggregation Server to target each data source, obtain data, and transform and aggregate as specified.

Design Surface

The Design Surface is the dedicated region in the Modeler that you will use to design your Data Diagram. In the Design Surface you will notice Objects representing different data source objects as well as output objects. Here, you will map your input data sources to functions, commands, scripts, queries and other objects to add and transform your data to the desired output.

Data Connection

A Data Connection is used when mapping the flow of your data in your Data Diagram. A connection is noted by a line between two Data Connectors. A data connection represents the flow of data from one Diagram Object to another.

• A data connection maps data from the dark blue output data set connector to the dark blue input data set connector in the Filter function.
• A data connection maps data from the dark blue output data connector in the filter function to the XML data source repeating sequence.
• A data connection maps the LastName field output data connector to the input string data connector in the IsNotEmpty function.
• A data connection maps the result output data connector in the IsNotEmpty function to the input filter-rule data connector in the Filter function.

Data Connector

A Data Connector is used when mapping Data Connections between Diagram Objects. There are two categories of data connectors: input and output, and a data connector can be either a value connector or a data set connector. In Modeler tool, you will notice that a Diagram Object has small arrows located on either side to be used for mapping data connections and these arrows are the Data Connectors.

Waypoints

You can use Waypoints to better organize the visual design of your Data Diagrams. When positioning Diagram Objects in your Data Diagrams, often times you may notice that Data Connections may overlap or be displayed under other Diagram Objects. You can modify each Data Connection to navigate around other objects in your diagram by creating Waypoints.

Ribbon

The Ribbon is used to access all necessary functionalities when designing your Data Diagrams. Select from different tabs and access the different groups within the Ribbon to find the feature you would like to explore.

Navigation Bar

The Navigation Bar is an important component of the Properties Pane in either Mouse or Touch Display Modes. This is helpful for allowing you to select specific elements and modify properties accordingly.

When selecting an object in your Diagram and selecting Show Properties from the View Tab in the Ribbon, you will notice the Navigation Bar at the bottom of the dialog. Additionally, in Mouse Display Mode, if selecting Show Properties from the View Tab, you will notice the same Properties Pane displayed. The Navigation Bar will always be present at the bottom of the Properties Pane allowing you to select the Diagram Object you wish to modify properties for.

Status Bar

The Status Bar is an element located under the Design Surface that enables to access viewing and navigation options when working with diagrams. This is useful for zooming on specific sections of your diagram design or switching Views to the Editor Source allowing you to view the diagram's source code.

Best Practices

EngageCX Modeler is a powerful tool that allows you to intuitively connect to any data source and use a visual interface to map and transform your data to the output of your choosing. Although this process is made easier with the Modeler, we recommend considering the following best practices before beginning the design of your Data Diagram.

Know your Data Sources

The first step in designing any Data Diagram will be to determine both the type of the diagram you are creating (output) but also to specify the Data Sources you will be using. It is important that you consider where your needed data is obtained from, familiarize yourself with data types, current values and structure of these data sources. You can follow these steps to assist you with familiarizing with the data sources you will be using:

• For databases, review table structures, sample queries, and previous data outputs to make note of the different fields and what type of data they hold.
• For XML input sources, open a sample XML file and look for repeating elements, child and parent relationships, and the locations of key attributes.
• For other data sources such as CSV, TXT, etc., make sure you open a sample and review the structure for column names, separators and more.
• Think about, if you would like to use this current diagram as a data source for other diagrams moving forward.

By investigating the input fields available to you and the data that is contained within, you will have a head start on designing your Data Diagrams before you even begin to add your Data Sources and Diagram Objects.

Consider Data Rules

Before you begin adding data sources, functions and other data objects to your Data Diagram, it is recommended to make a list of the fields you wish to include in our output, where this data is coming from and what type of restrictions or operations need to be placed to make this data optimized for production. List items such as the following can give you guidance in determining what objects to insert into your Data Diagrams:

• "I know that I need to have a repeating element for transactions in my output XML, but I need to make sure this only is for credit card transactions."
• "In my report I must display the first name from a database table, but the last name I am required to only display the first three letters."
• "In our monthly employee summary report, we must join data from two tables, but the driving condition is when the employee ID in one table equals the employee ID in the other."

By listing your data needs and the required rules, transformations and other operations, you can begin to explore specifically what Diagram Objects are designed to meet every one of those needs. For your reference, the three highlighted points above are answered below:

• Use Filters for transaction types.
• Use the Substring function to obtain specific strings within an input string.
• Use the Join Function and create a condition on when to join.

FAQs

How is this product licensed?

The Modeler is licensed per computer and licenses are installed locally using a guided on-screen installation tool.

Where do I start once I've installed the software?

The best place to begin is by reviewing the Terminology associated with this application. After this, we recommend reviewing our section on Best Practices. Once you have familiarized yourself with these items, you can move forward with Working with the Diagram Wizard and using the Design Guide to insert specific objects into your Data Diagram.

Where do I learn about the different components in the software?

The best place to learn about the different functions available to you is to visit the section of the help on Terminology.

What hardware and software requirements are needed to run the software?

You can visit the help page on System Requirements to find this information.

Keyboard Shortcuts

The EngageCX Studio Modeler does accept the traditional keyboard shortcuts as well as other that apply for all EngageCX's products. Please find a full list of the keyboard shortcuts for the Modeler below.

Design View

Shortcut	Action
F5	Preview
F1	Help
Ctrl + C	Copy
Ctrl + X	Cut
Ctrl + V	Paste
Ctrl + O	Open document
Ctrl + Z	Undo
Ctrl + Y	Redo
Ctrl + S	Save
Ctrl + '+'	Zoom in
Ctrl + '-'	Zoom out
Ctrl + P	Print
Ctrl + N	New document
Ctrl + W	Close document
Ctrl + Alt + 0	Zoom document to 100%
Alt + Enter	Access Properties
Delete	Delete
Escape	Exit any Dialog

In the Query Dialog

Shortcut	Action
F5	Run Query
Ctrl + C	Copy
Ctrl + X	Cut
Ctrl + V	Paste
Ctrl + Z	Undo
Ctrl + Y	Redo
Ctrl + S	Save
Ctrl + '+'	Zoom in
Ctrl + '-'	Zoom out
Escape	Exit any Dialog
Ctrl + A	Select all