Skip navigation links

oracle.bpel.services.workflow.activityguide.query
Interface IAGQueryService

public interface IAGQueryService

 This class provides a programmatic means for retrieving AGDisplayInfo objects, which contain 
 metadata info, instance info, and associated tasks for an AG instance. 
 The AGDisplayInfo objects can then be used by the UI layer to construct the AG tree structure.
 
 A typical usage would be as follows:
  1. Use an authentication method to authenticate a user and obtain a context
  2. Use the context and an AGDisplayInfo list method to retrieve AG instances that match 
     some filter criterion
  3. Use the context and an AGDisplayInfo details method to retrieve a full blown AGDisplayInfo 
     object, which contains instance info, metadata info, and associated tasks, for an 
     AGInstance in the list
  
 A sample code fragment that shows the usage in the above pattern in shown below:
 
   import java.util.ArrayList;
   import java.util.Date;
   import java.util.List;    
   import oracle.bpel.services.workflow.IWorkflowConstants;
   import oracle.bpel.services.workflow.client.IWorkflowServiceClient;
   import oracle.bpel.services.workflow.client.IWorkflowServiceClientConstants;
   import oracle.bpel.services.workflow.client.WorkflowServiceClientFactory;
   import oracle.bpel.services.workflow.repos.Ordering;
   import oracle.bpel.services.workflow.repos.Predicate;
   import oracle.bpel.services.workflow.repos.TableConstants;
   import oracle.bpel.services.workflow.task.model.Task;
   import oracle.bpel.services.workflow.verification.IWorkflowContext;     
   import oracle.bpel.services.workflow.activityguide.query.model.AGDisplayInfo;
   import oracle.bpel.services.workflow.activityguide.query.model.MilestoneDisplayInfoType;
   
   //User whose AGDisplayInfo list needs to be queried
   String userid="jstein";
   // Password for the user
   String password = "welcome1";
   
 
   // Get workflow service client
   IWorkflowServiceClient wfSvcClient = WorkflowServiceClientFactory.getWorkflowServiceClient(WorkflowServiceClientFactory.SOAP_CLIENT);
   // Get the workflow context
   IWorkflowContext wfCtx = wfSvcClient.getTaskQueryService().authenticate(userId, password, 
                                 oracle.tip.pc.services.identity.config.ISConfiguration.getDefaultRealmName(),
                                 null);
   // Admin can authenticate on behalf of another user
   //IWorkflowContext adminCtx = wfSvcClient.getTaskQueryService().authenticate(adminUserId, pwd, 
   //                              oracle.tip.pc.services.identity.config.ISConfiguration.getDefaultRealmName(),
   //                              userId);
   
   IAGQueryService agQuerySvc = wfSvcClient.getAGQueryService();      
   
   // Only for SOAP clients and it is mandatory for SOAP clients
   Predicate.enableXMLSerialization(true);
   
   // Build the predicate
   Predicate statePredicate = new Predicate(TableConstants.AGINSTANCE_STATUS_COLUMN,
                                Predicate.OP_NEQ,
                                IAGConstants.AG_STATE_INPROGRESS);
   Predicate datePredicate = new Predicate(TableConstants.AGINSTANCE_CREATIONDATE_COLUMN,
                                Predicate.OP_ON,
                                new Date());
   Predicate predicate = new Predicate(statePredicate, Predicate.AND, datePredicate);
   
   // Create the ordering
   Ordering ordering = new Ordering(TableConstants.AGINSTANCE_TITLE_COLUMN, true, true);        
     
   // List of AG display columns
   // For those AG instance columns that are not specified here, the queried AGDisplayInfo object will not 
   // hold any value.
   // For example: If TITLE is not specified, agDisplayInfo.getAGInstanceInfo().getTitle() will return null
   // For the list of most comonly used columns, check the table below
   // Note: CIKEY is fetched by default. So there is no need to explicitly specify it.
   List agQueryColumns = new ArrayList();
     agQueryColumns.add("IDENTIFICATION_KEY");     
     agQueryColumns.add("TITLE");
     agQueryColumns.add("CREATOR");
     agQueryColumns.add("CREATION_DATE");
     agQueryColumns.add("STATUS");

   List agDisplayInfosList = agQuerySvc.queryAGDisplayInfos(wfCtx,
                               agQueryColumns,
                               IAGQueryService.AGAssignmentFilter.MY,
                               predicate, 
                               ordering, 
                               0,0); // No Paging
                               
   // How to use paging:
   // 1. If you need to dynamically calculate paging size (or) to display/find 
   //    out the number of pages, the user has to scroll (Like page X of Y)
   //      Call queryAGs to find out the number of AGDisplayInfos it returns. Using this 
   //      calculate your paging size (The number of AGDisplayInfos you want in a page)
   //      Call queryAGs successively varing the startRow and endRow params.  
   //      For example: If the total number of AGDisplayInfos is 30 and your want a paging size
   //      of 10, you can call with (startRow, endRow): (1, 10) (11, 20) (21, 30) 
   // 2. If you have fixed paging size, just keep calling queryAGDisplayInfos successively with 
   //      the paging size (If your paging size is 10, you can call with (startRow, endRow): 
   //      (1, 10) (11, 20) (21, 30) (31, 40).....  until the number of agDisplayInfos returned is 
   //      less than your paging size (or) there are no more AGDisplayInfos returned     

   if (agDisplayinfosList != null) { // There are AGDisplayInfos 
     System.out.println("Total number of AGDisplayInfos: " + agDisplayInfosList.size()); 
     System.out.println("AGDisplayInfo List: ");
     AGDisplayInfo agDisplayInfo = null; 
     for (int i = 0; i < agDisplayInfosList.size(); i++) { 
       agDisplayInfo = (AGDisplayInfo) agDisplayInfosList.get(i);          
       System.out.println("AG IdentificationKey: " +  agDisplayInfo.getAGInstanceInfo().getIdentificationKey());
       System.out.println("AG Status: " +  agDisplayInfo.getAGInstanceInfo().getStatus());
       System.out.println("AG Title: " +  agDisplayInfo.getAGInstanceInfo().getTitle());
       System.out.println();
     }

     // Now get the full blown AGDisplayInfo object for the first AGDisplayInfo in the list
    
     // Get the cikey for the AG  
     long ciKey =  ((AGDisplayInfo) agDisplayInfosList.get(0)).getCiKey();

     // Define the task display columns for any tasks that are returned by the query
     // Since tasks have many columns and multiple tasks may be returned by this query, the column list is 
     // needed to confine the result set to avoid unnecessary overhead. 
     // For those columns that are not specified here, the queried Task object will not hold any value.
     // For example: If TITLE is not specified, task.getTitle() will return null
     // For the list of most comonly used task columns, refer to oracle.bpel.services.workflow.query.ITaskQueryService.
     // Note: TASKID is fetched by default. So there is no need to explicitly specity it.
     List taskQueryColumns = new ArrayList();
     taskQueryColumns.add("TASKNUMBER");     
     taskQueryColumns.add("TITLE");
     taskQueryColumns.add("PRIORITY");
     taskQueryColumns.add("STATE");

     // Query the full blown AGDisplayInfo object using the AG ciKey 
     agDisplayInfo = getAGDisplayInfoDetailsById(wfCtx,
                               taskQueryColumns,
                               ciKey);   

     if (agDisplayinfo != null) { 
       System.out.println("AG Title: " +  agDisplayInfo.getAGInstanceInfo().getTitle());
       System.out.println();
       List milestoneDisplayInfoList =  agDisplayInfo.getMilestoneDisplayInfo(); 
       System.out.println("Total number of milestones: " +  milestoneDisplayInfoList.size()); 
       System.out.println("Milestone List: ");
       MilestoneDisplayInfoType milestoneDisplayInfo = null; 
       List taskList =  null;
       Task task = null; 
       for (int i = 0; i < milestoneDisplayInfoList.size(); i++) { 
         milestoneDisplayInfo = (MilestoneDisplayInfoType)  milestoneDisplayInfoList.get(i);          
         System.out.println("Milestone title: " +  milestoneDisplayInfo.getTitle());
         System.out.println("Milestone Status: " +  milestoneDisplayInfo.getMilestoneInstanceInfo().getStatus());
         System.out.println();
         taskList =  milestoneDisplayInfo.getTask(); 
         System.out.println("Total number of tasks: " +  taskList.size()); 
         System.out.println("Task List: ");
         for (int j = 0; j < milestoneDisplayInfo.getTask().size(); j++) { 
           task = (Task)  taskList.get(j);     
           System.out.println("Task Id: " + task.getSystemAttributes().getTaskId());
           System.out.println("Title: " + task.getTitle());
           System.out.println("State: " + task.getSystemAttributes().getState());     
           System.out.println();
         }
       }
     }     
   }
   
   
 Beyond authentication, all methods require the worklist context as the first argument. The worklist context 
 helps the worklist service determine the user requesting the action, whether the user has permission to 
 perform the requested action on the agDisplayInfo and so forth. The context also contains information about the 
 user's locale and timezone information.
 

