Creating Custom Entities


Microsoft CRM creates over 120 entities when you install the software, and you can add an almost unlimited number of custom attributes to the customizable entities. However, you will most likely want to track business data that does not fit neatly into one of these existing entities. With most other CRM applications (and earlier versions of Microsoft CRM), tracking new categories of data usually required a custom application development project in which consultants would create new custom databases and user interface forms that they tried to blend into the host CRM application.

In addition to the obvious downsides of taking development time and costing money, these customized CRM application projects usually resulted in less-than-ideal functionality for system administrators and end users. Plus, when the host CRM application released an updated version, the consultants had to reprogram the business logic code, update the customized databases, and revise the user interface forms. Add all these factors up and you understand why CRM customization projects in the past required lots of time, money, and effort.

Custom Entity Benefits

Fortunately, Microsoft CRM solves many of the common CRM customzation issues related to tracking new categories of data by allowing you to create custom entities. Even more beneficial, Microsoft CRM allows you to create custom entities and manage their relationships with the Web-based administration interface (so no custom programming is required).

So how might you use custom entities? You have almost unlimited options for setting up and structuring your custom entities. An apartment management company might use custom entities to track its various property locations, leases, and rental applications. A professional services firm might create custom entities to track its various customer projects. A magazine publisher might use custom entities to capture data about its magazines and customer subscriptions. As you can see, how you use custom entities depends on the nature of your business and the types of data that you want to capture in Microsoft CRM.

When you create a custom entity to store a new category of data, Microsoft CRM automatically adds the entity to the metadata and its underlying system data. That means that custom entities behave as "first class" system entities, sharing almost all of the functionality of the default system entities created on installation. Some common benefits of custom entities and the default entities include the following:

  • You can customize the custom entity attributes, forms, and views with the same Web-based administration tools that you use to customize the default entities.

  • Users can use the Advanced Find feature to create and save custom queries on custom entities.

  • You can add client-side events such as onChange, onLoad, and onSave to the custom entity's form.

  • You can import and export custom entities and their customizations with the same import/export tool that you use for the default entities.

  • Users can access custom entities within the Microsoft CRM client for Microsoft Office Outlook (laptop or desktop).

  • Users can work with custom entities offline by using the Microsoft CRM laptop client for Office Outlook.

  • You can add relationships and mappings to custom entities, just as you can with the default entities.

  • Custom entities fully participate in the Microsoft CRM security framework, so you can set privileges such as Create, Read, and Write on an entity-by-entity basis.

  • Developers can programmatically access custom entities through the Microsoft CRM Software Development Kit (SDK), including Create, Retrieve, and Update operations.

  • Microsoft CRM supports pre- and post-callouts on custom entities.

  • Users can use the batch edit feature on custom entity records.

  • Microsoft CRM creates filtered views for custom entities in the SQL database that you can use for creating reports.

  • Users can export custom entities to Microsoft Office Excel as a dynamic PivotTable or dynamic worksheet.

  • You can modify the Microsoft CRM application navigation and menu structure to seamlessly blend custom entities into the user interface.

This list illustrates that custom entities behave almost identically to the default entities within the Microsoft CRM system.

Custom Entity Limitations

Despite all of the similarities between custom entities and default entities, a few notable limitations exist for custom entities:

  • Custom entities support one-to-many and many-to-one relationships only. You cannot create many-to-many relationships directly between two custom entities.

  • You cannot merge two custom entity records together.

  • The Microsoft CRM Data Migration Framework does not support custom entities. This means that you must export and import custom entity data by using a separate (custom) process.

  • The Microsoft CRM system entities include a relationship to Customer in which users can select an Account or a Contact. For custom entities, you can specify a relationship with the Account entity and the Contact entity, but you cannot create a relationship to the composite Customer entity (in which users can select an Account or a Contact on a single lookup).

  • You can specify only one parent relationship per custom entity, so you can't add custom entity lookups on non-parent entities.

  • Custom entities don't appear in an entity rollup (showing activities from child entities on the parent entity's record).

  • Organization-owned custom entities can't participate in Microsoft CRM workflow, but user-owned custom entities can.

As you can see, most of the limitations regarding custom entities revolve around the supported relationships that you can create. We'll explain setting up and configuring custom entity relationships (and their corresponding limitations) next.

