Intro to the GForgeNext API

GForgeNext is the newest incarnation of our long-lived project collaboration tool.  It ties together all of the most important features that teams need to deliver big things – like task tracking, team chat and integrated source control.   And in the next several months, we’ll add a lot more.

Next employs a Single Page Application (SPA) front end, and relies on our public REST API for all of its functionality.  Everyone can now build great tools and integration points with GForge using the same REST API that we do.

On that topic, then, let’s explore the API and build an example or two.

REST Basics

There are plenty of good, detailed tutorials about REST.  Here are the basics you need to get started with ours:

  • REST deals in resources.  In our case, things like users and projects.
  • REST uses the HTTP verbs you already know to get things done.  GET, POST, PUT and DELETE are the most common.
  • REST also uses the same HTTP response codes that web pages use.  404?  That record doesn’t exist.  400?  You submitted something invalid.  500?  You broke it.
  • REST uses the normal query string and request body that HTML pages use.
  • Data is typically exchanged (submitted and returned) in JSON format, which is easy to handle on most platforms.
  • Our REST API also accepts regular FORM POST format, so it can be called even from static HTML pages or libcurl.
  • All of the resources, methods and parameters for the API are documented in our API Docs.

Logging In

GForge has very deep and flexible access controls, and the data you receive from the API will usually depend on the user requesting it.  You can submit a separate user ID and password with each request, or get a session ID (from the /usersession endpoint).

Using curl:

curl -X POST

Results in:


The POST verb is used to create data on the server – in this case, a new session ID is created if the user and password match up.  You can then use the session ID in place of the password for further requests.  In a browser, the session ID will also be set in a cookie just like visiting the login page on a web site.

To “log out” and remove this session:

curl -X DELETE



Note that you have to include the session ID for both the authentication and to specify which session to delete.

Get Some Data

Now that we have an authenticated user, we can use it to get data from the API.  How about the user profile for a friend?




 "ccode":"US","language":"en ",

What’s Next?

Read the API docs, and see what you can get under the /api/user and /api/project endpoints.  There are a whole bunch of sub-entities within each one.  Then maybe move on to /api/tracker or even /api/trackeritem to see tasks.

For the especially brave, try /api/poll…

Got questions?  Comments?  Bugs? Leave a comment, or find me on Twitter @mtutty.

GForge Next – The API

A couple of weeks ago, Tony shared some screen shots of GForge Next, and talked about how we’re designing it to Get Out of Your Way.  Today, I’d like to talk about the other end of GForge Next – the API side.

We’ve Always Had An API

It’s true – the current GForge has an API, and it has for over ten years.  But it’s……not awesome.

If you have ever worked with SOAP services, then you know they can be overly complex, verbose and yet inscrutable.  Not to mention it can be fragile, especially between different platforms (I’m looking at you, Java/Axis/Axis2/XFire).

But the real flaw in our SOAP API is that is was bolted on to the existing code.  There’s quite a bit of logic shared between the GForge UI and the SOAP API, but also some duplicate code, so the API won’t always act the same way as the good old web UI.  As we continue to fix bugs and add features, it continues to be an extra effort to maintain these separate code modules and keep them working the same way.

Now With 100% More REST

Like everything else with GForge, we are our own worst critics, and our own first users.  So it was easy for us to decide that to be useful, the API had to be an integral part of the system.  The entire GForge Next UI runs against the API.  Logging in?  API call.  Getting your list of assigned tasks?  API call.  When we use GForge Next UI to accomplish tasks, we’re also automatically making sure that integration via the API will work for all of those use cases.

For wire protocol, we chose REST (like pretty much everyone else these days).  JSON + HTTP (GET, POST, PUT, DELETE) is a pretty simple, readable and capable combination, and it aligns nicely with the other parts of our technology stack (like AngularJS and Bootstrap).

The API is even self-documenting thanks to code-comment blocks in the underlying services and our /apidoc endpoint.  The API docs include all the entities, methods, parameters and even example input and output.  As we continue to add and change the API , the docs are automatically up to date.


For the most part, we submit data to the API using the same JS objects we receive from it.  That way, we can take an object from a list of values, assign it as a property on another object and submit it.  Super-simple on the client side, and pretty easy on the server as well.  But for external integration, it’s not so great.  Requiring callers to fetch a bunch of lists and sub-objects in order to properly craft a request makes the API less usable and more prone to invalid requests.  So, for most requests, we will accept any of the following values for sub-objects (like a project, a status, the user, etc.):

  • The “official” JS object for that type (retrieved from the API)
  • The ID or alias for the object, as a number or string value.  For example, ID 2000 or the short name mtutty for a user.
  • A JS object with an ID property, with the same value as the above bullet.

In general, the API back-end will work pretty hard to figure out what value you’re trying to use, and go find it based on the ID or key value submitted.  We also support vanilla FORM POST semantics, so that regular HTML forms, curl and wget requests are easy to do.

Complex Can Still Be Simple

So it’s pretty easy to create a basic CRUD API for a set of related tables.  The current GForge Next database has about 137 tables, which is a bit more complicated.  Add to that the fact that most realistic use cases (including our own UI views) are going to need multiple types of data, and using the API just went back to difficult and confusing.  Well, maybe not.

Largely for our own needs, we started adding related data as optional for many API calls.  By adding “rel=xyz” to a GET request, you can ask the GForge Next API for additional data that is related to the entity (or entities) you’re requesting.  So for example, GET /api/user/mtutty/details?rel=projects,activitylog includes the most-used projects and most-recent activity records for me.  That’s all the data needed for the user profile view, in one call.

Don’t need all that extra stuff?  Don’t include the rel, and you can get the payload down from 3.6K to 963 bytes.

How About Some Examples?

Here are a couple of ways we’re already using the API (outside of our own UI) to keep project data and knowledge moving, even when things are happening outside of GForge.

Build and Deployment Activity – We use Jenkins for CI/CD (and deploy GForge Next several times every day).  Whenever builds start or fail, or whenever a deployments starts or ends, we use the REST API to log an activity record.  This is visible in the Project Home page activity view and in the project chat room (which is where we see it most of the time).  Now as we’re working on tasks, we can see not only what tasks other people are working on, and their funny cat pictures, we can also see our build kicking off, and code going live, in real time.


Customer Feedback – First Dozen users will notice the green “Feedback” tab on every page in Next.  That tab submits data to a separate Tracker called, well, “Customer Feedback”, using the API.  Technically it’s part of our site but we have made a conscious effort to keep it separate from the AngularJS application that contains the rest of GForge Next.  The Tracker template will be available in GForge Next, and eventually we’ll make the widget available too, so customers can collect feedback from users directly into their GForge Next project.


Where To Go From Here

While we are excited for the new REST API in GForgeNEXT what really excites us is the creative ways developers will use the API.  Because the API is new and will continue to develop, we really hope you consider signing up for early access to GForgeNEXT. Those requesting early access will can expect the beta to begin officially over the next couple of weeks which will include immediate access to the API.

Maslow for Startups

Abraham Maslow was a psychologist and professor.  He designed this great hierarchy of human needs:

Maslow's Hierarchy
A simple version of Maslow’s Hierarchy

Basically, it says we need to breathe before bothering with staying warm.  And we need to eat before worrying about having any friends.  And we really can’t spend any time following our dreams until we’re clothed, fed, warm, have some friends, and overall feel pretty good about ourselves.

It seems natural to me that product-driven companies would follow a similar sort of hierarchy.  There’s a fairly common progression of needs that a company must satisfy in order to survive, grow and succeed.  In trying to figure out which GForge features you’ll really need, and in what order, I’ve come up with these buckets and given them catchy Greek-themed names.  We’re using these buckets to guide our feature deployment for GForge Next, so that we meet the needs of new users easily, and give them more features as they begin to need them.

Group 1: Atlas


The most basic level of business development.  This model depends heavily on large efforts by a small group.  Their roles, interactions and dependencies may be somewhat defined, but most processes are still ad-hoc, and are created, revised and discarded based on immediate needs.


Generally, boot-strapping – that is, getting to market on little (or no) financial budget.  Initial product/service delivery to see if the business model is viable, or trying to bring in the first customers to fund further expansion.


