NodeJS Server Input

NodeJS Server Input tasks are used to receive HTTP requests and to send replies to the servers from which the requests were made.

Essentially this task does the same as the HTTP Server Input task, but it uses a NodeJS Server (version 12.13.1, installed by Workflow) instead of Workflow's custom server component. The NodeJS Server is more secure, more up to date and more standardized.
For instance:

• PUT and DELETE actions can be posted to the server.
• The NodeJS Server can serve multiple static resources at once.
• Port numbers > 9999 are allowed.
• You can specify a HTTPS port separately.
• A Proxy list can be used to setup end points for redirecting requests to another server. This could be useful if for example the Connect server is on another server which could change; when it changes you’d only have to modify the proxy list instead of the configuration.
• You can enable or disable authentication using users from an Active Directory server.

The NodeJS Server is only started automatically by Workflow when NodeJS input plugins are detected in the configuration. If no NodeJS input plugins are present, the service ("ppNode") is not started by Workflow; it can still be started manually, but will only serve static resources and redirect requests to other servers.

Before using this plugin

1. Configure the NodeJS Server using its three settings dialogs in the Preferences (Workflow button > Preferences): NodeJS Server Input plugin preferences 1, NodeJS Server Input plugin preferences 2 and NodeJS Server Input plugin preferences 3.

2. In order to serve resources that come from the Connect Server the ppNode service needs to know the credentials and communication protocol to use for communication to the Connect Server.
   These must be entered in a file named default.js that is by default found in C:\Program Files (x86)\Objectif Lune\ppnode\src\constants\.
   Find the following line:
   export const DEFAULT_CONNECT_CREDS:{ auth: string; protocol: string } = { auth: "ol-admin:secret", protocol: "http" }; //Default user/pass and protocol for the Connect Server
   Enter the credentials and protocol (either http or https) in the auth and protocol entries.
   Once the file has been changed, the ppNode service needs to be restarted for the change to take effect.
   

Input

The NodeJS Server Input task does not, by itself, capture any files. Neither does it directly wait for requests to be received. Actually, it is the NodeJS service that receives the requests and places them in a specific location on the drive. When a request is received, the NodeJS Server Input polls that location and finds the requests and all attachments. It will always pick up the "oldest" request received first.

The request can contain one or more files, one being an XML file containing the request information as well as any GET, POST, PUT or DELETE variables that were received within this request. Other files are POST or PUT attachments.

The NodeJS Server Input task supports basic content-types: multipart/form-data, application/x-www-urlencoded, and application/octet-stream, as well as raw body content-types:

• text/plain (.txt)
• application/xml, text/xml (.xml)
• text/html (.html)
• application/xhtml+xml (.xhtml)
• text/css (.css)
• text/csv (.csv)
• application/json (.json)
• application/javascript (.js)

Note that the maximum number of multipart form data fields is 1000 by default.

Processing

Depending on the options chosen in the NodeJS Server Input task properties, the task may choose to ignore some of the files. For example, using the "Do not include XML envelope" means that only the POST attachments will be used in the process; the XML file will be discarded. Attachments are always saved on disk in a specific location, which is accessible either directly in the XML or directly as a data file through the "Loop each attachment as data file" option.

How arrays in input data are interpreted

When the names of Form inputs in an incoming POST request contain two pairs of square brackets: [..][..], the data are interpreted as an array. The value between the first pair of square brackets is expected to consist of two parts, separated by an underscore (e.g. row_0). The first part is considered to be the element's name. All content after the first underscore (preferably an integer) will be used as index, which is given as an attribute of the element (e.g. <row _idx=0>). This makes it easy to select all elements on the same level in a data mapping configuration, and to convert the XML to a JSON object.
For an example see Incoming HTML and Resulting XML structure with Enhanced PHP-like arrays.

Output

First, the output inside the process itself is, depending on the selected options, an XML request file, POST Attachments files, either one or both.

If the Send Immediate Response to client option is selected, the response file is sent back right away and the involvement of the input task ends then.
However, if this option is not checked, it means there is a second output that comes out of the NodeJS Server Input task: the last output generated by PlanetPress Workflow is sent back to the initial input, by which it is returned to the client.
Even if the process ends with a Delete task, it is still returned to the client; deleting the job file only means you are not doing anything with it locally.

If the requested HTTP action is not available, a '404 not found' HTML page will be returned.

Task properties

General Tab

• HTTP action: Enter the name of the action requested of PlanetPress Workflow by the client. This name corresponds to the URL that the client will be accessing. For example, if you enter "MakePDF" here, you could trigger the process by accessing http://127.0.0.1:9090/MakePDF. This is also what your HTML Form's action should be.

  The following characters are not allowed in an action name: $ * ? #, spaces, and any characters that are not permitted in Windows folder names, such as \ / : ? ” < > | .
  
  Action names are not case sensitive.