Custom Entity Relationships

As you learned earlier in this chapter, Microsoft CRM uses entity relationships to manage how two entities relate to one another. Entity relationships define the nature of the data relationship between entities, the behavior of that relationship, and how to map attributes between the entities. When you use custom entities, you will want to add custom relationships between your custom entities and the default system entities so that users can track and enter data about how the custom entities relate to the other entities. In addition, you will probably want to create custom relationships between custom entities to dictate how the custom entities interact with each other. After we explain how relationships work in the context of custom entities, we'll show you how to set up and create custom entities.

Table 6-4 shows the types of relationships that Microsoft CRM supports.

Table 6-4: Supported Custom Relationships

Primary entity type

Related entity type

Relationship behavior

Create custom relationships?

Create custom mappings?

System

Custom

Parental

Yes

Yes

System

Custom

Referential

Yes

Yes

Custom

Custom

Parental

Yes

Yes

Custom

Custom

Referential

Yes

Yes

Custom

System (Activity and/or Note)

Parental

Only on custom entity creation

No

Custom

System (Activity and/or Note)

Referential

No

No

Custom

System (all other entities)

Parental

No

Yes

Custom

System (all other entities)

Referential

Yes

Yes

System

System

Parental

No

Yes

System

System

Referential

No

Yes

In addition, you should be aware of the following nuances:

  • You cannot create a custom relationship between an entity and itself. So you could not create a concept similar to the account and sub-account feature that exists in Microsoft CRM.

  • Two entities can have only one distinct relationship between them. Therefore, you could not create relationships in such a way that a form has two or more lookups that connect to the same custom entity. However, you can create multiple relationships between a custom entity and other entities; you just can't create multiple relationships to the same entity.

  • You cannot create new custom relationships between existing system entities, such as adding additional relationships between the Opportunity and User entities. However, you can use relationship roles to create new opportunity relationships and customer relationships.

  • You cannot create many-to-many relationships (custom-to-custom or system-to-custom) between two entities.

  • You can create only one parental relationship behavior for each custom entity.

  • Custom entities cannot have a parental relationship behavior to system entities.

More Info 

Although Table 6-4 lists only parental and referential relationship behaviors, you can also use referential, restrict delete, and configurable cascading where appropriate because both of those behaviors are merely sub-types of parental and referential relationship behaviors.

To put these supported relationships and custom entity constraints into context, let's map out a real-world example of creating custom entities and relationships for a fictional property management firm called Litware, Inc.

Litware, Inc. manages 15 apartment buildings on the East Coast. The apartment complexes range in size from 25 to 75 apartments per building, including one-bedroom, two-bedroom, and three-bedroom apartments. As part of the rental process, each prospective tenant must complete a rental application and submit to a credit check. After receiving credit approval, all of the tenants sharing an apartment (roommates) sign a lease. Litware, Inc. will use Microsoft CRM to manage its current tenants and track potential tenants.

Based on this description, we created an initial design proposal in which Litware, Inc. would use the following entities in Microsoft CRM:

  • Building Custom entity with attributes such as name and address

  • Apartment Custom entity with attributes such as number of bedrooms, number of bathrooms, square footage, monthly rent, and floor number

  • Lease Custom entity with attributes such as monthly rent, start date, end date, and security deposit

  • Lease Application Custom entity with attributes such as employment information and previous addresses

  • Contact System entity used to track tenants and applicants

  • Opportunity System entity used to track potential rental opportunities

When you map out an entity design like this one, you should consider different scenarios because no hard rules exist to let you know whether you should create a custom entity or add attributes to an existing entity. We recommend that you try to map out all of the proposed entities and relationships that you think you'll need in your solution before you start entering changes in Microsoft CRM. Making changes to your entity relationships in a modeling tool such as Microsoft Office Visio is much easier and more efficient than making changes in Microsoft CRM. Figure 6-16 shows our proposed entity map for Litware, Inc.

image from book
Figure 6-16: Proposed entity relationship map for Litware, Inc.

Based on this initial design, we created visual mockups of the Opportunity and Contact entity forms, as shown in Figure 6-17 and Figure 6-18.

image from book
Figure 6-17: Mockup of the Opportunity form

image from book
Figure 6-18: Mockup of the Contact form