Atlas groups tend to:

  • Spend Time/Effort instead of Money

  • Be Flexible as opposed to Repeatable

  • Depend on A Few Heroes instead of Divide and Conquer

  • Prefer Simple Process over Robust/Complex Process


  1. Task/Issue Tracking – First and foremost, a persistent list for who is doing what. The group is very small, self-directed, and self-organizing, so features like metadata (e.g., severity, milestone, priority, workflow by status) and access control are not important.

  2. Version Control – Whatever type of product (software, design/creative/mkting, manufactured goods, etc.), there will be some kind of source code, documentation, images, or other output to be kept safe and trackable over time.

  3. Project Chat – A live, persistent and searchable scratchpad for quick discussions, news and humor without having everyone leave their desk.

Group 2: Vulcan


The first big change in team organization.  Initial product may be out, customers calling for support, feature requests, etc.  Team’s focus is still more tactical, day-to-day, but the group is growing to handle success.  Working some things in parallel, especially support tasks vs new features.


Leaders are focused on finding more customers, and keeping current ones happy.  Product delivery functions need to be automated, to allow tech staff to focus on what instead of how.  Customer service, support, operations and development tasks need to be centralized so that everyone can stay focused.  Knowledge needs to become somewhat portable so that team members can be added, back-fill others and cover breaks/days off.


Vulcan groups:

  • Place more premium on Time as money starts coming in

  • Need Repeatable processes that may still change often

  • Feel torn about moving key staff to bigger and better things

  • Start seeing many exceptions to what used to be simple processes


  1. Document Management & Wiki – Create a culture of portable knowledge early, and staff will maintain docs out of habit.  This makes it easier for players to switch positions, cover others during crunch times.

  2. Standups, Sprints & Milestones – Start to group tasks into small projects and track overall completion.  Allow different milestones to start competing for resources.  A first step toward portfolio management.

  3. Ubiquitous Search – Make it brain-dead simple to find that thing you saw a month ago, and share it with others.


Group 3: Prometheus


Things are really under way.  Founders may be somewhat disconnected from daily operations.  With monthly cash flow ensured, leaders begin to reach out to partners, competitors, upstream/downstream value chains, trying to expand customer base and/or find new features/products to add.  This phase usually includes the first serious wave of new hires who were not present at the founding of the org.  Cycle times get larger and more unpredictable as internal process and technical dependencies begin to weigh on the system.


Staying agile and responsive is even more important here than in previous phases.  Partners and competitors begin taking the product and company seriously.  This means real contracts, real accounts won and lost based on delivery.  At the same time, the heroes from Atlas phase are no longer able to touch everything every day.

At this point, the steering function has become as important to success as the rowing function.  Management needs to be able to see into the future, predict outcomes, plan for contingencies.


Prometheus groups:

  • Start to segregate knowledge to insulate groups from information overload and keep them focused.

  • Develop a strong need for metrics and measurement, instead of steering by feel.

  • Want standardized processes to allow for apples-to-apples comparisons over time.


  1. Robust Roles and Access Control – Organize things according to company structure, lines of business, etc.  Begin to control access by org and project membership.  Allow selected people/groups to collaborate from outside the company.

  2. Workflow and Audit  – As complexity and required quality levels both grow, more detailed workflow and audit trails are required to keep things moving quickly.



They Really Can’t, But You Can

Read this (now deleted) blog post by a dev at Oracle: No, You Really Can’t

There is so much wrong with that post.  But I’m in a hurry and don’t have time to put down 3000 words deconstructing Oracle’s entire business model and world-view.  Instead, I’ll just explain how we do the exact opposite.

GForge offers up the entire(*) code base for customers to examine, scan, and even change.  We maintain customer-accessible Git repositories (on, of course), so that customers have constant access to the current released version (that would be 6.4.1) and the version that’s in development, which we also deploy and use ourselves every day at

GForge customers can maintain their own Git repo (with, say, custom theme elements, or code to integrate with a custom database, or whatever), pull from ours, and keep up to date with new features, security patches and everything else we come out with.

As if that’s not easy enough, we also regularly send patches to customers to fix specific problems they report, even if they’re not at the current release version.  You don’t have to wait six months for the Oracle mega-patch, and get 3000 other changes you didn’t ask for.

Lastly, customers can (and are encouraged to) send us patches for things they have fixed or improved.  When Tony and I were GForge customers, we did this on a couple of occasions.  You’re welcome.

Every day, we try to treat customers the way we like to be treated.  Customer access to the source is just one reflection of that value.

