In this chapter, I will cover Team Development features. Team Development is an APEX application within the Application Express development environment and was introduced in version 4.0 of APEX. Figure 5-1 shows the Team Development main menu.

Team Development can be used to track features, bugs, milestones, and other elements, but the most striking functionality is the feedback feature. Using the feedback feature, you can support the reporting and communication of bugs and enhancement requests from your business analysts, application testers, and end users; this can happen from a test or production environment to your development environment, and vice versa. This chapter will cover how to set up this built-in functionality and give some examples of how to use it. You’ll also see how to use APEX views and packages to enhance Team Development’s functionality to meet your specific needs.

The different parts of Team Development, pictured in Figure 5-1, are discussed in more detail in this chapter. Each section ends with some tips and tricks on how to extend the usability of the standard features. As an example, you’ll use the development of an application you are familiar with: Oracle Application Express.

Milestones

Milestones being the first option in the menu shown in Figure 5-1 is not by accident. Defining the milestones is usually the first thing you want to do when you start with Team Development. A milestone is a project management term, marking the end of a stage, like the delivery of a work package. Milestones are used to determine whether a project is on schedule. For this reason, milestones are usually the first thing you’ll define. The milestones in this example are the delivery of APEX Early Adopter Release 1, Release 2, and the final production versions of APEX 5.0 and 5.1.

The Basics

Figure 5-2 shows the high-level data model used to record milestones. Each milestone is categorized by a milestone type, is associated with a release, and is owned by an owner. The Milestone Type, Release, and Owner entities are not implemented as actual tables but as a list of used values, such as select distinct milestone_type of milestones.

The advantage of the non-normalized implementation in Figure 5-2 is that you can create milestones quickly, without defining most related master data beforehand. All information regarding milestones is exposed through the APEX_TEAM_MILESTONES view.

To create a milestone, as shown in Figure 5-3, you have to set the milestone date and add some additional information. When entering this additional information, you might notice there is a feature in the user interface that differs from the other parts of APEX but is generally implemented in Team Development. For some fields you have the option to select a value from a select list or enter a new value. Be aware that the new value supersedes the value in the select list. So if you enter a new value, that one will be used, regardless of whatever you selected in the select list, even when the “new value” field is hidden when you select something from the select list!

The following are some descriptions of the fields shown in Figure 5-3:

• The Type field can be used to differentiate the type of the milestone, such as Early Adopter, Major Release, or Patch Release.
• The Owner field indicates who is responsible for the milestone. The select list is populated from all fields within Team Development where you can enter names, such as assigned to, contributor, and others, so you are not restricted to previously entered milestone owners. Note that the names you enter will be converted to lowercase.
• The Release field defines the version of the software you set the milestone for. In this example, you can expect releases such as 5.0, 5.0.1, 5.0.2, and 5.1.
• The Selectable for Features field gives you the option to hide milestones when adding a feature. This can be used for milestones that are tentative and not yet ready for use. Note that switching this off for a milestone doesn’t impact the features that are currently assigned to that milestone. Furthermore, you can add a full description of the milestone and add tags to it.

Extending Milestone Functionality

Later in this chapter you will learn how to display the information you entered in a Gantt chart, but first you have to set up your own Team Development Enhancement application. For this new application, you can pick any schema owner you like because you will use only the standard APEX views and packages within this application. Set Application Alias to TDE (for Team Development Enhancement) and create an empty home page in that application with HOME set to Page Alias.

Once you’ve done that, create a link to that application via the menu Team Development Utilities Manage Links. Click Create Link, give the link a meaningful name, and set Target to f?p=TDE:HOME. Now you can access your newly created application from within Team Development using the Manage Links action from the Utilities menu region on the right side of the Team Development main page.

An even nicer tweak is to add an image with a link to the Team Development main page. In APEX 4.2 you could do this by adding a script to the system message, but that trick doesn’t work anymore.

Firefox users can install the GreaseMonkey extension. GreaseMonkey allows you to run any custom JavaScript code on any page you want. Once you’ve installed GreaseMonkey, you can create and add your own user script that will run on any web page you want. So, open your favorite editor, copy the following code, and save the file using a .user.js extension (for instance tde.user.js). Now you can drag that file into your browser window where the GreaseMonkey extension will deal with it.

// ==UserScript==
// @name        Team Development Enhancements
// @namespace   apex
// @description Team Development Enhancements
// @include     http://oel6:8081/apex5/*   [The URL that points to your APEX environment]
// @version     1
// @grant       none
// ==/UserScript==
if ( $v(’pFlowStepId’)==’4000’) {
  // Create Image + Link to Team Development Enhancement on this page"
  $(’ul.a-ImageNav.team-dev’)
  .append(’
    <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
    <li class="a-ImageNav-item">
      <a title  = "Team Development Enhancement"
         href   = "f?p=TDE:HOME:::::P_SESSION:’ + $v(’pInstance’) +’"
         class  = "a-ImageNav-link"
         target = "_blank" >
         <span class = "a-ImageNav-img fa fa-connectdevelop fa-4x"
               style = "padding-top:12px;"></span>
         <span class="a-ImageNav-label">Team Development Enhancement</span>
      </a>
    </li>
    ’);
  }

This code adds an image with a link to your application to the Team Development main page, just like the icon on the far right in Figure 5-4. You have to adapt the href and src attributes to your liking. Please note that all HTML text used as parameters to the append function should be on one line, without additional carriage returns. In the previous listing, the code is formatted just to improve readability. I’ll explain the use of the P_SESSION parameter in a moment.

Features

Using features, you describe the functionality you want to add to or change in your application. You can assign a feature to an owner, and a feature can have a contributor. You can also make a distinction based on focus areas, such as Charts, Interactive Reports, or Themes. Once you’ve decided when to implement a feature, you can assign it to a certain release and milestone. Earlier on you might have defined a milestone as set for a certain release and that relationship is now used in the feature functionality, unlike the previous releases. You can break down features into subfeatures, adding detail to your planning and making different people responsible for different subfeatures.

The Basics

In Figure 5-5 you can see how the data model used for the features functionality is implemented. In addition to the select lists for the Owner, Contributor, Focus Area, and Release fields, there are three other select lists you’ll encounter when defining a feature: Status, Desirability, and Priority. Unlike the other select items, these last three contain predefined and fixed values and cannot be customized.

Values in the Status, Desirability, and Priority lists are defined using the following views in the APEX schema: WWV_FLOW_FEATURE_DEF_ST_CODES, WWV_FLOW_FEATURE_DESIRABLITY, and WWV_FLOW_FEATURE_PRIORITIES. The same holds for the other “status” views. In Figure 5-6 you’ll find an example of the feature functionality. You can begin to get an idea of what is available to you by looking at the various fields in the figure.

There is some date information that you can add to a feature, such as start date and due date. The latter is defaulted to the date of the corresponding milestone. You can also add more details such as a description, a justification, and a progress log. You can use these fields to create your own reports.

Although the standard options already offer you a lot of functionality, you can even expand the amount of data you can enter. If you click Team Development Settings in the task list on the right side of the Team Development home page, you can enable the tracking of attributes for all aspects of application development, such as user interface, testing, security, and the like. Figure 5-7 shows the drop-down menu items to enable this level of tracking.

For each of the tracking attributes you enable, a new region within your features screen appears at the bottom, as shown in Figure 5-8.

Now that you know what all these fields are for, you can use the standard functionality of APEX to customize the display of the feature’s interactive report to fit—more or less—your specific needs. Figure 5-9 shows a customized report.

Starting from the standard features interactive report, you can achieve the result, as shown in Figure 5-9, by applying these steps using the Action menu:

1. Set Control Break to Parent Feature.
2. Filter on “Parent Feature is not null.”
3. Select the columns you want to display. You have to select the Control Break column as well or the break won’t work.
4. Compute the Remaining field by entering a computation like BA * (100-BG)/100, where BA refers to the effort and BG to the status percent.
5. Aggregate the Effort field—and maybe the Remaining field as well.

Extending the Features Functionality

Now that you’ve entered some project information, it would be nice to see this information in a way you’re used to when running projects, namely, in a Gantt chart.

Create a new chart page in your Team Development Enhancement application, pick a Project Gantt chart as the type to display, set the other settings as you’d like them, and enter this SQL query:

SELECT  NULL                    link
,       FEATURE_NAME            task_name
,       FEATURE_ID              task_id
,       PARENT_FEATURE_ID       parent_id
,       NVL(START_DATE,SYSDATE) actual_start
,       NVL(DUE_DATE,SYSDATE)   actual_end
,       FEATURE_STATUS          progress
FROM APEX_TEAM_FEATURES
START WITH PARENT_FEATURE_ID IS NULL
CONNECT BY PRIOR FEATURE_ID = PARENT_FEATURE_ID

