Interface IDocumentPlugin2

This is the API that needs to be implemented by document plugins - objects that provide the link between a document repository and SuperOffice NetServer

Namespace: SuperOffice.CRM.Documents

Assembly: SuperOffice.Plugins.dll

Syntax

public interface IDocumentPlugin2 : IPlugin

Remarks

A document plugin must support basic operations for storing and retrieving documents, according to keys it generates itself. Optionally, it can support locking, versions, and WebDAV access.

Locking and versioning, if supported, can be selected on a per-document basis - support for versioning does not have to imply that every document in the plugins' repository is versioned.

Custom GUI declaration is not part of this interface, since the various clients that exist, may have different ways of declaring or implementing custom user interfaces. A document plugin that wants to implement a custom GUI should additionally implement the ICustomUIProvider or other (future) GUI-declaration interface, thereby making it possible to add GUI options in the future, without changing this basic document plugin interface.

NetServer will attempt to construct your object in two different ways:

1. With an IConfiguration parameter. This allows you to access config values and licenses without linking to SoCore/SoDatabase.

2. With no parameters. This is just the default constructor.

Implement the constructor that is most suitable for your plugin. Throw an exception from the constructor if your plugin does not want to be created. The exception is logged as Information, and your plugin will not be used.

Methods

CheckinDocument(IDocumentInfo, String[], String, String[])

Check in a currently checked-out document

Declaration

ReturnInfo CheckinDocument(IDocumentInfo documentInfo, string[] allowedReturnTypes, string versionDescription, string[] versionExtraFields)

Parameters

Type	Name	Description
IDocumentInfo	documentInfo	Fully populated document metadata, used to identify the document. Usefully contains ExternalReference and Filename properties.
String[]	allowedReturnTypes	Array of names of allowed return types; if this array is empty then no limits are placed on return type. ("None", "Message", "SoProtocol", "CustomGUI", "Other")
String	versionDescription	Version description.
String[]	versionExtraFields	Extra fields

Returns

Type	Description
ReturnInfo	Return value, indicating success/failure and any optional processing to be performed

Remarks

If the document plugin supports locking and the requesting user is the one who checked out the document, then the last-saved content by that user should become the new publicly visible content, and the checkout state should be reset. Calls by other users should result in failure and no state change.

If the document plugin does not support locking or versioning, then this call should perform no action.

CheckoutDocument(IDocumentInfo, String[])

Check out the document for editing

Declaration

ReturnInfo CheckoutDocument(IDocumentInfo documentInfo, string[] allowedReturnTypes)

Parameters

Type	Name	Description
IDocumentInfo	documentInfo	Fully populated document metadata, used to identify the document. Usefully contains ExternalReference and Filename properties.
String[]	allowedReturnTypes	Array of names of allowed return types; if this array is empty then no limits are placed on return type. ("None", "Message", "SoProtocol", "CustomGUI", "Other")

Returns

Type	Description
ReturnInfo	Return value, indicating success/failure and any optional processing to be performed

Remarks

A document plugin that supports versioning may internally prepare to receive new content and prepare a new internal version, but a subsequent GetVersionList(IDocumentInfo) call should not show this version – not until CheckinDocument(IDocumentInfo, String[], String, String[]) has been called.

After the completion of this call, the document is in checked out state and GetCheckoutState(IDocumentInfo) should return “Own” as the status. SaveDocumentFromStream(IDocumentInfo, String[], Stream) calls on behalf of other users should fail, as should CheckoutDocument(IDocumentInfo, String[]) and CheckinDocument(IDocumentInfo, String[], String, String[]) calls on behalf of other users.

If the document plugin does not support locking or versioning, then this call should perform no action.

CreateDefaultDocumentTemplate(Int32, IDocumentTemplateInfo)

Create a default document based on the given documentType. Called when creating a new template.

Declaration

TemplateInfo CreateDefaultDocumentTemplate(int documentTypeKey, IDocumentTemplateInfo documentTemplateInfo)

Parameters

Type	Name	Description
Int32	documentTypeKey	Id for a document type. 0 if plugin does not use document types.
IDocumentTemplateInfo	documentTemplateInfo	Document template info

Returns

Type	Description
TemplateInfo	Template info object, with MimeType and Extref/Filename for new template filled in. These values are written to the template record by NetServer. Other fields like TemplateInfo.PluginId or TemplateInfo.Name are ignored in the result. The plugin cannot alter these. Return NULL if no change, or if no blank document created.

Remarks

A document plugin must support basic operations for storing and retrieving documents, according to keys it generates itself. Optionally, it can support locking, versions, and WebDAV access.

Locking and versioning, if supported, can be selected on a per-document basis - support for versioning does not have to imply that every document in the plugins' repository is versioned.

Custom GUI declaration is not part of this interface, since the various clients that exist, may have different ways of declaring or implementing custom user interfaces. A document plugin that wants to implement a custom GUI should additionally implement the ICustomUIProvider or other (future) GUI-declaration interface, thereby making it possible to add GUI options in the future, without changing this basic document plugin interface.

