How to create Actions on a Board using the REST API

Modified on Tue, 20 Feb 2024 at 08:07 PM

This guild will walk through the steps required to create an Action or Actions on a specific Board in Fluid.

TABLE OF CONTENTS

Requirements
- Authentication - PAT token
- Board identifier - GUID
Creating a single Action on a Board
Creating multiple Actions on a Board
Definitions
Attachments[]
CustomProperties[]
Assignee[]
Author
ModifiedBy
Owners[]
Methods[]

In the context of this article, an Action can also be referred to as a Card or Task and this terminology can be used interchangeably.

Requirements

Authentication - PAT token

You will need a valid username and PAT token as part of the REST API request. You can find more information on how to generate a PAT token here Creating a Personal Access Token.

Board identifier - GUID

The board GUID is the key that uniquely identifies a board.

You can use the Board REST API here List Boards to find the board GUID or alternatively the GUID for a board can be found in the browser URL. Navigate to the board you want to create the action for, the URL should read as http://organisation.fluid.work/Process/Board/7505a102-93fc-4465-a23b-2eb6303f7f71 the value 7505a102-93fc-4465-a23b-2eb6303f7f71 is the board GUID you should pass as part of the create Action payload.

The board GUID is referred to as a Principal GUID in Fluid terminology. A principal is considered a tier 1 object within the Fluid framework and represents the container this Action belongs to. Examples of principals include Users, Meetings, Projects etc. In this article the Action is created with its principal GUID defined as the board GUID.

Creating a single Action on a Board

HTTP

POST https://organisation.fluid.work/rest/api/action

cURL

curl --user username:pattoken --location 'http://organisation.fluid.work/rest/api/action' \
--header 'Content-Type: application/json' \
--data '	{
    "fields": {
        "principalGuid": "7505a102-93fc-4465-a23b-2eb6303f7f71",
        "title": "Sample Title",
        "description": "Sample Description",
        "status": "Not Started",
        "taskType": "Task"
    }
}'

with optional parameters

HTTP

POST https://organisation.fluid.work/rest/api/action?fields={fields}&$expand={$expand}&version=3.0

cURL

curl --user username:pattoken --location 'http://organisation.fluid.work/rest/api/action?fields=all&expand=all' \
--header 'Content-Type: application/json' \
--data '	{
    "fields": {
        "principalGuid": "7505a102-93fc-4465-a23b-2eb6303f7f71",
        "title": "Sample Title",
        "description": "Sample Description",
        "status": "Not Started",
        "taskType": "Task"
    }
}'

Response

Status code: 200

JSON

{
    "fields": {
        "assignee": [
            {
                "id": 603,
                "guid": "f1cb6467-0262-4539-9148-7b869defd817",
                "name": "David Burt",
                "userName": "david.burt",
                "email": "dump18@fluidbsg.com"
            }
        ],
        "attachmentCount": 0,
        "author": {
            "id": 603,
            "guid": "f1cb6467-0262-4539-9148-7b869defd817",
            "name": "David Burt",
            "userName": "david.burt",
            "email": "dump18@fluidbsg.com"
        },
        "boardCategory": 0,
        "boardId": 0,
        "boardGuid": "7505a102-93fc-4465-a23b-2eb6303f7f71",
        "boardTitle": "Bulk edit",
        "businessValue": 0,
        "chatCount": 0,
        "contentType": "Process",
        "createDate": "2024-02-16T19:20:41.0000000",
        "description": "Sample Description - Create Action on a Board",
        "descriptionHtml": "Sample Description - Create Action on a Board",
        "dueDate": null,
        "endDate": null,
        "isClosed": false,
        "isCalculated": false,
        "isOwner": true,
        "modifiedBy": {
            "id": 603,
            "guid": "f1cb6467-0262-4539-9148-7b869defd817",
            "name": "David Burt",
            "userName": "david.burt",
            "email": "dump18@fluidbsg.com"
        },
        "modifiedDate": "2024-02-16T19:20:41.0000000",
        "principalGuid": "7505a102-93fc-4465-a23b-2eb6303f7f71",
        "shortCode": "BE-105",
        "startDate": null,
        "status": "Not Started",
        "statusCode": 1,
        "taskType": "Task",
        "title": "Sample Title - Create Action on a Board",
        "titleRichText": "Sample Title - Create Action on a Board",
        "titleHtml": "Sample Title - Create Action on a Board"
    },
    "id": 4433,
    "methods": [
        {
            "type": "PermaLink",
            "httpMethod": "GET",
            "url": "https://organisation.fluid.work/Action/EditFull/12c2e661-270c-43e1-8d05-1218b5842b6c"
        },
        {
            "type": "Update",
            "httpMethod": "PUT",
            "url": "https://organisation.fluid.work/rest/api/action/4433",
            "description": "Update Action",
            "payload": {
                "fields": {
                    "description": "<Description>",
                    "title": "<Title>"
                },
                "customProperties": []
            }
        },
        {
            "type": "Delete",
            "httpMethod": "DELETE",
            "url": "https://organisation.fluid.work/rest/api/action/4433"
        }
    ],
    "guid": "12c2e661-270c-43e1-8d05-1218b5842b6c",
    "url": "https://organisation.fluid.work/rest/api/action/4433"
}

