Please note: Globalscan NX is a discontinued product. Further, RiDP no longer supports plugin development. Queries about existing GSNX plugin maintenance should be directed to Ricoh Service and Support in your region.
GlobalScan NX is equipped with documentation that outlines key functionality, specifications, Java docs and much more. In addition to the included documentation this page will outline additional FAQs needed to accommodate those questions that spawn during all aspects of the Software Development Cycle.
Globalscan NX FAQs
How can I obtain the Admin Tools session ID during configuration of a Plug-in?
The session ID is available during project-level configuration. We strongly suggest against using the current thread contexts thread ID becuase the current thread ID can change throughout the same session. For example; if GSNX service is rebooted while someone is still in the Admin Tool the session ID will be renewed with a different value. While this is not a consistent scenario, the possiblilty for this to occur exists. (especially in development environments)
What is the correct method for administrators to successfully uninstall a plug-in? Must they manually remove Plug-in projects? Does the initializeForUninstall() or execute() method do this?
As an administrator; when uninstalling a plug-in, one must manually remove the Plug-in from the projects directory. If a project utilizes uninstalled plug-ins, job processing will fail when it reaches the uninstalled plug-in in the flow. As a result, plug-ins should implement logic in their uninstall implementation to check if there are any jobs or projects to which they belong. There are two methods for a plug-in to realize which project it is occupying:
1) By using the "DistributionConfig" and "DeliveryFlow" classes. The plug-in can list all projects that exist in the system by using the "DistributionConfig" class. Then, for each project, the plug-in can go through the delivery flow by using the "DeliveryFlow" class to check if the plug-in exist in the flow or not.
2) By creating an event plug-in that is notified when a plug-in is added to a project. When such a plug-in receives the notification, it can store that information.
Note: This method will not work if the "import profile" function is active. In v1.3, this is a new Admin Tool function, and in v1.2, this function is provided as standalone tool. In either case, Event Plug-in will not be notified. Therefore, using the "DistributionConfig" class and the "DeliveryFlow" class is the only method.
When I restart the GlobalScan NX service using the Admin Tool I sometimes get a HTTP 404 error. What am I doing wrong?
A HTTP 404 error occurs when GlobalScan NX restarts and its web services are not fully loaded. Therefore, when restarting GlobalScan NX, wait 10 or 15 seconds before accessing Admin Tool. (The amount of time to wait depends on environmental factors)
What is the best method to confirm that a Log Plug-in is loaded?
The best method to determine if a Log Plug-in is loaded or not is to write plug-in information into the log during the initialization or construction event of the plug-in. The GlobalScan NX SDK allows plug-ins to log data even though the rest of XG may not be loaded.
What is the best method to localize error messages during authentication?
The current version of GSNX SDK does not allow localization. Meaning, it does not allow a developer to provide text for the authenticating user (in the case of a failed authentication) as XG will provide a generic, but localized, text instead. The plug-in can log the text, however, since no language context is provided, it must be logged per the developer's choice at development time. Further, the LanguageCallback object cannot be used, because it is not supported in this version of GSNX
Are passwords stored in the configuration? Are they encrypted?
Yes, passwords are in encrypted and use a Blowfish algorithm.
Using a network packet capture, I see my passwords being sent in plaintext when saving a configuration record, and when reading a configuration record. Can I prevent this?
This behavior is documented in more detail in XG's security whitepaper. In short, you cannot prevent this, but if XG is configured to use HTTPS, then this should not be a problem.
How to prevent a control's contents from being updated during save, while others should save?
Unfortunately this feature is not available. But you can set the control's contents to blank, however this can not be done in the UI Event for OK button. Because this is the last event before saving the data, and no changes can be applied. You can create a button, like "Submit", and at that UI Event, return the control's data and "" for all undesired controls.
What is the difference between selecting multiple rows and using the checkboxes in a data grid?
The checkboxes can be confusing to use. The checkboxes, when used, control whether the edit and delete buttons (if used) is visible. When at least one row's checkbox is checked, these buttons are enabled. But when querying the selected items of the grid, you will find that it is the highlighted rows that are returned, not the checked checkboxes. Further, it is not possible to programmatically determine the checked items, only the selected items.
How can I update the parameter argument of the Output (or Filter) PluginInterface's "execute()" method?
Here's how:
Map<String, String> m = new HashMap<String, String>();
m.put( "NewKey", "someData" );
parameters.put( "rewriteParameter", m );
//if an error condition exists, throw exception...
Throw new PluginException(…);
//... or if no error, simply return normally:
ExecuteResult e = new ExecuteResult();
//set e data
return e;
How does using STATUS_CALL_BACK work?
When a plug-in returns a status of STATUS_CALL_BACK, GSNX will place the job back into the job queue, and it will do so indefinitely as long as the plug-in keeps returning STATUS_CALL_BACK. Therefore, it is up to the plug-in to provide break logic to prevent a job from forever sitting in the queue. For some plug-in, it may be easy to maintain a standalone job file which can be queried, so that when coming across a job, the plug-in can cross-reference the job with any references to it in the file, and if found, it can return a status of complete or error, as appropriate for the plug-in.
Using STATUS_CALL_BACK is a good way to prevent a plug-in from hogging all of the time used to process a job, but won't this just delay the job anyway?
Yes, it will. But you can use threads, and then use STATUS_CALL_BACK to query the status of that thread. This will allow GSNX to process other jobs at the same time your plug-in will process a task that is running in a separate thread. Once you spawn a thread and clean up your code, return with a status of STATUS_CALL_BACK, and later, you can get a chance to examine the thread state or results. Keep on returning STATUS_CALL_BACK until you have a final disposition for your job's task.
Why are there mutator (set...) methods on SdipDetailLogInfo? Will a plugin developer want to (or be expected to) use them? Why? What are the effects of using them?
he "setter"methods are used only by GSNX to pass the data to SdipDetailLogInfo. The log plug-in developer does not need to use these methods.
What value will be returned by SdipDeteailLogInfo.getPluginName()?
In the current release of GSNX, it would be the text of the plug-in display text as LAST entered by the administrator.
If a plug-in uses STATUS_CALL_BACK, how does a plug-in distinguish between the first time it is being called vs subsequent calls?
The plug-in can maintain a separate file and track the fact it visited the current job before (if this file isn't found, plug-in can assume it is handling the job for the first time).
If a plug-in updates the parameter object, when can it see those changes?
When a plug-in is handling the job again when the plug-in throws an error and the admin re-tries the job. The "parameter" object cannot be updated to be seen by another instance of the same plug-in. Each plug-in instance gets its own private copy of the "parameters" object. Also, the parameter argument cannot be updated to be seen again if the plug-in returns STATUS_CALL_BACK. For a plug-in to communicate between calls to STATUS_CALL_BACK, or between instances, it must manage a separate file for this purpose.
What is best practice for throwing exceptions, versus returning a status of STATUS_STOP_PROCESSING or STATUS_ERROR_BUT_CONTINUE?
Normally, when unexpected things happen, code should throw exceptions. In GSNX's case, though, plug-in who throw exceptions are given another opportunity to have the problem rectified and the job retried. Therefore, plug-in that find any problems - expected or otherwise - should generally consider these guidelines which are recommendations based on the idea of minimizing administrative burden:
(1) if a plug-in encounters a transient error that can self-correct in time (eg, fax phone line is busy), plug-in can report STATUS_CALL_BACK. Note that if the "transient error" never self-corrects, then the job will forever remain in STATUS_CALL_BACK. If the plugin instead throws PluginException, then there will at least be a few retries and, failing that, the admin can ultimately retry the job.
(2) if plug-in encounters a retryable error that only admin can retry (eg, re-configure external application), then throw an exception (because it can be fixed and manually retried later). Note that the plugin's configuration data passed to the plug-in during the execute() method never changes, even though admin might make more configuration changes.
(3) if plug-in encounters retryable error that user can fix, then return with STATUS_CALL_BACK
(and indicate helpful steps for ADMIN by using ExecuteResult.setTrackingData<ACCOUNTING_INFO_EXTRA_INFO, "Please perform the following steps....">
or indicate helpful steps for USER by sending an email with, "Please perform the following steps....">)
Note that when using setTrackingData(), the information is never sent to the end user, so a private mechanism for contacting the user must be used. Otherwise, the plugin should just throw an exception, forcing the admin to see the failure, which would cause the admin to 1) contact the user, 2) user fix the problem, 3) user notify the admin, and 4) admin re-try the job. Or, the admin can delete the error job.
(4) if plug-in encounters unrecoverable error, then a plug-in should report STATUS_STOP_PROCESSING.
Note: OUTPUT plugins should never report STATUS_ERROR_BUT_CONTINUE, as doing so could result in data loss to plugin's upstream in the workflow.
In Filter & Output Plugin SDK Specification.pdf, page 60, states that STATUS_ERROR_BUT_CONTINUE should be used in cases where authentication fails for a collaboration plug-in. Can you explain why?
When authentication of a collaboration plug-in fails, XG generally does not call that plug-in to process the job. But, there could be a case where the XG calls the collaboration plug-in even if the authentication fails. A Collaboration Plug-in should check whether the authentication the plug-in is collaborating with failed or not. If failed, then the plug-in should not process the data but allow the job to continue. Therefore the plug-in should return STATUS_ERROR_BUT_CONTINUE.
When using Combination Authentication Plug-ins; how can each know what project context they are in?
Per documentation of Authentication Plug-in SDK specification, use jp.co.ricoh.xgp.sdip.authentication.ProfileCommonKey.PROJECT_ID.
How do I access the Subject object's contents?
As of the current release of GSNX, it is not possible. Authentication plug-in should cache the credentials for use by itself. Non-authentication plug-in should consider implementing the authentication interfaces.
How do I make a collaborative authenticating output plugin?
Yes.
a) Create two Java projects, each will export to it's own jar file. The first implements the OutputPluginInterface. The second implements Combination.
b) Implement the methods for both projects according to your plug-ins specification, following the rules outlined in SDK documentation
c) Create a file called "PluginInfo.xml". Create a node in this manner
/PluginInformation/PluginAttributes/Attribute[@attribute_name="AuthType"]/Value/InternalValue/text()="xyz"
d) Be sure all other nodes as required by the SDK are also provided
e) In the project with the main class implementing the Combination interface, make sure that you include a no-arg constructor that includes this line:
super("xyz")
f) Note the "xyz" in c) matches the "xyz" in e)
g) Place the JAR file containing the Combination plug-in in GlobalScan/lib and the JAR file containing the output plug-in in GlobalScan/lib/plug-ins
During boot, XG associates the AuthType specification in the PluginInfo.xml file with the AuthType specified in the authentication plug-ins constructor's call to super(). So whenever the output plug-ins is added to a workflow, and a user chooses that project workflow on the device, the authentication pieces kick in, displaying a login screen.
How come my authentication plugin gets constructed so many times, and mostly when it is not being used for authentication?
In the current version of XG, the authentication libraries access all authentication plug-ins many times. So developers should be careful not to place expensive code inside constructors. Since authentication plug-ins are also constructed "just in time", it means that expensive code can be placed inside the login() method. To optimize performance, plug-ins may be able to employ a singleton pattern, as that means that the first usage of the plug-in would be slow, but all subsequent usages would be faster.
When the dynamic UI is enabled, as the result of uiEvent(), the value for the UI Part can be set via ParameterData object and the argument of UIEventResult#setResult(). What will happen if a different value is specified for the same UI Part?
Example
To the EditBox, “A” is specified in ParameterData object and “B” is
specified in UIEventResult#setResult().
The value specified in setResult() method wins.
When the getUI() method is invoked, the value for the UI Part can be specified via ParameterData object and directly written in Plug-in UI XML. What will happen if different values are specified for the same UI Part?
Example
To the EditBox, “A” is specified in ParameterData object and “B” is
specified in Plug-in UI XML.
The value specified in Plug-in UI XML wins.
What is Subject object in uiEvent() and execute()? How to use it?
The Subject object contains information about the logon user. Because of the security issues, the SDK documents does not contains detail description. Please contact your support person for detail.
When UI Part placed on MFD User interface is moved between the main screen and the 45 option screen on the AdminTool, UI Event does not work
There are two possible cases.
1. When the UI Part is moved between the main screen and the option screen, the screenID passed to the plug-in also changes. If the plug-in checks both the screen ID and the part ID when processing the ui Event, check only the part ID or expect to receive the screen ID of both the main and the option screen.
2. GlobalScan NX does not support applying a result of an event generated in one screen to another screen. For example, if the event is generated in the main screen, than the result of the event can only be applied to the main screen. The result can not be applied to the option screen. When designing a user interface, UI Parts that affect each other (for example, when the check box is selected, the edit box is grayed) should be grouped using <Set> tag. The UI Parts grouped using <Set> tag are always moved together on the AdminTool.
Why do I see a yen sign (“¥”) in the English documentation?
This is a by product of document localization. These characters are the
equivalent of a backslash (“\”).
Example:
c:¥Program Files¥GlobalScan
Equals:
c:\Program Files\GlobalScan