Workflo!Approval Troubleshooting


Table of Contents:

What Do I need to do to install Workflo!Approval?
How do I add Workflo!Approval to a form that I have already developed.
Can I use Workflo!Approval in a Web Browser environment?
What is an Approval Profile Document?
When should the Process Immediately be set to Yes in the Profile?
When the ACProcessAction agent runs the document is processed but no email is sent.
Can I develop a Complex routing that is composed of multiple steps?
How do I dynamically assign a list of Approvers upon submission?
What is the function of the Approvers Automation?
How do I create a custom transaction and where would I use it?
What does the Agent Log View do?
I get a Notes Exception Error when opening a web document


What Do I need to do to install Workflo!Approval?
Back to top

Workflo!Approval comes with an Install/Upgrade action, that will install all of the necessary components into and existing database, or create a new database. When the Install/Upgrade is run it will overwrite any existing components if they exist, or copy new design components. If you are installing into an existing database you may not want to copy the demo components into your database. If so select the Demo action and it will Select/De-Select the demo components.
Once the install is completed sign the database with an ID that has Manager access to the Database and the role [ACAdmin], it is advisable to do this with the Servers ID or with a Super User ID that you create just for this purpose. Generally anyone who uses the database should never enter the database with ACL access higher than Author. Higher access will negate most of the security features. The [ACAdmin] role allows the user to see and Edit all documents, plus perform a number of functions that should be reserved for an administrator.


How do I add Workflo!Approval to a form that I have already developed.
Back to top

To add Workflo!Approval to an existing form follow the these simple steps.
  1. Create an Approval Profile that will define how you want the process to function. In most cases the default settings will be a good starting place (the profile parameters can be changed later). Make sure that you add the names/group/role of the people that you want to act as approvers of your document.
  2. Create a hidden field called ACProfileName on your form and have it default to the Profile Name that you created in the previous step.
  3. Add a Computed Subform with the formula of "ApprovalCycle". You will notice there are two SubForms with the alias of "ApprovalCycle" one is visible to the Notes Client and the other to the Web Client. This way the Form will always open the correct SubForm depending on the client type.
  4. Enable the AC Process Action Agent.
  5. Create a Document and click Submit For Approval.

Can I use Workflo!Approval in a Web Browser environment?
Back to top

The Workflo!Approval Subforms and actions are all fully web enabled. An end user can do anything with a Web Browser that a Notes client user can do. The form and actions that you create must be compatible with the Web Browser.
There is a setting in the Approval Profile that may need to be set. Set the "Generate HTML for all Fields" on the technical tab of the profile if you do not have it set on your form.
Workflo!Approval has been used in many mixed environments of Web Browser and Notes Clients without difficulty.

What is an Approval Profile Document?
Back to top

Database may contain any number of Profile Documents that are used to control how a process functions. There are numerous fields that control how a document is routed, how the document is accessed, Notification, etc. Through out the profile document you will see click on any of these will display a detailed context help. Take some time to browse through a profile document and look to the help.

When should the Process Immediately be set to Yes in the Profile?
Back to top

When an action is triggered (Submit/Approve/Deny/etc) a transaction document is created of the appropriate 'type'. The AC Process Action Agent then processes the transaction. This done so the end user never needs more than Author access to the database and never needs to edit the request document (except as the creator). If there is no chance of more than one person being able to modify a document at the same time then Process Immediately can be set to Yes, otherwise it MUST be set to No or else there is a high probability of Save/Replication Conflicts that will be very difficult to resolve.

Problem Situations:
  1. If a document is routed in a parallel process. All people in the Approvers List are possibly active Approvers at the same time.
  2. When replica copies of the database reside on more than one server, then the AC Process Action Agent must be set to run on only one of the replica servers and Process Immediately must be set to No.

In some cases when there are a lot of notifications to be sent and/or there are numerous other actions that might be taken, you may want to set Process Immediately to No so that control is returned to the end user quicker.


When the ACProcessAction agent runs the document is processed but no email is sent.
Back to top