NetServer will attempt to construct your object in two different ways:

1. With an IConfiguration parameter. This allows you to access config values and licenses without linking to SoCore/SoDatabase.

2. With no parameters. This is just the default constructor.

Implement the constructor that is most suitable for your plugin. Throw an exception from the constructor if your plugin does not want to be created. The exception is logged as Information, and your plugin will not be used.

See Also

GetSupportedDocumentTypesForDocumentTemplates()

CreateDocument(IDocumentInfo, ref String, String[], String, String[])

Create an empty document file in the repository, returning the external reference that uniquely identifies the document in the repository.

Declaration

string CreateDocument(IDocumentInfo incomingInfo, ref string fileName, string[] extraFields, string versionDecription, string[] versionExtraFields)

Parameters

Type	Name	Description
IDocumentInfo	incomingInfo	SuperOffice metadata for the document, including the document Id and locking/versioning sematics requested for this document.
String	fileName	Suggested file name/document name. The document plugin must validate this name and amend it if needed (this is a ref parameter). If the name needs to be changed for any reason, a new and valid name must be generated by the plugin, and returned to the caller. NetServer will update the document record's Name field with the new filename.
String[]	extraFields	Plugin-dependent metadata for the document as a whole. The usual caveats apply, i.e., there may be name/value pairs in the parameter that belong to other parts of the system. Failure to recognize a name is not an error.
String	versionDecription	Description of the initial version, if versioning is supported and enabled for the document.
String[]	versionExtraFields	Plugin-dependent metadata for the initial version

Returns

Type	Description
String	The external reference that identifies this document. This return value is written to the document record's ExtRef field.

Remarks

Execution of this method should result in the creation of a document instance in the underlying repository, with empty content. If locking is supported, the status should be 'Checked-out'; the document should not be visible to other users. If locking is not supported, a zero-length content should be the result.

All metadata should be saved, an externalReference key should be assigned, and the file name/document name validated and reserved.

Notes on semantics
The IDocumentInfo. property is used to specify the locking/versioning semantics requested and implemented for a document. Semantics actually implemtned will be the lowest of what is requested and what is supported. Thus, a document may request semantics even if versioning is optionally supported by the document plugin, and in that case no versioning or locking should be performed.

On creation, if locking and/or versioning is supported and requested, then the document stream should be saved to a temporary area. Calls to GetDocumentStream should return an empty stream until the first call to CheckinDocument has succeeded. The result of that Checkin call will be the base version (version 1).

Locking semantics are set on creation and cannot be changed later.

NetServer will typically call several plugin functions create a new document like this:

• plugin.LoadDocumentTemplateStream(IDocumentTemplateInfo, String)
• (NetServer saves document template stream to temp file and runs tag substitution on the file, replacing <name> with company name, etc.)
• plugin.CreateDocument - creates empty file in repository.
• plugin.SaveDocumentFromStream(IDocumentInfo, String[], Stream)(temp-file) - moves temp file into repository, replacing the empty file.

DeleteDocument(IDocumentInfo, String[])

Delete a document, all versions and all metadata from the repository

Declaration

ReturnInfo DeleteDocument(IDocumentInfo documentInfo, string[] allowedReturnTypes)

Parameters

Type	Name	Description
IDocumentInfo	documentInfo	Fully populated document metadata, used to identify the document. Usefully contains ExternalReference and Filename properties.
String[]	allowedReturnTypes	Array of names of allowed return types; if this array is empty then no limits are placed on return type. ("None", "Message", "SoProtocol", "CustomGUI", "Other")

Returns

Type	Description
ReturnInfo	Return value, indicating success/failure and any optional processing to be performed

Remarks

A document plugin must support basic operations for storing and retrieving documents, according to keys it generates itself. Optionally, it can support locking, versions, and WebDAV access.

Locking and versioning, if supported, can be selected on a per-document basis - support for versioning does not have to imply that every document in the plugins' repository is versioned.

Custom GUI declaration is not part of this interface, since the various clients that exist, may have different ways of declaring or implementing custom user interfaces. A document plugin that wants to implement a custom GUI should additionally implement the ICustomUIProvider or other (future) GUI-declaration interface, thereby making it possible to add GUI options in the future, without changing this basic document plugin interface.

NetServer will attempt to construct your object in two different ways:

1. With an IConfiguration parameter. This allows you to access config values and licenses without linking to SoCore/SoDatabase.

2. With no parameters. This is just the default constructor.

Implement the constructor that is most suitable for your plugin. Throw an exception from the constructor if your plugin does not want to be created. The exception is logged as Information, and your plugin will not be used.

DeleteDocumentTemplate(IDocumentTemplateInfo, String[])

Delete a document template, all language variations and all metadata from the repository

Declaration

