Class: Notification

TrellinatorCore.Notification(notification)

The Notification object takes a notification from the Trello API sent to a webhook and makes it easy to determine what type of event took place and to get access to the entities that were part of the notification. The notifications passed into this constructor are always sent to webhooks registered at the board level. There are 4 types of method:

  • methods that return an object that was the source or origination of this notification, throwing an exception if that object is not present which indicates in turn that type of notification did not occur. The first part of the function name is the verb, with the object coming after, eg. archivedCard or completedChecklistItem.

  • methods that return an entity that was part of the notification, such as board(), card() and member(). Given these notifications are always at the board level, there is always a board() and given every notification originates with an action by a member there is always a member() however there is not always a card(), so if for example this notification is a list name being updated the card() method will throw an InvalidActionException

  • Finally there are a couple of convenience functions that are just shorthand for a few different common scenarios such as actionOnDueDate and replyToMember

  • Static methods that are used globally and are simply grouped within this class for logical reasons

There are some methods that are deprecated or used internally by other class methods so you can ignore those, they are marked as such in the code comments, but aren't included in the API documentation.

Even though all methods are marked as "static" by jsdoc, the ones that start with "this." aren't static. I don't know how to make jsdoc display them as non-static, so if you do then please send a pull request :)

Methods that deal with detecting whether an action took place will throw an InvalidActionException if that action did not take place.

Unless you want to explicitly take action in the case that some action didn't occur, you don't need to catch these exceptions; Trellinator will catch them for you. An InvalidActionException is not considered "fatal", neither is an InvalidDataException (typically thrown by entity classes or the IterableCollection).

If you do want to catch exceptions, you should look at the Exceptions.js documentation and the two static methods on this class Notification.logException and Notification.expectException to see how to do this according to Trellinator best practices

Constructor

new Notification(notification)

Parameters:
Name Type Description
notification Object

an object that has been posted to a webhook from the Trello API
Source:

Methods

(static) Notification.expectException(type, e)

When you catch an exception, throw it again if it is not the type you expected. This is useful when catching exceptions thrown by entity classes such as Card and Board. These will throw InvalidDataExceptions but will never intentionally throw a ReferenceError for example.

Parameters:
Name Type Description
type function

the constructor function of an exception, typically one from Exceptions.js
e Object

the exception you caught
Source:
Example
var notif = new Notification(posted);
//Remove any labels that were added that
//aren't "Urgent"
try
{
    var label = notif.addedLabel("Urgent");
}

catch(e)
{
    Notification.expectException(InvalidDataException,e);
    notif.card().removeLabel(notif.addedLabel());
}

(static) Notification.logException(message, e)

Log a message in the Info Log tab if this is a non fatal exception, or what is considered an "Expected Exception" from the types in Exceptions.js. These are exceptions thrown by the Notification class and entity classes like Card and Board. This static method will write any message from an "expected" exception to Info Log and rethrow the exception if it isn't one of these types. This method is used by Trellinator when executing functions anyway so you don't need to wrap all your functions using this try/catch, however it can be useful to have a shorthand way of creating a log entry for expected exceptions and then taking some other action, but halting execution if the exception was not expected

Parameters:
Name Type Description
message string

prepend the exception message
e Object

the exception that was caught
Source:
Example
var notif = new Notification(posted);

try
{
    notif.card().postComment("Hi there!");
}

catch(e)
{
    Notification.logException("We didn't see a card",e);
}

(static) this.actionOnDueDate(function_name, signature, callback)

Schedule a function to be executed by the Execution Queue at some point relative to the due date on a card, even if the due date was not added as part of the notification.

It is therefore important to use this in conjunction with another notification type because otherwise any notification for a card with a due date will schedule the function to execute.

By default, will execute on the due date, but you can optionally pass in a callback to modify the date relative to the due date of the card.

The original notification object is passed into the scheduled function, so you will need to call new Notification(params) in the scheduled function

Parameters:
Name Type Description
function_name string

the name of the function to execute
signature string

an arbitrary string but usually just the signature passed into the original function
callback function

(optional) a function into which the due date as a Date object, and a second argument with the notification params that will be passed into the function
Source:
Example
try
{
    var notif = new Notification(posted);
    notif.createdCard();
    //Action 3 days after the due date on a card only
    //if the card was just created
    notif.actionOnDueDate("doSomething",signature,function(date,params)
    {
        date.addDays(3).at("9:00");
        params.arbitrary_string = "I ain't afraid of no ghost";
    });
}

(static) this.actionOnDueDateAdded(function_name, signature, callback)