With data similar to the data presented in Figure 5-9 and a few additional features, you’ll get a Gantt chart when you run the page. You’ll notice that the start and end dates of the parent features don’t match the dates of the subfeatures. You can solve that by including the calculation of those dates in the SQL code using analytic functions. Later in the chapter, when you generate the XML used by the chart by yourself, you’ll learn how to let AnyChart do the calculation.

For now you can play with the settings until you get the desired result. Figure 5-10 shows the settings I used.

Now, let’s create a link from the Gantt chart back into Team Development. Notice I didn’t include a link in the SQL query because that solution doesn’t work anymore. Because APEX 5 automatically creates a new session when you run an application, you have to take care of the session ID of the originating session, such as the one that’s running Application Builder. Therefore, you’ve already added a P_SESSION parameter in the GreaseMonkey script. To make use of that, add an application item named P_SESSION with Session State Protection set to Unrestricted.

Now, go to Chart Series, add a Link of Type called Link to Custom Target, and set Target to the settings shown in Figure 5-11.

If you run the page again, you’ll see something like what’s shown in Figure 5-12. Now click a bar in the charts, and you will be redirected to the page where you can view and edit the feature you clicked. Notice the parameter used is #ID# and not the actual column name TASK_ID you provided in the SQL because the columns in the SQL statement are renamed by the AnyChart engine.

To Do’s

To-do items are small pieces of work, or tasks, you assign to your co-workers and want to track. As with features, you can create a multilevel breakdown of to-do items. But if you really want to keep track of things, creating a multilevel breakdown might not be the wisest thing to do, because if you have a lot of to-do items defined, it can be rather difficult to keep oversight of them all. Also, since Team Development is not a real planning tool (compared to Microsoft Project, for example), all the figures you enter, such as dates and estimated effort, are not accumulated to the higher level. So, you cannot simply rely on those figures; you’ll need some additional reports to get closer to the real situation.

The Basics

Figure 5-13 shows the data model for a to-do item. This gives you an idea of how the tables and views are related and where the fields on the page in Figure 5-14 originate.

A to-do item (also known as a task) is assigned to someone and can have a contributor or an additional contributor. A to-do item has a certain status. Similar to features, this status is hard-coded using a view: WWV_FLOW_TASK_DEF_STATUS_CODES. You can add more details to a to-do item by specifying a category, a release, a feature, and a milestone. Figure 5-13 shows an example of a to-do item.

All information regarding to-do items is exposed through the APEX_TEAM_TODOS view, which is mainly based on the WWV_FLOW_TASKS table. And, similar to feature progress, all information entered in the progress area is recorded as task progress and represented as a list of activities carried out.

Extending the To-Do Functionality

Now that you’ve explored the planning and activities aspects of Team Development, it would be nice to present milestones, features, and to-do items in one Gantt chart. The following are some of the details you’ll need to attend to in order to accomplish that goal:

• The roll-up of start and end dates from lower-level features to higher-level features or from to-do items to features—defined as the parent feature of a feature or the feature of a to-do item
• Defining, and showing in the Gantt chart, a predecessor for a to-do item—defined as the parent to-do item of a to-do item
• Defining, and showing in the Gantt chart, what to-do item is the last step for a milestone—defined as the Milestone property of a to-do item

First create a new project Gantt chart. You can use the SQL query provided earlier in “Extending the Features Functionality,” or any other valid query for the chart, because you won’t use the results of that query anyway.

Now, create a (dummy) static content region before the Chart region with a hidden field, named P3_XML_PG. Next, edit the chart XML by providing this custom XML:

<?xml version = "1.0" encoding="utf-8" standalone = "yes"?>
<anygantt>
  <settings>
    <background enabled="false" />
    <navigation enabled="true" position="Top" size="30">
      <buttons collapse_expand_button="false" align="Far"/>
      <text>Project Gantt</text>
    </navigation>
  </settings>
  <datagrid enabled="true" width="400" />
  <styles>
    <task_styles>
      <task_style name="defaultStyle">
        <actual>
          <bar_style>
            <middle>
              <fill enabled="true" type="Gradient">
                <gradient angle="-90">
                  <key color="#689663" position="0"/>
                  <key color="#6B9866" position="0.38"/>
                  <key color="#B4FFAB" position="1"/>
                </gradient>
              </fill>
            </middle>
          </bar_style>
        </actual>
      </task_style>
    </task_styles>
  </styles>
