Implementing a Creator
Applies to: SharePoint Server 2010
In this article
Description
Syntax
Remarks
Examples
Description
A Creator method instance enables you to create a new entity instance. For example, given a business object named Customer, this method can be used to create a customer "John" in the external system.
If an external content type does not have a Creator stereotype, new items (entity instances) cannot be created by using the Business Connectivity Services features. For example, you are not able to click the New Item button on the ribbon of an external list to create an item.
A Create method enables you to create external items on the external system by specifying the values of the fields that are required for Create. The set of fields that are required to create the new item is referred to as the Creator View. The field values do not necessarily correspond to fields of an external item. The method must return the identity corresponding to the external item that was created. The IFieldValueDictionary instance that is provided as an input to this method should be created from a view.
This method also enables you to create an external item by specifying the values of fields of the created external item. If the Create method instance accepts all the fields that are provided, BDC invokes only the Create method instance. Otherwise, BDC also invokes Update MethodInstance on the created external item to set the specified values for the remaining fields. The method returns the EntityInstanceReference to the external item that was created. The IFieldValueDictionary instance that is provided as an input to this method should be created from a view corresponding to a MethodInstance of type SpecificFinder, obtained via the GetCreatorView method.
Syntax
Following are the typical method signatures for a Creator method:
structureContainingIdentifierValues CreateEntity(EntityDataType fields)
void CreateEntity(EntityDataType fields)
structureContainingIdentifierValues CreateEntity()
Remarks
To qualify as a Creator, the corresponding method:
Should take as input parameters the fields that are mandatory to create an instance in the external system.
Can take optional fields in the external system as input parameters.
Can take the identifier (or combination of identifiers) of the item as input – OR – can return the identifier (or combination of identifiers) for the newly created item.
Should be transactional to protect from data loss.
The Creator view should be equal to, or a subset of, the view of the SpecificFinder method (see example below). If the Creator has more fields than a SpecificFinder, it cannot be taken offline to Microsoft Office 2010 clients.
If there are multiple specific finders, the Creator view should be equa to, or subset of, at least one specific finder view.
As mentioned, the Creator view must be equal to, or a subset of, at least one specific finder view (it may include read-only fields). This is because, in external lists, the Business Connectivity Services auto-generated forms that are used for creating items are based on the SpecificFinder view. If the Creator view has extra fields, these are not be displayed on the auto generated forms and can cause problems with the Create operation. To avoid this, Business Connectivity Services checks for this dependency and disables the Create operation on the external list if the Creator view is larger than the SpecificFinder view.
If the Creator view is a subset of the SpecificFinder view, Business Connectivity Services allows creation of the item with the Create operation in external lists. But, for offline scenarios, (for example, Microsoft Outlook), an Updater method is required because Business Connectivity Services calls the Updater method immediately after the Create method (for updating the fields that are not included in the Creator view).
Table 1 summarizes the dependencies for Creator View and Updater View and the status for create and update operations.
Table 1. Dependencies for Creator view and Update view and status for Create and Update operations
Scenario# |
Fields in Specific Finder View |
Fields in Creator View |
Fields in Updater View |
Operations Allowed |
Notes |
|---|---|---|---|---|---|
1. |
A B (read-only) C D E (read-only) |
A B C D E F |
A C D F |
Create: Not allowed Update: Not allowed Offline Create: Not allowed Offline Update: Not allowed |
Field F cannot be found on the specific finder. This causes BCS to disable create operations and update operations. |
2. |
A B (read-only) C D E (read-only) |
A B C D E |
A C D |
Create: Allowed Update: Allowed Offline Create: Allowed Offline Update: Allowed |
The values of field B and field E can be specified by the user during create, but cannot be updated later. |
3. |
A B (read-only) C D E (read-only) |
A B |
A C D |
Create: Allowed Update: Allowed Offline Create: Allowed Offline Update: Allowed |
The value of field B can be specified by the user during create, but cannot be updated later. The value of field E is assigned by the external system and cannot be updated by the user. For offline create, the update operation is called immediately after create. |
4. |
A B (read-only) C D E (read-only) |
A B |
A C |
Create: Allowed on default EL forms only Update: Not allowed Offline Create: Not allowed Offline Update: Not allowed |
Field D cannot be updated. This inconsistency causes BCS to disable the update operation. Offline create is disabled because there is no valid update operation. |
5. |
A B (read-only) C D E (read-only) |
A C D |
No update operation defined |
Create: Allowed Update: Not Allowed Offline Create: Allowed Offline Update: Not allowed |
The values of field B and field E are assigned by the external system. |
6. |
A B (read-only) C D E (read-only) |
A B C |
No update operation defined |
Create: Allowed on default EL forms only Update: Not allowed Offline Create: Not allowed Offline Update: Not allowed |
The value of field D cannot be set during create, and there is no valid update operation defined for setting it later. This causes BCS to disable the offline create operation. |
Ensure that you handle exceptions properly. If the creation operation fails on the external system, raise the exceptions that are listed in Table 2
Table 2. Exceptions
Exception Name |
Use This ExceptionWhen…. |
|---|---|
AccessDeniedException |
User is not allowed to perform this operation on the external system. |
PartialCreateException |
On a few external systems, there are some scenarios in which it is required to create a new item with a few fields and then update the remainder of the fields. When the item is created and the ID is returned, but the field values are not set correctly, raise this exception to optimize error handling. |
Runtime Exception |
If the create fails, ensure that you raise this exception to alert your users and to use the error handling features in Outlook 2010 and Microsoft SharePoint Workspace 2010. |
Note
The names of the parameters must be the same as what is defined in the external system. Names of parameters are case-sensitive. If the names of the parameters are not identical on all methods, Microsoft SharePoint Designer 2010 interprets them as different fields.
Examples
Code Snippet: Implementing a Creator
See Also
Concepts
XML Snippet: Modeling a Creator Method
Code Snippet: Execute the Creator Method Instance of an External Content Type