Schedule a function to be executed by the Execution Queue at some point relative to the due date added to or edited on a card.

By default, will execute on the due date, but you can optionally pass in a callback to modify the date relative to the due date of the card.

Parameters:
Name Type Description
function_name string

the name of the function to execute
signature string

an arbitrary string but usually just the signature passed into the original function
callback function

(optional) a function into which the due date as a Date object, and a second argument with the notification params that will be passed into the function, and the card to which the due date was added as a third parameter
Source:
Example
new Notification(posted).actionOnDueDateAdded("doSomething",signature,function(date,params,card)
{
    if(card.currentList().name() != "Action")
        throw new InvalidActionException("Don't action if card not in Action list");

    date.addDays(3).at("9:00");
    params.arbitrary_string = "I ain't afraid of no ghost";
});

(static) this.addedCard(optionaly)

Return a Card object if a card was added to a list as part of this notification. The "added" event can be any way that a card can arrive in a list, either by being created, copied, moved (within the same board or from a different board) or emailed to the board. If none of these things happened throws an InvalidActionException

Parameters:
Name Type Description
optionaly string | RegExp

pass in a string or RegExp to match against the name of the LIST into which the card was added
Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.addedCard(new RegExp("ToDo.*"))
.postComment("Hi there!");

(static) this.addedChecklist(name)

Return a Checklist object if a checklist was added to a card as part of this notification or throw an InvalidActionException

Parameters:
Name Type Description
name string | RegExp

optionally pass in a string or RegExp to match against the name of the checklist that was added to the card
Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.addedChecklist(new RegExp(".*Ghosts.*"))
.addItem("Who you gonna call?");

(static) this.addedChecklistItem(optionally)

Return a CheckItem object if it was added to a checklist

Parameters:
Name Type Description
optionally string | RegExp

only look for a checklist item matching a string or regex or RegExp object to match against the text of the completed item
Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.addedChecklistItem(/.*Fluffy.*Bunny/)
.card()
.postComment("Cute ^_^");

(static) this.addedComment()

Return a Comment object if a comment was added to a card as part of this Notification, or throw an InvalidActionException. BEWARE!! It's very easy to create "infinite loops" if you don't filter out comments added by Trellinator itself.

Source:
Throws:

InvalidActionException

Example
var notif = new Notification(posted);
var comment = notif.addedComment();

if(notif.member().notTrellinator())
    notif.card().postComment("Okay!");

(static) this.addedDueDate()

Return a Card object if a due date was added as part of this notification, or throw an InvalidActionException

Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.addedDueDate()
.postComment("Roger that!");

(static) this.addedLabel(optionally)

Return a Label object if a label was added to a card as part of this notification, or throw an InvalidActionException

Parameters:
Name Type Description
optionally string | RegExp

pass in a string or RegExp to match against the name of the label that was added
Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.addedLabel(new RegExp("Charles.*"))
.card()
.postComment("In Charge!");

(static) this.addedList()

Return a List object that was created or moved from another board

Source:
Throws:

InvalidActionException

Example
Card.create(new Notification(posted)
.addedList(),"Welcome to the list!");

(static) this.addedMemberToBoard(optional)

If this notification was the result of a member being added to a board, return an object of type Member, otherwise throw an InvalidActionException

Parameters:
Name Type Description
optional string | RegExp

name (string or regex) to match against username
Source:
Throws:

InvalidActionException

Example
var member = new Notification(posted).addedMemberToBoard();

(static) this.addedMemberToCard()

If this notification was the result of a member being added to a card, return an object of type Member, otherwise throw an InvalidActionException

Source:
Throws:

InvalidActionException

Example
var notif = new Notification(posted);
var comment = "@"+notif.addedMemberToCard().name()+" welcome!";
notif.card().postComment(comment);

(static) this.archivedCard()

Return a Card object if it was archived as part of this notification, or throw an InvalidActionException

Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.archivedCard()
.unArchive()
.postComment("No you don't!");

(static) this.archivedList()

Return a List object that was archived

Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.archivedList().unArchive();

(static) this.attachedBoard()

Return an Attachment object which will hold a reference to the Card object via the card() method, if an attachment was added to a card as part of this notification and that attachment was a Trello Board

Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.attachedBoard()
.card().postComment("I have a Trello Board");

(static) this.attachedCard()

Return an Attachment object which will hold a reference to the Card object via the card() method, if an attachment was added to a card as part of this notification and that attachment was a Trello card

Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.attachedCard()
.card().postComment("I have a Trello Card");

(static) this.attachedFile(optionaly)