&P3_XML_PG.
</anygantt>

See Figure 5-15 for where to put these lines of code.

Instead of using the standard #DATA# replacement, the chart will use the contents of the P3_XML_PG field to generate the chart. So, define a Pre-Rendering – After Header page process to load data into that field using a function you will create shortly.

begin
    :P3_XML_PG := GenerateProjectXML;
end;

See Figure 5-16 for where to put this code. You might see a message that there is an error in your code, but you can save the change. You will fix that error in the next step.

Next switch to APEX’s SQL Workshop and define that function.

create or replace function GenerateProjectXML
return varchar2
is
    l_chart_data_xml    varchar2(32767);
    l_task_xml          varchar2(32767);
    l_connector_xml     varchar2(32767);

    cursor tasks is
    select link
    ,      task_type
    ,      name
    ,      id
    ,      parent_id
    ,      predecessor
    ,      milestone_id
    ,      to_char(actual_start,’YYYY.MM.DD’) start_date
    ,      to_char(actual_end,’YYYY.MM.DD’)   end_date
    ,      progress
    from
    ( select null               link
      ,      ’T’                task_type
      ,      todo_name          name
      ,      todo_id            id
      ,      feature_id         parent_id
      ,      parent_todo_id     predecessor
      ,      milestone_id       milestone_id
      ,      start_date         actual_start
      ,      due_date           actual_end
      ,      todo_status        progress
      from   apex_team_todos
      union
      select  null                 link
      ,      ’F’                   task_type
      ,       feature_name         name
      ,       feature_id           id
      ,       parent_feature_id    parent_id
      ,       null                 predecessor
      ,       null                 milestone_id
      ,       null                 actual_start
      ,       null                 actual_end
      ,       feature_status       progress
      from    apex_team_features
      union
      select  null                 link
      ,       ’M’                  task_type
      ,       milestone            name
      ,       milestone_id         id
      ,       null                 parent_id
      ,       null                 predecessor
      ,       null                 milestone_id
      ,       milestone_date       actual_start
      ,       null                 actual_end
      ,       null                 progress
    from apex_team_milestones
    order by 5
    )
    start with parent_id is null
    connect by prior id = parent_id
    ;
begin

    -- Project Chart Opening Tag
    -- Define "auto_summary" so Anycharts does the calculations
    l_chart_data_xml := ’<project_chart>’||
                        ’<auto_summary enabled="True" />’
                        ;

    -- Task & Connectors Opening Tags
    l_task_xml := ’<tasks>’;
    l_connector_xml := ’<connectors>’;

    -- Loop through series data
    for c1 in tasks
    loop
      if c1.task_type =’T’ -- ToDo
      then
        -- Task Tag
        l_task_xml  := l_task_xml         ||
                        ’<task id="’      ||c1.id         ||’" ’||
                         ’name="’         ||c1.name       ||’" ’||
                         ’parent="’       ||c1.parent_id  ||’" ’||
                         ’actual_start="’ ||c1.start_date ||’" ’||
                         ’actual_end="’   ||c1.end_date   ||’" ’||
                         ’progress="’     ||c1.progress   ||’" ’||
                         ’style="Gantt" />’
                         ;
        l_connector_xml := l_connector_xml          ||
                           ’<connector ’            ||
                           ’type="FinishStart" ’    ||
                           ’from="’||c1.predecessor ||’" ’||
                           ’to="’  ||c1.id          ||’" ’||
                           ’ />’
                           ;
        if c1.milestone_id is not null
        then
          l_connector_xml := l_connector_xml          ||
                             ’<connector ’            ||
                             ’type="FinishStart" ’    ||
                             ’from="’||c1.id          ||’" ’||
                             ’to="’  ||c1.milestone_id||’" ’||
                             ’ />’
                             ;
        end if;
      elsif c1.task_type = ’F’ -- Feature
      then -- Start / End / Progress are auto-calculated
        l_task_xml  := l_task_xml         ||
                       ’<task id="’       ||c1.id        ||’" ’||
                         ’name="’         ||c1.name      ||’" ’||
                         ’parent="’       ||c1.parent_id ||’" ’||
                         ’/>’
                         ;

      elsif c1.task_type = ’M’ -- Milestone
      then -- A Milestone has no End date
        l_task_xml  := l_task_xml        ||
                       ’<task id="’      ||c1.id        ||’" ’||
                         ’name="’        ||c1.name      ||’" ’||
                         ’actual_start="’||c1.start_date||’" ’||
                         ’/>’
                         ;
      end if;
    end loop;

    -- Task Closing Tag
    l_task_xml := l_task_xml||’</tasks>’;

    -- Periods Closing Tag
    l_connector_xml := l_connector_xml||’</connectors>’;

    -- Project Chart Closing Tag
    l_chart_data_xml := l_chart_data_xml ||
                        l_task_xml       ||
                        l_connector_xml  ||
                        ’</project_chart>’;

    return l_chart_data_xml;