ReturnInfo DeleteDocumentTemplate(IDocumentTemplateInfo documentTemplateInfo, string[] allowedReturnTypes)

Parameters

Type	Name	Description
IDocumentTemplateInfo	documentTemplateInfo	Fully populated document metadata, used to identify the document. Usefully contains ExternalReference and Filename properties.
String[]	allowedReturnTypes	Array of names of allowed return types; if this array is empty then no limits are placed on return type. ("None", "Message", "SoProtocol", "CustomGUI", "Other")

Returns

Type	Description
ReturnInfo	Return value, indicating success/failure and any optional processing to be performed

Remarks

A document plugin must support basic operations for storing and retrieving documents, according to keys it generates itself. Optionally, it can support locking, versions, and WebDAV access.

Locking and versioning, if supported, can be selected on a per-document basis - support for versioning does not have to imply that every document in the plugins' repository is versioned.

Custom GUI declaration is not part of this interface, since the various clients that exist, may have different ways of declaring or implementing custom user interfaces. A document plugin that wants to implement a custom GUI should additionally implement the ICustomUIProvider or other (future) GUI-declaration interface, thereby making it possible to add GUI options in the future, without changing this basic document plugin interface.

NetServer will attempt to construct your object in two different ways:

1. With an IConfiguration parameter. This allows you to access config values and licenses without linking to SoCore/SoDatabase.

2. With no parameters. This is just the default constructor.

Implement the constructor that is most suitable for your plugin. Throw an exception from the constructor if your plugin does not want to be created. The exception is logged as Information, and your plugin will not be used.

DeleteDocumentTemplateLanguage(IDocumentTemplateInfo, String, String[])

Delete a specific language variation from the document template

Declaration

ReturnInfo DeleteDocumentTemplateLanguage(IDocumentTemplateInfo documentTemplateInfo, string languageCode, string[] allowedReturnTypes)

Parameters

Type	Name	Description
IDocumentTemplateInfo	documentTemplateInfo	Fully populated document template metadata used to identity the template.
String	languageCode	The language variation to delete
String[]	allowedReturnTypes	Array of names of allowed return types.

Returns

Type	Description
ReturnInfo	Return value, indicating success/failure and any optional processing to be performed

Remarks

A document plugin must support basic operations for storing and retrieving documents, according to keys it generates itself. Optionally, it can support locking, versions, and WebDAV access.

Locking and versioning, if supported, can be selected on a per-document basis - support for versioning does not have to imply that every document in the plugins' repository is versioned.

Custom GUI declaration is not part of this interface, since the various clients that exist, may have different ways of declaring or implementing custom user interfaces. A document plugin that wants to implement a custom GUI should additionally implement the ICustomUIProvider or other (future) GUI-declaration interface, thereby making it possible to add GUI options in the future, without changing this basic document plugin interface.

NetServer will attempt to construct your object in two different ways:

1. With an IConfiguration parameter. This allows you to access config values and licenses without linking to SoCore/SoDatabase.

2. With no parameters. This is just the default constructor.

Implement the constructor that is most suitable for your plugin. Throw an exception from the constructor if your plugin does not want to be created. The exception is logged as Information, and your plugin will not be used.

ExecuteDocumentCommand(IDocumentInfo, String, String[], String, String[])

Execute a custom command on a specified document and version

Declaration

ReturnInfo ExecuteDocumentCommand(IDocumentInfo documentInfo, string versionId, string[] allowedReturnTypes, string command, params string[] additionalData)

Parameters

Type	Name	Description
IDocumentInfo	documentInfo	Document info from the SuperOffice database
String	versionId	Version identifier, blank implies 'latest' version
String[]	allowedReturnTypes	Array of names of allowed return types; if this array is empty then no limits are placed on return type.
String	command	Command name, taken from an earlier call to GetDocumentCommands(IDocumentInfo, String[]) or any other command name that is understood by the provider. 'Private' commands that are not declared in GetDocumentCommands but are known to the authors of custom GUI code or OK.
String[]	additionalData	Array of strings containing whatever additional data the command may need. This parameter is intended for authors of more complex custom GUI's and works as a tunnel between the ultimate client and the document plugin. Standard GUI made by SuperOffice, such as a context menu connected to a document item in an archive, will not populate this member. It is strongly suggested that the convention of using name=value for each string array element be followed here.

Returns

Type	Description
ReturnInfo	Return value object, specifying failure or success plus any optional, additional processing to be triggered

Remarks

This command is called when the user chooses an action item from a dropdown/context menu. It is also reflected in the DocumentAgent service interface, so that custom GUI’s and external code can directly execute document plugin commands; this is useful if a plugin also has some corresponding custom GUI that needs to execute commands depending on user interaction.

The parameter allowedReturnTypes can be used by clients to hint to the plugin what kind of return value processing is available. For instance, a mobile client might only offer None and Message, and this information can be used by the document plugin to adapt the processing of a command, if it wants to (for instance, use default values instead of triggering some more advanced workflow).

