LiveDocx MailMerge API

MailMerge Constructor

  • Description:

    Creates a new instance of the MailMerge class.

  • Syntax: 
    public MailMerge();
  • Introduced:

    1.0

  • Demo:

    This sample creates a new instance of the LiveDocx MailMerge class. localhost.MailMerge is the reference to the LiveDocx API:

    localhost.MailMerge livedocx = new localhost.MailMerge();

CreateDocument

  • Description:

    Merges the field data into the template. If no field data are specified, the template will be used as the document.

  • Syntax: 
    public void CreateDocument()
  • Introduced:

    1.0

  • Exceptions:

    Throws an exception, if no template specified.

    Throws an exception, if creation fails.

DeleteTemplate

  • Description:

    Deletes a template from the server.

  • Syntax: 
    public void DeleteTemplate(string filename)
  • Introduced:

    1.0

  • Arguments:
    Value Type Description
    filename string The filename of the template to be deleted.
  • Exceptions:

    System.ArgumentException

    System.ArgumentNullException

    System.IO.DirectoryNotFoundException

    System.IO.IOException

    System.NotSupportedException

    System.IO.PathTooLongException

    System.UnauthorizedException

DownloadTemplate

  • Description:

    Returns a template.

  • Syntax: 
    public string DownloadTemplate(string filename)
  • Introduced:

    1.0

  • Arguments:
    Value Type Description
    filename string The filename of the template to be downloaded.
  • Return value:

    String. The template is returned as a Base64 encoded string.

  • Exceptions:

    System.ArgumentNullException

    System.ArgumentException

    System.IO.DirectoryNotFoundException

    System.IO.IOException

    System.NotSupportedException

    System.IO.PathTooLongException

    System.UnauthorizedException

    System.IO.FileNotFoundException

    System.Security.SecurityException

GetAllBitmaps

  • Description:

    Returns a string array containing encoded bitmaps—one for every page.

  • Syntax: 
    public string[] GetAllBitmaps(int zoomFactor, string format)
  • Introduced:

    1.2

  • Arguments:
    Value Type Description
    zoomFactor int The size of the images in percent relative to the original page size. The value of the zoom factor ranges between 10 and 400.
    format string The format of the images returned by this method. The supported formats can be obtained by calling GetImageFormats().
  • Return value:

    string[]. An array of Base64 string encoded byte arrays containing the bitmaps of all pages.

GetAllMetafiles

  • Description:

    Returns a string array containing encoded metafiles—one for every page.

  • Syntax: 
    public string[] GetAllMetafiles()
  • Introduced:

    1.2

  • Return value:

    string[]. An array of Base64 string encoded byte arrays containing the bitmaps of all pages.

GetBitmaps

  • Description:

    Returns a string array containing encoded bitmaps for the specified pages.

  • Syntax: 
    public string[] GetBitmaps(int fromPage, int toPage,
                           int zoomFactor, string format)
  • Introduced:

    1.2

  • Arguments:
    Value Type Description
    fromPage int The lower-bound page number of the page range that should be return as images.
    toPage int The upper-bound page number of the page range that should be return as images.
    zoomFactor int The size of the images in percent relative to the original page size. The value of the zoom factor ranges between 10 and 400.
    format string The format of the images returned by this method. The supported formats can be obtained by calling GetImageFormats().
  • Return value:

    string[]. An array of Base64 string encoded byte arrays containing the metafiles (i.e. image files) of all pages.

GetBlockFieldNames

  • Description:

    Returns the field names inside of block.

  • Syntax: 
    public string[] GetBlockFieldNames()
  • Introduced:

    1.0

  • Return value:

    String[]. An array of strings containing the names of the fields inside the merge block.

  • Exceptions:

    Throws an exception, if no template specified.

GetBlockNames

  • Description:

    Returns the merge block names.

  • Syntax: 
    public string[] GetBlockNames()
  • Introduced:

    1.0

  • Return value:

    String[]. An array of strings containing the names of the merge blocks inside the template.

