In this tutorial, you will learn how to build your first data authoring application. This application mimics an Employee (HR) domain where employees and contractors are authored, as well as the department to which they belong and their education credentials.

The overall data model for the application you are about to build looks like this :

What you'll learn

• Designing a logical model in xDM
• Creating the user experience
• Deploying the application
• Using the application

Before you start

This tutorial is the first of a series of six that will guide you through the steps to design a complete data management application.

In this tutorial, we assume that you have already set up a working Semarchy xDM environment and you have design-time privileges to connect to the Semarchy Application Builder.

If you have not yet set up Semarchy xDM, you can follow the Quick Install tutorials from the main menu. Additional setup information can also be found in the Installation guide

If you have not already done so, you can download resources such as images and data sets used within this tutorial by clicking on the button below.

DOWNLOAD TUTORIAL RESOURCES

The estimated duration of this unit is about 90 minutes.

Semarchy xDM uses an ER (Entity-Relationship) approach to help you create the logical model of your application.

To get started, you need to create a new logical model. The logical model will hold all your entities, attributes, rules, forms, collections, and application definitions.

Open the Application Builder:

1. Click on New Model:

2. The Create a New Model wizard opens. Set the name to HRTutorial and then click Finish.

3. In the context menu, right-click on Diagrams and then select Add Diagram.

4. The Create New Diagram wizard opens. In the Name field type MainDiagram and click Finish.

In the next step, you will add the first entity of your model.

You are now ready to create the Employee entity. Once fully set up, it will look as follows:

To create this entity, you will:

1. Create the entity and add the FirstName and LastName attributes.
2. Create 2 lists of values (LOVs) - Salutations and Subsidiaries.
3. Add the Salutation and Subsidiary attributes to your entity and refer to the LOVs you previously created.
4. Add all the remaining attributes.

Add the Employee entity to the model

The fastest way to add a new entity to your model is using the diagram.

The entity you will create is a Basic entity, which is best suited for data authoring use cases.

1. Select Add Entity in the diagram Palette.

2. Click anywhere on the diagram surface - the Entity wizard opens.

3. Set the Name to Employee and then click Next.

4. On the next page, set the Name attribute to ID.
   Keep the "Sequence" option selected for ID Generation. This means that the ID generation will use a sequence number instead of a manual or calculated value.

5. Click Finish. The new Employee entity appears on the diagram.

You have successfully added the Employee entity. In the next section, you will add its first attributes.

Add the FirstName and LastName attributes

1. Right-click the Employee entity in the diagram and select Add Simple Attribute.

2. The Simple Attribute wizard opens. Enter the following values, and then click Finish:

• Name: FirstName
• Type: String (Build-in Type)
• Select Mandatory.
  

3. Right-click again the Employee entity on the diagram and select Add Simple Attribute to create another attribute.

4. The Simple Attribute wizard opens. Enter the following values, and then click Finish:

• Name: LastName
• Type: String (Build-in Type)
• Select Mandatory.

6. Save all your work: click the Save all current contents button on the top of the Model Design View.

Congratulations

You have just created your first entity with three attributes. It appears on the diagram.

The ID of the Employee entity will be automatically set using a sequence.

In the next step, you will add lists of values to your model.

You will now create 2 lists of values that you will use to restrict the possible values for the Salutation and Subsidiary attributes.

Create the Salutations LOV

1. Right-click on Lists of Values from the Application Builder Model Design View and select Add List of Values.

2. The creation wizard opens. Set the Name to Salutations then click Finish.

3. Click on the Add Value button from the Values section.

4. Set the Code to Dr and click Finish.

5. Repeat the same operations to add the following values:
   

6. In the end, the Values section should look like this

Add the Salutation attribute

Now it is time to add the Salutation attribute to your entity and set its datatype to the previously created Salutations list of values.

1. In the Application Builder Model Design View, go to Entities > Employee, right-click on Attributes and select Add Simple Attribute.

