Searching processes and tasks

A TWSearch query includes the following steps.

1. Define the columns of data that you want to retrieve. See Columns.
2. Define any filters that you want to apply to a column. See Search filters.
3. Define the sort order for the returned records. See Search result order.
4. Define how results are organized. See Search result organization.
5. Execute the search and parse the results into a list of complex variables. See Search execution.

All columns, conditions, and sort criteria are held by a TWSearch object.

var search = new TWSearch();

Each column that you want to return is defined as a TWSearchColumn object. The following code sample defines a column that returns the identifier of a process instance.

var colInstanceId = new TWSearchColumn();
colInstanceId.type = TWSearchColumn.Types.ProcessInstance;
colInstanceId.name = TWSearchColumn.ProcessInstanceColumns.ID;

Each column has a type and a name. The most common types are ProcessInstance, Task, and BusinessData.

TWSearchColumn.Types.ProcessInstance
TWSearchColumn.Types.Task
TWSearchColumn.Types.BusinessData

In the following example, a column for business data is named serviceOrderNumber.

var colServiceOrderNumber = new TWSearchColumn;
colServiceOrderNumber.type = TWSearchColumn.Types.BusinessData;
colServiceOrderNumber.name = "serviceOrderNumber";

You can search for arrays of columns, as follows.

search.columns =
     new Array(
       colInstanceStatus,
     colInstanceId,
     colInstanceName,
     colTaskId,
     colTaskStatus,
     colClosedDateTime,
     colDueDateTime,
     );

You can apply filters to any column by defining conditions. You define each condition as a TWSearchCondition object. For example, the following code sample defines a column that retrieves the name of a process instance and then narrows down the results to process instance names that start with Service Order Fulfillment.

var colInstanceName = new TWSearchColumn();
colInstanceName.type = TWSearchColumn.Types.ProcessInstance;
colInstanceName.name = TWSearchColumn.ProcessInstanceColumns.Name;
     
var condInstanceName = new TWSearchCondition;
condInstanceName.column = colInstanceName;
condInstanceName.operator = TWSearchCondition.Operations.StartsWith;
condInstanceName.value = "Service Order Fulfillment:";

When you create a date condition by using a TWDate object, you must first convert the date to a string when you construct the condition. The following code sample defines a column to return the due date of the task, and then a defines a before and an after due date condition.

var colDueDateTime = new TWSearchColumn;
colDueDateTime.type = TWSearchColumn.Types.Task;
colDueDateTime.name = TWSearchColumn.TaskColumns.DueDate;
  
var condDueDateTimeBefore = new TWSearchCondition;
condDueDateTimeBefore.column = colDueDateTime;
condDueDateTimeBefore.operator = TWSearchCondition.Operations.LessThan;
condDueDateTimeBefore.value = tw.local.dueDateBefore.format("MM/dd/yyyy HH:mm:ss", "PST");
 
var condDueDateTimeAfter = new TWSearchCondition;
condDueDateTimeAfter.column = colDueDateTime;
condDueDateTimeAfter.operator = TWSearchCondition.Operations.GreaterThan;
condDueDateTimeAfter.value = tw.local.dueDateAfter.format("MM/dd/yyyy HH:mm:ss", "PST");

The previous example also shows that you can define multiple conditions on a single column. To determine the results, the search applies all the conditions as an array of inclusive conditions (implicit AND operator).

var conditions = new Array(condInstanceName, condInstanceStatus, condTaskStatus);
search.conditions = conditions;

If your search conditions are dynamic, you can take advantage of the JavaScript array push method, as shown in the next code sample.

var conditions = new Array(condInstanceName, condInstanceStatus, condTaskStatus);
 if(tw.local.fieldRepIdentifier != "All") {
 conditions.push(condFieldRepIdentifier);
 }
 search.conditions = conditions;

You can define ordering criteria for any column. Each ordering is defined as a TWSearchOrdering object. For example, the following code sample lists the retrieved process instance identifiers in ascending order.

var orderInstanceId = new TWSearchOrdering();
orderInstanceId .column = colInstanceId;
orderInstanceId .order = TWSearchOrdering.Orders.Ascending;

Your search holds an array of all the ordering criteria to be applied to the results.

search.orderBy = new Array(orderInstanceId );

You must also specify whether the results should be organized by process instance or by task. To do so, you use the TWSearch.organizedBy object. The behavior is the same as that of saved searches in Process Portal. If you choose to organize by process instance, you get only one result per process instance. The following code sample organizes search results by task.

search.organizedBy = TWSearch.OrganizeByTypes.Task;

After you have specified the columns, conditions, ordering, and organization for the search, you can execute it to retrieve an array of JavaScript rows.

var results = search.execute();

The execute method returns TWSearchResults objects.

The following code parses the native JavaScript array to create an array of custom variables.

tw.local.serviceOrderTasks = new tw.object.listOf.ServiceOrderTask();
 for(var i = 0; i < results.rows.length; i++) {
   var row = results.rows[i];
   tw.local.serviceOrderTasks[i] = new tw.object.ServiceOrderTask();
 
   tw.local.serviceOrderTasks[i].processInstanceId = row.values[0].toString();
   tw.local.serviceOrderTasks[i].processInstanceName = row.values[1].toString();
   tw.local.serviceOrderTasks[i].taskId = row.values[2].toString();
   tw.local.serviceOrderTasks[i].taskStatus = row.values[3].toString();
   if(row.values[4] != null)
   {
     tw.local.serviceOrderTasks[i].closedDate = row.values[4].toString();
   }
   if(row.values[5] != null)
   {
     tw.local.serviceOrderTasks[i].dueDate = row.values[5].toString();
   }
 }