Adding cards with the Trello API

Wednesday 15 December 2021

In this article, I will discuss the process of adding cards, labels, custom types and lists to Trello using php and the Trello API.

The team have recently completed a requirements gathering exercise, capturing stakeholder needs and wants for our careers redevelopment project. We interviewed over 50 people and collected over 150 user stories. Each story contained the following information:

A unique reference
A product – applications affected
The actor (As a). – the person requesting the action (As a)
The activity (I want to) – the task
The benefits (So that) – the desired outcome
Acceptance criteria – the definition of done
Targeted user category – the main beneficiary of the stories
Object category – the item or items involved in the stories such as CVs, Events
Status – must, could, should, or rejected
Notes – any other relevant useful information.

This data was initially captured and refined using an excel spreadsheet. However, as the project moves into the design phase the team prefers to use Trello to better visualise and manage each user story.

This left me with the task of entering all 150+ user stories into Trello. I was not that keen on manually typing out each user story so I looked for an automated approach. It didn’t take me long to find Trello’s rest API documentation and to write a php script to do the grunt work for me.

Trello API Key and token

Before you can access the Trello API you will need to take a note of your security key and token. You can find your key and token by signing into Trello and then navigating to the app-key page.

Adding cards to a list

To add a card to a list you will first need the list id of the targeted list. Each Trello board has a handy JSON file that holds all the ids’ you will need. You can access the JSON file by visiting https://trello.com/b/[Your short board id found in the URL]/reports.json. Alternatively, you can use the API to retrieve the list id.

Each user story was created as a Trello card with the card name set to the “I want to” statement and the card description set to the “So that” text. I also added in some of the additional information such as the reference and category into the card description text to help with card searching within Trello.


$url = https://api.trello.com/1/cards?key=[apiKey]&token=[apiToken]&idList=[listID]&name='.urlencode ( ['cardName']).'&desc='.urlencode (['cardDesc']);

$data = array(
'key' => [apiKey]
'token' => [apiToken]
'idList' => [listID]
 );

$data = json_encode($data);
$ch = curl_init();
// curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER,
array('Content-Type:application/json', )
);

Adding labels to the cards

The status of each user story (must, could, should reject) was added to each card using labels.

I created the labels that I needed within the Trello board as I normally would and then viewed the boards JSON file to retrieve get label ids.

You can also use the API to retrieve the label ids. I added the labels at the same time as I created the cards.


$url = https://api.trello.com/1/cards?key=[apiKey]&token=[apiToken]&idList=[listID]&name='.urlencode ( ['cardName']).'&desc='.urlencode (['cardDesc']);
$url .= isset($idLabels)?'&idLabels='.$idLabels:'';
    $data = array(
        'key' => [apiKey]
        'token' => [apiToken]
        'idList' => [listID]
      );
$data = json_encode($data);
$ch = curl_init();
// curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER,array('Content-Type:application/json',)
);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_URL, $url);
$result = curl_exec($ch);
curl_close($ch);

Adding a checklist to the cards

Each user story was further defined by an accompanying list of acceptance criteria. I added the acceptance criteria to each card as a checklist. To add a checklist you must first create an empty checklist and then add each item to that list.

Creating a checklist


$url = https://api.trello.com/1/checklists?key=[apiKey]&token=[apiToken]&name=Acceptance criteria

The create checklist function returns a checklist id of the newly created list. We can then use this checklist id to add items to the list.

Add an item to the checklist


$url = https://api.trello.com/1/checklists/['checklist id']/checkItems?key=[apiKey]&token=[apiToken]&name='.urlencode([item 1])
    $data = array(
        'key' => [apiKey]
        'token' => [apiToken]
        'idList' => [listID]
‘name’ => [item 1]
      );
   $data = json_encode($data);
   $ch = curl_init();
   // curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER,
array(
'Content-Type:application/json',        
    )
);
curl_setopt($ch, CURLOPT_URL, $url);
$result = curl_exec($ch);
curl_close($ch);

Adding custom data types

The remaining details were added to the card as custom data. To add custom data to a card you will need the card id and the id of the custom data field. I created the custom data fields that I needed within the Trello board as I normally would and then used the JSON file to find the ids. Alternatively, you can use the API to retrieve the custom field ids. A PUT action request is sent to the API with the value and id of the custom Meta field. The custom field was passed as a standard POST value.


$url = https://api.trello.com/1/cards/[cardID]/ /customField/[customFieldID]/?key=[apiKey]&token=[apiToken]

$url .= isset($idLabels)?'&idLabels='.$idLabels:'';
    $data = array(
        'key' => [apiKey]
        'token' =>; [apiToken]
        'idList' => [listID]
        'dataType' => [custom value]
      );
   $data = json_encode($data);
   $ch = curl_init();
   // curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER,
array(
'Content-Type:application/json',        
    )
);
curl_setopt($ch, CURLOPT_URL, $url);
$result = curl_exec($ch);
curl_close($ch);

Trello API offers a wide range of functions to enable developers to create scripts to add, edit and automate tasks. So far I have just scratched the surface on what the API can do. For more details, I suggest visiting the Trello developer guide.

My complete php code can be found on github.