Dom helper class

CRUD methods

The DomHelper class can be used in a script, protocol, or app to execute create, read, update, and delete (CRUD) actions on DOM objects.

For detailed info on how the helper and all its functionality can be used, refer to CRUD methods.

Special methods

In addition to the CRUD methods, the following special methods are also supported on a DomInstance CRUD helper component:

• DoStatusTransition: Used to transition a DomInstance from one status to another. See DOM status system.

• ExecuteAction: Used to execute an action in the context of a DomInstance that was defined on a DomBehaviorDefinition. See DOM actions.

Stitching

The stitching functionality makes it easier to work with a DomInstance. With this, there is no need to use the helper each time and retrieve the linked objects using an ID filter. When a DomInstance is stitched, it is possible to:

• Retrieve the full DomDefinition object that the DomInstance is linked to, by calling GetDomDefinition() on the instance.
• Retrieve the full SectionDefinition object that a Section is linked to, by calling GetSectionDefinition() on the Section
• Retrieve the full FieldDescriptor object that a FieldValue is linked to, by calling GetFieldDescriptor() on the FieldValue.

Note

When an item is not stitched, and one of the above-mentioned get methods is called (e.g., GetDomDefinition), an exception will be thrown.

There are two ways to stitch DOM instances:

• DomHelper.StitchDomInstances(List<DomInstance> domInstances): This will stitch the given list of DomInstances by retrieving all objects from the server using the SLNet callback on the helper.

• DomHelper.StitchDomInstances(List<DomInstance> domInstances, List<SectionDefinition> existingSectionDefinitions, List<DomDefinition> existingDomDefinitions): This will stitch the given list of DomInstances by trying to retrieve the other objects from the given lists. This is a more efficient option when you already have all necessary objects.

Note

If stitching is used and an object cannot be found, a null value will be assigned to the related property. The DomInstance will still be marked as stitched. This way, when that property is retrieved, you can know it is not available.

For example: If the second of the two methods above is used, but the provided existingDomDefinitions list is empty, the stitching logic will not be able to find the DomDefinition object linked to the instance. When you try to retrieve the DomDefinition using the DomInstance.GetDomDefinition() method, "null" will be returned.

Attachments

From DataMiner 10.1.3/10.2.0 onwards, it is possible to save attachments with the DomHelper. These are linked to a DomInstanceId. You can use the Attachments helper on the DomInstance CRUD component.

var domHelper = new DomHelper(engine.SendSLNetMessages, PermissionTestModuleId);
var fileBytes = File.ReadAllBytes("C:\MyDocuments\ImportantDocument.txt");

// Adding an attachment
domHelper.DomInstances.Attachments.Add(domInstanceId, "ImportantDocument.txt", fileBytes);

// Get the names of all attachments
List<string> fileNames = domHelper.DomInstances.Attachments.GetFileNames(domInstanceId);

// Get the content of an attachment
byte[] file = domHelper.DomInstances.Attachments.Get(domInstanceId, "ImportantDocument.txt");

// Delete an attachment
domHelper.DomInstances.Attachments.Delete(domInstanceId, "ImportantDocument.txt");

Note

• The size limit of the attachments is determined by the Documents.MaxSize setting in MaintenanceSettings.xml. The default value for this is 20 MB. Trying to upload a larger file using the helper will result in a DataMinerException.
• Deleting a DomInstance will delete all attachments from the file system. The attachments cannot be recovered.
• To view or download DomInstance attachments, read permission is required, and to add or edit them, edit permission is required.
• To include DomInstance attachments in a custom backup in Cube, select All documents located on this DMA.
• The attachments are synced in the DMS.