The command is obtained from the GetDocumentCommands(IDocumentInfo, String[]) method.

Exists(IDocumentInfo)

Determine if the document exists in the repository

Declaration

bool Exists(IDocumentInfo documentInfo)

Parameters

Type	Name	Description
IDocumentInfo	documentInfo	Document info used by the document plugin

Returns

Type	Description
Boolean	true if the document exists in the repository, otherwise false

Remarks

The plugin should declare, through the FastExists property, whether this call is highly efficient or not. If it is efficient, then document archive providers and similar code will call it when populating an archive, otherwise not.

GetCheckoutState(IDocumentInfo)

Get the checkout state of a document

Declaration

CheckoutInfo GetCheckoutState(IDocumentInfo documentInfo)

Parameters

Type	Name	Description
IDocumentInfo	documentInfo	Fully populated document metadata, used to identify the document. Usefully contains ExternalReference and Filename properties.

Returns

Type	Description
CheckoutInfo	Object that describes the checkout state of the document

Remarks

This API is called from inside document archive providers if the plugin has declared that it supports fast fetching of this attribute. If the document plugin does not support locking or versioning, then the return value should have state NotCheckedOut, associate id 0 and blank name.

GetDocumentCommands(IDocumentInfo, String[])

Get a list of custom commands, applicable to a specific document. Note that commands related to standard locking and versioning operations have their own API calls and are not 'custom commands' in this sense.

Declaration

CommandInfo[] GetDocumentCommands(IDocumentInfo documentInfo, string[] allowedReturnTypes)

Parameters

Type	Name	Description
IDocumentInfo	documentInfo	Document info from the SuperOffice database
String[]	allowedReturnTypes	Array of names of allowed return types; if this array is empty then no limits are placed on return type.

Returns

Type	Description
CommandInfo[]	Array of command descriptions. If there are no custom commands available, an empty array should be returned.

Remarks

This API is called before a menu, task button or other GUI item that gives access to document-specific commands is shown. It is used to populate the GUI with available commands for a particular document, the results are not cached by the GUI.

Depending on the return type indicated in the command, the command might be filtered by GUI. More information can be found in the CommandInfo topic.

GetDocumentIdFromPath(String)

Map a file path to a document. Return 0 if the plugin cannot map the path.

Declaration

int GetDocumentIdFromPath(string documentPathAndName)

Parameters

Type	Name	Description
String	documentPathAndName	"c:\path\to\a-document.docx"

Returns

Type	Description
Int32	Document id that matches, or 0 if no match

Remarks

A document plugin must support basic operations for storing and retrieving documents, according to keys it generates itself. Optionally, it can support locking, versions, and WebDAV access.

Locking and versioning, if supported, can be selected on a per-document basis - support for versioning does not have to imply that every document in the plugins' repository is versioned.

Custom GUI declaration is not part of this interface, since the various clients that exist, may have different ways of declaring or implementing custom user interfaces. A document plugin that wants to implement a custom GUI should additionally implement the ICustomUIProvider or other (future) GUI-declaration interface, thereby making it possible to add GUI options in the future, without changing this basic document plugin interface.

NetServer will attempt to construct your object in two different ways:

1. With an IConfiguration parameter. This allows you to access config values and licenses without linking to SoCore/SoDatabase.

2. With no parameters. This is just the default constructor.

Implement the constructor that is most suitable for your plugin. Throw an exception from the constructor if your plugin does not want to be created. The exception is logged as Information, and your plugin will not be used.

GetDocumentProperties(IDocumentInfo, String[])

Get the values of certain properties, for a given document

Declaration

Dictionary<string, string> GetDocumentProperties(IDocumentInfo documentInfo, string[] requestedProperties)

Parameters

Type	Name	Description
IDocumentInfo	documentInfo	Document record with filename, extref and primary key (document id).
String[]	requestedProperties	Array of property strings, for which values are requested

Returns

Type	Description
Dictionary<String, String>	Dictionary of key=value pairs, where the key is one of the requested property strings, and the value is the value of that property for the given document.

Remarks

Each document can have a number of properties associated with it. A set of standard properties is defined in the Constants.Properties class. Ideally, retrieving properties should be a lightweight operation.

Note that 'properties' are a one-way mechanism where the document plugin provides information about the document or certain aspects of it. This is not the same as document-specific metadata, which is handled by the LoadMetaData(IDocumentInfo) and SaveMetaData(IDocumentInfo, Dictionary<String, String>) methods.

GetDocumentTemplateLanguages(IDocumentTemplateInfo)

Get the list of languages supported by the given template, not including the default (blank) language.

Declaration

string[] GetDocumentTemplateLanguages(IDocumentTemplateInfo documentTemplateInfo)

Parameters

Type	Name	Description
IDocumentTemplateInfo	documentTemplateInfo	The template we are curious about

Returns

Type	Description
String[]	Array of ISO codes: ("en-US", "nb-NO", "fr")

Remarks

Used when populating the dropdown list in the admin client or the document dialog.

GetDocumentTemplateProperties(IDocumentTemplateInfo, String[])

Get the values of certain properties, for a given document template

Declaration

Dictionary<string, string> GetDocumentTemplateProperties(IDocumentTemplateInfo documentTemplateInfo, string[] requestedProperties)

Parameters

Type	Name	Description
IDocumentTemplateInfo	documentTemplateInfo	Document template record from the SuperOffice database
String[]	requestedProperties	Array of property strings, for which values are requested

Returns

Type	Description
Dictionary<String, String>	Dictionary of name=value pairs, where the name is one of the requested property strings, and the value is the value of that property for the given document.

Remarks

Each document can have a number of properties associated with it. A set of standard properties is defined in the Constants.Properties class. Ideally, retrieving properties should be a lightweight operation.

Note that 'properties' are a one-way mechanism where the document plugin provides information about the document or certain aspects of it. This is not the same as document-specific metadata, which is handled by the LoadMetaData(IDocumentInfo) and SaveMetaData(IDocumentInfo, Dictionary<String, String>) methods.

GetDocumentTemplateUrl(IDocumentTemplateInfo, Boolean, String)

Get a URL referring to the given document template

Declaration

string GetDocumentTemplateUrl(IDocumentTemplateInfo documentTemplateInfo, bool writeableUrl, string languageCode)

Parameters

Type	Name	Description
IDocumentTemplateInfo	documentTemplateInfo	The document template info from database
Boolean	writeableUrl	If true, then the request URL should allow the document editor to write content back to the repository; otherwise, a url that does not support writeback should be supplied if possible.
String	languageCode	Language variation on the template. May be ignored by the plugin, or used to keep language specific versions of the template.

Returns

Type	Description
String	URL that gives access to the template document. If the document plugin does not support URL access, then a blank string should be returned.

Remarks

Document plugins may support document access via URLs. This call is used to retrieve a url that will give the specified access to the document. This URL will be passed to the ultimate client (most probably a browser, but could be a text editor application), and control will not return to NetServer.

The string returned here should be a fully resolved URL that can be given directly to the editor application.

GetDocumentUrl(IDocumentInfo, String, Boolean)

Get a WebDAV-compliant URL referring to the given document

Declaration

string GetDocumentUrl(IDocumentInfo incomingInfo, string versionId, bool writeableUrl)

Parameters

Type	Name	Description
IDocumentInfo	incomingInfo	Fully populated document metadata, used to identify the document. Usefully contains ExternalReference and Filename properties.
String	versionId	Optional version identifier, blank implies 'latest' version
Boolean	writeableUrl	If true, then the request URL should allow the document editor to write content back to the repository; otherwise, a url that does not support writeback should be supplied if possible.

Returns

Type	Description
String	WebDAV-compliant URL that gives access to the document. If the document plugin does not support WebDAV access, then a blank string should be returned.

Remarks

Document plugins may support document access via WebDAV. This call is used to retrieve a WebDAV url that will give the specified access to the document. This URL will be passed to the ultimate client (most probably a text editor application), and control will not return to NetServer.

The string returned here should be a fully resolved URL that can be given directly to the editor application.

GetLength(IDocumentInfo, String)

Return the length of the physical document. This should be an efficient method

Declaration

long GetLength(IDocumentInfo documentInfo, string versionId)

Parameters

Type	Name	Description
IDocumentInfo	documentInfo	Document info used by the document plugin
String	versionId	Version identifier, blank implies 'latest' version

Returns

Type	Description
Int64	Physical document length in bytes - this should be the same as the length of the stream returned by the LoadDocumentStream method.

Remarks

A document plugin must support basic operations for storing and retrieving documents, according to keys it generates itself. Optionally, it can support locking, versions, and WebDAV access.

Locking and versioning, if supported, can be selected on a per-document basis - support for versioning does not have to imply that every document in the plugins' repository is versioned.

Custom GUI declaration is not part of this interface, since the various clients that exist, may have different ways of declaring or implementing custom user interfaces. A document plugin that wants to implement a custom GUI should additionally implement the ICustomUIProvider or other (future) GUI-declaration interface, thereby making it possible to add GUI options in the future, without changing this basic document plugin interface.

NetServer will attempt to construct your object in two different ways:

1. With an IConfiguration parameter. This allows you to access config values and licenses without linking to SoCore/SoDatabase.

2. With no parameters. This is just the default constructor.

Implement the constructor that is most suitable for your plugin. Throw an exception from the constructor if your plugin does not want to be created. The exception is logged as Information, and your plugin will not be used.

GetPluginCapabilities()

Get a list of capabilities (functionality) supported by this document plugin

Declaration

Dictionary<string, string> GetPluginCapabilities()

Returns

Type	Description
Dictionary<String, String>	Dictionary of name=value strings listing all known capabilities and their values

Remarks

