Skip to content

Managing Projects

Searching for projects is done with Filter at the bottom of the list, beside the row count. Press / or Ctrl/Cmd+F to jump to it. The filter searches project names and labels for matches and shows the results in the hierarchy.

To create a new project:

  1. Open Analyze
  2. Select “Projects” from the top menu bar
  3. Click the “New Project” button
  4. Complete the form information including the “Access Control” section
  5. Click “Create”

The project is now ready for updating access permissions, adding owners, and creating workflows.

On the project home, next to Connection Environment, pick a Default Document Account for the project — or None to clear it.

Inside the project, every file selector lists Project Default first, standing in for whichever account the project currently has set. It drops off the list once you leave the project, once the project has no default set, once that account has been deleted, or once you lack access to it.

A new file step preselects Project Default when the project has one. Existing steps are never rewritten — each keeps the account it was saved with until you change it yourself, since a document account is a per-step choice, while a step normally follows the project’s connection environment.

A step left on Project Default resolves to whichever account is the project’s default when it runs, so changing the default mid-run affects only the nodes that have not started yet — the same as changing the connection environment. If a step runs on Project Default and the project has no default set, the run fails and names the project, rather than falling back to another account.

Steps follow the project’s connection environment, so switching the project between QA and Production moves them all. A step whose form has an Environment setting offers two choices there:

  • Project environment follows the project’s connection environment. Keep this unless you have a reason not to.
  • Fixed environment ignores the project’s connection environment and always uses the environment you pick. Use it only for a step that must stay on one environment whatever the project is switched to, such as reading reference data from Production in a project set to QA. The warning icon is a reminder that the step won’t follow a switch.

A step with a fixed environment adds a warning to its log whenever it runs on an environment other than the project’s. If its fixed environment no longer exists, for example in a step copied from another workspace, the step fails and says so rather than running somewhere else.

ERP posting steps always use the project’s environment, so Fixed environment isn’t available on them.

The default environment can’t be deleted, and no other environment can be deleted while a project uses it, a step has it as a fixed environment, or an agent serves it. The message says what still uses it, naming what you have access to and counting the rest.

Every object in a project — a step, a UDF, a workflow, a dimension, a saved layout, a document or data editor, and the project’s own settings — is covered by version-history backups. A backup isn’t taken on every individual save; instead, once an object has gone 30 seconds without a further save, one backup is taken of its settled state. A burst of edits — several saves in quick succession — produces a single version containing the final result, not one version per save. Saving is never slowed down waiting for a backup: the countdown, and the backup itself, both run in the background. If you need a version right now, use Back up now to capture the current state immediately and wait for it to finish — available in the UI, the API, and as the *_versions MCP action backup. Version history is available on every plan, including Free.

Past versions support point-in-time recovery: restore an object to an earlier version. Restoring is refused inside a locked project, the same as any other change there.

A version restores in place. Restoring a version of a project, dimension, user-defined function, step, workflow or data editor replaces that same item, and naming a different item as the target is refused — for example, “A project version is restored in place. Leave the target out, or set it to this project.” Restoring is a change to the item, so it needs the same role as editing it; on a project that restricts rows, restoring the project or a dimension a restricted column reads takes a project Architect. To bring old table data back as a separate table, restore a table snapshot to a new table.

In addition to this automatic tracking, projects and their elements also allow for versioning. Not only is creating a version easy, you can also merge changes from one version to another. This provides a simple way to keep track of snapshots or to create a version for development and then be able to merge those changes into the non-development version when you want. See Collaborate: Versions, Compare, and Share for versioning, comparison, and merge in practice.

Table data has its own history — snapshots taken by the Lakehouse on every write — covered in Table Snapshots.

Restoring and Holding Through the AI Assistant or MCP

Section titled “Restoring and Holding Through the AI Assistant or MCP”

Through the AI assistant or MCP, dimension_versions restores, holds, and releases a dimension version by its version_id, and restore_project rolls every dimension in the project back to its last backup, and every *_versions listing (steps, UDFs, workflows, dimensions, projects) shows each version’s version_id and whether it is held. A restore through any *_versions tool, or the REST API, restores the item in place: leave the target out, or set it to the item itself. project_upsert can unlock a locked project, and honors if_match so it fails rather than overwrite a change made since you last read the project.

Project security has been simplified into three types of access:

  • All Workspace Members
  • Specific Members Only
  • Specific Security Groups Only

Setting the project security is easy to do:

  1. Open Analyze
  2. Select “Projects”
  3. Click the edit icon of the project you want to restrict
  4. Choose desired restriction under “Access Control”
  5. Click “Update”

Only a project Architect or a tenant admin can change who has access to a project — its access type, the members and security groups on it, and its data shares. Anyone else sees those panels read-only, with the note “Only project Architects can change access.”

“All Workspace Members” access is the most simple option since it provides access to all members of the workspace and does not require any additional assignment of members.

“The Specific Members Only” access setting requires assignment of each member to the project.To assign members to a project:

  1. Open Analyze
  2. Select “Projects” from the top menu bar
  3. Click the members icon
  4. Grant access to members by selecting the check box next to their name in the “Access” column
  5. Click “Update”