When the ACProcessAction agent runs it is run as a background agent and therefore looks in the Notes.ini for the location of the mail server. There must be an entry in the Notes.ini similar to this MailServer=CN=Your Server/O=Your Organization. Without this entry everything will work correctly but no mail will be sent. If the agent is run manually by a user with the role [ACAdmin] and Manager rights to the database mail will be sent because Notes is using the settings in the current Location Document.

Newer installs of the Domino Server automatically include the MailServer= line in the Notes.ini but we frequently find that it is missing from established Domino Servers. This only impacts background agents that send mail so is frequently not identified until a product like Workflo!Approval is added to the server.

Can I develop a Complex routing that is composed of multiple steps?
Back to top

Yes!
Create a Profile Document for each of the steps in your routing process. Lets call them StepOne, StepTwo and StepThree.
On the Post Cycle Tab of the StepOne profile we will specify that on Approval to start a new cycle and to change the Profile Document to StepTwo. Then on the StepTwo Profile Document specify On Approval to start a new cycle and change the Profile Document to StepThree.

You will notice that you can have decision points at each of these points and only start the new cycle based on a formula. So that if the Cost field on your form is greater than 10000 start StepTwo otherwise end the process with the document approved.

You can also specify that the Profile Document is defined by a formula So that if Cost is Less than 10000 us profile StepTwo if greater than 10000 use StepThree.

The number of 'Cycles' in the overall process are not limited, so you can define any number of profiles and link them together. In addition the process can be controlled by creating custom LotusScript code that modifies the Approvers, Profile and Form used. Custom transactions is discussed in a further FAQ.--> Database 'Approval FAQ', View 'All FAQs', Document 'How do I create a custom transaction and where would I use it?'

How do I dynamically assign a list of Approvers upon submission?
Back to top

There are two user defined fields (ACApproversDefaultPre and ACApproversDefaultPost) and if they contain a list of names they will be concatenated with the Approvers List in the Profile Document. The order will be ACApproversDefaultPre + ACApproversList + ACApproversDefaultPost.

The Demo form "XYZ Authorization (Dynamic)" demonstrates how the ACApproversDefaultPre/Post can be used to look up and return a list of Approvers from a view of the XYZ Routing Rules. You can extend this to return the Approvers from wherever you might have them.

What is the function of the Approvers Automation?
Back to top

The Approvers Automation allows you to set up automatic process for an individual. An Automation Document may have a start and end date during which the automated process will function. Some of the uses for Automation are:
  1. Create a proxy for a person while they are away on vacation, so that during the period that the automation document is active approval documents can be automatically delegated to another person.
  2. A Manager may want all request with a value of less than a certain amount are delegated to his/her assistant, while request greater than that amount are routed normally.
  3. A Manager may give his/her department member a specified spending limit so that all requests less than the limit are automatically Approved, while request greater than the limit will be routed for approval.
  4. The demo has an example where if the Current Approver is the Originator then it is automatically approved.

There are numerous other possible applications that will depend on your specific requirements.

How do I create a custom transaction and where would I use it?
Back to top

Custom transactions are LotusScript code that you write to control the routing at various points through out the process. On the Post Cycle tab of the Profile document there are several places where you can specify to run a user defined action. For example you can specify to run a piece of LS code Post Approval or Post Denial, in addition there a number of other places where you can execute Post Action 'hooks'.

For example if you enter "PostApproval" in the After Approval Create Custom Transaction field. When the AC Process Action Agent executes and a request document receives final approval it will create a transaction with an ACAction of type "PostApproval". AC Process Action will then try to process the action but it is not a recognized ACAction type. The Agent will then pass it to the OtherTransaction function in the AC Other Transactions script library. You can then place any LS code that you write in that library. This code could update information in a different database, or update another none Notes/Domino system.

What does the Agent Log View do?
Back to top

Every time the AC Process Action Agent runs it generates a document into the Agent Log View. The document contains details of what was done during that particular iteration. In event of any unusual action this should be the first place that you look to find if any errors have occurred. Also note that you need to have the Purge Agent Log agent enabled or this view can become very large. The Purge Agent Log removes documents more than seven days old.

I get a Notes Exception Error when opening a web document
Back to top

If you get a Notes Exception Error of Special database object cannot be located when you first try to open a document on the web it is because there is no About Document and the Database Properties is set to open this document. You can resoleve this by: