Generating Documents

An fDocs document can be requested by a user by running a URL with appropriate parameters. There are two ways of generating a document: either directly with no user interaction; or via an automatically generated form that will ask the user for more details before generating the document as required.

Both methods use a page in the fSeries web site. The direct method uses the fDGenerate.aspx page. The form method uses the fDSelect.aspx page. The parameters are similar as the fDSelect.aspx page passes all parameters on to fDGenerate.aspx for generation.

If you use the form method (fDSelect.aspx) and the system determines that there are no entries required the page will automatically redirect to fDGenerate.aspx and generate the document.

Parameters

Parameters may be passed in the form of a querystring (key=value&key=value&…) or an http form request.

DSD User Entries

You may pass any values that are required as “User Entries” in the templates associated DSD. The key is the user entry’s id. If you are using the automatic form method the values supplied mayeither be passed through to the generation or uses as default for the form entries.

Other Parameters

The page also takes a number of specific named parameters that identify how the document is to be generated:

fDTemplateLocation

The path, relative to the server’s published template path, of the template to be used.

This is optional as the full path may be included in the fDTemplateFile parameter.fDTemplateFileThe actual template to be used (including extension).

fDTemplateLocation and fDTemplateFile are combined to specify the template file to use, relative to the fSeries Published Path.fDFormatThe format(s) of the output. If only one is specified it is used without user input, otherwise the list overrides the configured list of available formats set in fAdmin.

The available formats may be “wordml” for the same format as the template, or any of the MS Word “Save As” formats, provided Word is available on the server.fDOutputFileIdSpecifies a pattern to use for the name of the file sent to the user.

This overrides the setting for the DSD. The default file id is the same as the template file. The options for substitution values are as follows:

• #file# for the template’s file id (without extension)
• #<user entry id># for any user entry value
• #dsd# for the DSD Id
• #effective# for the effective date in the format YYYY-MM-DD
• #guid# for a random string.

 

So for example you might use fDOutputFileId=Order-#OrderNo# to use the order number in the generated file name. Note that the extension is added automatically if not specified in the patten.

.fDInstanceTo specify an fAdmin configuration instance.fDHeadingOverrides the page heading (and the Login page if shown).fDOnlyFromRequest

(form method only)This is a comma separated list of user entry ids that are to be taken from the parameters passed and not requested from the user. This is useful to selectively force certain entries. For example you may want to generate a document for a specific account but let the user select the quote for that account.fDDefaultRequest

(form method only)If set to “true”, any user entry fields supplied as parameters (i.e. with a non-empty value) will be taken from the parameter and the user will not be asked to make an entry. This is useful if you only want users to be asked for details not known, and so not passed, by the application.

 

 

So the link may be to the following URL:

http://[fSeries]/fDGenerate.aspx?fDTemplateLocation=SalesDocs&TemplateFile=Quote.docx&quoteid={...}

This will take the Quote.docx template from the SalesDocs folder in the published templates, gather data using the quote specified and generate the output in docx format (the same as the template).

http://[fSeries]/fDSelect.aspx?fDDefaultRequest=true&fDFormat=pdf&fDTemplateLocation=SalesDocs&TemplateFile=Quote.docx&accountid={...}

This will open the form and ask the user to select a quote for the given account (assuming the DSD is setup this way). The user will not be asked for the account id as this is supplied in the URL. They will also not be asked to select a document format as this has been specified as pdf.

 

 

Open Form Page

If you need to ask the user for some input before generating their requested output, use fDSelect.aspx.

This may be simply to ask them which format they require, up to full entry of all of the DSD’s user entry fields.

fDSelect.aspx generates a form into which the user makes their entries. However, you can pass parameters to the page to tailor it to your needs.

By default the form has an entry box for each DSD user entry field, and a radio button selection for the format. However, the format is not requested if the configuration does not allow for either doc or pdf formats or if the format is passed (see fDFormat below).

Each user entry may be passed and either used as the default entry or prevent the user from being asked for the entry altogether.

The parameters that can be passed to the page to influence its behavior are as follows:

 fDHeading

Used as the page heading both for this page and for the login page if it is displayed.

fDTemplateLocation and fDTempateFile

The location, relative to the server’s published template folder and the name of the template file (including extension) of the template to be used to generate the output.