end;

If you run the page, you’ll get a representation of your Team Development data in a Gantt chart. See Figure 5-17 for an example.

Bugs

Bugs cover a functionality we are all familiar with. Bugs are deficiencies in the products we deliver, such as software or documentation. The model for bug tracking is built using a similar data structure as the other pieces of Team Development. Figure 5-18 shows the model. You’ll see a few real tables, a few views with fixed values, and some dynamic lists of values.

All information regarding to-do items is exposed through the APEX_TEAM_BUGS view, which is mainly based on the WWV_FLOW_BUGS table.

A bug has a status, a severity, and a priority. The values in these select lists are defined in the views WWV_FLOW_BUG_STATUS_CODES, WWV_FLOW_BUG_SEVERITY, and WWV_FLOW_BUG_PRIORITY. When resolving a bug, it’s assigned to a person and planned to be fixed by some release, milestone, and/or date. Furthermore, you can add a lot more information on the bug itself, like the platform, browser, or operating system. Figure 5-19 shows an example of a filed bug.

Because a bug contains only a fix date—and no start date or effort—you have to link a bug to a to-do item in order to use a reported bug in your customized Gantt chart. The Bug section is intended for capturing issues that might be customer browser- or operating system–specific.

Feedback

Of all functionality in the Team Development application, feedback is without any doubt the most valuable. Feedback offers you a simple mechanism to communicate with your end users, fellow developers, and business analysts. And feedback can be installed in your application with just a few mouse clicks. Be careful, though: If your application has hundreds or thousands of users, you might want to reduce the number of people who are allowed to enter feedback. Otherwise, you might find yourself buried under hundreds of trivial feedback entries. All information regarding feedback is exposed through the APEX_TEAM_FEEDBACK view, which is mainly based on the WWV_FLOW_FEEDBACK table. Figure 5-20 shows the data model with all tables and views related to the feedback functionality.

The APEX_TEAM_FEEDBACK view contains a lot of information regarding the environment of the user who enters the feedback. It not only contains the page and workspace identifiers but also contains the complete session state and even information about the browser used and the IP addresses of the client and server. And if that’s not enough to fit your needs, there are eight additional attributes at your disposal. Just as a side note, there might be a security issue here because not all organizations might be happy about production data being copied from production to development.

Feedback Process

The feedback process as implemented in Team Development consists of a couple of steps that form a cycle together. The first step is creating a feedback entry by a user. Then the feedback is exported from the environment the user is working in and imported into the development environment. The business analyst or developer analyzes the feedback and responds to it. He can also log the feedback entry as a bug, a to-do item, or even a feature. The responses, which may contain questions for clarification, are exported from the development environment and imported into the user’s environment. Then the user can follow up on the developer’s question. That information can be exported again, and the cycle can go round and round, as Figure 5-21 indicates.

Within one development environment you can manage feedback from multiple sources—for instance, from a test and production environment or even multiple production environments running at different customer sites.

Enable Feedback

In your application, add a page of type Feedback Page. When you keep the default settings, the Feedback page itself is created, an entry is added to the navigation bar, and feedback is enabled. When you or the users of your application click the link in the navigation bar, a page pops up like in Figure 5-22.

Because this is just a page in your application, you can change all fields and behavior to match your requirements. When creating the page itself, you can create up to eight custom attributes to the feedback page. These attributes are included in the submit process that is generated by the wizard. The default select list feedback type is created from select the_name, id from APEX_FEEDBACK_TYPES order by id. If you needed more or different feedback types, you might think of adding records to this table, but, like a lot of these kinds of select lists in Team Development, it isn’t a table but a view with predefined data. So, that wouldn’t work. Also, replacing the select list with your own dynamic or static select list isn’t a good idea because pages in Team Development rely on values that exist in that view. So, let’s just keep that one as it is.

