GETUSERSFROMDIR

Overview

The GETUSERSFROMDIR workflow application lets you retrieve a username list, a user email list, or a user ID list. These lists are obtained from a WorkflowGen automatic system action that executes SQL queries on the WorkflowGen database. They can either be used for automatic notifications or to define the users of an action in a WorkflowGen process (by storing the output of GETUSERSFROMDIR as a data element and using the resulting data element to specify the users in the notification or action assignment).

Definitions

• The x character: The x character in some parameter names means that there can be more than one instance of the parameter. For example, QUERYx_CMD means there can be QUERY1_CMD, QUERY2_CMD, QUERY3_CMD, etc.

• Action: You must create a GETUSERSFROMDIR type WorkflowGen action to use this application.

List of available fields and macros for queries

Listed below are the fields and macros available for the queries created in the QUERYx_CMD parameters. They can be used in the conditions for these queries to filter their results.

📌 Examples

This example returns a username list of users in the province of Quebec:

This example returns a username list of users that have email addresses ending with advantys.com:

This example returns a username list of users in my group:

Using additional parameters

QUERY1_CMD: Executing an SQL query

Description

To execute an SQL query, you must add the QUERY1_CMD IN parameter to the action. If the parameter is empty or non-existent, no operation will be performed.

📌 Example

This example returns the Montreal username list in the RESULT_LIST parameter:

RESULT_LIST / QUERYx_RESULT_LIST: Retrieving queries results

Description

To get the result of all the queries (username list in string format), you must add the RESULT_LIST OUT parameter to the action. To retrieve the result by query, you have to add the QUERYx_RESULT_LIST OUT parameter for each query (associated to their process data).

📌 Example

This example returns the username list of Montreal, Toronto, and New York in the RESULT_LIST parameter. QUERY1_RESULT_LIST contains the username list of Montreal, QUERY2_RESULT_LIST contains the username list of Toronto, and QUERY3_RESULT_LIST contains the username list of New York. RESULT_LIST contains the usernames of all three QUERYx_CMD parameters.

QUERY1_DIR: Directory specification

Description

You can specify the user directory on which the query will be executed. You have to add the QUERY1_DIR IN parameter in the action. If this parameter has a NULL value or does not exist, the default directory is WORKFLOWGEN (or the directory specified as the default by an Administrator).

📌 Example

This example returns the username list of users in Montreal from the YourCompany directory into the RESULT_LIST parameter:

QUERYx_CMD: Using more than one query

Description

You can add queries in the same WorkflowGen action and retrieve all of the results in one complete list or in one list per query. You must add the QUERYx_CMD IN parameters, where x is the number of the query. To get the result of each query, you have to add the QUERYx_RESULT_LIST OUT parameters.

📌 Example

This example returns the username list of users from Montreal in the WORKFLOWGEN directory into the QUERY1_RESULT_LIST parameter, the username list of users from Montreal in the INTRANET directory into the QUERY2_RESULT_LIST parameter, and the complete username list from the two queries into the RESULT_LIST parameter:

QUERYx_TOP: Specify results maximum

Description

You can specify the maximum number of records returned by your queries by adding QUERYx_TOP as an IN parameter of the action. The query will not be able to return more results than the number specified in this parameter.

📌 Examples

This example returns only the first two usernames of the query:

This example returns all usernames from this query:

QUERYx_DEFAULT_VALUE: Specify a default value

Description

You can specify a default value to be returned for queries that return no values. You must add the QUERYx_DEFAULT_VALUE IN parameter in the action.

📌 Example

In this example, the query returns no value because the company entered does not exist, so the RESULT_LIST parameter will contain default1:

RESULT_SEPARATOR: Separator specification

Description

You can specify the character that will separate the result in the returned list by adding the RESULT_SEPARATOR IN parameter. The default separator is , (comma).

📌 Example

In this example, the RESULT_LIST parameter value is: name1***name2***name3:

RESULT_COUNT / QUERYx_RESULT_COUNT: Number of records returned

Description

You can retrieve the number of records returned for each query or for all queries. For the total number of records returned for all queries, you must add the RESULT_COUNT OUT parameter to the action. For the number of records per query, you must add the QUERYx_RESULT_COUNT OUT parameters to the action.

📌 Example

The following example returns the total number of records in the RESULT_COUNT parameter and the number of records of each query (QUERY1 and QUERY2) in the QUERY1_RESULT_COUNT and QUERY2_RESULT_COUNT parameters:

Using parameter conditions in SQL queries

Description

You can also use parameters in the SQL conditions contained in the QUERYx_CMD parameter. You must add IN parameters with different names for the following reserved parameters:

• QUERYx_CMD

• QUERYx_DIR

• QUERYx_TOP

You can then call these parameters in the condition by prefixing them with the @ character.

📌 Example

This example returns the username list from Montreal in the WORKFLOWGEN directory:

Remember that the parameter name used in the condition must have the same name as the one defined in the WorkflowGen action.

QUERYx_CMD: Using macros in SQL query conditions

Description

You are also able to use macros in the SQL conditions contained in QUERYx_CMD by adding an available macro in the condition.

📌 Example

The following example returns the username list of users who are members of the Dev group, members of the WORKFLOWGEN directory, and are in Montreal:

RESULT_LIST_EMAIL / QUERYx_RESULT_LIST_EMAIL: Retrieving the queries result in an email list format

Description

If you want to retrieve the emails of the usernames returned by the queries, you must add the RESULT_LIST_EMAIL OUT parameter to the action. If you want to retrieve the emails by query, you must add the QUERYx_RESULT_LIST_EMAIL OUT parameter to each query.

📌 Example

This example returns the Montreal and Toronto email list of Montreal and Toronto in the RESULT_LIST_EMAIL parameter. QUERY1_RESULT_LIST_EMAIL contains the Montreal email list and QUERY2_RESULT_LIST_EMAIL contains the Toronto email list:

Error management in WorkflowGen

To manage execution errors, you must add a corrective (debug) action linked to the GETUSERSFROMDIR action. This corrective action is a manual action and is executed upon an execution error. You must add this exception on the transition between the two actions. The following table lists the most frequent errors returned by the application.

Maximum returned records number

The GetUsersFromDirMaxResultNb parameter in the WorkflowGen web.config file specifies the maximum number of records that can be returned by a query.

This limit reduces the risk of a time limit expiration error that may occur when query results are too large. If the number of returned records is higher than this constant value, an error message stating that the queries returned too many records will be displayed.