fDFormat

Set to wordml, doc or pdf to force a specific format. The user will not be asked to select a format.

User Entries

Any of the DSDs user entry fields may be passed, and in certain combinations of the above parameters must be passed. The parameter name is the same as the user entry field name.

fDOnlyFromRequest

If set to “true” no user entry fields will be requested and all user entry values will be taken from any parameters passed. This assumes that the application has and is passing all relevant details directly via the parameters.

 fDFromRequest

This is a comma separated list of user entry field names that are to be taken from the parameters passed and not requested from the user. This is useful to selectively force certain entries. For example for client letters you may want to force the selected client but ask the user to enter their user id to pick up “from” details.

fDDefaultRequest

If set to true, any user entry fields supplied as parameters (i.e. with a non-empty value) will be taken from the parameter and the user will not be asked to make an entry. This is useful if you only want users to be asked for details not known, and so not passed, by the application.

If the page has no user entries, it automatically forwards to the fDGenerate.aspx page to generate the output. Otherwise the user must make the entries and click Submit.

So the following will generate a client letter (Letter1.docx) for client ABC123 without asking the user to enter the client id, but allowing them to select the format and to enter their user id.

http://…/ fDSelect.aspx?fDTemplateLocation=ClientLetters&TemplateFile=Letter1.docx&ClientId=ABC123&fDDefaultRequest=true

 

Select From Index

From version 3.4

fDocs provides a method of deploying document generation as a menu of available templates based on an index. fDocs can then display a menu of templates based on the index and the user may click on any template in the list to select it to be generated.

The process is exactly the same as the fDSelect.aspx page but with some additional options. It is also necessary to carry out some configuration setup to make this operate.

Setup

In the fAdmin settings page for fDocs, check the option “IndexTemplates”. This instructs fDocs to index templates as appropriate according to other settings.

You may also set the option “DefaultTemplateIndex” to specify the name of the index in which all templates are to be indexed if none is specified in the template’s DSD. This will index all templates other than those with a designated index set in their DSD.

You can specify the index to be used in the advanced section of fData. The lets you designate multiple indexes in order to segment your templates. This option is only available for DSDs that have the fDocs purpose.

Note that you don’t need to actually create an index, just specify its name; fDocs will create and maintain the index automatically.

If you are specifying an index for the first time or changing the index ofr a DSD, go to the Tools option in fAdmin and select Rebuild Template Indexes to rebuild the indexes from existing templates. Thereafter the indexes will be maintained automatically.

Calling an Index

To deploy the index menu use the following style of link in your application web launcher:

http://[fSeries]/fDocs/Index.aspx?fIndex=MSCRM&fCheckEntries=all&fShowPath=true fDFormat=pdf&accountid={...}

This will display the MSCRM index but only show templates whose DSD’s user entries include accountid and only accountid. Templates will be shown including their full path from the published template location. When the user click to generate a document from the list it will be generated directly as no further entries are required by the user (the accounted and fDFormat are supplied by the link).

The index menu links to the fDSelect.aspx page passing forward all parameters (except fCheckEntries, fShowPath and fIndex).

You may pass all parameters to the Index.aspx page that are available to the fDSelect.aspx page (see above). If the fDDefaultRequest parameter is not supplied the link forward will have fDDefaultRequest=true added to prevent unnecessary requests for the user to supply values already included in the parameters.

In addition the following parameters specific to Index.aspx are also available:

fCheckEntries	This filters the templates to include either those for which all user entry values are supplied (“all”), those for which mandatory user entries are supplied (“mandatory”) or those with no user entries (“none”). Any other value will return every template regardless of the parameters supplied.
fShowPath	If set to “true” the path of each template, relative to the published template location, will be displayed with the file id. Otherwise only the file id (without extension) will be shown.
fIndex	fDocs allows for multiple indexes and this parameter will let you specify which index to show. If not specified the default template index is used.

 

So a further example would be:

http://[fSeries]/fDocs/Index.aspx

This would show every template in the default template index as no fCheckEntries is specified, showing only the file id without the path. When the user clicks on an option the fDSelect.aspx page will be displayed and request all user entries and the format required.

Note that the index menu page includes a search filter that allows the user to narrow down the templates available from which to choose.