GetDocumentFormats

  • Description:

    Returns the formats which generated documents can be retrieved as.

  • Syntax: 
    public string[] GetDocumentFormats();
  • Introduced:

    1.0

  • Return value:

    string[]. An array of strings containing the names of all valid document types.

GetFieldNames

  • Description:

    Returns the field names.

  • Syntax: 
    public string[] GetFieldNames();
  • Introduced:

    1.0

  • Return value:

    string[]. An array of strings containing the names of all fields inside the current template.

GetFontNames

  • Description:

    Returns a list of all fonts on the respective LiveDocx server that can be used with the API.

  • Syntax: 
    public string[] GetFontNames();
  • Introduced:

    1.2

  • Return value:

    string[]. An array of strings containing the names of all supported fonts.

GetImageFormats

  • Description:

    Returns the formats which images, generated by GetAllBitmaps() and GetBitmaps(), can be retrieved as.

  • Syntax: 
    public string[] GetImageFormats();
  • Introduced:

    1.2

  • Return value:

    string[]. An array of strings containing the names of all valid image types.

GetMetafiles

  • Description:

    Returns a metafile (i.e. the image format) string array from the specified pages.

  • Syntax: 
    public string[] GetMetafiles(int fromPage, int toPage)
  • Introduced:

    1.0

  • Return value:

    string[]. An array of Base64 string encoded byte arrays containing the metafiles (i.e. image files) of the specified pages.

GetTemplateFormats

  • Description:

    Returns the accepted formats of template files.

  • Syntax: 
    public string[] GetTemplateFormats();
  • Introduced:

    1.0

  • Return value:

    string[]. An array of strings containing the names of all valid template types.

ListTemplates

  • Description:

    Returns an array of arrays that includes all templates with its properties.

  • Syntax: 
    public string[][] ListTemplates()
  • Introduced:

    1.0

  • Properties:
    Value Type Description
    Name string The filename of the template.
    Size string The size of the template in bytes.
    Created at string The creation date of the template in RFC1123 format.
    Modified at string The modification date of the template in RFC1123 format.
  • Return value:

    string[][]

  • Exceptions:

    System.ArgumentException

    System.ArgumentNullException

    System.IO.DirectoryNotFoundException

    System.IO.IOException

    System.IO.PathTooLongException

LogIn

  • Description:

    Log onto the web service.

  • Syntax: 
    public void LogIn(string username, string password)
  • Introduced:

    1.0

  • Arguments:
    Value Type Description
    username string This argument specifies the user name.
    password string This argument specifies the password.
  • Exceptions:

    Throws an exception, if the LogIn method fails.

  • Demo:

    This sample creates a new instance of the LiveDocx MailMerge class and calls the LogIn method:

    localhost.MailMerge livedocx = new localhost.MailMerge();
livedocx.LogIn("username", "password");

LogOut

  • Description:

    Log off the web service.

  • Syntax: 
    public LogOut();
  • Introduced:

    1.0

RetrieveDocument

  • Description:

    Returns the document in a specific format.

  • Syntax: 
    public string RetrieveDocument(string format)
  • Introduced:

    1.0

  • Arguments:
    Value Type Description
    DOC string Binary Microsoft Word DOC format
    DOCX string Binary Microsoft Word DOCX format
    HTML string XHTML 1.0 Transitional format
    PDF string Binary Adobe PDF format
    RTF string Microsoft Rich Text Format
    TXD string Binary TX Text Control format
    TXT string ANSI plain text
  • Return value:

    string. A Base64 encoded string that contains the document.

  • Exceptions:

    Throws an exception, if no template specified.

    Throws an exception, if the arguments are not valid.

    System.ArgumentNullException

  • Remarks:

    HTML is only available in 1.2 or newer.