• MIME Type: Select the MIME type of the file that will be returned by the plugin.
• Form Data Encoding: Specifies how this endpoint will interpret any form data received by the web server.
  

  Even though it is strongly recommended to use the <meta charset="utf-8"/> element in web pages, some might use another encoding or not have the element at all, affecting the character set used by the browser to send the parameters and file names.

  • System language: Sets the encoding attribute in the request XML file to the system codepage (e.g. Windows-1252).
  • UTF-8: Causes all parameters as well as file names from the request to be interpreted as a UTF-8 text stream.
    With this option enabled, POST attachment file names will be randomized on disk to avoid misinterpretation. If the original file name is needed, it can be found in the original attribute of the file tag in the request XML.
    If form data are submitted from HTML files that are made with the OL Connect software, you can expect them to be UTF-8 encoded.
    Don't use any non-ASCII characters in Workflow's working directories path (in the V8WorkingDirectory registry key). Combined with the UTF-8 Form Data Encoding setting, this might make it impossible for Workflow to retrieve files from that path, depending on the actual path name and the system locale.
• Loop each attachment as a data file: When receiving attachments through a POST request (HTML Form), this option will make the NodeJS Server Input task loop through each attachment. Each data file is an XML with the accompanied file.
  • Do not include XML envelope: Only active when the previous Loop option is checked. When checked, the XML file containing the request data will not be available. Only the attachment itself is sent as a data file.
• Respond on error: Enter a message to be sent to the client as the output file if the process encounters an error and is unable to send a reply that includes the actual output file. The information can be in any desired format such as HTML or plain text. However, if it must be displayed in a browser, the format should match the selected MIME type.
  This is a variable property box. You can use any combination of text, variables and data selections; see Variable task properties.
  This option requires every plugin in the process to be explicitly set to "On Error: Stop process" (see Using the On Error tab), even if the process itself is set to "On Error: Stop process".
• Send immediate response to client: Do not wait for the process to finish and send a static HTML or Text file back to the client instead. This prevents any timeout from occurring.
  • Response file: Select which file to return. Note that the file name doesn't have to be static. You can use any combination of text, variables and data selections; see Variable task properties.
• Use custom HTTP server response code: When the process ends and a response is sent to the requesting client, a custom response code can be specified depending on how the process goes; for example: "200 OK", "404 Not Found" or "401 Unauthorized".
  Choose a response code between 100 and 599. (See: List of HTTP status codes on Wikipedia.) If the response isn't currently handled by any HTTP response code, you may use an unused code in that range.
  The response code must start with 3 digits, followed by a space and then the error message. If the first few characters can't be converted to a valid number, the server automatically returns "500 Internal Server Error", regardless of the actual response code provided by the process.
  • Variable containing the response code: The contents of the Job Info variable or local variable (see About variables) selected in this drop-down, presumed to be a valid response code, will be returned in the response header. This is the value that is present at the end of the process, not the beginning.
• Ignore global authentication settings: Disable authentication for this particular URL, regardless of the global authentication settings. 'Global authentication settings' refers to the authentication settings of the NodeJS Server, set in the preferences: NodeJS Server Input plugin preferences 3. If authentication is not enabled in the preferences, this option has no effect.

"Other" Tab

• Job Information group
  • Information elements: Indicates what Job Info variables are automatically created by the input task.
  • Add lines before first data page: Using the arrows keys you can add any job information directly at the beginning of your data file.
• Backup input files: Check this to save a copy of each data file that is captured by your input. These files are saved in the PlanetPress Workflow Tools working folders under the "Backup" folder.
  To navigate quickly to the Workflow working folders, press the keyboard shortcut CTRL+ALT+Shift+F4 from within the Workflow configuration tool.
  The number of days to keep backups of jobs processed by input tasks is set per process; see Process properties.
• Backup filename: Enter the file name that you wish the input data file backup to be saved under.
• Delete Existing Metadata: Check to remove any Metadata from memory. This option is disabled on initial input tasks, and is checked by default on secondary input tasks.

Job Information definitions

• %1 - Client IP Address: Contains the IP address of the HTTP client requesting a response.
• %2 - Request Header: Contains the headers of the request, which can contain information such as the Browser and Operating System, languages, etc.
• %3 - Filename: Contains the local file name of the job file created by this task (and XML file). This is equivalent to %o.
• %4 - Attachment Index: Contains the index number of the current attachment while looping the attachments as data files. When the option Loop each attachment as a data file is not checked, the Attachment Index is 0.

On Error Tab

For a description of the options on the On Error tab see Using the On Error tab.

Miscellaneous Tab

The Miscellaneous tab is common to all tasks.

It contains a text area (Task comments) that lets you write comments about the task. These comments are saved when the dialog is closed with the OK button and are displayed in The Task Comments Pane.

Check the option Use as step description to display the text next to the icon of the plugin in the Process area.

The tab also provides an option to highlight the task in The Process area with the default color, set in the Preferences (see Colors), or the color selected or defined under Highlight color on this tab.
To revert the selected highlight color to the default color, open this tab, turn the Highlight option off and close the dialog with the OK button; then turn highlighting back on.
Highlighting can also be turned on and off via the task's contextual menu and with the Highlight button on the View ribbon.