Results Command

Menu: Found in the Tools menu

Analyzer offers a Results command in the Tools menu that can be used to send results to the Results Manager.

The Results command can only be used in conjunction with the Results Manager system (RM).

The Results command and the associated Results Manager are typically used as part of a continuous monitoring strategy.

For specific information on the Results Manager system, see the Arbutus Results Manager Installation and User Guides.

It is a recommended best practice that the Results command be utilized as part of a scheduled job on the Arbutus Hub Server (i.e. as part of a continuous monitoring process), rather than as part of a sporadically run interactive job.

The Results command can be issued from local procedures, workflows or scheduled jobs on the Arbutus Hub Server to send and assign identified results to an individual or group (i.e. to review and address identified results) within the RM system.

The Results command sends one or more identified initial results into the RM system to be addressed.

The output options for the Results command are:

•

(Default) - Add individual results to the RM system for each separately identified initial result within the open results table. If there were a large number of customers whose AR balances exceeded their credit limits, each of these customers would be assigned as individual items in the RM system that could be addressed separately by one or more individuals. This means that each result could be individually addressed and closed independently of the other results.

•

(Optional - Single Item) – The optional keyword Single adds a single initial result to the RM system so that the result can be addressed by a single individual. For example, if a result was identified that a customer’s AR balance had exceeded its credit limit, the best (recommended) use of the attachment option would be to attach a PDF of a specific customer’s detailed AR statement to assist with assessing and closing the individual result. Alternatively, results for a set of customers could be bundled and attached as list that is entered as a single result in the RM system. This may be very inefficient (especially if the attached list contains a large number of customers with results) as this approach requires that one individual must assess and address all results in the attached list before the result entry in the RM system can be closed.

The Results command cannot be issued from within a Group command.

Parameters

The Results command has the following mandatory and optional command parameters, some of which must be initially defined within the RM system.

The Results command does not support use of the If or While parameters. Users should first create a table of results, using the same If or While parameters, prior to issuing the Results command. When using the Single command parameter this is probably not relevant.

Since the Result command parameters can be entered as constants, if all supplied parameters are constants then the Results command will only output one record as the parameter values will not change.

Workflow Name

A mandatory Workflow keyword that specifies the name of the RM workflow (as defined in the RM system, for example "AP Results"). This is selected/specified via a pull down selector listing existing Workflow names from the RM system.

Creator

A mandatory Creator keyword that specifies the owner/creator of the result (for example a procedure name like "AP_01").

Single Item

An optional Single keyword that specifies that only a single result will be created.

ID

A mandatory Reference keyword that specifies a reference value (for example an account number like "123456") - basically any relevant reference number like an employee, customer, PO, invoice or vendor number. The maximum length is 60 characters.

Amount

An optional Number keyword that allows the user to associate a specific numeric value with the result, such as an invoice amount or any other relevant numeric data, so that results can be ranked by size. When included, this value can then be compared to a second result field within the RM system itself, which may be filled in by RM users as each result is processed (where this makes sense). For instance, when used in this way the difference between the two could then be derived, for example to determine the actual amount of the error.

Description

A mandatory Description keyword that specifies a meaningful description (for example "AP Vendor Missing Address") that adequately describes the result within the RM system. This may include a field name or a concatenated set of fields. The maximum length is 1000 characters.

Attachments

An optional Attachment keyword that specifies an attachment (for example "C:\DATA\AP\Vendors_Missing_Address.xlsx") – you can use either relative pathing from the project root or absolute pathing to specify the location of the attachment

Note

An optional Note keyword that allows the creation of an initial note for the result. Notes can be up specified up to a maximum length 32,000 characters.

Priority

An optional Priority keyword that specifies the results priority (the range is from 1-9 where 1 is the highest priority). If not specified, the default priority is 5. This allows results to be sorted by priority within the RM system

Type

An optional Type keyword that allows a single character (like "A" or "B", etc.) to be assigned to results – this allows results to be sorted by Type within the RM system.

Max Limit

An optional Errorlimit keyword that species the error limit (the default is 20). The error limit is a fail-safe value that expresses the maximum number of reasonably expected results. If the number of actual results exceeds the specified error limit then something has gone wrong in the process (most likely faulty data or an incorrect data file was processed, etc.). If the specified error limit is exceeded, a fatal error will occur to alert you that there were an unreasonable number of results encountered which should be investigated. No results will be sent to the RM system if the specified error limit is exceeded.

Assignee

An optional Select keyword that provides a more detailed specification of who or where to assign the result.

For more detailed examples and best practices for using the Select parameter, see the Results Manager User Guide and review the Group and Workflow sections. Of specific interest is the sub-section on Assigning Ownership to Workflows.

There are two Select options:

1. Specify an individual’s RM system name (as "*name"), or

2. Specify an existing group name (as "group" from the pre-set list of group names assigned to the various processes defined for the workflow within the RM system).

Usage of the Select options ensure that a result is either assigned to a specific individual (regardless of the specified process) or to a suitable individual who is a member of a specific group ("audit", "finance", etc..) or sub-group for the initial process specified within the RM system.

The user must know the exact individual’s RM system name or the exact group name as specified in the RM system.

For generic command parameters, see Command Parameters. For a description of supported field modifiers see Field Modifiers.

Form

For some workflows, there is an initial form with optional questions that users can choose to answer. Filling in the form is optional because the form can also be completed later within the RM system by the assigned user. Typically, users will fill in the portions of the form where the required information is known or available to them.

To answer questions in the form, simply click the Supply Form Information button to load the form.

