jsreport v2 is major release which on top of great new features also includes several breaking changes. It is not in-place replacement for jsreport v1 and you should carefully review how the changes affect your application. To make this task easier we have prepared migration utility that analyses your jsreport application, process some automatic migration tasks and print warning with help for the rest.
You can install and run the migration utility in the following way.
npm install -g jsreport-migration
jsreport-migration
IMPORTANT NOTE: The migration utility works for the mainstream jsreport applications. This means applications that was installed by the basic steps described in page download. The custom node application (apps using custom jsreport extensions, or apps that start jsreport in some custom way) as well as single exe users needs to read the upgrade guide. There is no migration automation for those cases.
The rest of the document provides the list of the breaking changes in jsreport v2. I case we were able to automate the change for you using the migration utility the chapter includes note about it.
The jsreport v2 requires at least node.js >= 8.9
The migration utility should automatically convert your configuration files.
The extensions config is now nested in extra property called extensions. So for example scripts can be configured like this.
{
extensions: {
scripts: { timeout: 50000, strategy: 'dedicated-process'}
}
}
The connectionString property was renamed to the store and looks the following now.
{ store: { provider: 'fs' } }
The tasks property was renamed to templatingEngines.
{ templatingEngines: { timeout: 1000, allowedModules: ['request'] } }
The blobStorage property should be now object with structure as store.
{ blobStorage: { provider: 'fs' } }
jsreport v2 introduce new config property allowLocalFilesAccess.
{ allowLocalFilesAccess: true | false }
When true this property specifies that jsreport should allow access to the local file system and use of custom nodejs modules during rendering execution.
The phantomjs project is no longer active and we decided to switch to headless chrome in the default installation. This doesn't mean you can't continue using phantomjs. You just need to additionally install it if you don't want to migrate your templates.
npm install jsreport-phantom-pdf --save
npm install phantomjs-prebuilt --save
If you want to skip chrome download completely you can set this environment variable before npm install.
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD true
Images extension is no longer part of the standard jsreport installation and it is also not being maintained. The more powerful assets extension takes its place.
The migration from images to assets is automated by the migration utility
fop-pdf rcipe is no longer part of the standard jsreport installation, however you can easily additionally install it.
npm install jsreport-fop-pdf --save
The data passed to the API needs to be object. Using array [] as data is no longer supported.
The data extension doesn't parse long time deprecated value from req.template.data.dataJson .
isChildRequest is now exposed under the context object property of request
function afterRender(req, res, done) {
//filter out script execution for child request
if (req.context.isChildRequest)
return done();
//your script
done();
}
Rendering request with script strictly accepts format
{ template: { scripts: [{shortid: 'xxx', content: 'xxx'}]} }
Where each script needs to be identified by shortid or contain direct content.
The long time deprecated format request.template.scriptId or
request.template.script is no longer supported.
The custom script hook needs to expect parameters req, res, done or req, res.
function beforeRender(req, res, done) {
done()
}
The long time deprecated hooks with single done parameter or scripts declared as code in global scope is no longer supported. Note you can now also exclude done the last parameter and return a value from a promise from the hook.
Using req.reporter.render is no longer supported. Instead you need to use:
// TODO promises
const proxy = require('jsreport-proxy')
function beforeRender(req, res, done) {
proxy.render({ template: {...}}, function (err, res) {
done()
})
}
The migration utility validates if there are stored script in deprecated format and prints warnings.
The public templates supports only read public links. Let us know if you use the write links.
--install,--uninstall, --init, --repair commands are no longer available to be called using node node_modules/jsreport --init, use jsreport-cli instead.
Month format of cron expressions is changed from 0-11 to 1-12 to match standard cron expressions.
Day of Week now also supports specifying 7 as Sunday, format changed from 0-6 to 0-7, where both 0 and 7 represent Sunday.
Cron expressions are now validated to contain at least 5 or 6 parts, so expressions like * * or * * * are invalid now.
Internal cron parser changed from node-cron to cron-parser package.
The migration utility automatically convert cron expressions from old month format
0-11to new format1-12
The logging no longer supports deprecated structure with providerName. The only currently supported structure is
"logger": {
"console": {
"transport": "console",
"level": "debug"
},
"file": {
"transport": "file",
"level": "info",
"filename": "logs/reporter.log"
},
"error": {
"transport": "file",
"level": "error",
"filename": "logs/error.log"
}
},
The migration utility should fix your old logger format.
render method now returns a promise instead of accepting a callback.
render no longer resolves to an instance of node.js http response stream, instead it resolves to a stream with the same properties of a node.js http response stream, it is identical with the same properties, just that it is no longer a real instance of node.js http response stream.