But you can add an item, as long as it fits within a varchar2(4000) column. In the example in Figure 5-23, I added two additional items to help qualifying the feedback when it comes in by letting the end user enter a severity and a priority.

If you’ve defined your own feedback items, you have to change the standard submit feedback page process a little. Here’s an example:

apex_util.submit_feedback (
    p_comment         => :P102_FEEDBACK,
    p_type            => :P102_FEEDBACK_TYPE,
    p_application_id  => :P102_APPLICATION_ID,
    p_page_id         => :P102_PAGE_ID,
    p_email           => :P102_EMAIL,
    p_attribute_01    => :P102_SEVERITY,
    p_label_01        => ’Severity’,
    p_attribute_02    => :P102_PRIORITY,
    p_label_02        => ’Priority’);

You have to use your own items as values for the parameter p_attribute_01, and so on, and for easier interpretation of the values, it is a good idea to provide the parameter p_label_01 with a value that tells what attribute_01 actually is. These values show up in the Additional Attributes region of the feedback.

One of the other parameters is the user’s e-mail address. This is automatically filled with the e-mail address of the user—but only if you use the APEX authentication. If you use another type of authentication, you should place your own function here to extract the e-mail address from the username. Or, if you use public pages with no authentication at all, you should add an e-mail address item on your feedback page.

Exporting Feedback to Development

If you develop your applications in the same workspace as your users are using, there is no need to export and import the feedback. But that’s an unusual case. Mostly you develop in a development instance and your users are testing in a test environment—perhaps even more than one—and running production in another environment.

Exporting feedback starts from the Workspace Utilities main page. When you click the Export link there, you get a number of objects you can export. Just click the last one on the left, called Team Development Feedback (see Figure 5-24), or click the Feedback tab on the far right.

All feedback entered after the date you enter in the Changes Since field will be exported. Usually you’ll set that to the date you last exported the feedback. Leave it empty for all feedback.

One other setting is Deployment System. This setting is used to distinguish feedback from one workspace and another. That’s especially important if you have deployed your application in more than one workspace, like test and production, or in production at multiple customer sites. This way you can see where feedback originates from and where the responses on the feedback should be sent to. To make this distinction, you have to be sure that this value is different for each implementation. You can set this value in the APEX Administration utility, via Edit Workspace Information, as shown in Figure 5-25. There it is called Feedback Synchronization Source Identifier, and it’s defaulted to the workspace name.

The feedback export file is named feedback_export_from_<Deployment System>.sql. If you entered a date/time value in the Changes Since field, the file name is appended with _since_<datetimestamp>.

Importing Feedback into Development

From the Application Builder main page, you can access the import function. You can import the exported feedback, which is just a SQL file, like any other APEX component. You can import the feedback as many times as you like and in any other workspace you want. If you try to import feedback into the same workspace you exported it from, you’ll get an error. Feedback is uniquely identified by the deployment system and a sequence number.

Team Development Integration in the Page Designer

One of the really neat features of APEX 5 is a closer integration between Team Development and the Page Designer. This is because when you are working on a page, it would be nice if you could easily spot whether there are bugs or feedback entries reported on that page. In APEX 5, you are notified that there might be more to do on your page than you might think. The upper-right corner of the Team Development icon has a badge indicating the number of Team Development entries that are still open. You can open the drop-down and directly navigate to that relevant bug or feedback entry. See Figure 5-26 for an example.

Processing Feedback

Once you’ve imported feedback, you can start processing it. Figure 5-27 shows the screen from which you begin doing that.

When you click the Log as Bug button on the page in Figure 5-27, the feedback is converted into a bug. During that conversion step you can change the title and add some additional information. Automatically some context is filled in, such as the application and the page affected by the bug. Figure 5-28 shows the resulting bug report.

Strangely, other information that is captured by using feedback isn’t automatically added to the bug, such as the platform, browser, and operating system. And even more interesting stuff, such as the complete session state, is captured but not copied to the bug description. There is also no visible reference from the bug to the feedback to retrieve that information afterward.

Similar to creating a bug from a feedback entry, you can also create a to-do item from a feedback entry and even transform a feedback entry into a feature. Remarkably, only when transforming a feedback entry into a to-do item is there an option to delete the feedback entry. But deleting feedback before the issue is completely solved isn’t a good idea because of all the information that’s contained within the feedback that might be relevant for sorting out the issue.

