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.
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 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:

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

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

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

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

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.

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.

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.

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)