Source Control Integration

You can easily connect an existing source control solution with Axosoft by creating an entry for it in "Tools > Other Settings > Source Control Types". Once you've named and enabled your source control type in the Axosoft Suite, you only need to configure a few options:

1. Set default user to assign commits/changes to if they don't map up to an existing user.
2. Optionally map commits to a user by email if it can't find a user with a matching username.
3. Generate an API key.

For all of the values in the lower "Mappings" section, fill them out according to the documentation provided with the integration plugin. If you don't have any documentation, contact the original developer of the integration.

The only things you should need to provide to your source control plugin are the address of your Axosoft installation and the API key you've generated.

Developing your own custom Axosoft source control integrations

What you need from the user

To integrate with the Axosoft Suite, your plugin needs two pieces of information from the user setting up the system: The address used to access the Axosoft Suite and an API key specific to your integration, which is a guid generated by the Axosoft administrator. These values should not be expected to change frequently, but should be able to be changed easily in case the user regenerates the key or their url changes.

Forming your data

Each time you get a commit (or a push), you'll want to post some information about it to Axosoft. The actual data about your commits will be sent as JSON. The nice thing about the Axosoft source control api is that bar one small restriction, you can format this data however you like, and almost all of it is optional.

The API accepts the following information for each commit:

Each of these properties can be stored anywhere in your object as long as it can be reached through an explicit path. You can have all of the user information in an object inside another object like so:

{
"text": 'bob did things [axod: 74],
"meta": {
    "user": {
        "display_name": 'Greg Greggerson',
        "domain_id": '//GREGSDONUTSHOP/GREGGREG',
        "website": {
            "url": 'http://greg.gregsdonutshop.biz/greg'
        }
    }
}

The user configuring Axosoft just needs the following information to fill out the mappings section in the Add Source Control Type dialog:

• Message: "text"
• User display name: "meta.user.display_name"
• User login: "meta.user.domain_id"
• User URL: "meta.user.webiste.url"

There is one extra option available to you when formatting your post data. You can send multiple commits at once. The user has an option to configure a "commits" parameter. This parameter can be referenced by an explicit path just like the others, and like the files parameter is an array of JSON objects. When Axosoft receives a post for a type which is configured to have a commits parameter, it will pull out the array at that location in the object, and pass the objects along individually to be processed as if they were sent in multiple posts.

Note: The entirety of the data you post is saved in string format by Axosoft. Where possible, avoid sending extraneous data.

Formatting Message

Any message that contains a specially formatted Axosoft tag will attempt to be linked to the corresponding Axosoft item when adding a commit or check-in. The required format is as follows:

[axox: id# (wl: n timeunit)]

Where the x in axox can be:

• d for defects (axod)
• f for user stories (features) (axof)
• t for custom items (tasks) (axot)
• i for incidents (axoi)

For legacy versions, use otx, where x is the letter for item type as shown above.

Note: d f t and i are constant even if you've renamed the item types in Axosoft.

id# is the Axosoft item ID.

wl: n timeunit is optional. When provided, it will add a work log entry to the item when the commit is pushed to GitHub.

n needs to be a non-negative real number.

timeunit is a valid time unit that is used in your installation, either fully spelled or abbreviated with respect to your Axosoft time unit list type configuration.

A few examples of valid tags (assuming you have hours as a time unit in Axosoft and its abbreviated spelling is 'hrs'):

• [axod: 45]
• [axof: 2]
• [axof: 823 wl: 5 hours]
• [axot: 92 wl: 8.3 hrs]
• [axoi: srx0091]

Making Your Post

Posting to the api is fairly simple. It's a straight forward HTTP post to a specific url with JSON data and an additional query string parameter. To send a post do the following:

1. Put together the URL. The URL is the root url you received, with /api/v5/source_control_commits/ appended, e.g. "https://gregsdonutshop.axosoft.com/api/v5/source_control_commits".
2. Build your post data as described above, and convert it to a string.
3. Append the api key you get from the user to the JSON string, and hash this with SHA256. Append this to your url as a query string parameter called hash, e.g. &hash=xyz....
4. Set your "Content-Type" header to application/json.
5. Send your request with the HTTP verb POST

The Response

Axosoft will respond in one of 3 ways.

• If the hash doesn't match up with any source control types (you have the wrong api key) Axosoft will respond with a 404 Not found.
• If Axosoft receives the commit and finds a matching type, but doesn't find any items matching the tags in the commit it will respond with a 200 OK.
• If Axosoft successfully hooks up the commit to one or more items, it will respond with a 201 Created.