KanBo API for versions 2.2-2.6
Last modified:
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
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:
id – id of the card you want to get
Task<string> GetClosedBoards()
Description:
Returns intended JSON for KanBo closed boards.
Task<string> GetList(int listId)
Description:
Returns intended JSON for KanBo list.
Parameters:
listId – id of the list you want to get.
Task<string> GetLists(int boardId)
Description:
Returns intended JSON for KanBo lists.
Parameters:
boardId – id of the board from which you want to get lists from.
Task<string> GetUnreadBoardsActivitiesCount()
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
Task<bool> AddUserToKanBo(string login)
Description:
Adding user to KanBo
Parameters:
login – full login of a user you want to add
Returns:
Returns true
Action methods
Task<bool> ArchiveCard(int cardId)
Description:
Archiving card
Parameters:
cardId – if=d of a card you want to archive
Returns:
Returns true.
Task<bool> ChangeBoardColor(int boardId, int color)
Description:
Changing board color.
Parameters:
boardId – id of a board
color – chosen colr
Returns:
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.
Task<bool> DeleteCard(int cardId)
Description:
Deleting card
Parameters:
cardId – id of a card
Returns:
Returns true.
Task<bool> MakeUserResponsible(int userId, int cardId)
Description:
Making user responsible
Parameters:
userId – id of a user
cardId – id of a card
Returns:
Returns true.
Task<bool> MoveCard(int cardId, int listId)
Description:
Moving card between boards
Parameters:
cardId – id of a card
listId – id of a target list
Returns:
Returns true.
Task<bool> PositionList(int listId, int listPosition)
Description:
Changing list position within board
Parameters:
listId – id of a list
listPosition – new position
Returns:
Returns true.
Task<bool> RemoveDocument(int containerId, int cardId)
Description:
Removing document from card
Parameters:
containerId – id of a document container inside card
cardId – id of a parent card
Returns:
Returns true.
Task<bool> RemoveDueDate(int id)
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.
Task<string> RemoveList(int listId)
Description:
Removing list from board
Parameters:
listId – list id
Returns:
Returns intended JSON for removed list.
Task<bool> RemoveUserFromCard(int userId, int cardId)
Description:
Removing user from card.
Parameters:
userId – id of a user
cardId – id of a parent card
Returns:
Returns true.
Task<bool> RenameCard(int id, string name)
Description:
Renaming card.
Parameters:
id – id of a card
name – new card title
Returns:
Returns true.
Task<bool> RenameElement(int id, string name)
Description:
Renaming element in card (Checklist, Note, Document container, etc.)
Parameters:
id – element id
name – new title
Returns:
Returns true.
Task<bool> SaveBoardAsTemplate(int boardId, string title, string description)
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.