Creating multiple Actions on a Board

HTTP

POST https://organisation.fluid.work/rest/api/action/bulk

cURL

curl --user username:patToken --location 'http://organisation.fluid.work/rest/api/action/bulk' \
--header 'Content-Type: application/json' \
--data '[
    {
        "Fields": {
            "principalGuid": "7505a102-93fc-4465-a23b-2eb6303f7f71",
            "title": "BULK Create 1",
            "description": "Bulk Create 1 - Description",
            "status": "Not Started",
            "taskType": "Task"
        }
    },
    {
        "fields": {
            "principalGuid": "7505a102-93fc-4465-a23b-2eb6303f7f71",
            "title": "BULK Create 2",
            "description": "Bulk Create 2  - Description",
            "status": "Not Started",
            "taskType": "Task"
        }
    }
]'

with optional parameters

HTTP

POST https://organisation.fluid.work/rest/api/action/bulk?fields={fields}&$expand={$expand}&version=3.0

cURL

curl --user username:pat_token --location 'http://organisation.fluid.work/rest/api/action/bulk?fields=all&expand=all' \
--header 'Content-Type: application/json' \
--data '[
    {
        "Fields": {
            "principalGuid": "7505a102-93fc-4465-a23b-2eb6303f7f71",
            "title": "BULK Create 1",
            "description": "Bulk Create 1 - Description",
            "status": "Not Started",
            "taskType": "Task"
        }
    },
    {
        "fields": {
            "principalGuid": "7505a102-93fc-4465-a23b-2eb6303f7f71",
            "title": "BULK Create 2",
            "description": "Bulk Create 2  - Description",
            "status": "Not Started",
            "taskType": "Task"
        }
    }
]'

Response

Status code: 200

JSON

