Creating your own export script

Export scripts provide a mechanism to extend product functionality at the end of a successful workflow activity. A common use case is to send information in FileHold such as metadata to other systems, like ERP software. For example, invoices can be added to FileHold prior to being paid, so FileHold workflow can be used to approve the invoices for payment and FileHold can be the place where the invoice lifecycle is managed. When the approval workflow is complete, information like the invoice date, amount, vendor, etc. can be used to create a voucher for payment in an external system.

An export script is made up of two components: an executable DLL and its associated configuration. Via configuration, a single DLL could serve many purposes or the main functionality of the export script could be coded in the DLL leaving little to configure. The executable is used for two purposes: providing information about configuring the DLL to the administration interface and executing at the end of a workflow activity. The system provides the user interface and storage mechanism for the configuration and a method to attach the configured DLL to a workflow activity. Thus, the actual content of the DLL can be very simple and still perform complex tasks.

Additional functionality comes from the system's batch job processing queue. When the workflow is ready for the export script to execute, it adds a job to the batch queue. Administrators can review the queue to see the status of the export script. They can also receive emails when the batch job fails and restart the batch job after a failure when enabled.

Beginner to intermediate level Microsoft dot net programming skills are necessary to create an export script. 

The remainder of this document provides information to assist customers with creating their own export script DLL.

Starting with FileHold 16.3 there is developer API documentation and sample code on the FileHold server for self-hosted customers. FileHold Cloud customers can also create export script DLLs, but they will need the assistance of the FileCare team for their deployment. In addition to the sample code, some ready-made DLLs are optionally available that provide commonly requested functionality. Any customer creating custom integrations to FileHold should have a non-production license of FileHold for testing and development.

Steps to create the export script

1. Plan the solution by determining what data will be exported and where it will be exported to.
2. Develop the export script DLL.
3. Install the export script DLL on your document management application server. FileHold Cloud customers can request assistance from the FileCare team.
4. Add the DLL and configuration details to the export script management page.
5. Add the export script to the necessary workflow activities.

Develop the export script DLL

Before you start, you should review the export script demo source code as it provides a working example with the basic structure. The demo source is available in the ApiKit folder of your application server. FileHold Cloud customers can request the API kit from the FileCare team. The demo exports the text field values from the first document in the workflow to an XML file.

The DLL must implement the ILibraryManagerScript2 interface. The core of the solution is the FinalizeActivity method. This is called by the application server when the workflow activity has been approved or reviewed. Your code will need to implement this method to export the data.

Dictionary<string, string> FinalizeActivity(
	Guid workflowGuid,
	int activityIndex,
	List<int> documentVersionIds,
	List<int> supportingDocumentVersionIds
)

The workflowGuid and activityIndex provide details about the specific workflow and activity that was completed when FinalizeActivity was called. The main and supporting document versions are provided in the documentVersionIds and supportDocumentVersionIds lists respectively.

The rest of the code will provide details for configuring the script.

• GetParameters provides a list of configuration options and their data types to the management interface. It returns a list of ScriptParameter.
• SetParameters is called by the application server to update the configuration data inside the DLL.
• ValidateParameters is called when the configuration page validates the user entered data before saving it. All parameters are validated at one time and the application server will call SetParameters before ValidateParameters is called. The method can return a message that will be displayed in an error box if there are any issues.
• The Version property is displayed on the configuration page to help the user ensure they have installed the correct version of the DLL. This is simply a string so the format of the version is up to the implementation.
• The AllowRestart property is used with the batch management screen. It allows the DLL developer to indicate if Finalize activity can be restarted following an error. This can be useful for scenarios where the destination for the exported data is not 100% reliable.
• For each configuration option, you will need a getter and setter.

Other methods in ILibraryManagerScript2 are reserved for FileHold use only. These should be implemented as stubs that return null.