README

This package provides an easy way to interface directly with the ClickUp API. It includes several common functions, such as adding tasks, and an extended interface for dealing with attachments that fail to attach correctly.

Architecture

If you intend to use this package with a new application, please be sure that you follow these architectural requirements:

Any model that will send a task to Clickup must have the following fields, with these specific names:
- title
- description
- due_date
- priority
- clickup_task_id
If you intend to use attachments:
- the attachments field on the model must be:
  - attached_files
- the model must use the following trait:
  - ClickupAttachable

Installation

composer require oafasys/clickup

After installation, publish assets:

php artisan vendor:publish

You will need to choose the ClickupServiceProvider from the list. This will create a new config file, clickup.php, as well as a new migration, create_clickup_orphaned_files_table.php.

Config

Your .env should include:

CLICKUP_ACTIVE=true|false
CLICKUP_ENVIRONMENT=staging|prod
CLICKUP_TOKEN=

Please note that currently CLICKUP_ACTIVE and CLICKUP_ENVIRONMENT are not yet implemented; as such, these values have no real effect.

Assets

Artisan commands

Installing this package provides a new Artisan command, clickup:attach-orphaned-files, which should be set to run at repeating intervals of your choice. This command will attempt to re-attach orphaned temporary files that failed their original attachment process.

Filesystems

Installing this package creates two new disks, clickup_temp_files and clickup_orphaned_files.

Logging

Installing this package creates a new channel, clickup_api.

Usage

Extending the Clickup model

The Clickup model included within this package is not intended to function on its own. Rather, you should extend this package's Clickup model with a Clickup model of your own, with relevant files. For instance, if you are submitting a task, you can use this Clickup model's createNewTask method in your application's Clickup model's method submitProjectRequest.

Attachments

Faulty attachments are handled entirely by the package -- all you need to do is make sure your application attaches any files to the task, via the attachFilesToTask method, and runs the provided Artisan command on a scheduled basis to handle orphans. Everything else -- managing the database, managing the files, etc. -- is handled by this package.

Available methods

There are more methods than listed below, but the ones I've left out are generally to be used only by the Clickup package itself rather than by users of the package. For instance, many of these "missing" methods deal with orphaned attachments.

unpackClickupResponse($response)

This method takes a Guzzle response and unpacks it so that we can access relevant properties.

You should only use this method if you are crafting a completely new API request, as it is already baked into some of the methods this package provides, such as createNewTask.

getCustomFields($list_id)

This method returns the complete object representatives of the custom fields accessible to the $list_id.

This is particularly useful when you are creating a $customFieldsCrosswalk for the createNewTask method.

getCustomFieldOptions($list_id)

This method returns an associative array with the options for each accessible custom field on the given list.

Note that only custom fields with enumerated options are returned -- custom fields of the text type, for instance, will not appear in the resulting array.

getLists($folder_id, $for = null)

If you provide no $for, this method will return the full objects of the lists available to the $folder_id.

You may also pass 'dropdown', which will return an array whose keys are the list IDs and whose values are the list names.

createNewTask($list_id, $universalFields, $customFieldsCrosswalk)

$universalFields can be either an array or an object, but it must contain a property/key of title.

Additional properties/keys are optional:

description: string
due_date: any string that converts easily to a Carbon instance (e.g., 2021-01-01)
priority: integer (1-4), with 1 being urgent and 4 being low

$customFieldsCrosswalk is an array whose keys represent the name of the custom field in Clickup and whose values are the value to assign to the field.

For instance:

$requester = Auth::user();

$crosswalk = [
    'Requestor Name'  => $requester->name,
    'Requestor Email' => $requester->email 
];

Regardless of whether the creation was a success, this method returns an array with several useful keys:

return [
    'was_successful' => true|false,
    'id' => task ID on successful creation; null on failure,
    'response' => unadulterated Clickup response via Guzzle
    'result' => unpacked Clickup response
];

attachFilesToTask($files, $task_id)

Please do not confuse this method with attachFileToTask, which is an internal method that should not be used on its own.

$files should be an array of attached files, where each item in the array is a string in the format |.