{
    "fields": {
        "assignee": [
            {
                "id": 603,
                "guid": "f1cb6467-0262-4539-9148-7b869defd817",
                "name": "David Burt",
                "userName": "david.burt",
                "email": "dump18@fluidbsg.com"
            }
        ],
        "attachmentCount": 0,
        "author": {
            "id": 603,
            "guid": "f1cb6467-0262-4539-9148-7b869defd817",
            "name": "David Burt",
            "userName": "david.burt",
            "email": "dump18@fluidbsg.com"
        },
        "boardCategory": 0,
        "boardId": 0,
        "businessValue": 0,
        "chatCount": 0,
        "contentType": "Task",
        "createDate": "2024-02-16T18:22:18.0000000",
        "description": "Bulk Create 1 - Descrption",
        "descriptionHtml": "Bulk Create 1 - Descrption",
        "dueDate": null,
        "endDate": null,
        "impediment": 0,
        "isClosed": false,
        "isCalculated": false,
        "isOwner": true,
        "modifiedBy": {
            "id": 603,
            "guid": "f1cb6467-0262-4539-9148-7b869defd817",
            "name": "David Burt",
            "userName": "david.burt",
            "email": "dump18@fluidbsg.com"
        },
        "modifiedDate": "2024-02-16T18:22:18.0000000",
        "owners": [
            {
                "id": 603,
                "guid": "f1cb6467-0262-4539-9148-7b869defd817",
                "name": "David Burt",
                "userName": "david.burt",
                "email": "dump18@fluidbsg.com"
            }
        ],
        "priority": "Medium",
        "principalGuid": "f1cb6467-0262-4539-9148-7b869defd817",
        "ragStatus": "Green",
        "shortCode": "DB-117",
        "startDate": null,
        "status": "Not Started",
        "statusCode": 4,
        "taskType": "Task",
        "title": "BULK Create 1",
        "titleRichText": "BULK Create 1",
        "titleHtml": "BULK Create 1"
    },
    "id": 4415,
    "methods": [
        {
            "type": "PermaLink",
            "httpMethod": "GET",
            "url": "https://organisation.fluid.work/Action/EditFull/90d486aa-11e9-461d-85a0-f72df83a5e5f"
        },
        {
            "type": "Update",
            "httpMethod": "PUT",
            "url": "https://organisation.fluid.work/rest/api/action/4415",
            "description": "Update Action",
            "payload": {
                "fields": {
                    "description": "<Description>",
                    "title": "<Title>"
                },
                "customProperties": []
            }
        },
        {
            "type": "Delete",
            "httpMethod": "DELETE",
            "url": "https://organisation.fluid.work/rest/api/action/4415"
        }
    ],
    "guid": "90d486aa-11e9-461d-85a0-f72df83a5e5f",
    "url": "https://organisation.fluid.work/rest/api/action/4415"
},
{
    "fields": {
        "assignee": [
            {
                "id": 603,
                "guid": "f1cb6467-0262-4539-9148-7b869defd817",
                "name": "David Burt",
                "userName": "david.burt",
                "email": "dump18@fluidbsg.com"
            }
        ],
        "attachmentCount": 0,
        "author": {
            "id": 603,
            "guid": "f1cb6467-0262-4539-9148-7b869defd817",
            "name": "David Burt",
            "userName": "david.burt",
            "email": "dump18@fluidbsg.com"
        },
        "boardCategory": 0,
        "boardId": 0,
        "businessValue": 0,
        "chatCount": 0,
        "contentType": "Task",
        "createDate": "2024-02-16T18:22:18.0000000",
        "description": "Bulk Create 2 - Descrption",
        "descriptionHtml": "Bulk Create 2  - Descrption",
        "dueDate": null,
        "endDate": null,
        "impediment": 0,
        "isClosed": false,
        "isCalculated": false,
        "isOwner": true,
        "modifiedBy": {
            "id": 603,
            "guid": "f1cb6467-0262-4539-9148-7b869defd817",
            "name": "David Burt",
            "userName": "david.burt",
            "email": "dump18@fluidbsg.com"
        },
        "modifiedDate": "2024-02-16T18:22:18.0000000",
        "owners": [
            {
                "id": 603,
                "guid": "f1cb6467-0262-4539-9148-7b869defd817",
                "name": "David Burt",
                "userName": "david.burt",
                "email": "dump18@fluidbsg.com"
            }
        ],
        "priority": "Medium",
        "principalGuid": "f1cb6467-0262-4539-9148-7b869defd817",
        "ragStatus": "Green",
        "shortCode": "DB-118",
        "startDate": null,
        "status": "Not Started",
        "statusCode": 4,
        "taskType": "Task",
        "title": "BULK Create 2",
        "titleRichText": "BULK Create 2",
        "titleHtml": "BULK Create 2"
    },
    "id": 4416,
    "methods": [
        {
            "type": "PermaLink",
            "httpMethod": "GET",
            "url": "https://organisation.fluid.work/Action/EditFull/778f7f08-fe2b-4b4f-9e52-49ea2c9319e8"
        },
        {
            "type": "Update",
            "httpMethod": "PUT",
            "url": "https://organisation.fluid.work/rest/api/action/4416",
            "description": "Update Action",
            "payload": {
                "fields": {
                    "description": "<Description>",
                    "title": "<Title>"
                },
                "customProperties": []
            }
        },
        {
            "type": "Delete",
            "httpMethod": "DELETE",
            "url": "https://organisation.fluid.work/rest/api/action/4416"
        }
    ],
    "guid": "778f7f08-fe2b-4b4f-9e52-49ea2c9319e8",
    "url": "https://organisation.fluid.work/rest/api/action/4416"
}