PS – As if on cue, here’s a great example of why you don’t want to wait six months for the vendor’s bug fixes.

*Okay, okay.  There’s one file that we encrypt, that handles validation of the customer’s license key.  I know Richard Stallman is pro-actively spinning in his grave, but if you really want to see what’s in there, I’m sure we can arrange something.

GForge 6.3.1 Released

Today we are happy to announce the immediate availability of GForge Advanced Server v6.3.1.  This is primarily a bugfix release and the highlights include fixes for the Support Tracker feature and some minor security enhancements.

Download GForge Advanced Server v6.3.1 Now!

Support Tracker Fixes

If you haven’t already tried out the Support feature in GForge AS 6.3, you definitely should.  Here are a few key fixes and enhancements to that feature:

  • [#15070] Support tracker: Member group not set properly.
  • [#15071] Support tracker: skip first notification after the TI is submitted and set the timestamp
  • [#15134] Support group and assignee lost.  Suspecting cron15.php
  • [#15151] Support tracker: autoclose sets close date correctly  but it’s not visible in browse or TI pages.
  • [#15433] Filter “Out Of Office” replies (and similar automated messages) from creating support requests in GForge

Miscellaneous Improvements

There are also a few other improvements that warrant a quick mention:

  • [#11848] Mass Delete broken
  • [#19112] Navigating wiki versions doesn’t quite work right.
  • [#19246] License Tracker – Valid user gets access denied
  • [#19258] Docman allows uploading of HTML files which can have spam  possibly JS making it possible CSRF vuln
  • [#19388] My Account > Disable Account not working
  • [#19221] When parsing files  filesystem_index cronjob could trigger a tracker item notification
  • [#11830] Fix xss vulnerability in tracker item edit screen
  • [#19331] Sanitize paginator parameters
  • [#19847] MAG: change default database name to “gforge” instead of “gforge5”
  • [#19649] upgrade_gforge – Unused plugins cause confusing output

For full details, please have a look at the Complete GForge v6.3.1 ChangeLog

Download GForge Advanced Server v6.3.1 Now!

How Valuable Are You?

A long time ago, I learned some great criteria for taking or keeping any job.  I mean, like, a long time ago.  Like, before Google.

Here they are, in random order – apply your own prioritization:

  • Will you be successful? That is, will you deliver projects, make money, become famous, get the girl, whatever it is that you want.
  • Will you learn something new?  Might be technical, might not.
  • Will you be valued?  Will the people you’re working with (and for) be capable of understanding your contributions?  Will they appreciate your contributions?

For me, the third bullet has always been the toughest to find or keep.  Maybe that’s why it is my most important criteria.  Or, maybe it was already my most important, and I just noticed how much trouble finding it could be.

So, how do people make themselves valuable?  I’ve seen two basic approaches in the twenty or so years I’ve been doing this.

The Wrong Way – What You Keep to Yourself

Historically, people make themselves valuable (and/or powerful) by becoming the choke point for information, or approval, or funding, or whatever.  When only one person in your organization is allowed to touch the requirements (or the database, or whatever), you may be dealing with someone who measures their value this way.

“I take the requirements documents from the customers and bring them to the developers”

He may have people skills, dammit, but he’s not helping the team – he’s making sure that they can’t get along without him.  Or so he thinks.

As a manager, I can tell you that my biggest HR risks are always the people who bottleneck knowledge, process, money, whatever.  If they get hit by a bus, decide they want a big raise, or take an extended vacation, we’re hosed.  They have knowledge, skills or connections that we can’t easily reproduce.  So as the person who’s responsible when bad things happen, I’m going to actively pursue this person’s secrets, and make sure they’re backed up somewhere, by someone.

If it sounds like a bad situation for the team, it is.  But it’s actually just as bad for the person, in most cases.  Ten years ago, I started a new job as a team leader.  The biggest complaint from the team was that they were each chained to a given project.  They were the only person on the project, they carried all of the knowledge, the relationship, and the responsibility.  They couldn’t move on, they couldn’t learn anything new.  They were just stuck.  For most people, this does not feel like success.

A year later, we had standardized our process, the documents we used, even much of the code templates.  People were able to move from one project to another.  They were even able to talk to each other about different projects using common terms.  There were a few people who didn’t like this change, even though they had complained about lack of mobility.  Those folks still hadn’t adjusted their way of measuring their own value.

The Right Way – What You Give Away

Plenty of good engineers are collaborative by nature – that is, they enjoy sharing their knowledge and getting some of yours in return.  And while it’s certainly a more friendly way to work together, it’s also more productive, more robust and more resilient, especially in the face of team or project changes.  But believe it or not, giving away what you know actually makes you more valuable as well.  Think about how valuable Stack Overflow is today, and you’ll see that it’s true.  Compare SO and its success against ExpertsExchange, which largely hides answers behind a paywall.  EE might make some money, but SO rules the world.

Being an “open knowledge” kind of person is also the best defense against Competence Debt and other creeping forms of team decay.  So as a team member I like the approach, but as a manager I demand it.


GForge: What’s Next?

The Pitch

Won’t you make some time to come help us build and perfect GForge Next?  Just leave a comment – we’ll be recruiting First Dozen candidates through the end of April, and would love to hear from you.  If you can’t make it for May, then we’ll add you to the invite list for the Next Hundred phase.  Send a link to anyone that might be looking for a better, more powerful and more cost-effective tool for tracking tasks and collaborating on projects.

First, A Bit Of Background

If you’re already familiar with GForge and what it does, feel free to skip ahead.  If not, you’re in the right place.

GForge is a commercial product built and maintained by the GForge Group.  It was originally started as a fork of the Sourceforge code nearly 15 years ago.  It’s a project collaboration web application that includes a ton of modules for each project, from task tracking to version control, mailing lists and forums to wiki pages and blogs.  It has very broad and deep configurability, and nearly everything can be access-controlled to specific (and configurable) project roles.  Pretty much everything gets logged in an audit table for traceability, and there’s reporting almost everywhere.

Most of our customers are large, engineering-oriented shops with CMM, DoD or other stringent standards to meet, across dozens or even thousands of projects.  Think chip makers, defense contractors, gigantic world-wide engineering and manufacturing conglomerates, that kind of thing.  We license the code to our customers, and they have access to that code for their own security analysis, review or customization purposes.  We’re extremely customer focused.

The Problem

I’ve been at GForge for nearly two years now.  In that time, we’ve added some significant new features (chat and support trackers come to mind), cleaned up a lot of old code, and generally moved the product forward in lots of very gratifying ways.  Before working for GForge, I was a customer for nearly ten years, so I developed some pretty clear ideas of what was special about the product, and what could, uh, use some work.  And while we’ve done many of the things I had in mind, in the end, it’s not enough.

The features, the integration between them, and the data – those are all very solid and still very relevant in 2014.  But the existing GForge code, the existing layout and user experience will just never do the things we want them to do.  The structure of the code is out of step with current patterns, and simply won’t work with autoloaders, Composer and other tools that make PHP so productive in 2014.  Much of it isn’t very testable.  There’s all manner of technical debt in the old code, like raw HTML output from domain models, overly-complicated URL parsing and generation, and so. many. different. pages.

To build the next GForge, we’re going to start from scratch – well, sort of.

Existing GForge Customers: This plan involves a gradual re-implementation of the features currently available in GForge AS.  There is NO plan to end new development or support for GForge AS, and there won’t be any plan until GForge Next is ready for prime time.  Just as we did with the 5.x sunset, existing customers will have plenty of time to evaluate, test and migrate from GForge AS to GForge Next.  We will develop and support both GForge AS and GForge Next for quite some time, and we’ll make sure that the transition is low-risk and high-value for you.

The Plan

To build GForge Next, we’re going to write brand new code on top of the same database.  This means that we’ll be able to check what the new code does by reading and running the old code, using the same data.  It also means that as people start testing GForge Next, they will also be able to switch to (old) and see the exact same data.  Or do something that the new code doesn’t support yet, which brings me to my next point.

The existing features are broad and deep.  In fact, they can be distracting or downright intimidating for new users, who don’t need that kind of power or flexibility.  So we’re going to deliver GForge Next in roughly four phases, outlined below.  The first phase will be focused on task tracking and version control.  It’ll be very simple and very opinionated – many of the choices you could make in the current GForge release will be pre-set and not configurable.   Subsequent phases will add back the existing GForge features, but with carefully reconsidered user experiences, and (wherever possible) mobile and touch-friendly rendering.

Our phases revolve roughly around the size of the testing user base, as follows:

The First Dozen (FREE!)

Starting in late May, we’ll have a very basic, low-friction version of GForge Next deployed and running.  We’re looking for about a dozen people/groups to use it on a daily/weekly basis and work closely with us to ask questions, tell us what works (and what doesn’t work), and basically give us lots of feedback.  In return, we’re going to update the site many times each week (or each day), tweaking the look and feel, fixing bugs and adding features constantly.

Main features for The First Dozen will be pretty basic:

  • Login – Using a GForge account, or others (possibly Github, G+, even Stack Overflow?)
  • Create a Project
  • Invite users to your project
  • Project Chat – Ever-present contact with the entire project team.  Archived, searchable, and integrated with the other GForge Next features.
  • Git repo (including the option to clone a remote as part of the project setup)
  • Kanban Task View (we call them Tracker Items)
  • Tracker Item Browse – a more tabular view than Kanban, with more filtering, sorting, export and edit capability

The goal for this phase is to allow small teams or casual users to test GForge Next with their existing code, with less than 5 minutes of setup time.

The Next Hundred (Still FREE!)

In late July or early August, we’ll add up to 100 users/projects to our test group, and the following features:

  • Sprints – Group Tracker Items, track velocity for each Sprint
  • Super Search – One search bar, in the same place on every page.  Searches everything you’re involved with, and shows results by project or module.
  • The “G” Mega-Menu – Super-simple navigation across everything you might need
  • Git repository browser – See tags, branches, file tree, revisions, commits, and diffs as part of the GForge Next interface
  • Batch Import – Create a bunch of Tracker Items with as little as a title for each.  Paste lines into the box and voila.
  • Activity Stream – See a real-time feed of who’s doing what on the project.  Commits, Kanban and Tracker Item changes, all that stuff.
  • Pull Requests – View and comment on the diff, iterate on the changes, and promote new code, all on the GForge Next server.
  • Standup Report – Get your story straight a the daily, weekly or random standup in 60 seconds or less.  Then everyone can share their 1/2/3 list quickly or review it later via web.

 Open For Business

Late this year, we’ll launch the paid version of the service.  Projects from The First Dozen and The Next Hundred will get free or heavily discounted rates, as will qualified open-source projects and even some startups.  This version will include practically everything currently included in GForge AS, plus some all-new features and capabilities:

  • Workflow Design – Fully-customizable Tracker workflow.  Define who can move a Tracker Item to each status, require fields based on the new status, trigger scripts, set/update fields.
  • Reporting and Charting – Powerful data gathering, filtering and sorting, combined with tabular and printable views, file export, and charting.
  • Project Homepage
  • Wiki
  • Kanban Setup – Define your own custom planning board.  Choose almost any field for the columns (like release, assignee, sprint), group values together, show aggregates for each column (like count or average size).  Save and name your board and let the whole team use it.
  • Organizations and User Groups – Define organizations and put projects under them.  Create groups of users (like customers, vendors, or various departments), and give those groups access to what they need.
  • Customer Support Tracker – Currently available in GForge AS 6.3, give your customers the ability to submit and update tickets.  The customer view shows only those Tracker Items that belong to the user’s group or organization.

But Wait, There’s More!

Starting in 2Q 2015, we’ll add even more:

  • Discussions / mailing lists
  • Social features – Upvoting, endorsements, suggestions based on friends of friends or shared technology between projects.
  • Document Management – The powerful docman module currently available in GForge AS 6.3.  Drag-and-drop upload/download, versioning, comments, even inline edit for text/html.
  • Release Management – Build a roadmap of product versions, and manage the set of Tracker Items in each release.
  • Request To Join
  • Project Fork – Clone the setup and the Git repository for an existing GForge Next project.
  • Blog/CMS Module
  • Tracker Detail Designer – Lay out the Submit or Edit form your way.
  • Migrations from Github and Jira
  • Enterprise Login – Install GForge Next inside the firewall and use LDAP, SSO, or OAuth for your internal user base.
  • SVN and Mercurial support
  • Jenkins Integration – View and kick off Jenkins builds from GForge Next.  Install the Jenkins plugin and give project users seamless access to their GForge Next projects in Jenkins.