Following are all AG columns
Column objects are defined in oracle.bpel.services.workflow.repos.TableConstants, and they can also be obtained by passing the column name to the static method getColumn() on oracle.bpel.services.workflow.repos.Column.

Column	Description	Column Object	How to retrieve
CIKEY	CiKey	AGINSTANCE_CIKEY_COLUMN	agDisplayInfo.getAGInstanceInfo().getCiKey()
DEFINITION_ID	Definition Id	AGINSTANCE_DEFINITIONID_COLUMN	agDisplayInfo.getAGInstanceInfo().getDefinitionId()
ROOT_AG_ID	Root AG Id	AGINSTANCE_ROOTAGID_COLUMN	agDisplayInfo.getAGInstanceInfo().getRootAGId()
COMPONENT_REF	Component Ref	AGINSTANCE_COMPONENTREF_COLUMN	agDisplayInfo.getAGInstanceInfo().getComponentRef()
CMPST_ID	Composite Id	AGINSTANCE_CMPSTID_COLUMN	agDisplayInfo.getAGInstanceInfo().getCmpstId()
CREATION_DATE	Creation Date	AGINSTANCE_CREATIONDATE_COLUMN	agDisplayInfo.getAGInstanceInfo().getCreationDate()
CREATOR	Creator	AGINSTANCE_CREATOR_COLUMN	agDisplayInfo.getAGInstanceInfo().getCreator()
TITLE	Title	AGINSTANCE_TITLE_COLUMN	agDisplayInfo.getAGInstanceInfo().getTitle()
IDENTIFICATION_KEY	Identification Key	AGINSTANCE_IDENTIFICATIONKEY_COLUMN	agDisplayInfo.getAGInstanceInfo().getIdentificationKey()
STATUS	Status	AGINSTANCE_STATUS_COLUMN	agDisplayInfo.getAGInstanceInfo().getStatus()
COMPLETION_PERCENTAGE	Completion Percentage	AGINSTANCE_COMPLETIONPERCENTAGE_COLUMN	agDisplayInfo.getAGInstanceInfo().getCompletionPercentage()
ERROR_MESSAGE	Error Message	AGINSTANCE_ERRORMESSAGE_COLUMN	agDisplayInfo.getAGInstanceInfo().getErrorMessage()
MILESTONE_STATE	Milestone State	AGINSTANCE_MILESTONESTATE_COLUMN	agDisplayInfo.getMilestoneDisplayInfo()
BPEL_STATUS	BPEL Status	CUBEINSTANCE_STATE_COLUMN	agDisplayInfo.getAGInstanceInfo().getBpelStatus()

Nested Class Summary

static class

IAGQueryService.AGAssignmentFilter

Field Summary

static java.lang.String	AGASSIGNMENT_FILTER_ADMIN
static java.lang.String	AGASSIGNMENT_FILTER_CREATOR
static java.lang.String	AGASSIGNMENT_FILTER_MY
static java.lang.String	AGASSIGNMENT_FILTER_PREVIOUS
static java.lang.String	AGASSIGNMENT_FILTER_REPORTEES

Method Summary

AGDisplayInfo	getAGDisplayInfoDetailsById(IWorkflowContext ctx, long ciKey, java.util.List taskDisplayColumns) getAGDisplayInfoDetailsById gets the details of an AGDisplayInfo object specified by ciKey The AGDisplayInfo objects returned contain the following information: 1.
MilestoneDisplayInfo	getMilestoneDisplayInfo(IWorkflowContext ctx, long cikey, java.lang.String milestoneName, java.util.List taskDisplayColumns) getMilestoneDisplayInfo gets the MilestoneDisplayInfo object for the specified milestone in the specified AG This API is useful when the UI needs to retrieve and refresh only the milestone subtree instead of the entire AG tree.
java.util.List	queryAGDisplayInfos(IWorkflowContext ctx, java.util.List agDisplayColumns, IAGQueryService.AGAssignmentFilter agAssignmentFilter, Predicate predicate, Ordering ordering, int startRow, int endRow) queryAGDisplayInfos returns a list of AGDisplayInfo objects.
java.util.List	queryAGDisplayInfos(IWorkflowContext ctx, java.util.List agDisplayColumns, java.lang.String agAssignmentFilter, Predicate predicate, Ordering ordering, int startRow, int endRow) queryAGDisplayInfos returns a list of AGDisplayInfo objects.

