Best practices when creating a custom write plugin
This topic contains best practices that are advised when creating new write plugins.
Implementation plan
- Choose the category of the plugin. For example, if you want the plugin to be triggered on Update, you need to create a Write Plugin.
- Choose the interface to implement. When writing a new custom plugin, you should implement one of the available interfaces:
- Choose
IWriteMetadataPluginwhen your plugin only needs to access metadata fields. This plugins will be executed regardless of whether the BLOB is submitted or not. - Choose
IWriteMetadataAndBlobPluginwhen your plugin needs to access the BLOB. If the BLOB is not submitted, the plugin is ignored.
- Choose
- Implement
Initialize. Here plugin should read its parameters and parse their values. In case the value is invalid, the plugin sequence can fail early in the process, before any plugin is executed. - Implement the
ObjectContentTypeproperty. If you are implementing theIWriteMetadataAndBlobPlugininterface, you need to specify how your plugin will consume the blob: as anXmlDocumentor as a stream. - Implement
Run. Here you put the main logic of the plugin. Anything that your plugin can do is available to it through the context, which includes:- Accessing the
IshType,LogicalIdand so on - Getting the current metadata field values
- Getting the original metadata field values
- Setting the current metadata field values
- Accessing the BLOB and the BLOB properties (
Edtdefinition) - Logging: use the
LogServiceproperty of the context to add the logging statement to the standard application log file. - Adding events to the event queue: use the
EventQueueproperty of the context to access the mechanism to add events to the queue.
- Accessing the
-
General best practices
-
Pass
falseto any API 2.5 constructor - Make sure to pass one parameter, set to
false, to any API 2.5 constructors you use in your plugin. Without this parameter included and set tofalse, you get a security error. This parameter,initializeCallContext, when set tofalse, causes the call context to be reused, effectively keeping your code within the same process. - Explicitly specify all the metadata fields that are required by the plugin in the working set
- It can be that the field is available for the plugin because it is being updated, it is a system field or another plugin requested it using the working set. However, it's safe not to rely on the other components and explicitly request fields required by the plugin by specifying them in the working set.
- Limit the number of fields in the working set
- Every field that is specified in the working set has to be retrieved from the database and stored in the database in the end, which might affect the performance. Don't specify the field that you don't need.
-
Verify the parameter values in
Initialize - If plugin cannot be executed because some parameters were not provided or have wrong values, it is better that the main operation fails as soon as possible.
-
Prefer getting and setting field values using
IshValueType.element - The element name does not change and guaranteed to be unique.
- Do not pass data between plugins using class private fields or static fields
- Every plugin runs as a new instance. The only supported way to pass the data between plugins is the metadata field of the object.
-
Use the appropriate field type when getting or setting the value of
LOVValueandCardReferencefields -
When you get or set
LOVValueandCardReferencefield values, use string and multistring field types. -
Avoid unnecessary content conversion (from
XmlDocumenttoStreamand back) - When adding plugins into the plugin XML configuration file, try grouping plugins that require the same content type together. This way, the plugin engine will be able to simply pass the content to the next plugin without conversion.