The purpose of this call is to enable NetServer and clients to determine what functionality this plugin can offer. Plugins should populate the return array with all capabilities they know about. NetServer will call this API only once.

As an example of use, the Document archive provider inside NetServer will look at plugin capabilities, and read document properties as appropriate.

i.e. if “fast-lock-status=false”, then the archive provider will not call the IsCheckedOut(externalReference) function. Otherwise it will make the call (if the client has requested the appropriate column in the GUI), so that the user can see which documents are checked out.

String constants for capabilities are available in the Constants.Capabilities static class.

GetSupportedDocumentTypesForDocumentTemplates()

Get a list of supported document template types for this document plugin. May be empty.

Declaration

Dictionary<int, string> GetSupportedDocumentTypesForDocumentTemplates()

Returns

Type	Description
Dictionary<Int32, String>	An dictionary of key=display-name for supported document types for template. Empty dictionary if no document types supported.

Remarks

A document plugin must support basic operations for storing and retrieving documents, according to keys it generates itself. Optionally, it can support locking, versions, and WebDAV access.

Locking and versioning, if supported, can be selected on a per-document basis - support for versioning does not have to imply that every document in the plugins' repository is versioned.

Custom GUI declaration is not part of this interface, since the various clients that exist, may have different ways of declaring or implementing custom user interfaces. A document plugin that wants to implement a custom GUI should additionally implement the ICustomUIProvider or other (future) GUI-declaration interface, thereby making it possible to add GUI options in the future, without changing this basic document plugin interface.

NetServer will attempt to construct your object in two different ways:

1. With an IConfiguration parameter. This allows you to access config values and licenses without linking to SoCore/SoDatabase.

2. With no parameters. This is just the default constructor.

Implement the constructor that is most suitable for your plugin. Throw an exception from the constructor if your plugin does not want to be created. The exception is logged as Information, and your plugin will not be used.

GetTemplateExtension(IDocumentTemplateInfo)

Get the "extension" for the template, i.e., what the file extension would have been - to help identify the stream content format

Declaration

string GetTemplateExtension(IDocumentTemplateInfo documentTemplateInfo)

Parameters

Type	Name	Description
IDocumentTemplateInfo	documentTemplateInfo	Document template info: contains the extref/filename, template id, mime type

Returns

Type	Description
String	String equivalent to a file extension, for instance ".docx"

Remarks

Template documents are generally created in text editors and stored as files of some kind. The file extension indicates the kind of document - doc, docx, xls, txt, and so on. While the template may be stored inside the document repository as any kind of data byte collection, a concept akin to the file extension is still needed to help identify the document format, ahead of actually reading the template content.

GetVersionList(IDocumentInfo)

Get the list of current versions for the given document

Declaration

VersionInfo[] GetVersionList(IDocumentInfo documentInfo)

Parameters

Type	Name	Description
IDocumentInfo	documentInfo	Fully populated document metadata, used to identify the document. Usefully contains ExternalReference and Filename properties.

Returns

Type	Description
VersionInfo[]	Array of objects describing the existing, committed versions for this document

Remarks

The list should not include an “in-work” version, if the document is currently checked out – only versions visible and accessible to any authorized user.

If the document plugin does not support versioning, then this call should return an empty array.

LoadDocumentStream(IDocumentInfo, String)

Get document content as a stream. NetServer will read-to-end and close this stream.

Declaration

Stream LoadDocumentStream(IDocumentInfo incomingInfo, string versionId)

Parameters

Type	Name	Description
IDocumentInfo	incomingInfo	Fully populated document metadata, used to identify the document. Usefully contains ExternalReference and Filename properties.
String	versionId	Optional version identifier, blank implies 'latest' version

Returns

Type	Description
Stream	Document content stream

Remarks

It is up to the document plugin whether it can open a stream directly into the underlying repository, or whether it has to extract the document to some temporary area and then stream that – however, the fewer buffers the better.

LoadDocumentTemplateStream(IDocumentTemplateInfo, String)

Get the document template content as a stream. NetServer will read-to-end and close this stream

Declaration

Stream LoadDocumentTemplateStream(IDocumentTemplateInfo documentTemplateInfo, string languageCode)

Parameters

Type	Name	Description
IDocumentTemplateInfo	documentTemplateInfo	Document template info: contains the extref/filename, template id, mime type. TemplateInfo.Id = 0 when archiving mail messages.
String	languageCode	Language (en-US, nb-NO, etc) that the user is using in the user interface. Can be used to select language-specific templates.

Returns

Type	Description
Stream	Stream containing the template content for the appropriate language. Null if no suitable template content found in this plugin.

Remarks

Document templates may be stored in a repository, with or without special content tags. Because a document template does not have a corresponding document record within SuperOffice, there is no documentId to identify it.

This call is used by NetServer to retrieve a document template based on either an externalreference value stored in the corresponding doctmpl record, or the Id of the doctmpl record itself. The document plugin is free to use either method of identification.