SetBlockFieldValues

  • Description:

    Sets the application field values for a block.

  • Syntax: 
    public void SetBlockFieldValues(string blockName,
string[][] blockFieldValues)
  • Introduced:

    1.0

  • Arguments:
    Value Type Description
    blockName string The name of the merge block in the template.
    blockFieldValues String[][] An array of string arrays that contain the merge field data of the specified block.
  • Exceptions:

    System.ArgumentNullException

SetFieldValues

  • Description:

    Sets the application field values.

  • Syntax: 
    public void SetFieldValues(string[][] fieldValues)
  • Introduced:

    1.0

  • Arguments:
    Value Type Description
    fieldValues string[][] An array of string arrays that contain the merge field data.
  • Exceptions:

    System.ArgumentNullException

  • Remarks:

    Starting from version 1.2, if the argument fieldValues contains more than one line of field values, CreateDocument() generates the according number of documents which are appended to each other. This is useful for scenarios such as label printing.

    Using templates that contain blocks and/or numbered lists may not always lead to the expected result, when creating multiple document in one run. Be sure to double-check the generated documents.

SetIgnoreSubTemplates

  • Description:

    Specifies whether INCLUDETEXT field should be merged.

  • Syntax: 
    public void SetIgnoreSubTemplates(bool ignore)
  • Introduced:

    1.1

  • Arguments:
    Value Type Description
    ignore bool A bool which determines whether INCLUDETEXT fields are merged. Setting this to true means all INCLUDETEXT fields in the template are ignored during the merge process. The default value is false.

SetLocalTemplate

  • Description:

    Specifies a local template that can be used for further processing.

  • Syntax: 
    public void SetLocalTemplate(string template, string format)
  • Introduced:

    1.0

  • Arguments:
    Value Type Description
    template string A Base64 string encoded representation of the template.
    format string The format of the template.
  • Possible template formats:
    Value Type Description
    DOC string Binary Microsoft Word DOC format
    DOCX string Binary Microsoft Word DOCX format
    RTF string Microsoft Rich Text Format
    TXD string Binary TX Text Control format
  • Exceptions:

    Throws an exception, if no template specified.

    System.ArgumentNullException

    System.ArgumentException

SetRemoteTemplate

  • Description:

    Specifies a server-side template that can be used for further processing.

  • Syntax: 
    public void SetRemoteTemplate(string filename)
  • Introduced:

    1.0

  • Arguments:
    Value Type Description
    filename string The name of the template that has been uploaded to the server.
  • Exceptions:

    Throws an exception, if no template specified.

    System.ArgumentException

    System.ArgumentNullException

    System.IO.DirectoryNotFoundException

    System.IO.IOException

    System.NotSupportedException

    System.IO.PathTooLongException

    System.UnauthorizedException

TemplateExists

  • Description:

    Checks whether a template exists on the LiveDocx server.

  • Syntax: 
    public bool TemplateExists(string filename)
  • Introduced:

    1.0

  • Return value:

    bool. It returns true, if the document has been found.

  • Exceptions:

    System.ArgumentException

    System.ArgumentNullException

    System.IO.DirectoryNotFoundException

    System.IO.IOException

    System.NotSupportedException

    System.IO.PathTooLongException

    System.UnauthorizedException

UploadTemplate

  • Description:

    Uploads a template to the server. This template will be stored on the LiveDocx server and can be used for merge processes.

  • Syntax: 
    public void UploadTemplate(string template, string filename)
  • Introduced:

    1.0

  • Arguments:
    Value Type Description
    template string A Base64 string encoded representation of the template.
    filename string The name of the template that will been saved to the server.
  • Exceptions:

    Throws an exception, if the template is not valid.

    System.ArgumentException

    System.ArgumentNullException

    System.IO.DirectoryNotFoundException

    System.IO.IOException

    System.NotSupportedException

    System.IO.PathTooLongException

    System.UnauthorizedException

LiveDocx Documentation