Field Detail

AGASSIGNMENT_FILTER_MY

static final java.lang.String AGASSIGNMENT_FILTER_MY

See Also:

Constant Field Values

AGASSIGNMENT_FILTER_REPORTEES

static final java.lang.String AGASSIGNMENT_FILTER_REPORTEES

See Also:

Constant Field Values

AGASSIGNMENT_FILTER_CREATOR

static final java.lang.String AGASSIGNMENT_FILTER_CREATOR

See Also:

Constant Field Values

AGASSIGNMENT_FILTER_PREVIOUS

static final java.lang.String AGASSIGNMENT_FILTER_PREVIOUS

See Also:

Constant Field Values

AGASSIGNMENT_FILTER_ADMIN

static final java.lang.String AGASSIGNMENT_FILTER_ADMIN

See Also:

Constant Field Values

Method Detail

queryAGDisplayInfos

java.util.List queryAGDisplayInfos(IWorkflowContext ctx,
                                   java.util.List agDisplayColumns,
                                   IAGQueryService.AGAssignmentFilter agAssignmentFilter,
                                   Predicate predicate,
                                   Ordering ordering,
                                   int startRow,
                                   int endRow)
                                   throws WorkflowException

queryAGDisplayInfos returns a list of AGDisplayInfo objects. The AGDisplayInfo objects returned contain the following information: 1. AG metadata info such as AG name 2. AG instance info such as AG instance status. The columns returned are controlled by the agDisplayColumns parameter. 3. A list of milestones with the following info if MILESTONE_STATE column is included in agDisplayColumns parameter. (1) Milestone metadata info such as milestone icon location (2) Milestone instance info such as milestone status The AGDisplayInfo objects returned do not contain task information, which can be retrieved only by the queryAGDisplayInfoDetailsById API The assignmentFilter is used to filter the AGdisplaInfos based on the AG assignment. The AGDisplayInfos returned can be restricted by specifying valid values (>0) for the startRow and endRow to facilitate database level paging. If these values are set to 0 then all qualifying AGDisplayInfos are returned.

Parameters:

ctx - the workflow context (can contain valid token or credentials)

agAssignmentFilter - the assignment filter

 For all possible values, check the assignment filters defined in this interface, 
 like AGASSIGNMENT_FILTER_<Filter Name>
 

agDisplayColumns - a list containing names of AG columns to be retrieved

 For those columns that are not specified here, the queried AGDisplayInfo object will not hold any value.
 For example: If CREATOR is not specified, agDisplayInfo.getAGInstanceInfo().getCreator() will return null.

 The MILESTONE_STATE column has particular importance in that it determines whether any milestone information 
 will be returned by the query. Only specify this column when necessary to void unwanted performance overhead.

 The following AG columns will always be returned regardless of the agDisplayColumns setting

  

ColumnName	Column
CIKEY	AGINSTANCE_CIKEY_COLUMN
TITLE	AGINSTANCE_TITLE_COLUMN
IDENTIFICATION_KEY	AGINSTANCE_IDENTIFICATIONKEY_COLUMN
STATUS	AGINSTANCE_STATUS_COLUMN
DEFINITION_ID	AGINSTANCE_DEFINITIONID_COLUMN

 If agDisplayColumns is null or has no elements, then the following additional columns will be returned
 by default:

  

ColumnName	Column
CREATION_DATE	AGINSTANCE_CREATIONDATE_COLUMN
CREATOR	AGINSTANCE_CREATOR_COLUMN
COMPLETION_PERCENTAGE	AGINSTANCE_COMPLETIONPERCENTAGE_COLUMN

predicate - the predicate for filtering the AGDisplayInfos

ordering - the ordering criteria for sorting the AGDisplayInfos

startRow - the rownum of the starting row for this query (set to 0 for no paging)

endRow - the rownum of the ending row for this query (set to 0 for no paging)

Returns:

a list of AGDisplayInfo objects

