Integration with RaptorXML Server
When you integrate RaptorXML Server and FlowForce Server, RaptorXML Server's functions become available as built-in FlowForce Server functions. This means that you can create jobs that validate and check the well-formedness of XML and JSON documents, XBRL taxonomies and instance files. You can also perform XSLT transformations and execute XQuery documents.
Integration
After you have installed RaptorXML Server, together with FlowForce Server (available on Windows) or as a standalone product (available on any platform), you will need to integrate the RaptorXML functionality into FlowForce Server. The possible integration options are listed below:
•Via the FlowForce Server Setup page
•Via several CLI commands
•Via the integration script
For details, see the subsections below.
Integration via the Setup page
This is the fastest and most convenient way to integrate the RaptorXML functionality into FlowForce Server. Proceed as follows:
1.Open the Setup page. Depending on your platform, the instructions vary:
2.On the Setup page, click the Integrate Tools button for the relevant server instance.
3.In the dialog that opens, click Integrate. The log will display integration details, as shown in the screenshot below.
It is recommended to integrate RaptorXML Server before installing the FlowForce Server and FlowForce Web Server services. You can also integrate RaptorXML at a later stage. Note, however, that you must stop the services before being able to click the Integrate Tools button.
Integration via the CLI
You can use several CLI commands with the --integratetools options to integrate RaptorXML functions to a new (with createdb, initdb or migratedb) or to an existing (with initdb or upgradedb) FlowForce instance.
Integration via the script
Another way to integrate RaptorXML is to run the script available at the following path:
{RaptorXML installation directory}\etc\functions\integrate.bat
| Note: | On Unix systems, the script's name is integrate.cs. Superuser privileges (sudo) are required to run this script. |
This script takes two arguments: the path to the FlowForce Server installation directory and the path to the FlowForce Server instance-data directory (see Important Paths). When you run the script, the following happens:
•All the release-specific functions of the integrated RaptorXML Server version become available in FlowForce Server.
•The generic (release-agnostic) RaptorXML functions are updated to the release-specific functions of the integrated RaptorXML version.
For details about release-specific and generic RaptorXML functions, see Generic vs Release-specific RaptorXML Functions below.
If the script returns errors, the function definitions of the integrated RaptorXML version are not compatible with FlowForce Server. In the unlikely event that this happens, please contact support.
After integration
After RaptorXML has been integrated into FlowForce, all the RaptorXML Server functions become available in the /RaptorXML container of FlowForce (screenshot below). In the case of RaptorXML+XBRL Server, the container's name is /RaptorXMLXBRL.
How to call RaptorXML functions
You can call RaptorXML's functions in one of the following ways:
•By navigating to the /RaptorXML (or /RaptorXMLXBRL) container, opening a function of interest, and then clicking Create Job. You can select release-independent functions such as /RaptorXML/valjson or release-specific functions such as /RaptorXML/2024/valjson. The differences between the two are described below.
•By creating a new execution step in a job and calling the desired RaptorXML function from this step. For example, the step below calls the valjson function:
For examples of jobs that call RaptorXML Server, see:
•Validate a Document with RaptorXML
•Validate XML with Error Logging
•Use RaptorXML to Pass Key/Value Parameter Pairs
For information about the available RaptorXML functions, see the RaptorXML Server documentation (https://www.altova.com/documentation).
Generic vs release-specific RaptorXML functions
The functions available in the RaptorXML or RaptorXMLXBRL containers are organized as follows:
•Functions from the /RaptorXML container are backward compatible down to the 2014 version of FlowForce Server (which is the first version supporting RaptorXML functions). These generic functions act as wrappers to the release-specific functions from the /RaptorXML/{Release} container. They are guaranteed to be compatible between releases but they do not provide all the features of the latest installed RaptorXML Server.
•Functions from the /RaptorXML/{Release} containers provide all the features of the corresponding RaptorXML release. These functions are compatible with FlowForce Server of the same release. However, any version of RaptorXML Server is not necessarily compatible with any version of FlowForce Server. You can check compatibility by running the integration script (as described in Integration above).
If a job calls a generic RaptorXML function, the function acts as a wrapper to the equivalent release-specific function of the RaptorXML Server. The selected RaptorXML release is the one that was most recently integrated into FlowForce, including manually-integrated releases. However, such calls will not benefit from the latest RaptorXML features (such as new arguments or even functions). To make use of the latest RaptorXML features from FlowForce jobs, call a release-specific function directly.
A release-specific function determines which RaptorXML .tool file should be used in order to look up the RaptorXML executable. A separate .tool file exists for each RaptorXML Server release. A .tool file informs FlowForce Server about the location of the RaptorXML Server executable and can also be used to set environment variables (see Setting Environment Variables).
If your FlowForce jobs refer to version-specific RaptorXML functions, and if you would like to upgrade to a newer version of FlowForce Server and RaptorXML Server, you can either modify all the jobs to point to the latest release-specific RaptorXML functions, or you can map the Raptor.tool file to a newer version of the RaptorXML Server executable, as follows:
1.Copy the Raptor_<release>.tool file from {installation}\etc directory of RaptorXML Server of the latest installed release to the {configuration data}\tools directory of FlowForce Server of the same release.
2.Rename the file to match the version of the old release (the Raptor release your jobs are pointing to). For example, if the old release is RaptorXML 2017r3, then rename the file Raptor_2017r3.tool.
If you take the mapping approach, all the existing jobs will continue to look as if they called RaptorXML 2017r3 functions, whereas the .tool file will map in fact to the latest RaptorXML Server executable.