Updated Custom Fields

Continuing the discussion from Updated Custom Fields!:

@Joe_Trollo @Jeff_Schneider @Matt_Bramlage
Does this Asana change have any ramifications for the API?

For example, when we programmatically create a custom field, will we be able to specify whether it should be a workspace-wide or project-specific custom field?


Hey @Phil_Seeman,

Yes, you will be in charge of it being global or not.

We’re still working on getting some docs up for it, but the param is named is_global_to_workspace. It’s opt_in for GET and can Not be used in POST.

Let me know if you have any issues with it!


Cool, thanks @Ross_Grambo.

I’m needing to determine if my current code will be OK or now needs modification. Obviously I can test it but wondering if you can comment:

Will the /workspaces/{id}/custom_fields endpoint return only the workspace-global fields, or it will include all project-specific non-global fields as well?

Hey @Phil_Seeman,

The /workspaces/{id}/custom_fields endpoint will not return project specific ones.

I was wrong earlier. The is_global_to_workspace is read only. It looks like you create project specific ones with /projects/:id/addCustomFieldSetting.

I don’t get how that would work. That endpoint requires that one supply the ID of an existing custom field. There’s no (documented) ability to supply new custom field info (name, type) in that endpoint.

This update to how custom fields work is a BREAKING CHANGE for external developers, so I am hoping you can rush out some documentation ASAP on all of the API-related changes. :pray:

More critically for me right now than how to create a project-specific custom field, is how do I query for project-specific custom fields for a given project??

1 Like

@Ross_Grambo I thought it might help to elaborate on why it’s a Breaking Change. Here’s the one use case I know of from Flowsana.

At one point in my code, I need to add a custom field to a project if it’s not already there.

I query for all custom fields in the current workspace. If a field with the correct name and type already exists, I use it. If it does not exist, I add a new field of that name and type.

But now with this model change, what if a project-specific field of that name and type exists in my target project (or for that matter, in any project in the workspace)? I’m assuming my “add” operation will fail, a state which I’m not currently expecting because it wasn’t possible before. (But will it fail?)

And let’s say the “add” operation doesn’t fail, and my new field is created. Then my next step is to add the new field to the target project’s custom field settings. But again, what if a field of that name and type already exists in that project? Then I’m assuming my “add to settings” operation will fail - again a state which I’m not currently expecting. (But will it fail? And if not, does that mean there are two fields of the same name and type in the project?)

Hopefully the above gives you a good example of my questions and my confusion as to how things work now.

cc: @Joe_Trollo


Hey @Phil_Seeman,

I opened up the api team’s design docs. It looks I left out an important snippet.

Calls to POST /projects/:id/addCustomFieldSetting may now specify a JSON blob in the custom_field parameter instead of an ID. This will create a custom field local to that container.

{ "data": {
	"custom_field": {
		"name": "hello",
		"resource_subtype": "text"

In your example, when a project already has a local field named “foo” and we’re adding a global one named “foo”. The add operation would not fail. You would add an additional custom field added to the project with the same name and type. One would be global and one would be local.

I wouldn’t call this a breaking change, because all functionality with global fields will continue to work in the same way. In order for an app to have their custom fields integrate nicely with local custom fields (like avoid duplicates), then they have to add additional functionality.

Ah, OK, cool!

I still have this question, though:
How do I query for project-specific custom fields for a given project??

Whoa, really? OK. I guess you’re right then that technically it’s not a breaking change because existing code won’t fail where it worked before; but I’m really surprised this is the new behavior (I know that’s not API-related but rather is a more core product-design decision). I would bet money that this behavior of allowing two identical fields, one local and one global, in the same project will cause user confusion and Asana support-team nightmares down the line. But that’s just me. :slight_smile:



I completely agree with you. I had the same concern, but after talking to a few people here, there’s good reasoning why this is the case. Hopefully the UI will offer a nice way to distinguish global vs local.

You’ll have to opt_fields the custom_field_settings on the project.

1 Like

Thanks for the query solution, Ross!

We’ll see how good you all consider it after you see the tech support metrics on it haha!


Eagerly waiting for the official doc and rollout date as I will be heavily impacted with https://minimalist-work.com/asana/custom-fields

It’s already rolled out!

The API is already rolled out then? Damn my tool must be broken then!

It’s not really “broken” per se, it’s just not reporting on project-specific custom fields. To get those, you have to query each project as Ross described here:

Yes, it is broken in the sense that it does not list all custom fields anymore :stuck_out_tongue:

I have an easy way to make it not broken - just rename it to “Global Custom Field Explorer”. All fixed! :laughing: