Revision history:

Introduced in QPR 7.5.1

 

Returns a list of IDs of actions defined by search parameters and filter criteria. First actions are fetched based on search parameters. Then the list of found actions is filtered based on filter criteria which is an optional parameter. Bookmarks, Booklets, and other Portal internal objects are not supported.

 

Synopsis:

Actions.Find(Parameters, Criteria, SortBy, out ActionList)

 

Parameters:

 

Parameters: A semicolon-separated list of parameters for defining the search base. Supported keywords are:

•PRODUCT = PG | SC | PORTAL, Can be omitted only if both MODELIDS and OBJECTIDS are empty.

•MODELIDS = Comma-separated list of model IDs. If this is omitted, the default value "" (all models) is used.

•OBJECTIDS = Comma-separated list of object IDs. If this is omitted, the default value "" (all objects) is used.

•ACTIONTYPES = Comma-separated list of action type names or IDs. If this is omitted, the default value "" (all action types)  is used. Supported action type names: COMMENT, ACTIONPLAN, LESSON, DOCUMENT, RISK, STRATEGYITEM, EMBEDDEDATTACHMENT, LINKEDATTACHMENT, and the name of any customized action type with spaces removed from it.

•PARENTS = Comma-separated list of action IDs. If this is omitted, the default value "" (parents are ignored) is used. If this is NULL, actions that have no parents are searched for.

•EXTERNALPARENTS = Comma-separated list of external (i.e. non-action) parent IDs. If this is omitted, the default value "" (parents are ignored) is used. If this is NULL, actions that have no external parents are searched for. The external parent ID string is in the same string format that Portal uses e.g. “(<product id>_0_<model id>_<object id>)”.

•IDS = Comma-separated list of action IDs. If this is omitted, the default value "" (all actions are processed provided that other parameters match) is used. This parameter specifies the action IDs of the actions on which the search is based on.

•INCLUDECHILDREN = 0 | 1. If this is omitted, the default value 0 is used. Defines whether the search covers also possible child actions of the actions included in the search base.

Criteria: An expression that must return true for an action in order for it to be returned in the result list. Supported expressions include:

•Logical operators: AND, OR, NOT. Note that these are case sensitive, so only the uppercase versions work.

•Binary comparison operators: =, <>, <, <=, >, >=

•Mathematical operators: +, -, *, /, ^

•String constants using double quotes: “string constant”

•Parentheses to group expressions and enforce calculation order: ()

•Find function:

oExpression: Find(<what>, <attribute>)

•Parameters:

▪<what> = Text to match (usually a string constant)

▪<attribute> = Action attribute (see list of supported attributes below)

oReturn value: True if the text is found in the given action attribute.

•Any combination of these:

oFind(“Not categorized”, Category) OR (Creator.LoginName = “qpr”)

Note: Since string constants are defined using double quotes in VBScript, they must be escaped correctly (by doubling the double quotes).

 

Note: Date-based searches should be done using the following form: iResult = SCApplication.Actions.Find("","Value(CreatedDate) >= EncodeDate(2006, 1, 1)", "", olResults)

 

SortBy: A comma-separated list of action attributes possibly prefixed by a dash ("-“) character. SortBy defines the output list order. If SortBy is an empty string then actions are not sorted at all, meaning that the order of elements may differ between successive runs. If an action attribute is prefixed with a dash, then that action attribute is used for descending sorting. Otherwise ascending sorting is used. See the list of supported attributes below.

out ActionList: Variant for storing an array which contains the actions matching the search base and sorted in the order defined by the SortBy parameter.

 

Supported attributes:

•Id: Integer.

•FullId: String. ID in external object ID format, i.e. <product_id>_0_<model id>_<object id>

•Header: String.

•Description: String.

•Type: Integer.

•TypeName: String.

•ModifiedDate: DateTime.

•CreatedDate: DateTime.

•Creator.Id: Integer.

•Creator.LoginName: String.

•Creator.FullName: String.

•Modifier.Id: Integer.

•Modifier.LoginName: String.

•Modifier.FullName: String.

•PublishType: Integer. Defines the users for who the action is published. 0 = action's creator, 1 = parent element users, 2 = selected users, 3 = all.

•PublishForUsers: Integer | String. Either an integer array or a comma-separated list of user IDs for who the action is published. This is valid only if PublishType is 2.

•ParentActions: String. A comma-separated list of parent action IDs.

•ChildActions: String

•Category: String.

•Owner.Id: Integer.

•Owner.LoginName: String.

•Owner.FullName: String.

•AssignedTo.Id: Integer

•AssignedTo.LoginName: String.

•AssignedTo.FullName: String.

•ApprovedBy.Id: Integer.

•ApprovedBy.LoginName: String

•ApprovedBy.FullName: String

•StartDate: DateTime.

•Deadline: DateTime.

•Status: String.

•Progress: Integer | Float.

•Version: String.

•EmbeddedData: String.

•LinkedLocation: String.

•ValidFrom: DateTime.

•ValidTo: DateTime.

•Severity: String.

•IdentifiedBy.Id: Integer.

•IdentifiedBy.LoginName: String

•IdentifiedBy.FullName: String

•Identified: DateTime.

•Probability: String.

•ImpactMinimization: String.

•Mitigation: String.

•Impact: String

•Rating: String.

•Notes: String.

•ExternalParentObjects: String. A comma-separated list of external object IDs (<product_id>_0_<model id>_<object id>).

 

NOTE: The listing above assumes that the default actiontypes.ini is used. With customized actiontypes.ini files some default attributes can be missing or additional ones available.

 

Required Rights:

 

View rights to actions.

 

Return Values:

Below are listed the return values that this function can return:

 

RV_SUCCESS

RV_ACCESS_DENIED

RV_UNKNOWN_ERROR

RV_APPLICATION_QUIT_CALLED

RV_NOT_CONNECTED_TO_SERVER

RV_NOT_AUTHENTICATED

 

Example Procedure:

 

iRet = SCApplication.Actions.Find("PRODUCT=SC;ACTIONTYPES=Actionplan,comment", _

        "Creator.LoginName = ""jsmith""", "Header", olResults)

'Finds all action plans and comments connected to SC elements and created by jsmith

'and sorts them by header.