Image
Cloning document schemas using Powershell
Some scientists clone cells, plants or even sheep. From time-to-time, FileHold administrators would like to clone objects in FileHold. The good news is that cloning a FileHold object is much simpler (and much less controversial) than cloning a living thing.
There are some objects like workflow templates or folders that offer a basic cloning option directly in the user interface and others like document schemas that do not. The good news is that the following techniques can be used with both and have the benefit of eliminating a lot of manual effort when a large number of objects need to be cloned or when the clone requires a number of changes from the original.
For the purposes of this article we will clone a document schema as there is no manual cloning option and typically the clones will require more modifications than just a new name. We have already established a pattern of using Powershell for backend administrative tasks that use the API and that is a great way to clone a document schema.
A common scenario in FileHold to is to create an email schema that will be used to apply automatic data extraction rules and then have its schema changed to something more relevant like a project document or general client correspondence. Since the fields necessary to hold things like email addresses or the email subject will be the same for every document, the Email schema can be considered a base schema for the others. A Powershell command like the following can create two new schemas with all the existing metadata fields and other settings from the email schema.
'Project', 'Client correspondence'|Copy-FileHoldSchema -SourceName 'Email'
There are a number of other Powershell examples below that cover the basics of using Powershell with FileHold, but let’s review what this one intends to do. The pipe or vertical bar (|) character separates two Powershell statements. The first creates a list of names and the second executes a script called Copy-FileHoldSchema. The advantage of this approach is the list of new schema names could come from a CSV file, database or anything else accessible to a Powershell command.
The name of the schema that will be used as the source of the base information is provide in the SourceName parameter and if all you want to do is make a copy, download the code at the end of the article. However, there are tweaks possible if you would like to further automate the creation process.
Fair warning, details about the FileHold API and the workings of Powershell follow. The faint of heart can safely step away now.
There are three main API methods that are useful for cloning document schema and they are all part of the DocumentSchemaManager service:
• GetDocumentSchemaOverviewList – gets a list of all document schemas configured in the system.
• GetDocumentSchema – get a complete schema object given its internal ID.
• AddDocumentSchema – given a document schema object, well, you get the picture.
This service and these methods are all documented in the FileHold API reference guide included in the ApiKit with every system and the current version is online at http://api.filehold.com.
When the script first gets started, it will check to make sure the source name exists as a document schema.
$schemas = (DocumentSchemaManager).GetDocumentSchemasOverviewList()
$sourceId = $schemas.Where( { $_.Name -ieq $SourceName } ).DocumentSchemaId
When $sourceId is greater than zero, we have a valid schema name and the ID we will need to get the full option which we will do below.
$sourceSchema = (DocumentSchemaManager).GetDocumentSchema( $sourceId )
What I would like to do is just create a copy of $sourceSchema and call it $destinationSchema or something like that, but that presents a bit of a challenge in Powershell. $sourceSchema is actually just a reference and I have not been able to find any way to copy the referenced object to a new object without doing it piece by piece. This is necessary if your code will clone more than one schema at a time.
Feel free to speak up if you know a way to do this, but for now, we are just going to copy a couple of bits of information that we do not want to lose. Depending on how simple or complex your clone will be, you may need to do more. If you need a lot, you could just call GetDocumentSchema again. It’s a bit kludgy but it works, and you can complain to the Powershell gods if you dislike not having a built-in deep copy method as much as I do.
$backupName = $sourceSchema.Name
$backupDescription = $sourceSchema.Description
The process of creating the clone is now as simple or complex as you want. For our example, we will modify the description for each clone by incorporating the source schema details, but you could modify any fields you choose like the list of events. Let’s assume our list of new schema names come to us in $DestinationName.
$sourceSchema.Name = $DestinationName
$sourceSchema.Description = "$backupDescription -- copied from '$backupName' ($($sourceSchema.Id))"
$null = (DocumentSchemaManager).AddDocumentSchema( $sourceSchema )
Note the last assignment to $null is to throw away the new ID for the schema we just created as it is not needed for the cloning process. You may also note in the full sample code that I call GetDocumentSchemasOverviewList twice. This is to protect me from accidentally adding the same destination name twice, but if you know your list of input names is perfect, you could skip this.
The downloaded code is provided as a basis for modification. If you would like to run it directly you will need to set the execution policy on your workstation suitable for your organization and running unsigned code. For example, Set-Executionpolicy -ExecutionPolicy Bypass.
Russ Beinder is the Chief Technology Officer at FileHold. He is an entrepreneur, a seasoned business analyst, computer technologist and a certified Project Management Professional (PMP). For over 35 years he has used computer technology to help organizations solve business problems.