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
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 semanticsThe IDocumentInfo.
- 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[])
|
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. |
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 parameterallowedReturnTypes
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 = 0LoadMetaData(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.