Definitions

Name	Description
id	The Id integer, uniquely identifies this particular Action, can be interchangeable with guid, see below
guid	The guid string, uniquely identifies this particular Action, can be interchangeable with id, see above
url	The REST GET Url for this Action
fields	Map of field and values for the Action
assignee[]	Describes a list of users this action has been assigned to
author	Describes the user who authored this Action
modifiedBy	Describes the user who last modified this Action
owners[]	Describes a list of users this action is owned by
customProperties[]	Describes a list of customProperties for this Action if configured.
methods[]	Describes relevant actions that can be made against this Action, including REST url and payload information

Attachments[]

Name	Description
id	The Id integer, uniquely identifies this particular User, can be interchangeable with guid, see below
guid	The guid string, uniquely identifies this particular User, can be interchangeable with id, see above
type	The type of attachment, Report etc
status	Status of the attachment
fileName	The filename of the attachment
title	Title of the attachment
modifiedDate	The last date the attachment was modified
modifiedBy	The User that made the last modification to the attachment
link	The URL link to download the attachment

CustomProperties[]

Name	Description
guid	The guid string, uniquely identifies this particular custom property
dataType	The data type of the value for this Custom Property. eg string, datetime etc
isAdminLocked
isCatalogType	Custom Property is a Catalog Type and is used as part of taxonomy
isMultiple	Can contain multiple values
isSubType
key	Unique name key that identifies this Custom Property by name
required	Flag to indicate this Custom Property requires a valid value
reportable	Flag to indicate this Custom Property is reportable
readOnly	Flag to indicate value is read only and cannot be changed
value	The value of this Custom Property

Assignee[]

Name	Description
id	The Id integer, uniquely identifies this particular User, can be interchangeable with guid, see below
guid	The guid string, uniquely identifies this particular User, can be interchangeable with id, see above
name	The long name of this User
username	The username associated with this User
email	Unique email associated with this User

Author

Name	Description
id	The Id integer, uniquely identifies this particular User, can be interchangeable with guid, see below
guid	The guid string, uniquely identifies this particular User, can be interchangeable with id, see above
name	The long name of this User
username	The username associated with this User
email	Unique email associated with this User

ModifiedBy

Name	Description
id	The Id integer, uniquely identifies this particular User, can be interchangeable with guid, see below
guid	The guid string, uniquely identifies this particular User, can be interchangeable with id, see above
name	The long name of this User
username	The username associated with this User
email	Unique email associated with this User

Owners[]

Name	Description
id	The Id integer, uniquely identifies this particular User, can be interchangeable with guid, see below
guid	The guid string, uniquely identifies this particular User, can be interchangeable with id, see above
name	The long name of this User
username	The username associated with this User
email	Unique email associated with this User

Methods[]

Name	Description
type	The type of action this method performs
httpMethod	HTTP Request Method verb
url	The REST URL that can be used with the Http Method verb
description	Description of what this method performs
payload	Sample payload related to the HTTP Method verb. This payload is typically the minimal payload required to perform the verb method.