KanBo API for versions 2.2-2.6

Last modified: 4 years ago

API

Configuring KanBo app

If you want to use KanBo API via KanBo.Client.dll you have to first configure your KanBo app.

This instructions is intended to be used with KanBo 2.2 - 2.6

Download KanBo API samples.

Abstract

If you want to use KanBo API via KanBo.Client.dll you have to first configure your KanBo app.

Authentication providers will reside inside *web.config* in section `<kanbo><authentication>`.

In order to use KanBo with fully-trusted app you will have to register x509 certificate that will be used to validate the token issued by your client application.

The *CreateCert.ps1* in api sample is the powershell script used to create *x509* certificate and private key in *pkcs #12* using *makecert.exe* and *pvk2pfx.exe*. You can find them both in the Windows SDK. You can also generate the public+private key pair using other tools (for example with IIS or openssl), they will work as long as they're pfx + cer pair.

The configuration should look mostly like that (more about how to configure in configuring KanBo

(#Configuring kanbo), be wary not to remove the Sharepoint authentication method):

XML:

  <kanbo>
    <authentication>
      <provider id="my-fancy-app" type="AppSignedUser">
        <signer type="X509SignerFromFile" file="C:\fancyapp\mycert1.cer" />
      </provider>
    </authentication>
  </kanbo>

In C#:

public async Task Example()
{
  var kanboUrl = "https://kanbo.example.org";
  // instance of your kanbo app
  var instanceId = 3;
  // id of your kanbo user
  var userId = 42;
  // private key specified and the issuer bound to it
  var certificate = new X509Certificate2(@"C:\fancyapp\mycert1.pfx", "secret!");
  var issuer = "my-fancy-app";
  // you can use any timespan here, but try to keep it short
  // using small or negative values will make your request always fail
  // your server and client need to have synchronized clocks
  var duration = TimeSpan.FromMinutes(10);
  // create a token source
  var tokenSource = new UserToken(issuer, userId, instanceId, duration, certificate);
  // create a requester
  var requester = new JsonApiRequester(tokenSource, kanboUrl);
  // do a request
  var currentUserData = await requester.GetData("CurrentUser", new { });
}

The code above uses `IRequester` interface, which returns raw json objects from the request. They can be casted either into `JArray` and `JObject` types. There's also a special `Api` class that contains helpers for some methods/versions of api for more info about it, see [using api](#Using Api) section.

Configuring KanBo

The general format for a provider entry in web.config looks like this:

In web.config (XML):

<provider id="{issuer}" type="{type}">
  {signer}
</provider>

The `issuer` can be whatever you like, you will pass this identifier with your token. The issuer id must be unique.

The `type` declares the token consumer type and it needs to use one of the following:

- **AppSignedLogin** - kanbo will identify you as the user with given login

- on-prem login will look like this: `i:0#.w|domain\user` `domain\user`
- o365 login will look like this `i:0#.f|membership|[email protected]` `[email protected]`
- example: `<provider id="login" type="AppSignedLogin">{signer}</provider>`

- **AppSignedUser** - kanbo will identify you as the user with given id. Example:

XML:

<provider id="user" type="AppSignedUser">{signer}</provider>

- **AppSignedService** - kanbo will give you full access to everything, but you won't be identified as user (some methods that need user context will fail). Example:

XML:

<provider id="app" type="AppSignedService" name="Test service">`{signer}</provider>

The `signer` declares which certificate will be used to validate the signature of given token, possible types are:

- **X509SignerFromFile** - contains a public or private key read from a file by specified path (you can use either .cer or .pfx here, pfx file will need a key). Examples:
- `<signer type="X509SignerFromFile" file="c:\.ssl\kanbo_id.pfx" key="MyKanBo" />`
`<signer type="X509SignerFromFile" file="c:\.ssl\kanbo_id.cer" />`

- **X509SignerFromStore** - contains a public or private key read from a certificate in given certificate store by specified property
- `<signer type="X509SignerFromStore" storeName="My" storeLocation="CurrentUser" key="Thumbprint" value="A89369E6705C2B3E446AF5DD5A2A1B559F913152" />`
- `<signer type="X509SignerFromStore" storeName="My" storeLocation="LocalMachine" key="Thumbprint" value="a89369e6705c2b3e446af5dd5a2a1b559f913152" />`
- `<signer type="X509SignerFromStore" storeName="My" storeLocation="LocalMachine" key="Thumbprint" value="a8 93 69 e6 70 5c 2b 3e 44 6a f5 dd 5a 2a 1b 55 9f 91 31 52" />`
- `<signer type="X509SignerFromStore" storeName="My" storeLocation="LocalMachine" key="SerialNumber" value="a89369e6705c2b3e446af5dd5a2a1b559f913152" />`
- `<signer type="X509SignerFromStore" storeName="My" storeLocation="LocalMachine" key="SubjectName" value="MyFancyApp" />`

Using API

Api is comprised of a few layers:

1. Token source `ITokenSource`

2. Requester `IRequester`
3. `Api` wrapper

1. Token source `ITokenSource`

Generates the validated token for KanBo, it's described by string, there are a few implementations in KanBo.Client.dll. The common parameters are:

- **issuer** - issuer for the used signing certificate
- **instanceId** - id of an KanBo instance
- **userId** - id of a user our service will impersonate (**only for `UserToken`**)
- **userLogin **- login of a user our service will impersonate **(only for `LoginToken`)**
- **certificate** - the certificate used to sign the user, create it like this: `new X509Certificate2("C:\cert\path.pfx", "secret!");`

- **duration** - it will define for how long the token is valid (after that it's re-issued)
- it's suggested to use the default value, however if your clocks are synchronized, if not, you may consider using [special tokens that synchronize your client with server](https://bitbucket.org/objectconnect/kanbo-additionaltokens)

Example usages of the tokens:

In C#:

var userToken = new UserToken(issuer1, userId, instanceId, TimeSpan.FromMinutes(10), userCer);
var serviceToken = new ServiceToken(issuer2, instanceId, TimeSpan.FromMinutes(10), serviceCer);
var loginToken = new LoginToken(issuer, loginName, instanceId, TimeSpan.FromMinutes(10), loginCer);

2. Requester `IRequester`

Makes the requests against given url. You can invoke methods with SignalR or JsonApi (it's suggested to use JsonApi as it doesn't have underlying hidden connection state).

In C#:

var req = new JsonApiRequester(token, kanboUrl);
JObject result = await req.GetData("CurrentUser", new {});
JObject result = await req.Action("CreateMyBoard", new {});

This gives you the api the same as used by the javascript client. You can get the list of methods and arguments with the following helper class:

In C#:

class ApiMethodsLister
{
  private readonly IRequester requester;
  public ApiMethodsLister(JsonApiRequester requester)
    => this.requester = requester;
  private async Task<IEnumerable<ApiMethod>> List(string type)
  {
    JArray methods = (await requester.GetData(type, new { })).Methods;
    return methods.ToObject<IEnumerable<ApiMethod>>().OrderBy(o=>o.Name);
  }
  public Task<IEnumerable<ApiMethod>> GetDataMethods() => List("GetDataMethods");
  public Task<IEnumerable<ApiMethod>> ActionMethods() => List("ActionMethods");
  public class ApiMethod
  {
    public string Name { get; set; }
    public ApiArg[] Args { get; set; }
    public override string ToString() => $"{Name} ({string.Join(", ", Args.Select(x=>x.ToString()))})";
  }
  public class ApiArg
  {
    public string TypeName { get; set; }
    public string Name { get; set; }
    /// <summary>
    /// this will be true if the field is *always* required
    /// </summary>
    public bool IsRequired { get; set; }
    public override string ToString() => string.Format("{0} {1}{2}", TypeName, IsRequired ? "*": null, Name);
  }
}

3. 'API' Wrapper

Helps you make requests against KanBo server, keep in mind that due to changes of the internal api between versions, some of methods may change, in which case you'll need to use raw `IRequester` like described above.

Available methods

Get data methods

Task<string> GetBoard(int id)

Description:

Returns intended JSON for KanBo board.

Parameters:

id – id of the board which you want to get

Task<string> GetBoardGroups()

Description:

Returns intended JSON for KanBo board groups.

Task<string> GetBoardTemplates()

Description:

Returns intended JSON for board templates

Task<string> GetCard(int id)

Description:

Returns intended JSON for KanBo card.

Parameters:

Description:

Returns intended JSON for unread activities count by board.

Task<string> GetUsers()

Description:

Returns intended JSON for KanBo users

Task<string> ViewLandingPage()

Description:

Returns intended JSON for landing page.

Add data methods

Task<string> AddBoardsGroup(string title)

Description:

Adding new board group on KanBo

Parameters:

title – title for the new board group

Returns:

Returns intended JSON for created board group

Task<string> AddBoard(int boardGroupId, string title, int color)

This function can be called only by Api object created by using userToken or loginToken.

Description:

Adding a new board on KanBo

Parameters:

boardGroupId – id of a board group to which you want to add board

title – title of a new board

color – id of a color for board (0-15)

Returns:

Returns intended JSON for created board

Task<string> AddBoardChatMessage(int boardId, string text)

This function can be called only by Api object created by using userToken.

Description:

Adding new message on board chat

Parameters:

boardId – id of a board on which you want post message

text – content of a message

Returns:

Returns intended JSON for added message

Task<string> AddCard(int listId, string title)

Description:

Adding new card to list

Parameters:

listId – id of a list on which you want to add card

title – title of a card

Returns:

Returns intended JSON for added card

Task<string> AddChecklist(int id, string text)

Description:

Adding new checklist on card

Parameters:

id – id of a parent card

text – checklist title

Returns:

Returns intended JSON for added checklist

Task<string> AddChecklistitem(int checklistId, string text)

Description:

Adding new item to checklist

Parameters:

checklistId – id of a parent checklist

text – content of checklistitem

Returns:

Returns intended JSON for added checklistitem

Task<string> AddCommentOnCard(int id, string text)

Description:

Adding comment on card

Parameters:

id – id of a parent card

text – comment content

Returns:

Returns intended JSON for added comment

Task<bool> AddDocumentToCard(int cardId, int? docSourceId, string path)

Description:

Attaching document on card

Parameters:

cardId – id of a parent card

docSourceId – id of board document source

path – path to file in document source

Returns:

Returns true

Task<string> AddLabel(int cardId, int labelId)

Description:

Adding label on card

Parameters:

cardId – id of a parent card

labelId – id of a label

Returns:

Returns intended JSON for added label

Task<string> AddList(int boardId, string title)

Description:

Adding new list on board

Parameters:

boardId – id of a parent board

title – list title

Returns:

Returns intended JSON for added List

Task<string> AddNote(int id, string name, string text)

Description:

Adding new note on card

Parameters:

id – id of a parent card

name – note title

text – note content

Returns:

Returns intended JSON for added Note

Task<bool> AddUserToBoard(int userId, int groupId)

Description:

Adding user to board

Parameters:

userId – id of a user u want to add

groupId – id of a permission group associated with board

Returns:

Returns true

Task<bool> AddUserToCard(int userId, int cardId)

Description:

Adding user to board

Parameters:

userId – id of a user you want to add

cardId – id of a parent card

Returns:

Returns true

Returns true.

Task<bool> ChangeCardParent(int containerFromId, int containerToId, int id)

Description:

Moving card

Parameters:

containerFromId – start list id

containerToId – target list id

id – card id

Returns:

Returns true.

Task<bool> ChangeListSettings(int listId, int color, bool ignoreDueDate, int wipLimit)

Description:

Changing KanBo list settings

Parameters:

listId – id of a list

color – chosen color

ignoreDueDate – should list ignore due dates

wipLimit – wip limit count

Returns:

Returns true.

Task<bool> ChangeNoteContent(int id, string text)

Description:

Changing note content

Parameters:

id – id of a note

text – new note content

Returns:

Returns true.

Task<bool> CloseBoard(int boardId)

Description:

Closing board

Parameters:

boardId – id of a board

Returns:

Returns true.

Task<bool> CompleteChecklistItem(int id)

Description:

Marking checklist item as complete

Parameters:

Id – id of item

Returns:

Returns true.

Description:

Removing due date

Parameters:

id – id of a parent card

Returns:

Returns true.

Task<bool> RemoveElement(int id)

Description:

Removing element from card (Checklist, Note, Document Container, etc.)

Parameters:

id – element id

Returns:

Returns true.

Description:

Saving desired board as template for future use

Parameters:

boardId – id of a board

title – title for template

description – description of a template

Returns:

Returns true.

Task<bool> SetDueDate(string date, int id)

Description:

Setting due date on a card

Parameters:

date – new date to set

id – id of a parent card

Returns:

Returns true.

Task<bool> UncompleteChecklistItem(int id)

Description:

Marks checklist item as uncompleted

Parameters:

Id – id of item

Returns:

Returns true.