Using custom destinations

As an example a custom destination type is created that stores documents on the server file system.

Use case:

  • Use an existing document type, or create a new one.
  • You create a new library, which stores documents on the file system. This library must be registered as custom destination type.

Complete these steps:

  1. Create a new library tccomdomdestfs with this content: 
    domain	tcmcs.str256m	g.path
	domain	tcmcs.str256m	g.folder
	domain	tcmcs.str256m	g.filenames(1) based
	domain	tcmcs.str256m	g.displaynames(1) based
	long			g.nr.files


function extern long distribution.new(ref string o.error.msg)
{
	FunctionUsage
	Expl:	Initializes distribution.
	Pre:	-
	Post:	-
	Input:	-
	Output:	- o.error.msg	- The error message if anything went wrong
	Return: 0 if OK, otherwise the error code
	EndFunctionUsage

	g.path = bse.dir$() & "/dom/"

	g.nr.files = 0

	return(0)
}

function extern long distribution.set.document.file(
			const	string	i.filename,
			const	string	i.displayname,
			const	string	i.mime.type,
			ref string o.error.msg)
{
	FunctionUsage
	Expl:	Sets the document file to be distributed.
	Pre:	-
	Post:	-
	Input:	- i.filename	- The file name which contains the document file
		- i.displayname	- The name to be displayed in the distribution
		- i.mime.type	- The MIME type of the document
	Output:	- o.error.msg	- The error message if anything went wrong
	Return: 0 if OK, otherwise the error code
	EndFunctionUsage

	store.file(i.filename, i.displayname)
	
	return(0)
}

function extern long distribution.add.attachment(
			const	string	i.filename,
			const	string	i.displayname,
			const	string	i.mime.type,
			ref string o.error.msg)
{
	FunctionUsage
	Expl:	Adds additional attachment files to the distribution.
	Pre:	-
	Post:	-
	Input:	- i.filename	- The file name which contains the attachment
		- i.displayname	- The name to be displayed in the distribution
		- i.mime.type	- The MIME type of the document
	Output:	- o.error.msg	- The error message if anything went wrong
	Return: 0 if OK, otherwise the error code
	EndFunctionUsage

	store.file(i.filename, i.displayname)
	
	return(0)
}

function extern long distribution.set.destination(
			const	string	i.address,
			ref string o.error.msg)
{
	FunctionUsage
	Expl:	Sets the destination address.
	Pre:	-
	Post:	-
	Input:	- i.address	- The address of the destination
	Output:	- o.error.msg	- The error message if anything went wrong
	Return: 0 if OK, otherwise the error code
	EndFunctionUsage

	g.folder = i.address

	return(0)
}

function extern long distribution.send(ref string o.error.msg)
{
	FunctionUsage
	Expl:	Stores the received document and attachment on the filesystem
		in the subfolder defined in destination address.
	Pre:	-
	Post:	-
	Input:	-
	Output:	- o.error.msg	- The error message if anything went wrong
	Return: 0 if OK, otherwise the error code
	EndFunctionUsage

	domain	tcmcs.str256m	path
	long	i
	long	ret

	path = strip$(g.path) & strip$(g.folder)
	ret = mkdir(path)

	for i = 1 to g.nr.files
		ret = file.cp(g.filenames(1, i), path & "/" & g.displaynames(1, i))
		if ret < 0 then
			o.error.msg = "Failed to store file " & g.displaynames(1, i)
			return (ret)
		endif
	endfor

	return (0)
}

function extern long distribution.end(ref string o.error.msg)
{
	FunctionUsage
	Expl:	Finalizes a distribution.
	Pre:	-
	Post:	-
	Input:	-
	Output:	- o.error.msg - The error message if anything went wrong
	Return: 0 if OK, otherwise the error code
	EndFunctionUsage

	g.nr.files = 0
	free.mem(g.filenames)
	free.mem(g.displaynames)

	return(0)
}

function extern long distribution.cancel(ref string o.error.msg)
{
	FunctionUsage
	Expl:	Cancels and removes a distribution.
	Pre:	-
	Post:	-
	Input:	-
	Output:	- o.error.msg - The error message if anything went wrong
	Return: 0 if OK, otherwise the error code
	EndFunctionUsage

	return(distribution.end(o.error.msg))
}

function store.file(
			const	string	i.filename,
			const	string	i.displayname)
{
	domain	tcmcs.str256m	str	fixed

	INC(g.nr.files)
	alloc.mem(g.filenames, len(str), g.nr.files)
	g.filenames(1, g.nr.files) = strip$(i.filename)
	alloc.mem(g.displaynames, len(str), g.nr.files)
	g.displaynames(1, g.nr.files) = strip$(i.displayname)
}
  2. Start the Custom Destination Types (ttrpi2554m000) session and create a custom destination type with these properties:
    • Description: Filesystem Destination
    • Custom Destination Type: FILESYSTEM
    • Library: tccomdomdestfs
  3. Use this custom destination type to send the document to the file system. How to do this depends on your receiver type:
    • If you use receiver type Contact, Business Partner, or Employee, start the Document Management Output Details (tccom6170m000) session. Add a record for your receiver type, your document type, destination type 'Custom', and custom destination type 'FILESYSTEM'.
      Note: The Custom Destination Type field is initially hidden in the Document Management Output Details (tccom6170m000) session. You can unhide the field in the Personalization Workbench. To start this workbench, click the gear icon in the session's toolbar and select Personalize Form.
    • If you use receiver type User, start the User Document Type Settings (ttrpi2551m100) session. Open the details of a specific user or all users and your specific document type. Add a record with destination type 'Custom' and custom destination type 'FILESYSTEM'.
  4. Print to the Document Output Management device and view the result. Note that the documents are stored on the file system in this directory: <bse_path>/dom.