How does an integrated application interact with other TeamForge tools?

When you integrate an external application into your TeamForge site, the application can take full advantage of object IDs, links and Go URLs.

To look at how this works, we'll use the Pebble application as an example. Pebble is a blogging tool that you can quickly integrate with TeamForge.

Object IDs

Integrated application object IDs are of the form "prefix_objectId". Object IDs uniquely identify a TeamForge object so that you can access and use it in different contexts. For example, to get to artifact artf1234 quickly, you just enter artf1234 in the Jump To ID box. In the Pebble tutorial application, the date of a blog post, in YYYYMMDD format, is used as the object ID.

A prefix is an alphanumeric string attached to the beginning of an object ID that TeamForge uses to manage object IDs from different tools. For example, in the Pebble app, <prefix>_20100601 gets you a page showing all the blog posts in the project that were published on June 1, 2010.

In an object ID such as "prefix_objectId", the "prefix" is case-insensitive, whereas the "objectId" is case-sensitive. For example, the two object IDs, "PT_SC1" and "pt_SC1", refer to the same object in TeamForge. Whereas, the two object IDs, "PT_SC1" and "PT_sc1", refer to two different objects in TeamForge. Here, PT and pt are case-insensitive and the SC1 and sc1 are case-sensitive.

The prefix can either be the one specified when an integrated application is added to a project by project administrator, or the one in the XML Application configuration file depending on the "require-per-project-prefix" setting. The "require-per-project-prefix" setting can be true or false. If it is false, each project integration would not need to provide a project prefix; so the one provided in the XML application configuration file takes effect. If the "require-per-project-prefix" setting is true, a prefix needs to be provided by the user during every project association.

The amount of information the prefix carries depends on the kind of application you are integrating into your TeamForge site.

With applications that use object IDs, such as Project Tracker and JIRA, you can identify the project that the object belongs to from its object ID.
For applications that don't have uniquely identified objects, or don't have the notion of "project," such as MoinMoin or Review Board, you can choose a prefix that's specific to the project where the integrated tool is used.

Setting up multiple prefixes for integrated applications

At times, you may want to use more than one prefix for an integrated application such as the TeamForge EventQ. It is possible to have multiple prefixes set up for integrated applications. You must have the prefixes, separated by commas, included in the XML application configuration file and upload the file to your TeamForge site. For more information about uploading the application configuration file, see Edit an integrated application.

Consider the following while setting up multiple prefixes for an integrated application:

Prefixes, once set up using the XML application configuration file, cannot be modified.
A prefix can be up to six alpha-numeric characters in length. However, the combined length of all the prefixes cannot exceed 128 alpha-numeric characters.
The "require-per-project-prefix" must be set to false in the application configuration file. In case it is set to true, an error message appears when you upload the application configuration file.
Do not use existing prefixes. You cannot upload an application configuration file consisting of one or more prefixes already in use in TeamForge.

Go URLs

Go URLs allow a user to get to a particular object ID with a short, handy URL. To use this for Pebble, construct a URL like this: https://mysite.com/sf/go/<prefix>_<date in format YYYYMMDD>.

For example, if the Pebble tool in your project has the prefix PA, and you want to send someone all the blog posts published on app June 1, 2010, send them this link: https://mysite.com/sf/go/PA_20100601.

Associations

The object ID can be used to associate objects with other TeamForge objects. For example, if you want to associate a document with the blogs published on June 1, 2010, go to the document's Associations tab and add an association to PA_20100601 as the object ID.

Automatic links

When you type text of the format <prefix> _<date in YYYYMMDDD> in any TeamForge text field, the text is converted to a link. When you click the link you see the blog posts for that date, if any.