You can immediately see how some of our proposed entity relationships manifest themselves in the user interface. For example, our proposed design includes the following benefits and caveats:

  • We can track multiple Contact records per lease because of the one-to-many relationship between Lease and Contact. However, this relationship also means that each Contact can have only one related lease record (as you can see in Figure 6-18). In reality, a tenant might rent from Litware, Inc. for several consecutive years and have multiple leases. However, Microsoft CRM does not support this type of relationship because multiple contacts on a lease and multiple leases per contact would constitute a many-to-many relationship.

  • For any single apartment, we can view all of the related Opportunities because of the one-to-many relationship between Apartment and Opportunity. However, if a potential tenant were trying to decide between two different apartments, Litware, Inc. could track only one of those apartments. The apartment lookup field on the Opportunity form allows a user to select only one apartment. Again, this constraint appears because Microsoft CRM does not support many-to-many relationships.

  • Although you can specify only one lease per Contact, Litware, Inc. can view the entire lease history for any single apartment because of the one-to-many relationship between Apartment and Lease.

  • Because we cannot create new relationships between system entities, we could not create a new relationship between Opportunity and Contact. Therefore, on the Opportunity form, we can select only one contact record, even though the apartment might have two or three roommates. Fortunately, opportunity relationships give us an easy workaround for this situation. We can create a new relationship role (in Settings) called Roommate, and then simply add roommates as additional contacts.

    image from book

  • Our design allows Litware, Inc. to create a unique Contact record for each tenant and add multiple tenants to an apartment. Therefore, the company can quickly and easily find the current tenants for any given apartment with one click from the apartment record.

  • The proposed design allows each tenant to complete his or her own lease application independently.

If Litware, Inc. reviewed our proposed relationship design, the reviewers might decide to make changes to the entity relationships based on specific business needs. For example, they might want to change the Contact and Lease Application relationship so that Lease Application becomes the primary entity and Contact becomes the related entity. This change would allow company managers to view multiple Contacts on a single application (our original design allowed them to view multiple lease applications per contact).

Another potential design change might involve eliminating the relationship between Apartment and Contact. At first, this might strike you as strange because it seems intuitive that a relationship should exist between those two entities. However, by eliminating the link between Apartment and Contact in addition to flipping the primary/related entity relationship between Contact and Lease Application, we effectively create a many-to-many relationship between Apartment and Contact! Each apartment can have many leases, and each lease can have many contacts. Therefore, each apartment can have many Contacts and each Contact can have many apartments (through the Lease entity).

Important 

Although you cannot create a custom many-to-many relationship between two entities in Microsoft CRM, you can effectively create a many-to-many relationship behavior between two entities (A and B) by creating an intermediate entity (C) and then creating two custom one-to-many relationships. Create one relationship between A and C and create a one-to-many relationship between C and B.

Figure 6-19 shows the modified relationship design.

image from book
Figure 6-19: Revised entity relationship map for Litware, Inc.

Of course, when you change the entity relationships, you must also update your entity forms. The downside of removing the relationship between Apartment and Contact is that to view the Contacts for an apartment, you must first click the lease record and then click the Contacts link in the navigation pane on the lease record. Figure 6-20 and Figure 6-21 show mockups of what the Lease and Apartment forms would look like for the revised design.

image from book
Figure 6-20: Lease form for the revised entity relationship design

image from book
Figure 6-21: Apartment form for the revised entity relationship design

In summary, either of these designs could work perfectly well for Litware, Inc. However, both designs offer unique benefits and drawbacks that you must consider when you create custom entities. Hopefully, this example also convinced you of the benefits of mapping out all of the entity relationships in a tool such as Microsoft Visio.

Ownership

Microsoft CRM assigns an owner to almost all of the records in its database. Records such as Leads, Accounts, Activities, and Contacts have a Microsoft CRM user for their owner. However, Microsoft CRM assigns ownership of records such as products, sales literature, and sites to the organization. These types of records store information that theoretically applies to all of the users in the organization, regardless of their business unit. For each custom entity you create, you must specify one of two ownership types:

  • User-owned

  • Organization-owned

