Extend a data entity

Completed

When you add fields to tables, you need to ensure that the corresponding data entity includes these fields. Additionally, you can extend existing data entities with these new fields. Data entities have two parts:

• Data entity - You need to create an extension of the existing data entity.
• Staging table - You need to create a table extension manually for a staging table.

Also, you can add new fields to a data entity by creating a duplicate entity and then adding the new fields and functionality. As a result, you don’t need to extend the original entity.

Add new fields to extend a data entity

You can add fields to a data entity by creating an extension. For example, consider a scenario where you create a new PhoneMobile field (EDT: PhoneMobile) as an extension on the CustTable table. In this case, you could create an extension for the data entity by completing the following steps:

1. Find the CustCustomerV3Entity data entity in Application Explorer (under Data Model) in Visual Studio. (In addition to the usual options, make sure that your model references the Directory, Dimensions, and PersonnelCore packages.)

2. Right-click the data entity to open the context menu, and then select Create extension. The system adds an extension for CustCustomerV3Entity to your project in Solution Explorer.

3. Select the extension to add it to the Designer.

4. Go to the Data sources node, select CustTable, select Fields, and then locate the new PhoneMobile field.

5. Right-click the new PhoneMobile field to open the context menu, and then select Copy.

6. Go to the Fields node on the data entity. Right-click the node to open the context menu, and then select Paste. The new field should now show in CustCustomerV3Entity.

7. Select Save all. Right-click your project in Solution Explorer to open the context menu, and then select Build.

8. Right-click your project again to open the context menu, and then select Synchronize <your project> With Database (if available). The CustCustomerV3Entity data entity shows as extended and includes the PhoneMobile field.

   

You can create code extensions by finding the data entity in Application Explorer, right-clicking it to open the context menu, and then selecting Create Code Extension.

The system creates a class for code extensions of the data entity, and then you can extend methods with Chain of Command or create new methods.

For example, you can create a computed column on the data entity and then have the system create its static method in the code extension class.

You should be aware of performance considerations when doing data entity extensions and data entity code extensions. For more information, see the previous unit in this module.

As a best practice, your organization could require a naming standard for new fields, such as a specific prefix. However, the example in this unit doesn't use a naming standard.

Extend a staging table

In the Designer, you can use Regenerate staging table and Update staging table to add fields to a staging table. However, this method isn’t possible for a data entity extension. You must create fields manually by using a table extension.

1. Find the CustCustomerV3Staging table in Application Explorer.
2. Right-click the table to open the context menu, and then select Create extension. The system adds an extension for CustCustomerV3Staging to your project in Solution Explorer.
3. Select the extension to add it to the Designer.
4. Find the extended data type for the field that you want to add. In this example, it’s Extended Data Type PhoneMobile, which you should drag into the Fields node for the staging table.
5. Select Save all. Select your project in Solution Explorer to open the context menu and then select Build.
6. Right-click the project again to open the context menu, and then select Synchronize <your project> With Database (if available). The new field on the staging table now shows as synced with SQL Server.

Note

Fields, and the data type for fields, on a staging table extension and data entity extension should be the same. If you’re using different data types, a best practice error appears after the build finishes.

Refresh an entity list and verify the extension

If you want to use changes to an entity that extensions made, select Refresh entity in finance and operations apps. The Refresh entity option re-creates mappings for an entity, including new fields.

To refresh manually on the front end, go to Data management > Framework parameters > Entity settings > Refresh entity list. Refreshing the entity list ensures all entities are available in the environment and that the entities have the latest metadata.

Developers can open SQL Server Management Studio to verify the view and table that they create for the data entity and staging table, respectively. Extensions to data entities should appear on the data entity and the staging table.