How to retrieve a list of individuals in Queues

I’m back with the latest tutorial in our series that focuses on Processes and Process Queues.

If you remember, the last tutorial in this series guided you step-by-step in building a quick tool to list a process and the various queues within the process.

If you’ve not reviewed the previous tutorial, then please take a moment to peruse.  It’s critical that you do review the previous tutorial as it’s the foundation for today’s tutorial.

We’ll take the previous tutorial a step further today, discussing and showing you how to access and display individuals in their respective process queues.  Let’s begin.

Extending the retrieval of queues for a given process

To begin this tutorial, crack open your text editor, and copy and paste the code from this tutorial.  Save the file and name it queue-individuals.php.

Everything within the code will remain the same with the exception of the code within the foreach statement.

From within the foreach statement, define two response_object variables and have both use the .= operator.  The first response_object variable concatenates each queue name placed within h2 header tag while the second response_object variable concatenates a list of individuals to the respective queue using the getQueueIndividuals function we’ll soon discuss.

 

Creating the getQueueIndividuals function

To retrieve a list of individuals in a respective queue, we’re creating a function named getQueueIndividuals and passing it the queue id. Click here to read and learn more about creating reusable functions.  Let’s move forward.

Create the getQueueIndividuals function and pass it the id variable.  If you remember, we created the two response_object variables.  The second response_object variable was defined to the value of the getQueueIndividuals function.  The queue id (i.e., $node[‘id’]) is passed to the getQueueIndividuals function as an argument (see above).

Now, we’re ready to develop the inner workings of the getQueueIndividuals function. Starting one line after the include function until the end of the code, copy and paste the code above inside the getQueueIndividuals.

Yes, I know this sounds crazy, but we’re in the busy of increasing productivity via reusability.

Now, inside the getQueueIndividuals function, make the following changes:

  • set apiService variable equal to the CCB API’s queue_individuals service.
  • change personID variable to queueID variable
  • set queueID variable equal to id variable
  • change the urlData array label id’s value from processID variable to queueID variable
  • set rss variable’s xpath query expression to the following: //individuals/individual.
  • change echo $response_object; to return $response_object;

I know, we moved through that setup rather quickly and without much explanation.  You’ll have to review previous tutorials to make up the difference, or go back to the very beginning, the very first tutorial.

We’re now ready to modify the inner workings of the getQueueIndividuals function’s foreach statement.

Inside the foreach statement, create triggerStatus and statusFilter variables.  Set the triggerStatus variable equal to 0 for now.  Set the statusFilter variable equal to not-started for now.  I’ll explain both of these variables shortly, so sit tight for now and let’s continue forward.

Next, create and if else statement.  Basically, we want to test to see if we are returning all individuals regardless of their status, or returning individuals based on a respective status.

When using CCB queues, there are four status options that can be assigned to individuals in queues: waiting, in-process, done and not-started.  And for this reason, that’s why we’re using a if else statement.

The if else statement will allow you to set a trigger to find a specific list of individuals within a queue with a certain status, or all individuals regardless of their status.  If the former, set the triggerStatus variable equal to 1 and set the appropriate status of individuals you wanted returned.  If not, then leave the triggerStatus variable equal to 0, and all individuals in the respective queue will be returned.

Let’s continue to develop the if else statement’s logic.

Within the if statement, we first check to see if the triggerStatus variable is set.  If set, then we use another if statement to compare the statusFilter variable value to that of the status of the individual (i.e., $node->status).

If the statusFilter variable value is equal to the individual status using PHP’s strtolower, then capture and concatenate the response_object variable’s value using the .= operator, which the value is the individual’s name concatenated to the <br/> html tag.

That’s it for the if statement.  Now, time for the else statement.

The else statement is quite simple in that the code within it is nothing more than capturing and concatenating the response_object variable’s value using the .= operator, which the value is the individual’s name concatenated to the <br/> html tag.

Close the if else statement, and we’re done with the getQueueIndividuals function.

Ready… Aim… It’s time to test!

Now, it’s time to put the code together and test functionality.  Place the code in your it queue-individuals.php file, and save it.  Your code should look like the code below.

 

Next, open the file using a browser and you should see a list of queue headings with their respective list of individuals under each queue heading.

It’s possible that you may not see individuals.  If this is the case, then you might want to check to be sure that you set the correct processID variable value, or that your queue does have individuals assigned to it.

There are many things that you can do to extend this tutorial.  For instance, you could take the data and create an automated report, email data, create a spreadsheet, place data into a database and the list goes on.

Next week, we’ll continue and expand upon this tutorial when I’ll show you how to create a list of individuals that are assigned to queues multiple times in the same CCB process.

Hang in there, you’re doing well with this series.  I’m sure you’re thinking of many different ways to use what you’ve just learned!

Until the next post, be blessed with API coding success!


Please comment if this tutorial has helped you.