Appendix D: Using Exit Points

WebDocs has a number of exit points where you can insert custom code to enhance the base functionality. This appendix describes the most common situations for using exit programs and provides best practices for creating your own.

Use the following resources and best practices when writing exit programs:

  • If you do not have the CL programming experience to write exit programs, contact RJS Software about CL programming services.
  • The sample source code for all the exit programs listed below is available in RJSIMAGE/SOURCE:

    WRKMBRPDM RJSIMAGE/SOURCE

    Copy the sample code into your own source file in another library and then compile to RJSIMAGE.
  • Exit programs must complete before control is returned to the user. To avoid interrupting users' workflow, submit lengthy operations as jobs. For example: Avoid making a user in RJS Imaging Scan Workstation wait until a fax machine processes a request.
  • By default, the sample source code contains minimal logging. RJS Software strongly recommends adding helpful error messages to your custom code. This will provide your users with meaningful errors should they encounter them, and it also makes troubleshooting easier if you encounter an issue and need to contact RJS Software technical support.
  • Make a record of any code changes you make for exit programs. You will need to recompile your exit programs when you upgrade to a new version of WebDocs.

The following exit programs are available in WebDocs iSeries:

Pre- and Post-Check-In Exit Programs

Pre- and Post-Update Exit Programs

Pre- and Post-Route Exit Programs

Post-Email Exit Program

Pre- and Post-Check-In Exit Programs

Any time a new document is added to WebDocs iSeries, from any interface, it calls the DOCCHKIN command. By default, DOCCHKIN calls two exit programs:

  • Pre-check-in exit program:DOCEXITPC runs before any changes are made to the WebDocs physical files and before any files are written to the final IFS destinations. This lets you verify or reject the metadata for incoming documents.

    For example:
    • If a search key for a Document Type needs to be a valid invoice number, the pre-check-in exit program can send a query to an ERP system to verify whether that invoice number exists. If the invoice number doesn't exist, you can have WebDocs either:
      • Not allow the check-in and give the user an error message.
      • Set a flag for someone to review the document after check-in.
    • After a user enters only two or three pieces of information, the exit program uses logic and queries to determine what the remaining search keys should be.
  • Post-check-in exit program: After the pre-check-in exit program has returned successfully, DOCCHKIN saves the file to the IFS and updates the physical files in RJSIMAGE. Then, it calls the post-check-in exit program, DOCEXITC. Because the document is now in WebDocs iSeries, the post-check-in exit program allows you to reference the IFS file or document ID when submitting jobs or executing commands.

    For example: On check-in:
    • Add the document to a route or workflow.
    • Email the document.
    • Fax the document.
    • Print document.

Note: Because these exit programs run at the command level, and therefore occur for all interfaces, make sure that code intended only for one Document Type does not run for all Document Types and that all logic is conditioned appropriately.

Pre- and Post-Update Exit Programs

Any time a document's information is updated in to WebDocs iSeries, from any interface, it calls the DOCINFOUPD command. By default, DOCINFOUPD calls two exit programs:

Caution: While document files are version controlled, the document information - such as titles and search keys - is not. If you incorrectly overwrite document information, you will need to restore the relevant physical files from your back-up.

  • Pre-update exit program:DOCEXITUPC runs before any changes are made to the WebDocs physical files or the IFS. This lets you verify or reject the modifications to documents' information.

    For example: If a user changes a search key to correct the invoice number, the pre-update exit program can send a query to an ERP system to verify whether the updated invoice number exists. If the invoice number does exist, the exit program can replace other related search keys. If the invoice number doesn't exist, WebDocs does not allow the check-in and gives the user an error message.

    Best Practice: Enforce rules on search keys (for example: make them required, read-only, and so on) as much as possible when you set up Document Types and search keys. This will reduce the amount of necessary exit programming.
  • Post-update exit program: After the pre-check-in exit program has returned successfully, DOCINFOUPD updates the document's information. Then, it calls the post-check-in exit program DOCEXITUC.

    For example: After updating a document's information:
    • Add the document to a route or workflow.
    • Email the document.
    • Fax the document.
    • Print document.

Note: Because these exit programs run at the command level, and therefore occur for all interfaces, make sure that code intended only for one Document Type does not run for all Document Types and that all logic has appropriate conditions.

Pre- and Post-Route Exit Programs

WebDocs calls the same two exit programs for each of the following routing events:

  • When a user adds a document to a route.
  • When a user approves a document.
  • When a user rejects a document.
  • When a user inserts another inbox in a route.
  • When a document completes a route.

Because these exit programs are being called in multiple places, you need to condition your code so that your exit programs only apply to the specific route, step, or action that you want them to. To help you do this, each exit program has parameters that define the current route, step, acting user, and action.

The two route exit programs are:

  • Pre-route exit program:DOCFLOWPXC is called before the routing action occurs.

    Note: This exit program is only available in WebDocs iSeries version 3.21.00 and above.

    The pre-route exit program has several parameters that the post-route exit program does not have, including parameters for all routing commands to simplify validation and modification.

    To block an invalid user action, set &ERRRTN to 1and then put an error message in&ERRRTNMSG, which will display for the user in the browser or client application.

    For example:
    • Prevent a user from rejecting a document on the first inbox in a route.
    • Prevent a user from rejecting a document and also sending it to the next user on the route.
    • Prevent a user from adding inboxes.
  • Post-route exit program:DOCFLOWEXC is called after the routing action occurs.

    For example:
    • Send custom email notifications.
    • Approve all related routing documents instead of the user having to approve each one separately.
    • Trigger a process when certain documents are approved.

Post-Email Exit Program

After a user sends an email from WebDocs iSeries, it calls thepost-email exit program,DOCEMEXITC.

For example: Send custom notifications after the email is sent.

 

Copyright © HelpSystems, LLC.
All trademarks and registered trademarks are the property of their respective owners.
4.0 | 201802260747 | February, 2018