Difference between revisions of "AppSuite:DocumentAutomation"
(Automatically fill fields in ODF templates) |
(→The conversion URL) |
||
| (6 intermediate revisions by the same user not shown) | |||
| Line 5: | Line 5: | ||
OX Text allows the user to automatically fill user fields in ODF text documents when creating a document from a template. | OX Text allows the user to automatically fill user fields in ODF text documents when creating a document from a template. | ||
| − | This can be | + | This can be achieved via regular urls passed to the browser, so that the process can also be triggered from outside, e.g. from a desktop application. |
| − | The data can easily be | + | The data can easily be encoded in the url, but as the length of urls has limitations, you can also specify a cvs file in OX Drive. |
=== The document template === | === The document template === | ||
| − | The source template or regular document needs to include fields of type | + | The source template or regular document needs to include fields of type ''Mail merge field''. |
| − | Note: In Open Office the field type is called | + | Note: In Open Office the field type is called ''Mail merge field''. Unfortunately you can’t specify the name of the field, as you can only select items from an existing database. So you need to add fields with the desired name to the database that comes with Open Office. Alternatively, use ''MergeField'' in Microsoft Word and specify the name, but don’t forget to save as ODF. |
=== The conversion process === | === The conversion process === | ||
| − | To create a new | + | To create a new document based on an existing document or template, with updating the content of the fields, you have different choices to pass the field data to OX Text. |
=== The conversion URL === | === The conversion URL === | ||
The general syntax for all the different ways to perform a conversion is: | The general syntax for all the different ways to perform a conversion is: | ||
| − | https://appsuiteserver/appsuite/#!&folder=FOLDERID&id=FILEID&app=io.ox/office/text&EXTRA | + | |
| − | + | ''<nowiki>https://appsuiteserver/appsuite/#!&folder=FOLDERID&id=FILEID&app=io.ox/office/text&convert=1&EXTRA</nowiki>'' | |
| − | EXTRA | + | |
| + | Replace FOLDERID and FILEID with the actual values of your document. | ||
| + | |||
| + | The parameter ''convert=1'' parameter is needed so that a new document will be created. Without this parameter, the original template will just be opened in the editor. | ||
| + | |||
| + | The new document will be created in "my files". | ||
| + | |||
| + | Optional parameters: | ||
| + | ''destfilename=<filename>'' | ||
| + | The file will be named <filename>.odt. If the name already exists, a unique name will be created | ||
| + | |||
| + | ''destfolderid=<folderid>'' | ||
| + | The new document will be places in <folderid>, if the user has write access | ||
| + | |||
| + | The EXTRA parameter depends on the way how you want to transfer the data, see below. | ||
==== Field values via URL ==== | ==== Field values via URL ==== | ||
| + | |||
This solution is convenient if you have just a few fields. Keep in mind that the maximum length of the url is limited, the limit might vary from browser to browser. | This solution is convenient if you have just a few fields. Keep in mind that the maximum length of the url is limited, the limit might vary from browser to browser. | ||
| Line 33: | Line 48: | ||
===== field/value pair notation ===== | ===== field/value pair notation ===== | ||
| − | url EXTRA parameter: fields=FIELDNAME1;FIELDVALUE1;FIELDNAME2;FIELDVALUE2 | + | url EXTRA parameter: ''fields=FIELDNAME1;FIELDVALUE1;FIELDNAME2;FIELDVALUE2'' |
| − | FIELDNAME<n> is the name of the field, FIELDVALUE<n> is the text that you want to place into the field. Add as many name/ | + | |
| + | FIELDNAME<n> is the name of the field, FIELDVALUE<n> is the text that you want to place into the field. Add as many name/value pairs as you want, separated by semicolon. | ||
===== JSON notation ===== | ===== JSON notation ===== | ||
| − | fields={“FIELDNAME1”:“FIELDVALUE1”,“FIELDNAME2”:“FIELDVALUE2” } | + | url EXTRA parameter: ''fields={“FIELDNAME1”:“FIELDVALUE1”,“FIELDNAME2”:“FIELDVALUE2” }'' |
| − | + | ||
| + | FIELDNAME<n> is the name of the field, FIELDVALUE<n> is the text that you want to place into the field. Add as many name/value pairs as you want, separated by comma. | ||
==== Field values via CVS File ==== | ==== Field values via CVS File ==== | ||
| Line 48: | Line 65: | ||
The csv file can use tabs, semicolons or commas as a separator. All fields containing commas or semicolons must be placed inside quotes. The first line in the csv file contains the field names, the second line contains the field values. | The csv file can use tabs, semicolons or commas as a separator. All fields containing commas or semicolons must be placed inside quotes. The first line in the csv file contains the field names, the second line contains the field values. | ||
| − | url EXTRA parameter: fields-source=CSVFILEID | + | |
| + | url EXTRA parameter: ''fields-source=CSVFILEID'' | ||
| + | |||
CSVFILEID is the id of the cvs file. | CSVFILEID is the id of the cvs file. | ||
Revision as of 17:25, 21 May 2015
Contents
OX Text field automation
OX Text allows the user to automatically fill user fields in ODF text documents when creating a document from a template.
This can be achieved via regular urls passed to the browser, so that the process can also be triggered from outside, e.g. from a desktop application.
The data can easily be encoded in the url, but as the length of urls has limitations, you can also specify a cvs file in OX Drive.
The document template
The source template or regular document needs to include fields of type Mail merge field.
Note: In Open Office the field type is called Mail merge field. Unfortunately you can’t specify the name of the field, as you can only select items from an existing database. So you need to add fields with the desired name to the database that comes with Open Office. Alternatively, use MergeField in Microsoft Word and specify the name, but don’t forget to save as ODF.
The conversion process
To create a new document based on an existing document or template, with updating the content of the fields, you have different choices to pass the field data to OX Text.
The conversion URL
The general syntax for all the different ways to perform a conversion is:
https://appsuiteserver/appsuite/#!&folder=FOLDERID&id=FILEID&app=io.ox/office/text&convert=1&EXTRA
Replace FOLDERID and FILEID with the actual values of your document.
The parameter convert=1 parameter is needed so that a new document will be created. Without this parameter, the original template will just be opened in the editor.
The new document will be created in "my files".
Optional parameters:
destfilename=<filename> The file will be named <filename>.odt. If the name already exists, a unique name will be created
destfolderid=<folderid> The new document will be places in <folderid>, if the user has write access
The EXTRA parameter depends on the way how you want to transfer the data, see below.
Field values via URL
This solution is convenient if you have just a few fields. Keep in mind that the maximum length of the url is limited, the limit might vary from browser to browser.
To the base url described above, add the data in field/value notation, or in JSON notation.
field/value pair notation
url EXTRA parameter: fields=FIELDNAME1;FIELDVALUE1;FIELDNAME2;FIELDVALUE2
FIELDNAME<n> is the name of the field, FIELDVALUE<n> is the text that you want to place into the field. Add as many name/value pairs as you want, separated by semicolon.
JSON notation
url EXTRA parameter: fields={“FIELDNAME1”:“FIELDVALUE1”,“FIELDNAME2”:“FIELDVALUE2” }
FIELDNAME<n> is the name of the field, FIELDVALUE<n> is the text that you want to place into the field. Add as many name/value pairs as you want, separated by comma.
Field values via CVS File
The values can also be read from a cvs file located in OX Drive. This avoids exceeding the maximum url length.
CSV notation
The csv file can use tabs, semicolons or commas as a separator. All fields containing commas or semicolons must be placed inside quotes. The first line in the csv file contains the field names, the second line contains the field values.
url EXTRA parameter: fields-source=CSVFILEID
CSVFILEID is the id of the cvs file.