Mail templates are passed in using extref = "filename=xyz&allowPersonal=1" and docTemplateId = 0

LoadMetaData(IDocumentInfo)

Retrieve metadata owned by the plugin/repository, related to one document (excluding version-dependent metadata)

Declaration

Dictionary<string, string> LoadMetaData(IDocumentInfo documentInfo)

Parameters

Type	Name	Description
IDocumentInfo	documentInfo	Contains extref and primary key, filename of the document.

Returns

Type	Description
Dictionary<String, String>	Array of name=value strings, each representing one key and one value. The same convention is used here as in the GetPluginCapabilities() and GetDocumentProperties(IDocumentInfo, String[]) methods.

Remarks

A document plugin may consume and provide an arbitrary number of metadata fields. These are placed in a string, string dictionary, representing name/value pairs. This call should not retrieve metadata related to any particular version, only data related to the document as a whole.

The NetServer service call DocumentAgent.GetDocumentEntity will (among other things) result in a call to this API to populate the ExtraFields property of the document entity carrier. Note, however, that the carrier handed over to the client may contain other fields in addition to those supplied by the document plugin, since the extrafields mechanism is generic and there may be other metadata providers along the line.

Attribute names should be prefixed with the name of the document plugin, to maintain global uniqueness.

It is strongly suggested that non-string data be formatted according to the rules followed by the CultureDataFormatter class, to avoid problems when parsing dates and floating-point types between different cultures and platforms.

LoadVersionInfo(IDocumentInfo, String)

Retrieve metadata owned by the plugin/repository, related to one particular version of one document

Declaration

VersionInfo LoadVersionInfo(IDocumentInfo documentInfo, string versionId)

Parameters

Type	Name	Description
IDocumentInfo	documentInfo	Document info from the SuperOffice database
String	versionId	Version identifier, blank implies 'latest' version

Returns

Type	Description
VersionInfo	Fully populated version info structure

Remarks

A document plugin may consume and provide an arbitrary number of metadata fields. These are placed in a string, string dictionary, representing name/value pairs. This call should only retrieve metadata related to a version.

The NetServer service call DocumentAgent.GetDocumentEntity will (among other things) result in a call to this API to populate the VersionInfo property of the document entity carrier.

Attribute names should be prefixed with the name of the document plugin, to maintain global uniqueness.

It is strongly suggested that non-string data be formatted according to the rules followed by the CultureDataFormatter class, to avoid problems when parsing dates and floating-point types between different cultures and platforms.

To efficiently retrieve information about all versions, use the GetVersionList(IDocumentInfo) method, instead of iterating over this method.

RenameDocument(IDocumentInfo, String)

Rename a document in the repository

Declaration

string RenameDocument(IDocumentInfo documentInfo, string suggestedNewName)

Parameters

Type	Name	Description
IDocumentInfo	documentInfo	Fully populated document metadata, used to identify the document. Usefully contains ExternalReference and Filename properties.
String	suggestedNewName	Suggested new document name

Returns

Type	Description
String	Actual new document name, limited to 254 characters

Remarks

The document name should be changed from the existing to the new name. However, if the new name is not valid (or collides with an existing name of some other document), then the plugin should amend the name to a valid one and return it, instead of throwing an exception.

SaveDocumentFromStream(IDocumentInfo, String[], Stream)

Save the stream as the document content in the repository; depending on the state, this may imply creating a temporary save pending a final checkin, or an immediately visible result.

Declaration

ReturnInfo SaveDocumentFromStream(IDocumentInfo incomingInfo, string[] allowedReturnTypes, Stream content)

Parameters

Type	Name	Description
IDocumentInfo	incomingInfo	Incoming document metadata, used to identify the document. Metadata changes are not to be checked or saved by this operation - only the document stream is saved.
String[]	allowedReturnTypes	Array of names of allowed return types; if this array is empty then no limits are placed on return type. ("None", "Message", "SoProtocol", "CustomGUI", "Other")
Stream	content	Document content, a binary stream about which nothing is assumed. The document plugin should read-to-end and close this stream.

Returns

Type	Description
ReturnInfo	Return value, indicating success/failure and any optional processing to be performed

Remarks

An empty document must have been created in the repository with CreateDocument(IDocumentInfo, ref String, String[], String, String[]) before content can be streamed into it.

If the document is currently checked out to the current user, then the stream should be saved, but this call does not imply the automatic creation of a new version (visible to other users) or automatic checkin. However, it is an advantage if subsequent GetDocument calls made by the same user using the same key return the latest known content – while other users see the latest checked-in version.

If the plugin does not support locking and versioning (or such semantics are not requested, see below), then each call to this API overwrites any prior content completely and becomes the new, official content immediately. The Save operation should be atomic, and should not destroy earlier content if it fails.

If locking is supported and requested, the document is checked out and some other associate than the one that has checked it out calls this API, a failure message should be returned.