You must make the entity ownership decision carefully because you cannot change the entity ownership type after you create the entity. Some of the differences between user ownership and organization ownership include the following:

  • User-owned entities can be assigned to other users; organization-owned entities cannot.

  • User-owned entities can be shared with one or more teams; organization-owned entities cannot.

  • Because user-owned entities belong to a user and each user belongs to a business unit, you have more flexibility when configuring security on user-owned entities than you do with organization-owned entities. When you configure a security role regarding organization-owned entities, you can specify only None or Organization access levels. For user-owned entities, you can specify one of five different access levels: None, User, Business Unit, Parent: Child Business Units, or Organization.

  • Organization-owned entities can require less work to administer because they belong to the company. However, you must always assign a user-owned entity to a specific user record.

  • You can create and run workflow rules on user-owned entities only.

As this list illustrates, making custom entities user-owned provides you with more options and configurability. However, user ownership does require that you carefully assign each entity to the correct owner and configure the security roles correctly. If your users frequently change business units or job functions, you will want to update entity ownership accordingly. In such scenarios, the work of maintaining the correct user ownership might offset the additional configurability and workflow benefits.

Entity Icons

Microsoft CRM uses different icons in the user interface to represent each of the default system entities. These icons appear in the navigation pane, in various views, and on a related entity's form. In addition to improving the visual aesthetics, these entity icons help users navigate the system by providing graphical indicators about each type of record they are working with. By default, Microsoft CRM assigns the icon shown in Figure 6-22 to each new custom entity.

image from book
Figure 6-22: Default custom entity icon

When you have more than a few custom entities in your system, using the same default icon for all of the custom entities diminishes the aesthetic benefit of icons and might cause confusion with your users because the same icon appears for multiple entities. Figure 6-23 shows an example of four different custom entities, all using the default icon.

image from book
Figure 6-23: Multiple custom entities using the same default icon

Fortunately, Microsoft CRM allows you to upload your own custom icons for each custom entity. We highly recommend that you try to use custom icons for each custom entity in your system. You can upload two types of entity icons for each custom entity, and they must meet the specifications outlined in Table 6-5.

Table 6-5: Entity Icon Specifications

Icon usage

File type

Size (in pixels)

Maximum file size

Web application

.gif

16 × 16

10 kilobytes

Microsoft CRM client for Outlook

.ico (16 colors)

32 × 32

10 kilobytes

In addition, you should use files with transparent backgrounds for both types of entity icon file. When the icons appear on dark backgrounds or when Microsoft CRM highlights the record, failure to use transparency in your images creates an unpleasant effect.

Most graphics editing programs provide the tools to create these icons to the specifications of Microsoft CRM. When you have your icon files ready, uploading them to the custom entity is easy.

Updating Custom Entity Icons
  1. In the entity editor, click Actions, and then click Update Icons. The following dialog box appears.

    image from book

  2. For both the Web and Outlook file types, browse and upload the icon files that you want to use, and then click OK. A preview of the icon that you uploaded appears, in addition to the current published icon.

  3. Publish the entity so that users can see the new icons.

More Info 

Microsoft CRM allows you to upload icons for custom entities, but you can also change the entity icons by using the site map. The site map allows you to specify new image files for custom entities and the default system entities, such as Leads, Accounts, and Contacts. We explain the site map in more detail later in this chapter.

Creating a Custom Entity

By now you should understand the concepts, benefits, and limitations related to custom entities. Now let's go through the steps that you will follow to create a custom entity in Microsoft CRM. For every custom entity you create, you must configure the following parameters:

  • Entity definition

  • Offline availability

  • Associated entities

  • Display areas

  • Primary attribute

Figure 6-24 shows the user interface for creating a new entity; we'll provide a little more information about each parameter.

image from book
Figure 6-24: Creating a new custom entity

Entity Definition

In the Entity Definition section, you will enter some basic parameters about the custom entity, including:

  • Name

  • Plural name

  • Ownership (user or organization)

  • Schema name

  • Description (optional)

In Chapter 4, we discussed how the name, plural name, schema name, and description parameters work with regard to renaming entities, so you should be familiar with these concepts. Remember that you cannot change the schema name after you create the entity, but you can modify the name, plural name, and description at any time.

Tip 

You can change the default schema name prefix from new_ to a different value by configuring the schema-name prefix. To alter this value, browse to Settings, click Organization Settings, click System Settings, and then click Customization.

For the ownership parameter, you must specify whether the entity will be user-owned or organization-owned, as discussed earlier in this chapter.

Offline Availability