Return an Attachment object which will hold a reference to the Card object via the card() method, if an attachment was added to a card as part of this notification and that attachment was a file optionally with a file name matching a regex or string passed in

Parameters:
Name Type Description
optionaly string | RegExp

pass in a string or RegExp to match against the name of the file (not the name of the attachment)
Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.attachedFile(new RegExp("*.pdf","i"))
.card().postComment("I have a PDF file");

Return an Attachment object which will hold a reference to the Card object via the card() method, if an attachment was added to a card as part of this notification and that attachment was a link/URL, optionally matching a regex or string passed in

Parameters:
Name Type Description
optionaly string | RegExp

pass in a string or RegExp to match against the URL of the attachment
Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.attachedLink(new RegExp("*google.com*"))
.card().postComment("I have a new Google link");

(static) this.board()

Return the Board object on which this action was performed. Since all notifications are at the board level, this will always return a valid Board object

Source:
Example
new Notification(posted)
.board().card("Updates")
.postComment("Something happened!");

(static) this.boardBefore()

Return a Board object that a card was moved from or throw InvalidActionException.

Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.boardBefore().name();

(static) this.card()

Return the Card object on which this action was performed. If this action was not performed on a card, throw an InvalidActionException

Source:
Example
new Notification(posted)
.card().postComment("You rang?");

(static) this.changedCardDescription(optionally)

Return a Card object if the description of the card was changed or throw an InvalidActionException if no card description was changed

Parameters:
Name Type Description
optionally string | RegExp

pass in a name of card to match
Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.changedCardDescription()
.postComment("how dare you!");

(static) this.changedCardName()

Return a Card object if the name/title of the card was changed or throw an InvalidActionException if no card name was changed

Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.changedCardName()
.postComment("how dare you!");

(static) this.changedCustomField(optionaly)

Return a Custom Field object that was changed, optionally pass in a string or regex to match against the name of the field

Parameters:
Name Type Description
optionaly string | RegExp

pass in a string or RegExp to match against the name of the CARD on which the field was changed
Source:
Throws:

InvalidActionException

Example
var card = new Notification(posted).changedCustomField("Priority").card();

(static) this.changedListName()

Return a List object that had it's name changed or throws an InvalidActionException if no list name was changed

Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.changedListName()
.cards().first()
.postComment("My name changed");

(static) this.completedAllChecklists()

Return a Card object if all checklists were completed as part of this notification, or throw an InvalidActionException

Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.completedAllChecklists()
.moveToNextList();

(static) this.completedChecklist(optionally)

If a checklist was completed as part of this notification return a Checklist object, otherwise throw an InvalidActionException

Parameters:
Name Type Description
optionally string | RegExp

pass in a string or RegExp object to match against the name of the completed checklist
Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.completedChecklist(new RegExp(".*Carmen San Diego.*"))
.card().postComment("Great work gumshoe!");

(static) this.completedChecklistItem(optionally)

Return a CheckItem object if it was marked as complete or throw an InvalidActionException

Parameters:
Name Type Description
optionally string | RegExp

include a string or RegExp object to match against the text of the completed item
Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.completedChecklistItem(new RegExp("URGENT.*"))
.card()
.postComment("Crisis averted");

(static) this.completedDueDate()

Return a Card object if the due date was marked complete or throw an InvalidActionException if no due date was completed

Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.completedDueDate()
.postComment("Feels gooood :)");

(static) this.convertedChecklistItemToCard(optionally)

If a checklist item was converted to a card return a Card object, otherwise throw an InvalidActionException

Parameters:
Name Type Description
optionally string | RegExp

pass in a string or RegExp object to match against the name of the converted checklist item
Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.convertedChecklistItemToCard(new RegExp(".*Carmen San Diego.*"))
.checklist().card().postComment("Great work gumshoe!");

(static) this.copiedBoard(optional)

A board was copied, returns an object of type Board

Parameters:
Name Type Description
optional string | RegExp

name (string or regex) to match against username
Source:
Throws:

InvalidActionException

Example
var board = new Notification(posted).copiedBoard();

(static) this.createdBoard(optional)

A board was created, returns an object of type Board This is true if the board was created or copied from another board

Parameters:
Name Type Description
optional string | RegExp

name (string or regex) to match against username
Source:
Throws:

InvalidActionException

Example
var board = new Notification(posted).createdBoard();

(static) this.createdCard(optionaly)

Return a Card object if a card was created on this board as part of this notification. The "created" event can be any way that a card can be added to a board for the first time, ie. created by a user, copied from another card including from a different board or emailed to the board. If none of these things happened throws an InvalidActionException

Parameters:
Name Type Description
optionaly string | RegExp

pass in a string or RegExp to match against the name of the LIST in which the card was created
Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.createdCard(new RegExp("Incoming.*"))
.postComment("Hi there!");

(static) this.createdList()

Return a List object that was created

Source:
Throws:

InvalidActionException

Example
Card.create(new Notification(posted)
.createdList(),"Welcome to the list!");

(static) this.ignoreMemberWebhooks()

Throw an invalid action exception if the notification came in on a member webhook rather than a board webhook

Source:
Example
new Notification(posted)
.ignoreMemberWebhooks()

(static) this.listAfter()

Return a List object that a card was moved into if a card was moved as part of this notification, or return an InvalidActionException

Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.listAfter().cards()
.first()
.postComment("Welcome friend!");

(static) this.listBefore()

Return a List object that a card was moved out of if a card was moved as part of this notification, or return an InvalidActionException

Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.listBefore().cards()
.first()
.postComment("We'll miss you!");

(static) this.member()

Return the Member object who initiated this notification. Since all notifications are at the board level, this will always return a valid Member object

Source:
Example
var notif = new Notification(posted);
var comment = notif.member().name()+" dug a hole");
notif.card()
.postComment(comment);

(static) this.mentionedMember(optionally)

Return a Member object if the member's username was mentioned in a comment or throw an InvalidActionException if no due date was completed. This will apply only to members who were mentioned who are part of this board, rather than arbitrary strings preceded by an @ sign

Parameters:
Name Type Description
optionally string | RegExp

pass in a string or RegExp to match against the mentioned member's username
Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.mentionedMember("johnnydepp")
.postComment("Yarrrrr");

(static) this.mentionedMembers()

Return an IterableCollection of Member objects that were mentioned in a comment, or throw an InvalidActionException if no members were mentioned. This applies only to members who are actually on the board, so won't consider any string preceded by an @ sign as a member name

Source:
Throws:

InvalidActionException

Example
var notif = new Notification(posted);
notif.mentionedMembers()
.each(function(member)
{
    notif.card().addMember(member);
});

(static) this.movedCard(optionaly)

Return a Card object if a card was moved from one list to another (either on the same board or to a different board) as part of this notification, otherwise throw an InvalidActionException

Parameters:
Name Type Description
optionaly string | RegExp

pass in a string or RegExp to match against the name of the LIST into which the card was moved
Source:
Throws:

InvalidActionException

Example
var notif = new Notification(posted);
var card = notif.movedCard(new RegExp("Done.*"));
var from = notif.listBefore().name();
var to = notif.listAfter().name();
card.postComment(from+" to "+to);

(static) this.oldCardDescription(optionally)

Return previous desc if it was changed as part of this notification

Parameters:
Name Type Description
optionally string | RegExp

pass in a name of card to match
Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.oldCardDescription();

(static) this.oldValue()

Return the previous value after a change

Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.changedCardName().setName(new Notification(posted).oldValue());

(static) this.removedLabel(optionally)

Return a Label object if a label was removed from a card as part of this notification, or throw an InvalidActionException

Parameters:
Name Type Description
optionally string | RegExp

pass in a string or RegExp to match against the name of the label that was removed
Source:
Throws:

InvalidActionException

Example
new Notification(posted)
.removedLabel(new RegExp("Charles.*"))
.card()
.postComment("In Charge!");

(static) this.removedMemberFromBoard(optional)

If this notification was the result of a member being removed from a board, return an object of type Member, otherwise throw an InvalidActionException

Parameters:
Name Type Description
optional string | RegExp

name (string or regex) to match against username
Source:
Throws:

InvalidActionException

Example
var member = new Notification(posted).removedMemberFromBoard();

(static) this.removedMemberFromCard()

If this notification was the result of a member being removed from a card, return an object of type Member, otherwise throw an InvalidActionException

Source:
Throws:

InvalidActionException

Example
var notif = new Notification(posted);
var comment = "@"+notif.removedMemberFromCard().name()+" welcome!";
notif.card().postComment(comment);

(static) this.replyToMember(message)

Post a comment on the card associated with this notification mentioning the member who initiated the notification

Parameters:
Name Type Description
message string

the message to post, without a username (this will be added automatically)
Source:
Example
new Notification(posted)
.replyToMember("Aaaaaaas yoooooou wiiiiiiiish!");

(static) this.whatChanged()

Return the name of the attribute that changed

Source:
Throws:

InvalidActionException

Example
var notif = new Notification(posted);
notif
.changedCardName().setName(notif.oldValue());
notif.replyToMember("You changed: "+notif.whatChanged());