sheepFlow¶

A kanban board for sheepCRM.

Flow Terminology¶

board: a view with a number of columns, each column having a number of cards. boards can only represent a single sheepCRM data type
columns: a board column typically represent a state of a resource e.g. pending, active
card: each record is represented as a card assigned to a column
base filter: the filter or query which applies to the whole board and can not be modified by the user
default filter: a filter layered on top of the base filter but which can be edited or removed by the user. showing only recently edited records would be a good default filter

Get available boards¶

$ http GET https://api.sheepcrm.com/api/v1/$FLOCK/flow_board/ "Authorization: Bearer $API_KEY"

Get a board with full config¶

$ http GET https://api.sheepcrm.com/api/v1/$FLOCK/flow_board/full/ "Authorization: Bearer $API_KEY"

Get a board with column config¶

$ http GET https://api.sheepcrm.com/api/v1/$FLOCK/flow_board/column/ "Authorization: Bearer $API_KEY"

Get a board with full config and cards¶

$ http GET https://api.sheepcrm.com/api/v1/$FLOCK/flow_board/cards/ "Authorization: Bearer $API_KEY"

Updating cards (bulk actions)¶

column: column name
cards: a list of card IDs to update
action: the bulk action to be applied move_cards: - default action if not supplied add_tag / remove_tag: only applicable to forms additional parameter of tag required assign_reviewer / assign_scorer: only applicable to forms additional parameter of user required bulk_xls: export cards as XLS

Not all actions are available for all data types and may require premium packages.

$ http POST https://api.sheepcrm.com/api/v1/$FLOCK/flow_board/cards/ "Authorization: Bearer $API_KEY" column='active' cards:='["card1", "../member/", "/example/member/5f85c9a880859e454b8124e9/"]'


{
    "data": {
        "errors": [
            "card1 is not a valid card for this board, expected member",
            "URI ../member/ error (URI (../member/) is too short)"
        ],
        "failed": [
            "card1",
            "../member/"
        ],
        "updated": [
            "/example/member/5f85c9a880859e454b8124e9/"
        ]
    }
}

Configuring a board¶

name: board name
creator: creator string
description: helpful description of the boards purpose
active: boolean - use to hide old boards
resource_type: sheepCRM resource type e.g. form_response, member
user_groups: user group permissions for this board, leave blank for default sheepCRM permissions
columns: structured dictionary config
base filter: the filter or query which applies to the whole board and can not be modified by the user
default filter: a filter layered on top of the base filter but which can be edited or removed by the user. showing only recently edited records would be a good default filter

$ http PUT https://api.sheepcrm.com/api/v1/$FLOCK/flow_board/5ffdb4db80859eff9185cb71/ "Authorization: Bearer $API_KEY" base_filter:='{"membership_plan_type": "individual"}' default_filter:='{"amount__gte":80}'

{
    "errors": {},
    "updates": {
        "base_filter": {
            "membership_plan_type": "individual"
        },
        "default_filter": {
            "amount__gte": 80
        }
    }
}

This example configures the board to only show individual membership types and by default only show memberships with an amount great than or equal (gte) 80. Note, these filter fields are dictionary types.

Flow configs are detailed JSON documents and best edited through the user interface. Creating a JSON file (or editing an existing example) and sending through the API is supported e.g.

Example Column Configs:¶

Three column Form Response

Two column Membership Approval

$ cat flow-three-column-form-response.json | http PUT https://api.sheepcrm.com:/api/v1/$FLOCK/flow_board/5ffdb4db80859eff9185cb71/ "Authorization: Bearer $API_KEY"

Setup through the user interface¶

Temporary instructions until new UI control built.

Create a new Flow Board¶

View existing boards in Theme3 e.g. https://sheepcrm.com/example/flow_board/
Create or Clone:
- Create a new, empty board
  
  go to https://sheepcrm.com/example/flow_board/new/
- Clone an existing board
  
  Go to the board you want to clone e.g. https://sheepcrm.com/example/flow_board/603799e1683e801e9d85db2d/
  
  create the clone URL e.g. https://sheepcrm.com/api/v1/example/flow_board/603799e1683e801e9d85db2d/clone/ (note the api/v1/ )
Edit the board
- Legacy UID can be left blank
- Name - the name for the board
- Creator - free text - put your name/email
- Description - free text
- Active - Y
- Resource Type - only form responses and memberships are currently supported
- User Groups - leave blank
- Users - leave blank
- Columns - leave blank not currently used
- Base Filter - leave blank
- Default Filter - leave blank
Go to https://flow.sheepcrm.com
- Look for your new board (caching can mean a 10 minute wait)