Notice that Figure 5-28 mentions “Converting feedback to a bug will set the feedback status to closed.” So, that saves you one step while processing your feedback items. Instead of—or in addition to—logging the feedback as a bug or a to-do item, you can also edit the feedback. Doing so, you can change the status and add comments. See the example in Figure 5-29.

The next challenge is to get those comments back to the originating system. After all, it doesn’t do much good to comment on feedback if the person originating that feedback never gets to see the comment. The next section shows how to meet this challenge.

Exporting Response to Deployment

For exporting your response back to deployment, you have to take the same steps as when exporting feedback from deployment into development. Notice the Direction setting in Figure 5-30 when exporting the feedback. It says “Export response to deployment” now.

You can also select the deployment system. The select lists contain every deployment system for which there is feedback imported beforehand. This feedback export file is now named feedback_import_for_dev.sql. You can see in Figure 5-30 that DEV is the system selected in the Deployment System drop-down.

Importing Response into Deployment

You have to take the same steps to import your response into the deployment system as you do when importing feedback into development. The difference is that you are going in the opposite direction.

After importing, you will see that the changes you made in development are reflected in the feedback of the deployment system, as shown in Figure 5-31. And although the Developer comments you entered are exported, they are not imported.

Once you’ve imported the response, you have reached the end of the feedback life cycle. But sometimes you need some additional information to solve an issue, as in the previous example. Of course, you can call or e-mail the person who submitted the feedback, but there is an option within Team Development that supports this functionality as well. Unfortunately, it is not automatically implemented, but you can implement it yourself with some additional easy steps.

Extending Feedback: Creating a Report

The first thing to do is to create a report on the feedback, so the user not only can report feedback but also has insight on the status. To begin, create a report page, with page number 103 in this example, and make it accessible according to your standard application navigation style; it can be an entry in a list, a tab, or a link in the navigation bar. The following select statement selects the data from the apex_team_feedback view and should show only the feedback for the current application. You can also choose to narrow the selection down, so users can only see the feedback they entered themselves or feedback with a certain status. That’s all up to you. If you use the wizard to create this report, you have to set Link to Single Row View to No in order to prevent an error from being raised.

SELECT feedback_number "Nr."
,      feedback_id     "Follow up"
,      feedback
,      CASE
       WHEN feedback_type = 1 THEN ’General Comment’
       WHEN feedback_type = 2 THEN ’Enhancement Requested’
       WHEN feedback_type = 3 THEN ’Bug’
       END           "Type"
,      CASE
       WHEN feedback_status = 0 THEN ’No Status’
       WHEN feedback_status = 1 THEN ’Acknowledged’
       WHEN feedback_status = 2 THEN ’Additional Info. Requested’
       WHEN feedback_status = 3 THEN ’Open’
       WHEN feedback_status = 4 THEN ’Closed’
       END           "Status"
,      page_name     "Page"
,      public_response "Response"
FROM   apex_team_feedback
WHERE  application_id = :APP_ID
ORDER BY updated_on DESC

Figure 5-32 shows what the report page you’re trying to achieve will look like.