2. The wizard opens. Set the Name to Salutation, select for the Type: Salutations [List of Values], and then click Finish.

Create the Subsidiaries LOV

Create another List of Values named Subsidiaries the same way you did for Salutations, with the following values:

Add the Subsidiaries attribute

You will now add the Subsidiary attribute. Note that this attribute is mandatory.

Create another simple attribute with the following values, then click Finish:

• Name: Subsidiary
• Type: Subsidiaries [List of Values]
• Select Mandatory.

Congratulations

You have successfully created 2 lists of values and added to your model attributes using them.

In the next step, you will finalize the Employee entity by adding the other attributes.

Add the other attributes

It is now time to finalize the Employee entity.

1. Following the same instructions that you used in step 3. Create the Employee entity, add the remaining attributes of the Employee entity:

2. Double-click on the Attributes node under Entites > Employee in the Model Design View to review the Employee entity. Check that all attributes have been added and that the datatypes and mandatory checkbox are correctly configured.

3. Save your work.

Congratulations

You have successfully created the main entity of your model.

What we've covered

• Creating a model and a diagram
• Creating an entity and adding attributes
• Creating lists of values

In the next step, you will add a second entity and link it with the Employee entity.

You are now ready to create the Department entity.

Departments are created and maintained by business users and each employee refers to a single department.

In this step, you will:

1. Create the entity and add its attributes.
2. Add a reference to describe the one-to-many relationship between departments and employees.

Create the entity and its attributes

To create the Department entity, follow the same procedure as you did earlier with the Employee entity.

1. Add a new entity to the MainDiagram with the following values, and then click Next:

• Name: Department
• Entity Type: Basic

1. Set the primary key attribute with the following values and then click Finish:

• Name: ID
• ID Generation: Select Manual
• Type: String
• Length: 20

2. Add the Name attribute with the following values and then click Finish:

• Name: Name
• Description: Name of the department
• Select Mandatory
• Type: String
• Length: 128

3. Add the Description attribute with the following values:

• Name: Description
• Description: Optional description of this department
• Mandatory: Unchecked
• Type: String
• Length: 4000

Add the Employee-Department reference

From the Main Diagram, create the reference relationship named EmployeeDepartment, from Employee to Department:

1. Click Add Reference in the Palette.

2. Click on the Employee entity and drag the line to the Department entity:

3. Configure the reference with the following values and then click Finish:

• Name: EmployeeInDepartment
• Select Mandatory (One To Many).

4. Review the Main Diagram.

Note that the Department foreign attribute has been added to the Employee entity.

5. Save your work.

Congratulations

You have successfully added the Department entity and enforced referential integrity by creating a reference.

In the next step, you will add the Education entity.

You are now ready to create the Education entity. At the end of the creation process, it will be configured as follows:

This entity is used to track the curriculum of an employee with dates and degrees received in schools across countries. Each employee will have multiple education records.

In this step you will:

1. Create the entity and add its attributes.
2. Add a reference to describe the one-to-many relationship between education records and employees.

Create the entity and its attributes

1. Create the Education entity the same way you did for Department: add a new entity to your Main Diagram with the following values and then click Next:

• Name: Education
• Entity Type: Basic

2. Set the primary key attribute with the following values then click Finish:

• Name: ID
• ID Generation: Sequence

3. Following the same instructions you used for the attributes of the Department entity, add the attributes below to the Education entity:

Add the Education-Employee reference

From the Main Diagram, create the reference relationship named EducationsEmployee, from Education to Employee:

1. Click Add Reference in the Palette.

2. Draw a line from the Education entity to the Employee entity.

3. Set the reference with the following values and then click Finish:

• Name: EducationsEmployee
• Select Mandatory (One To Many).

4. Review the Main Diagram:

• Note that the Employee foreign attribute has been added to the Education entity.
• Your diagram should now look like this:

5. Save your work.

Congratulations

You have successfully added the Education entity and created a reference to the Employee entity. Your model now contains all the entities that you need.

In the next step, you will get even more fun by defining the user experience for your application. You will learn how to add forms, collections, and more.

Semarchy xDM uses Material Design as the design language for defining a business user interface. The user interface uses multiple application components that you will define in the next sections.

Application components

Data Applications in Semarchy xDM rely on several components that you can directly generate and configure in the Application Builder. The following examples are taken from the Product Retail demo application.

• Display cards provide a compact and visual representation of a record.

• Collections configure how multiple records are displayed in a table or list or grid.

• Forms define how one record is displayed in a form to browse or author the data.

• Steppers determine the guided data authoring experience.
• Action Sets are data actions available for one or multiple records.

• Business Views tie all of the above together to form a consumable view.

• The Navigation Drawer allows navigation to business views.

Generate application components

Once you have completed the initial configuration of your data model, you can quickly use the Generate Application Components wizard to automatically generate most of the components you will need to enable user interaction with your data.

To generate application components, follow these steps:

1. Right-click on the Department entity and select Create Application Components.

2. Click Next.

3. Set the following values for the entity's Display Card text expressions, and then click Finish:

• Primary Text Expression: Name
• Secondary Text Expression: Description

4. Repeat the steps above for the Education entity with the following values:

• Primary Text Expression: DegreeReceived || ' (' || Country || ')'
• Secondary Text Expression: to_char(coalesce(ToDate, FromDate), 'YYYY') || ' - ' || School

5. Repeat the steps above for the Employee entity with the following values:

• Primary Text Expression: FirstName || ' ' || LastName
• Secondary Text Expression: Title || ' (' || Subsidiary || ')'

6. Save your work.

Explore what was generated

The wizard has generated the following elements for each of your entities:

• Display Card
• Collection
• Form
• Stepper
• Action Set
• Business View

Expand the Department entity to see the generated components:

Scroll down in the Model Design View and go to Applications > DefaultApplication.

Double-click on Folders and Actions and observe that a default list of menu items was initialized and includes the following actions to browse each entity:

• BrowseDepartment
• Browse Education
• BrowseEmployee

Assign visual icons

It is a best practice to assign icons to your entities. These icons will visually guide users in several places in your application.

1. From the MainDiagram, select the Employee entity.
2. In the Properties view below the editor, identify the Icon property within the Name and Description tab, and then click Select Image:

3. Type "account.svg" in the search bar and press Enter to filter the images.
4. Select the mdi/account.svg image:

5. Repeat the same steps for the Department entity. Search and select domain.svg.

6. Repeat the same steps for the Education entity. Search and select school.svg.

7. Save your work.

Customize forms and collections

In this section, you will open the collection and form of the Employee and Education entities and configure the date attributes to use a date picker visual component:

1. Navigate to Entities > Education > Collections in the Model Design View and double-click on EducationCollection.

2. Select the FromDate attribute and set the Component Type to Date Picker in the General section of the Property Inspector.

3. Repeat the same operation for the ToDate attribute.
4. Expand the Forms node under Entities > Education and then open the EducationForm.
5. Select the FromDate attribute and make sure the Component Type in the General tab of the Property Inspector is set to Date Picker.

6. Repeat the same operation for the ToDate attribute.
7. Repeat the same process for the Employee entity with the attributes HireDate and EndDate in both the EmployeeCollection and the EmployeeForm.
8. Save your work.

Configure Global Search

The Global Search Configuration defines which business views are searched when a search string is entered in the Global Search page, and how they are searched.

1. Navigate to Applications > Default Application in the Model Design View, and then double-click Global Search Configuration.

2. Click the Add Business View to Search button in the Searched Business Views section.

3. Enter the following values and then click Finish:

• Name: EmployeeSearch
• Business View: Employee [Business View]

4. Click again the Add Business View to Search, enter the following values, and finally click Finish:

• Name: DepartmentSearch
• Business View: Department [Business View]

Brand your application

1. Double-click Applications > DefaultApplication in the Model Design View.
2. Enter the following values:

• Select Auto Fill
• Name: EmployeeTutorial
• Label: Employee Tutorial
• Title: Employee Tutorial
• Avatar: images://mdi/account.svg (copy and paste the value, or click the Select Image button and search for "domain" to find that image)

3. Save your work.

Validate your model

Before deploying your application, it is a best practice to validate your model.

1. Right-click on the HRTutorial node in the Model Design View and then select Validate.

2. Your model is analyzed and the Validation Report is displayed in the bottom section of the Application Builder. You should have no errors.

Congratulations

You have successfully completed the second part of this tutorial by creating a first auto-generated application.

What we've covered

• Generating application components
• Assigning visual icons
• Customizing display cards, collections, and forms
• Configuring Global Search
• Renaming your application
• Validating your model

In the next step, you will learn how to deploy and connect to this application for the first time.

Semarchy xDM allows you to deploy your model into a Data Location. It will create all the tables and columns in a relational database (Oracle, SQL Server, or PostgreSQL) and it will also generate the user interfaces for your applications to enable the business user experience.

Create a Datasource

Before creating a Data Location and deploying your model, you must create a Platform Datasource to connect to the SEMARCHY_EMP_TUTORIAL database schema that was created in the Quick Install tutorials.

1. In the Application Builder toolbar, expand the user menu, and then select Welcome Page.

2. Select Configuration.

3. Scroll down to the Connections section and click Datasources.

4. Click the Add datasource floating action button.

5. Enter the following values and then click CREATE:

• Name: EMPLOYEE_TUTORIAL
• Database Type: select the value that corresponds to your database.

6. Enter the following connection parameters in the editor:

• The URL is populated with a default value. Check that the default host, port and database name in the connection URL are correct.
• Driver: keep the default value.
• Username: semarchy_emp_tutorial.

7. Enter the password of the database schema:

• Click the Edit Secret button next to the Password field.

• Keep the current value of the Secure with field (or select another encryption method if you have configured any), enter semarchy_emp_tutorial in the Value of "Password" field, and then click OK.

8. Click Test this Datasource in the button bar above the editor:

9. The Datasource test successful message should be displayed. Click OK.

If another message is displayed, identify the error and fix the connection parameters.

10. Click the Save and apply datasource modification button on the datasource editor.

11. Open the user menu on the top-right corner and then select All applications to go back to the Welcome Page.

Create a Data Location

In this section, you will create the EmployeeTutorial Data Location and deploy your model into it:

1. Open the Application Builder.
2. Click the Management button in the Application Builder toolbar to access the Management perspective.

3. Right-click Data Locations and select New Data Location

4. Enter the following values and then click Finish:

• Name: EmployeeTutorial
• Data Source Name: select the datasource you created in the previous section, EMPLOYEE_TUTORIAL.
• Deployed Model Edition: select HRTutorial

Connect to the application

In this section, you will learn how to connect to the Employee Tutorial Application that you have just deployed:

1. In the Application Builder toolbar, expand the user menu, and then select Welcome Page.

2. Click the Employee Tutorial button to open the application.

3. If you have not yet completed the profile for the semadmin user in a previous tutorial, a popup appears. Click NEXT.

4. Enter the following information for semadmin and click CONTINUE:

• First name: Semarchy
• Last name: Admin
• Email: semadmin@semarchy.com

5. On the next screen, press GET STARTED.
6. Discover the user interface that was built for your application:

• The Navigation Drawer contains the actions that you configured in the Folders and Actions.
• The Global Search form is displayed by default.

Congratulations

You have successfully completed the third part of this tutorial by deploying your first application into a Data Location.

What we've covered

• Deploying a model and an application into a Data Location
• Connecting to the generated application

In the next step, you will learn how to use this application to start entering data and navigate in the business user data management interface.

Now that you have successfully deployed your model and application, it is time to start authoring data.

Semarchy xDM has generated all the actions and menus to allow you to author data, import it from spreadsheets, search for data and refine your search to spot data typos.

For more information about using applications, you can refer to the Product Retail Demo Application that showcases a fully functional product data application.

User profile

As a first time user, you will need to update your profile information and preferences.

Please follow these steps:

1. In the Employee Tutorial application, open the user menu on the upper-right corner and select Profile from the menu.

1. Basic information about yourself is already set. Move your mouse over the default profile picture and click the Change profile picture button:

2. Select on your hard drive the semadmin.jpg picture which is available under the data-consolidation/pictures folder of the tutorial resources you downloaded previously. Click UPLOAD.

3. Optionally, customize your user preferences like date format, language, etc (Settings tab) and then save.

Author or import departments

In this section, you will learn:

• How to author new departments
• How to import those departments from an excel spreadsheet.

1. In the Employee Tutorial application, click the Departments menu item in the Navigation Drawer, and then select Create from the actions menu above the Departments collection.

2. Create the first department with the following values then click Finish:

• ID: SAL
• Name: Sales Department
• Description: Sales Department

3. Wait until the toaster at the bottom-left corner of the screen indicates "Changes successfully applied", and then select CLICK TO REFRESH to see the imported data:

4. Select Import in the actions menu to load the rest of the departments:

5. Select the data-authoring\datasets\departments-data.xlsx file from the tutorial resources you downloaded earlier.
6. Review the import contents then click CONTINUE.

7. On the Define mappings screen, keep the default mappings and click CONTINUE:

8. Review the Import Summary and then click FINISH to import the data:

9. Review the imported data and click FINISH. This submits the data to the certification process so that all users will have access to it:

10. Wait until the toaster at the bottom-left corner of the screen indicates "Changes successfully applied", and then select CLICK TO REFRESH to see the imported data:

11. The Departments Collection is now showing 6 records:

Import employees

In this section, you will import employees from an excel spreadsheet:

1. Click on Employees in the Navigation Drawer and select Import from the actions menu:

2. Select the data-authoring\datasets\employees-data.xlsx file from the tutorial resources you downloaded.
3. Review the import contents and then click CONTINUE:

4. Click CONTINUE on the next page to confirm the mapping.
5. Click FINISH on the Import Summary page.
6. Review the data to import and then click FINISH.

7. When the toaster indicates "Changes successfully applied", select CLICK TO REFRESH to see the imported data.

8. Observe that 34 employees have been imported:

Global Search

Global search allows you to search for records across multiple entities. In this tutorial, we previously configured Global Search to search in both the Department and Employee entities.

1. Select Global Search in the Navigation Drawer.

2. Enter Sales in the Search text field and click the Search button.

3. Notice that the application found one department named Sales and several employees that contain the word sales in their title.

Search and edit an employee

In this section, you will learn how to use advanced search to refine your results. In the employee data provided to you by Semarchy, there is a misspelled title that reads "Fenior Consultant" instead of "Senior Consultant". You will now search for this employee record and fix it.

1. Select Employees item in the Navigation Drawer and click the Filter button located above the Employees Collection.

2. Enter fenior in the Search Text field, and then click APPLY or press Enter to search for the misspelled record.

3. The search returns one unique record. Click the checkbox next to this record to select it. pen the actions menu and then select Edit.

4. Fix the Title by setting it to Senior Consultant and then click FINISH.

5. Wait for the toaster to display "Changes successfully applied", and then select CLICK TO REFRESH.

6. The search now returns no results.

7. Click the Filter button again to display the filter panel again.
8. Enter markle in the Search Text field and click APPLY to retrieve the record you modified.

9. Observe on the employee's display card that his title is now correct:

Well done, you have built your first data authoring application with Semarchy xDM!

What we've covered

• Model: You created an employee model with entities, attributes, and relationships.
• User Experience: You added forms, collections, and display cards to customize the user experience.
• Deployment: You deployed your model and application to a data location.
• Use: You've learned how to use your application to author, edit, import, and filter data.

What's next?

In the next unit, you will learn how to enforce data quality within your Employee application with enrichers, data validation, and duplicates detection rules.