SaveDocumentTemplateStream(IDocumentTemplateInfo, Stream, String)

Create or update the document template contents. Usually used when uploading a file to a new document template.

Declaration

TemplateInfo SaveDocumentTemplateStream(IDocumentTemplateInfo templateInfo, Stream content, string languageCode)

Parameters

Type	Name	Description
IDocumentTemplateInfo	templateInfo	Name, tooltip and mime type from the document template record in the database. The ExtRef/Filename may be set if this is an edit rather than an add.
Stream	content	Stream containing file content
String	languageCode	Language variation on the template. May be ignored by the plugin, or used to keep language specific versions of the template.

Returns

Type	Description
TemplateInfo	Template information with ExtRef/Filename and MimeType filled in. These values are saved in the DocTmpl record.

Remarks

A document plugin must support basic operations for storing and retrieving documents, according to keys it generates itself. Optionally, it can support locking, versions, and WebDAV access.

Locking and versioning, if supported, can be selected on a per-document basis - support for versioning does not have to imply that every document in the plugins' repository is versioned.

Custom GUI declaration is not part of this interface, since the various clients that exist, may have different ways of declaring or implementing custom user interfaces. A document plugin that wants to implement a custom GUI should additionally implement the ICustomUIProvider or other (future) GUI-declaration interface, thereby making it possible to add GUI options in the future, without changing this basic document plugin interface.

NetServer will attempt to construct your object in two different ways:

1. With an IConfiguration parameter. This allows you to access config values and licenses without linking to SoCore/SoDatabase.

2. With no parameters. This is just the default constructor.

Implement the constructor that is most suitable for your plugin. Throw an exception from the constructor if your plugin does not want to be created. The exception is logged as Information, and your plugin will not be used.

SaveMetaData(IDocumentInfo, Dictionary<String, String>)

Store/update plugin-dependent document metadata in the repository

Declaration

void SaveMetaData(IDocumentInfo incomingInfo, Dictionary<string, string> pluginData)

Parameters

Type	Name	Description
IDocumentInfo	incomingInfo	SuperOffice metadata. Note that the plugin is not responsible for storing this data; however, it is allowed to look at it, in case it influences how the document is stored. However, it should always be possible to retrieve a document using the ExternalReference or DocumentId keys alone.
Dictionary<String, String>	pluginData	Name/value dictionary containing metadata

Remarks

This call is made when the document metadata should be stored, and is the complement of the LoadMetaData(IDocumentInfo) method. The document plugin should extract whatever elements it recognizes from the pluginData name/value dictionary. Failure to recognize an element should not cause an exception, as there may be other plugins along the line (not document plugins, but service-level field providers) that own the data. Likewise, absence of a value should be taken to imply “no change” to that value - not "delete".

It is strongly suggested that non-string data be formatted according to the rules followed by the CultureDataFormatter class, to avoid problems when parsing dates and floating-point types between different cultures and platforms.

SaveVersionInfo(IDocumentInfo, VersionInfo)

Store/update plugin-dependent document version metadata in the repository

Declaration

void SaveVersionInfo(IDocumentInfo documentInfo, VersionInfo versionInfo)

Parameters

Type	Name	Description
IDocumentInfo	documentInfo	Document that version is being saved on
VersionInfo	versionInfo	Version information to be saved

Remarks

This call is made when the document version metadata should be stored, and is the complement of the LoadVersionInfo(IDocumentInfo, String) method. The document plugin should extract whatever elements it recognizes from the pluginData name/value dictionary. Failure to recognize an element should not cause an exception, as there may be other plugins along the line (not document plugins, but service-level field providers) that own the data. Likewise, absence of a value should be taken to imply “no change” to that value - not "delete".

It is strongly suggested that non-string data be formatted according to the rules followed by the CultureDataFormatter class, to avoid problems when parsing dates and floating-point types between different cultures and platforms.

UndoCheckoutDocument(IDocumentInfo, String[])

Undo (abandon) a checkout

Declaration

ReturnInfo UndoCheckoutDocument(IDocumentInfo documentInfo, string[] allowedReturnTypes)

Parameters

Type	Name	Description
IDocumentInfo	documentInfo	Fully populated document metadata, used to identify the document. Usefully contains ExternalReference and Filename properties.
String[]	allowedReturnTypes	Array of names of allowed return types; if this array is empty then no limits are placed on return type. ("None", "Message", "SoProtocol", "CustomGUI", "Other")

Returns

Type	Description
ReturnInfo	Return value, indicating success/failure and any optional processing to be performed

Remarks

If the document plugin supports locking and the requesting user is the one who checked out the document, then any content saved since the checkout should be discarded and the checkout state reset. The content will be as before checkout.

Calls by other users should result in failure and no state change – except if the calling user has the right to force an undo

If the document plugin does not support locking or versioning, then this call should perform no action.

Extension Methods

EnumUtil.MapEnums<From, To>(From)

Converters.MapEnums<From, To>(From)