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

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:

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

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

  1. 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:

Attribute

Datatype

Mandatory

Notes

ID

Number

Yes

Auto-numbered ID

FirstName

String(128)

Yes

LastName

String(128)

Yes

Salutation

List of values

No

Refers to the Salutations LOV

Subsidiary

List of values

Yes

Refers t to the Subsidiaries LOV

Title

String(128)

No

-

HireDate

Date (*)

Yes

-

EndDate

Date (*)

No

-

IsContractor

Boolean

No

-

Email

String(500)

No

-

Phone

String(128)

No

-

Picture

Binary

No

Will hold the employee picture

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.

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

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

  1. 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.

  1. 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.

  1. The Simple Attribute wizard opens. Enter the following values, and then click Finish:
  1. 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:


  1. 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.

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

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

  1. Set the Code to Dr and click Finish.

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

Code

Label

Mr

Mr

Mrs

Mrs

Miss

Miss

  1. 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.

  1. 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:

Code

Label

ACME_APAC

ACME APAC

ACME_EU

ACME EU

ACME_US

ACME US

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:

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:

Attribute

Datatype

Mandatory

Notes

Title

String(128)

No

-

HireDate

Date (*)

Yes

-

EndDate

Date (*)

No

-

IsContractor

Boolean

No

-

Email

String(500)

No

-

Phone

String(128)

No

-

Picture

Binary

No

Will hold the employee picture

  1. 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.

  1. Save your work.

Congratulations

You have successfully created the main entity of your model.

What we've covered

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.

Attribute

Datatype

Mandatory

Notes

ID

String(20)

Yes

ID is set manually

Name

String(128)

Yes

Name of the department

Description

String(4000)

No

Description of this department

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:

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

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

  1. Add the Description attribute with the following values:

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.

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

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

  1. Review the Main Diagram.

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

  1. 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:

Attribute

Datatype

Mandatory

Description

Notes

ID

Sequence

Yes

Automatically generated

FromDate

Date

Yes

Start date of curriculum

ToDate

Date

No

End date of curriculum

DegreeReceived

String(128)

Yes

Freeform name of degree received

Country

String(128)

No

Freeform name of country

School

String(128)

No

Free form text for the school name

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:

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

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

Attribute

Datatype

Mandatory

Description

Notes

FromDate

Date

Yes

Start date of curriculum

ToDate

Date

No

End date of curriculum

DegreeReceived

String(128)

Yes

Freeform name of degree received

Country

String(128)

No

Freeform name of country

School

String(128)

No

Free form text for the school name

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.

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

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

  1. Review the Main Diagram:

  1. 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.

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.

  1. Click Next.

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

  1. Repeat the steps above for the Education entity with the following values:
  1. Repeat the steps above for the Employee entity with the following values:
  1. Save your work.

Explore what was generated

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

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:

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:

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

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

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

  1. 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.

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

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

  1. Repeat the same operation for the ToDate attribute.
  2. Repeat the same process for the Employee entity with the attributes HireDate and EndDate in both the EmployeeCollection and the EmployeeForm.
  3. 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.

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

  1. Enter the following values and then click Finish:

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

Brand your application

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

  1. 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.

  1. 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

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.

  1. Select Configuration.

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

  1. Click the Add datasource floating action button.

  1. Enter the following values and then click CREATE:

  1. Enter the following connection parameters in the editor:

  1. Enter the password of the database schema:

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

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

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

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

  1. 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.

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

  1. Enter the following values and then click Finish:

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.

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

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

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

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

Congratulations

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

What we've covered

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:

  1. 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.

  1. 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:

  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.

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

  1. 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:

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

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

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

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

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

  1. 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:

  1. 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:

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

  1. Click CONTINUE on the next page to confirm the mapping.
  2. Click FINISH on the Import Summary page.
  3. Review the data to import and then click FINISH.

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

  1. 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.

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

  1. 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.

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

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

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

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

  1. The search now returns no results.

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

  1. 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

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.