The user can choose which questions in the form that they wish to answer. For any question, a user can either choose an answer or supply a value. Alternatively, if a table is open, the user can choose a field from the field pull down menu to supply the answer based on the fields value for records outputted by the Results command.

The field pull down menus only appear if a table is open.

Fields listed in the pull down menu are supplied from the open table. When choosing fields from the pull down menu to answer a question, the fields displayed in the pull down menu are provided based on how the question is being asked.

For example:

•

Questions using radio buttons generate numeric values, so the fields in the pull down menu must be numeric fields

•

Questions using check boxes generate true or false values, so the fields in the pull down menu must be logical fields

•

Questions using text boxes generate text values, so the fields in the pull down menu must be character fields

•

Questions using date selectors generate a datetime value, so the fields in the pull down menu must be datetime fields

Command Mode Syntax

RESULTS

WORKFLOW "RM workflow name"

CREATOR "name-maximum-length-59"

REFERENCE "reference number-maximum-length-19"

DESCRIPTION "description-maximum-length-255"

<FORM "question1" "answer1" "question2" "answer2" ... ¿

The Results command cannot be issued from within a Group command.

Examples

Results command syntax specifying errorlimit:

RESULTS WORKFLOW "AR" CREATOR "AR01-Over Credit Limit" REF custno DESC custname ERRORLIMIT 100¿

Results command syntax specifying attachment:

RESULTS WORKFLOW "AR" CREATOR "AR01-Over Credit Limit" REF custno DESC custname SINGLE ATTACHMENT “c:\data\list.xlsx”¿

Results command syntax specifying a select parameter for a specific user:

RESULTS WORKFLOW "AR" CREATOR "AR01-Over Credit Limit" REF custno DESC custname SELECT "*Joe Smith"¿

Results command syntax specifying a select parameter for a specific group:

RESULTS WORKFLOW "AR" CREATOR "AR01-Over Credit Limit" REF custno DESC custname SELECT "Denver"¿

Results command syntax showing a form parameter detailing the users form responses:

RESULTS WORKFLOW "AR" CREATOR "AR01-Over Credit Limit" REF custno DESC custname SELECT "Denver" FORM "RadioButtonControl" "Vancouver" "NumericscaleControl" "84" "CheckboxControlEmpty" "F" "" "T" "DropdownControl" "Evening" ¿

Allocation of Results

It is important to note that each defined workflow in the RM system has an initial state that will specify the individual or group to receive the result(s) for that process by default. If the initial state specifies an individual, then that individual will receive all results for that workflow. If the initial state specifies a group, then the results will be allocated amongst the members of the group using the allocation method specified for the workflow within the RM system.

Errors

A fatal error will occur if:

•

The specified workflow parameter is incorrectly specified

•

The attachment name and / or path is invalid

•

The RM server has not been specified (an RM server profile does not exist or is incorrectly configured)

•

The number of actual results exceeds the maximum number of expected results specified by Errorlimit parameter (or the default value of 20)

General Rules

The following lists some general rules of the Results command and the RM system:

•

If the Results command is run from the Analyzer client, the attachment file must be accessible from the client. If you are scheduling the job on the Arbutus Hub Server then it must be accessible from the server Analyzer.

•

The Reference and Description parameters can be specified as field names from the open table, where it is reasonable that the field value might change for each record (result) added.

•

The Priority and Select parameters may also reference fields from the open table. For example, you might specify a numeric computed field in the Priority parameter that sets the priority for the results being added, or you might reference a Region field in the Select parameter if this corresponds to the pre-specified Group list in the RM.

•

Parameter specifications discussed above may be character constants, variables, fields from the first row of the table or any mixture. If they are fields or variables, then any of character, date or numeric may be used, and will be converted to character (with the exception of the PRIORITY parameter which must be numeric).

•

If you do not specify the Single keyword, then each row in the open table will generate a distinct result in the RM system. Presumably one or more of the parameter fields is a column in the open table, otherwise you will get 'n' identical results.

•

If you specify an Attachment, then the attachment will be separately added for each of the results. If the attachment is a constant, then the same attachment will be added to each item. If the attachment reference is a field, then you may be able to specify unique attachments for each result.

•

If you specify Select "*name" then the result will be allocated to the named individual, whether or not they belong to the process group defined to receive results. If the (case insensitive) name is not found then the result will be allocated as if there were no SELECT.

•

If you specify Select "additional-group-name", and the specified process initially assigns to a group, then the system will attempt to allocate to the subset of the receiving group that is also a member of the sub-group “additional-group-name”. If there are no group members that are also a member of “additional-group-name” sub-group then the allocation will be made as if there were no Select parameter.

RM Server Profile

The RM system uses a special server profile. This server profile is defined within Analyzer in the same manner as any other server profile, EXCEPT that the Results Manager Server check box in the lower right of Server Profile dialog must be selected. You can only have a single RM system installed on the server and therefore can only designate one server profile as the RM server profile. You will get an error if you try to designate more than one RM server profile.

The designated RM server profile is automatically excluded from any server lists (in particular for commands), and can only be viewed and modified within Analyzer's server profiles dialog. This means that you cannot use the designated RM server profile as a target for output from any Analyzer commands (like Extract or Export), even if the RM system is installed on the same physical box as your Arbutus Hub Server. If you want command output to go to this server, then you will need to create and use an undesignated copy of your designated RM server profile (for example naming it “RM_Server_Alternate” or “RM_Server_Output”).

For more information see Results Manager and Creating a Server Profile