Microsoft CRM includes two different Office Outlook clients: Microsoft CRM desktop client for Microsoft Office Outlook and the Microsoft CRM laptop client for Microsoft Office Outlook.

The laptop client allows your users to access Microsoft CRM data if they disconnect from your network. Microsoft CRM refers to this concept of working disconnected from the network as working offline. The desktop client works only when users are connected to the server. You have the option to use one, none, or both of the Outlook clients in your deployment.

When you create a custom entity, you can choose whether you want your users to work offline with custom entities. Obviously, this parameter affects you only if your organization deploys the laptop client because only that client can go offline. The offline availability option has no impact on the desktop client.

Tip 

Even if you decide to include a custom entity for offline availability, the default synchronization settings for the laptop client will not include any custom entities. Therefore, your users must also manually configure their offline filters to include the custom entity when they go offline.

You have the option to toggle the offline availability feature off or on at any time.

Associated Entities

When you create a custom entity, you can choose whether you want to enable Notes and Activities for the entity. Notes and Activities for custom entities behave just like Notes and Activities for the default system entities. Therefore, if you enable Activities, users can add any type of Activity record (such as Task, Phone Call, or Letter) that their security privileges allow.

You must configure Notes and Activities at the time that you create a custom entity. You cannot change the associated entities settings at a later time.

More Info 

Because you can't change these settings later, you might be tempted to always include Notes and Activities on your custom entities. Remember that when you include Activities on a custom entity, that entity will appear as an option in the Regarding list for Tasks, Phone Calls, and so on. If you don't want users to select the custom entity as a regarding value, make sure that you do not include Activities.

Display Areas

Microsoft CRM allows you to specify where to display the custom entity to users in the application navigation. The default display area options include:

  • Workplace

  • Sales

  • Marketing

  • Service

  • Settings

You can choose to display the custom entity in all, some, or none of the areas. When you choose to include a custom entity, Microsoft CRM adds a link in the navigation pane in addition to a link in the application menu bar. You have the ability to toggle the display settings whenever you want, not just during entity creation.

Tip 

You can further customize the user interface and application navigation with the site map that we will cover later in this chapter. By modifying the site map, you can include additional areas as options for your users to check.

Primary Attribute

Every entity, including the default system entities, has a primary attribute that Microsoft CRM uses to display on the lookup field in related entities. Figure 6-25 shows how Microsoft CRM displays an entity's primary attribute on a related entity's form. In this figure, the schema field name is the primary attribute of the apartment entity, so the name of the apartment record appears in the lookup field of its related records.

image from book
Figure 6-25: An entity's primary attribute appears on a related entity's lookup field

You can probably guess that most custom and default entities use a name field as the primary attribute, but you are not required to do so. However, you will notice that Microsoft CRM does require you to create a primary attribute with a data type of nvarchar and a format of text. You can set up a maximum length and business requirement level for the primary attribute that makes sense for your business.

Tip 

After you create a custom entity, the data fields on the Primary Attribute tab become read-only so it appears that you cannot edit the primary attribute. However, if you navigate to the list of attributes for the custom entity and double-click the primary attribute, you can modify the primary attribute's name, business requirement level, and maximum length in the attribute editor. Although you can edit some of the primary attribute's values, you cannot change the primary attribute of a custom entity.

Other than the data type and data format requirement, the rules and restrictions for creating a primary attribute are the same as they are for creating any attribute for an entity.

Deleting a Custom Entity

If you decide you no longer need to use a custom entity, you can easily delete it from Microsoft CRM. Just like deleting attributes, you must remove all existing references to the custom entity that you want to delete before Microsoft CRM will allow you to delete it. To remove references to an entity, you should do the following:

  • Remove references to the entity that you want to delete from the form of any related entities, and then delete any relationships linking to the custom entity.

  • Remove the entity from any reports.

  • Remove the entity from any script or code references.

Warning 

Deleting a custom entity also deletes all of the data stored in that entity, and you can never retrieve that data. Microsoft CRM also permanently deletes all of the notes and activities related to that entity. Make sure you take the appropriate steps to back up all of your data before deleting an entity or attribute.




Working with Microsoft Dynamics CRM 3.0
Working with Microsoft Dynamics(TM) CRM 3.0
ISBN: 0735622590
EAN: 2147483647
Year: 2006
Pages: 120

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net