For clouds with large numbers of members, this approach can often require more effort than desired, which is where security groups become useful.

The “Specific Security Groups Only” option enables assigning specific security groups permission to access the account. With access restrictions relying on association with a security group or groups, the administration of account access for larger groups is much simpler. This is particularly useful when combined with single sign-on automatic group association. By using single sign-on to set member group assignments, these groups can also enable and disable access to projects implicitly.

To edit assigned groups:

  1. Open Analyze
  2. Select “Projects” from the top menu bar
  3. Click the security groups icon
  4. Grant access to security groups by selecting the check box next to their name in the “Access” column
  5. Click “Update”

A data share lets one project reach another project’s tables — for example, so the Import Project Table and Export Project Table steps can move data between them. A share is granted by the project whose data is shared, to one other project:

  1. Open the project whose data you want to share, and go to its Project home.
  2. Open Access & sharing. Under Data shares, click New Data Share.
  3. Under Select Project, choose the project that may use this project’s data.
  4. Under Allowed Operations, tick Read, Write, or both, and click Add Data Share.

Delete Data Share removes a share, after you confirm. Only a project Architect or a tenant admin can add or delete a project’s data shares.

A share is granted to a project, so it speaks only for that project’s members and its workflows:

  • Reading through a share needs a role in the project it was granted to. Someone with no role there gets nothing from the share.
  • Writing through a share — creating a table, a folder or a dimension in the sharing project — needs a Write share and the Manager or Architect role in your own project, the role that could make the same change there. Anyone else is told “Writing to this project through a data share needs a write share from it to your project, and the Manager or Architect role in your project.”

Workflows run as their project’s own identity, so Import Project Table and Export Project Table steps work through a share whoever starts the run.

Many times a project may require several transformations and tables to complete intermediate steps while the end result may end up only consisting of a few tables. Members do not always require viewing of all the elements of the project, sometimes just the final product. PlaidCloud offers you the ability to set different viewing roles to easily declutter and control the visibility of each member.

There are three built-in viewing roles: Architect, Manager, and Explorer

The Architect role is the most simple because it allows full visibility and control of projects, workflows, tables, variables, data editors, hierarchies, and user defined functions.

The Manager and Explorer roles have no specific access privileges but can be custom-defined. In other words, you can choose which items are visible to each group.

You can make everyone an Architect if you feel visibility of everything within the project is needed; otherwise, you can designate members as Manager and/or Explorer project members and control visibility that way.

To set the different role:

  1. Open Analyze
  2. Select “Projects”
  3. Click the members icon
  4. Select the member you whose role you would like to change
  5. Double click their current role in the “Role” column
  6. Select the desired role
  7. Click “Update”

When running a project or workflow it may be useful to set variables for recurring tasks in order to decrease clutter and save time. These variables operate just like a normal algebraic variable by allowing you to set what the variable represents and what operation should follow it. PlaidCloud allows you to set these variables at the project level, which will effect all the workflows within that project, or at the workflow level, which will only effect that specific workflow.

To set a project level variable:

  1. Open Analyze
  2. Select “Projects”
  3. Click the Manage Project Variables icon

From the Variables Table you can view the variables and view/edit the current values. You can also add new or delete existing variables by clicking the “New Project Variable” button.

Copy Project copies a project — all of it, or just the parts you pick — into a brand-new project or into a project that already exists.

To copy a project:

  1. Open Analyze
  2. Select “Projects”
  3. Select the project you want to copy
  4. Click the Actions button and choose Copy Project
  5. Choose the target, pick what to bring across and what data to copy, and click Copy Project
  6. Check the Review Before Copying summary and click Start Copy

The selection tree lists what the project holds, by type — workflows, steps, tables, dimensions, data editors, user-defined functions. Leave everything ticked to copy the whole project, or tick only the parts you want.

You do not have to work out what those parts depend on. Anything you tick brings its dependencies with it: the tables a step reads and writes, the dimensions it loads or allocates against, the user-defined functions it calls, and any sub-workflow or macro it invokes. A workflow’s sensors come with the workflow.

Copied sensors arrive disabled. Nothing fires on the copy until you turn each sensor on in the destination project. An import that overwrites duplicate items doesn’t add a second sensor when the destination workflow already has it.

Give the new project a name and an ID. The ID becomes its schema name and cannot be changed later.

Schedules arrive paused. When you copy a whole project into a new one, each workflow’s scheduled events come across paused, so the copy doesn’t start running them on its own. When the copy finishes, a message lists the events that were active in the original. To run one on the copy, select it in Tools > Event Scheduler and click Enable Selected — see Pausing an Event.

Pick the target from the project list. The copy adds to that project rather than replacing it.

You need to be able to change the target. A copy into a project you hold no role on is refused, as is a copy into a project that has been locked to prevent changes — checked before anything is read or written, so a refused copy leaves the target untouched. A project also cannot be copied into itself.

Copying a project that restricts rows takes a project Architect. The copy is a new project with no row access restriction, and the copy tells you so: “This copy is not row-restricted.” Set up Row Access on the copy before you share it. Copying into an existing project that restricts rows likewise needs one of its Architects or a tenant admin.

