We shall learn about building custom apps through an example. We will build a simple bug tracking application. We shall assume we have two teams: Developers - they fix bugs, and QA (short for Quality Assurance) - they test the fixes by developers. We will to the model the following bug workflow:

In plain english, the diagram translates to:

  • When a bug is reported, it is in the New state.
  • QA verifies the bug. If it is not a bug, the bug moves to Closed; else to the Verified state.
  • A verified bug fixed by a developer moves to the Fixed state.
  • The fix is then tested by QA and the bug moves to Reopened, if test fails; or Closed, if the test passes.
  • A Reopened bug fixed by the developer moves to the Fixed state.
Each bubble is represents a stage in the bug life-cycle while each arrow an end-user action. Next to each state we have defined the team responsible for it. Also, note that there is no way for a bug to move from any state directly to any other state e.g. A bug cannot move directly from New to Fixed

We, ourselves use our own bug tracking application but we have a lot more states to indicate whether a test case was present, if documentation was updated, if a test case was added, etc. Similarly you can make the workflow as complex or simple as you like. But for now, let's stick to the simple workflow that we discussed above.

Creating an App

To create an app, go to Top MenuAdminCustom AppsApps and click on Add. You will see a form with many tabs. We will cover each tab below.

The Basic tab
This tab defines some basic properties of the app. In addition, it also controls certain behaviours of the app.
Name The name of your app. We will put Bug here.
Plural The plural name for the name.
Initially Assign ToSelect the user who will be automatically assigned to new instances.
Use Requestor FieldBy default the creator of an app item is also the requestor for that app item. However, there could be cases where you would want to initiate an app on someone else's behalf and have notifications and updates sent to that person and not the creator. In our app, we would want our support agents to be able to open bugs on behalf of a customer, but we would like updates to be sent to the customer. So we turn it on. When enabled, you will see a Requestor field on while creating a new instance of an app.
Allow time loggingWhether to allow logging time on the app item. We would like our developers and QA team to log time, we so check this option.
Clients can initiate this appWhether you want your clients to create new instances. We would like our clients to report bugs, so we check this option.
Description A brief description for your app.
Followers Select the default followers. Followers will receive notifications when there is reassignment, state change or new comments.
ActiveWhether to enable or disable your app. Marking it as inactive will not delete existing instances of that app.

The States tab
This tab defines the states of the app. You can also mark the start and end states in the workflow. We have listed all the states in our bug workflow.
Start StateWen an app item is created, it is moved to this state. In our case it is New.
End StateWhen an app item moves to this state, the process is considered as finished. In our case it is Closed.

The Workflow tab
This tab defines all the arrows in the workflow diagram. Each arrow represents an end-user action. We shall see more about its usage later on in the documentation.
ActionThe name for the action. This will be used in action menus for bugs.
FromThe state where the arrow originates.
ToThe state where the arrow terminates. Once the action is performed, our bug will be moved to this state.
Assign ToThe user to whom the workflow will be assigned to after the action is performed. Prompt in Role: Developer indicates that the user performing the Verify action on the bug will be presented with a list of developers from which to choose the new assignee.
Allow UserDetermines whether this action can be performed by a user. In some cases, we would not want end-users to perform the action. E.g. in help desk systems, unresponsive tickets are automatically closed after a few days of inactivity.

The Triggers tab

Using triggers you can tell Celoxis to perform state transitions when it receives an email from the requestor.

In our bug tracking app, we don't need any triggers. However, let's take this help desk workflow for example. In case of the help desk app, the requestor will be the person who asked a question. When that person replies via email, we would want the ticket to be automatically moved to the Unresolved state as then it would be brought to the attention of the support team. In other words, we would want the Reopen transitions to happen. In this case, we would be defining our triggers like this:

The State Managers tab

A state managers is a user who is treated as a Manager when an app is in a particular state. They are notified when things happen to an item in this state. In our example below, Mark is the QA manager, so he is responsible for the New and Fixed states where the QA team is supposed to do work.

You can override state managers at a project level if the person managing that state is different.

What's Next?

We have created a custom app for our bug workflow. In the next chapter we will be adding some custom fields to the bug.