To get that result, you have to make some minor changes. First, the column Follow Up in Figure 5-32 is used as a link column. Set the link text to the image of your liking and set the URL target to javascript:FollowUp( ’#Follow up#’);. The JavaScript function is defined in the Function and Global Variable Declaration section of the page as follows:

function FollowUp( pId ){
  $s(’P103_FEEDBACK_ID’, pId);
  $(’#FollowUp’).show();
}

Within the same page, create a new HTML region named FollowUp with two items: P103_FEEDBACK_ID as Hidden and Value Protected set to No and P103_FOLLOW_UP as a text area. Set the static ID of the region to FollowUp, and set Region Custom Attributes to style="display:none; width:540px". So, the region will be hidden by default and shown when a user clicks the little edit image in the report. Also, create a Region Button there to submit the page.

Next, create an On Submit Page Process to save the follow-up on the feedback using the apex_util.submit_feedback_followup procedure, as shown in Figure 5-33.

You can also show the follow-up on that page using the apex_util.get_feedback_follow_up function or querying the apex_team_feedback_followup view. Once the follow-up is entered by the end user, that information can be transferred back to the development system.

Extending Feedback: Feeding Back the Follow-Up

You execute the same steps to get follow-up back into the development system as you did to get the feedback from deployment to development. You export and import the feedback, and the follow-up is exported and imported as well.

Further Enhancements

Instead of waiting for the feedback to arrive in your development environment, you can also opt for sending the entered feedback by e-mail. This may be only for the more serious entries, but that’s up to you. And of course that will work only if there is a mail server configured for sending e-mail from APEX.

Another enhancement you might think of is sending feedback automatically by e-mail on a regular basis. Obviously, you also need a mail server configured for this. You can create a procedure like the one listed next and use the apex_plsql_job.submit_process function to schedule the procedure.

create or replace procedure send_feedback
          ( p_workspace apex_workspaces.workspace%type
          , p_send_to   varchar2
          )
is
  l_mail_id      number;
  l_clob         clob;
  l_blob         blob;
  l_mail_blob    blob;
  l_dest_offset  number  := 1;
  l_src_offset   number  := 1;
  l_amount       integer := dbms_lob.lobmaxsize;
  l_blob_csid    number  := dbms_lob.default_csid;
  l_lang_ctx     integer := dbms_lob.default_lang_ctx;
  l_warning      integer;
  -- The name of the Workspace you want to export the Feedback from
  l_workspace_id apex_workspaces.workspace_id%type;
  -- Search string for removing all "trash". Real SQL starts from there
  l_search       varchar2(255) := ’set define off’;
begin
  -- Get the ID of the Workspace and set the environment
  l_workspace_id := apex_util.find_security_group_id ( p_workspace );
  wwv_flow_api.set_security_group_id( l_workspace_id );
  -- Create the mail object
  l_mail_id   := apex_mail.send
                   ( p_to    => p_send_to
                   , p_from  => ’[email protected]’
                   , p_subj  => ’Feedback Export from Deployment to Development’
                   , p_body  => ’See the attachment.’
                   );
  -- Create the CLOB
  -- Export the Feedback to Development for the Workspace provided
  l_clob :=
     wwv_flow_utilities.export_feedback_to_development ( l_workspace_id );
  -- Convert to BLOB
  dbms_lob.createtemporary ( lob_loc => l_blob
                           , cache   => true
                           );
  dbms_lob.converttoblob ( l_blob
                         , l_clob
                         , l_amount
                         , l_dest_offset
                         , l_src_offset
                         , l_blob_csid
                         , l_lang_ctx
                         , l_warning
                         );
  -- Remove all "trash", so only real SQL is left over
 dbms_lob.createtemporary ( lob_loc => l_mail_blob
                          , cache   => true
                          );
 dbms_lob.copy(  l_mail_blob
               , l_blob
               , dbms_lob.lobmaxsize
               , 1
               , dbms_lob.instr( lob_loc => l_blob
                                , pattern => utl_raw.cast_to_raw(l_search)
                                )
               );
 -- Add the file as a BLOB attachment to the mail
 apex_mail.add_attachment
       ( p_mail_id    => l_mail_id
       , p_attachment => l_mail_blob
       , p_filename   => ’feedback_export_from_’||lower(p_workspace)||’.sql’
       , p_mime_type  => ’application/text’
       );
  commit;
end;

Summary

Now that you know about the functionality of Team Development, it may become clear that the planning capacity of Team Development doesn’t beat a “real” project management tool, like Microsoft Project. Even if you add some nice Gantt charts, which are an absolute necessity for any planning tool, Team Development still lacks too much functionality. Here are a few things you can’t do with Team Development:

• Add a capacity to a resource (like 40 hours per week)
• Plan using the given capacity
• Add a cost to a resource so you can plan how much money you have to spend
• Monitor how many hours a resource spends, using an interface with a time reporting application
• Add multiple predecessors to to-do items so you can plan and execute the actions in the right order and determine the critical path

Of course, you can build all this in your custom Team Development Enhancement application, but capacity planning and critical path determination are complex mathematical issues and not easy to solve. Still, for small projects (up to five people or so), Team Development might be a convenient—and inexpensive—tool to use. But when a project starts getting more complex, you have to spend some money and buy a specialized tool to support your business.

That said, the feedback feature of Team Development is in itself so powerful—especially when you add functionality like that shown in the examples—that for feedback alone you should consider using Team Development. When you’re in the test phase of your project in particular, feedback will facilitate communication between users and developers. Your application can only benefit from that.