The target keeps its own settings. Its name, ID, data connection environment, storage defaults, document account, access type, access lists and row-access grants are all left as they are. Only the contents you selected are brought in.

A step set to Project Default carries that setting across, not an account — once copied, it resolves to whatever default the target project has, not the one it had in the source.

Where an incoming item is the same item as one already in the target, you choose what happens:

  • Overwrite duplicate items with incoming data — the incoming version replaces the one in the target.
  • Create new copy of duplicate items — the target keeps what it has, and the incoming one is added alongside it with copy appended to its name, and a counter if that name is taken too.

Project and workflow variables are the exception to Create new copy: a variable is identified by its name, so there is no way to add a second copy of one without renaming it into something nothing refers to. Where the target already defines a variable the copy also carries, the target’s own value is kept and the copy tells you which variables it left alone. Overwrite treats variables like everything else and replaces them.

This matching is by identity, not by name — an item that came from the same project originally is recognised as the same item, while two items that merely happen to share a name are treated as different items and both will be present afterwards.

Under Data to copy, two settings decide what data comes across with your selection.

Table data sets how many of each table’s rows are copied:

Choice What is copied
No table data Tables, steps and the rest of the selection, with no rows. This is the default.
Full Every table’s rows, on the same lakehouse and across lakehouses.
Sample Up to the number of rows per table you enter, for a new project only. The number can be 1 to 1,000,000.

A sampled table holds up to that many rows, or all of its rows when it has fewer. A Full or Sample copy copies several tables at once, so a project with many tables finishes faster.

Copy dimension members copies the members of every dimension in the selection, whichever Table data choice you make. It is on by default, so a copy with no table data still arrives with populated dimensions and is quick to make. Clear it to copy the dimensions without their members.

Through the REST API (POST /rest/v1/analyze/project/copy) or the project_copy MCP tool, set data_mode to structure, full or sample, and dimension_members to true or false. When you leave dimension_members out, members are copied only when table rows are. project_copy also returns the copy’s warnings, such as ERP write authorizations that were not copied.

Before anything is copied, Review Before Copying summarizes the copy: the project it comes from, where it goes, the Table data choice, whether Dimension members are included, the number of tables and views, the size, an estimated time, the source and target lakehouse, and any warnings under Please note. Click Start Copy to begin, or Cancel to go back and change the selection.

A copy made with data — table rows, dimension members, or both — is private to the person who made it. Share it from the new project when you are ready. A copy of a project with row-level security stays private for the same reason.

Copying data into an existing project needs write access to that project.

A new copy that is private to you keeps the source project’s ERP write authorizations, so you can test its posting workflows without authorizing the copy again. That is any copy into a new project made with table data (Full or Sample), dimension members, or both. The authorizations are copied when:

  • You are an Architect of the source project or a workspace admin.
  • You make the copy yourself, not through an agent or a service account.

Each authorization is copied only if you could grant it yourself today: its connection and environment still exist, and you have write access to the connection. The copied authorizations are recorded as yours.

The copy arrives in Simulate. If the source project’s ERP Posting Mode is Live, the copy’s is set to Simulate, so its workflows build and check what they would post without contacting the ERP. A source set to Simulate or Off keeps that setting. When you are ready to post for real from the copy, set ERP Posting Mode under ERP Posting on the copy’s home page to Live — see Choose a Posting Mode. Schedules and sensors still arrive paused and disabled as described above, so nothing runs on the copy until you turn it on.

A copy into an existing project, or one with no table data and no dimension members, starts without the source’s authorizations. Authorize it under ERP Posting > ERP Write Authorizations on its home page before it posts.

Copy Results reports what happened, for example “2 ERP write authorizations copied; ERP posting is in Simulate”, along with how many were not copied.

When the copy finishes, a Copy Results window summarizes the tables and dimension members copied and lists each table and dimension by name with its outcome — Copied, Copied with changes, Sampled, Skipped or Failed — and the reason for any that was skipped or failed. Click Retry failed items to copy the failed tables and dimensions again; their current contents in the copy are replaced. You are notified, by message and by email, when a copy finishes or fails, and you can reopen the results from the message, or later by selecting the copy on the Projects tab and choosing View Import or Copy Result from the Actions menu.

The results stay on the copy until someone dismisses them. Once the copy has finished, click Dismiss Result to remove them for everyone who can open the project. Nothing in the project changes, but its failed items can no longer be retried from the window. Dismissing needs edit access to the project, and the project must not be locked.

A project’s workflow steps refer to tables and other objects inside that project. Update References rewrites those references so they point at the copy rather than the original — which is almost always what you want, and is why it is on by default. Turning it off leaves the copied steps pointing back at the project they came from.

When a project or workflow is dynamic, maintaining detailed documentation becomes a challenge. To help solve this problem, PlaidCloud provides the ability to generate a project-level report that gives detailed documentation of workflows, workflow steps, user defined transforms, variables, and tables. This report is generated on-demand and reflects the current state of the project.

To download the report:

  1. Open Analyze
  2. Select “Projects”
  3. Click the report icon