Throws:

WorkflowException - if any runtime error occurs while querying AGDisplayInfos

queryAGDisplayInfos

java.util.List queryAGDisplayInfos(IWorkflowContext ctx,
                                   java.util.List agDisplayColumns,
                                   java.lang.String agAssignmentFilter,
                                   Predicate predicate,
                                   Ordering ordering,
                                   int startRow,
                                   int endRow)
                                   throws WorkflowException

queryAGDisplayInfos returns a list of AGDisplayInfo objects. This method is the same as as the queryAGDisplayInfos API, except that it takes a string assignment filter instead of an AGAssignmentFilter enum as input. This method is to be called by class AGQueryServiceWSIF only, which gets a string assignment filter from the XML input.

Throws:

WorkflowException

getAGDisplayInfoDetailsById

AGDisplayInfo getAGDisplayInfoDetailsById(IWorkflowContext ctx,
                                          long ciKey,
                                          java.util.List taskDisplayColumns)
                                          throws WorkflowException

getAGDisplayInfoDetailsById gets the details of an AGDisplayInfo object specified by ciKey The AGDisplayInfo objects returned contain the following information: 1. AG metadata info such as AG name 2. AG instance info such as AG instance status. All AG instance columns are returned. 3. A list of milestones with the following info (1) Milestone metadata info such as milestone icon location (2) Milestone instance info such as milestone status (3) A list of tasks. The task columns returned are controlled by the taskDisplayColumns parameter.

Parameters:

ctx - the workflow context (can contain valid token or credentials)

ciKey - the ciKey of the AGDisplayInfo whose details are needed

taskDisplayColumns - a list containing names of task columns to be retrieved

 For a list of common task columns, refer to oracle.bpel.services.workflow.query.ITaskQueryService.
 
 If taskDisplayColumns is null or has no elements, then the following columns will be returned
 by default:

  

Column

WFTASK_TASKID_COLUMN

WFTASK_TASKGROUPID_COLUMN

WFTASK_TASKNUMBER_COLUMN

WFTASK_TASKDEFINITIONID_COLUMN

WFTASK_TASKGROUPINSTANCEID_COLUMN

WFTASK_SUBTASKGROUPINSTANCEID_COLUMN

WFTASK_ACQUIREDBY_COLUMN

WFTASK_ASSIGNEES_COLUMN

WFTASK_REVIEWERS_COLUMN

WFTASK_CREATOR_COLUMN

WFTASK_OWNERUSER_COLUMN

WFTASK_OWNERGROUP_COLUMN

WFTASK_DIGITALSIGNATUREREQUIRED_COLUMN

WFTASK_EXPIRATIONDATE_COLUMN

WFTASK_PRIORITY_COLUMN

WFTASK_ASSIGNEDDATE_COLUMN

WFTASK_CREATEDDATE_COLUMN

WFTASK_ENDDATE_COLUMN

WFTASK_STATE_COLUMN

WFTASK_UPDATEDBY_COLUMN

WFTASK_UPDATEDDATE_COLUMN

WFTASK_WORKFLOWPATTERN_COLUMN

WFTASK_TITLE_COLUMN

WFTASK_CATEGORY_COLUMN

WFTASK_DUEDATE_COLUMN

WFTASK_PERCENTAGECOMPLETE_COLUMN

WFTASK_STARTDATE_COLUMN

Returns:

a AGDisplayInfo object with details

Throws:

WorkflowException - if any runtime error occurs while getting AGDisplayInfo details

getMilestoneDisplayInfo

MilestoneDisplayInfo getMilestoneDisplayInfo(IWorkflowContext ctx,
                                             long cikey,
                                             java.lang.String milestoneName,
                                             java.util.List taskDisplayColumns)
                                             throws WorkflowException

getMilestoneDisplayInfo gets the MilestoneDisplayInfo object for the specified milestone in the specified AG This API is useful when the UI needs to retrieve and refresh only the milestone subtree instead of the entire AG tree.

Parameters:

ctx - the workflow context (can contain valid token or credentials)

ciKey - the ciKey of the AG instance

milestoneName - the name of the milestone

taskDisplayColumns - a list containing names of task columns to be retrieved, which is the same as the one in getAGDisplayInfoDetailsById API above

Returns:

a MilestoneDisplayInfo object

Throws:

WorkflowException - if any runtime error occurs while getting MilestoneDisplayInfo