Project references（项目引用(Project references)）

In Foundry, Projects define both a conceptual boundary around related work, and a security boundary for applying and managing access. Using data across project boundaries must be treated with extra care.

Referencing a resource

Project references provide a mechanism for users with higher permissions - typically the owners of a dataset or pipeline - to allow the discovery and use of data in other projects. They add an increased layer of scrutiny for moving data between projects by explicitly acknowledging when a dataset is imported into a project.

To reference a resource, go to the Project navigation panel at the root level of the project. Click the +Add button to add a reference to a dataset or template. In the below image, the datasets flights and training_data and the Code Workbook template scatterplot template are added as references in the project. This means that Code Repositories and Code Workbooks in the project can use flights and training_data as an input, and the scatterplot template template can be used by Code Workbooks in the project.

• To reference a resource, you must have compass:import-resource-from on the resource (usually expanded from the Viewer role) and compass:import-resource-to on the destination project (usually expanded from the Editor role).
• These roles can be customized using Custom Roles.

Project-scoped Workbooks

All new Code Workbooks are project scoped, meaning they respect project boundaries and use a token scoped to the project.

In a project-scoped workbook:

• All input datasets and templates must be in project scope: they must be in the same project as the workbook, or added as a reference in the project.
• All output datasets must be in the same project as the workbook.
• API calls to Foundry services using the job token will fail.

If there are any noncompliant inputs or outputs in a project-scoped workbook, those transforms will fail to build and their job specs will not update.

In a project-scoped workbook, noncompliant inputs and outputs will be listed in the project scope dialog. If you have the necessary permissions, you can add references to out-of-scope input datasets and templates from the dialog. Alternatively, you can use the Project Summary Panel at the root of the project.

In a project-scoped workbook, noncompliant inputs and outputs are also denoted with a red icon.

Enabling project scoping on your workbook

For workbooks created prior to project scoping being enabled by default, you will be prompted to enable project scoping. The project scope dialog will list the non-compliant inputs and outputs on the selected branch. You must resolve these issues prior to enabling project scoping on the master branch. If you do not enable project scoping, the workbook will continue to run with the user token as before. You will be able to continue to work normally, edit, and run builds in the workbook. You will still be able to reach Foundry APIs, use imported datasets that are out of project scope, etc.

Project scoping can only be enabled on the master branch. Once you have enabled project scoping on the master branch, other branches may still have non-compliant inputs or outputs. These will be listed in the project scope dialog on those branches. Once you have enabled project scoping, there is no way to disable it through the UI.

---

中文翻译

项目引用(Project references)

在 Foundry 中，项目(Projects) 既定义了相关工作的概念边界，也定义了应用和管理访问权限的安全边界。跨项目边界使用数据必须格外谨慎。

引用资源

项目引用为具有较高权限的用户（通常是数据集或数据管道(pipeline)的所有者）提供了一种机制，允许发现和使用其他项目中的数据。通过在将数据集导入项目时进行明确确认，它们为跨项目移动数据增加了一层更严格的审查。

要引用资源，请前往项目根级别的项目导航面板(Project navigation panel)。点击 +Add 按钮添加对数据集或模板的引用。在下图中，数据集 flights 和 training_data 以及 Code Workbook 模板 scatterplot template 已作为引用添加到项目中。这意味着项目中的 Code Repositories 和 Code Workbooks 可以将 flights 和 training_data 用作输入，并且项目中的 Code Workbooks 可以使用 scatterplot template 模板。

• 要引用资源，您必须对该资源拥有 compass:import-resource-from 权限（通常从 Viewer 角色扩展），并对目标项目拥有 compass:import-resource-to 权限（通常从 Editor 角色扩展）。
• 这些角色可以使用自定义角色(Custom Roles)进行定制。

项目作用域工作簿

所有新的 Code Workbooks 都具有项目作用域(project scoped)，这意味着它们遵循项目边界并使用限定于该项目的作用域令牌(token)。

在项目作用域工作簿中：

• 所有输入数据集和模板必须位于项目作用域内：它们必须与工作簿位于同一项目中，或作为引用添加到项目中。
• 所有输出数据集必须与工作簿位于同一项目中。
• 使用作业令牌(job token)对 Foundry 服务进行的 API 调用将会失败。

如果项目作用域工作簿中存在任何不合规的输入或输出，这些转换(transforms)将构建失败，并且其作业规范(job specs)不会更新。

在项目作用域工作簿中，不合规的输入和输出将列在项目作用域对话框中。如果您拥有必要的权限，可以通过该对话框为超出作用域的输入数据集和模板添加引用。或者，您可以使用项目根目录下的项目摘要面板(Project Summary Panel)。

在项目作用域工作簿中，不合规的输入和输出还会用红色图标标示。

在工作簿上启用项目作用域

对于在默认启用项目作用域之前创建的工作簿，系统将提示您启用项目作用域。项目作用域对话框将列出所选分支上不合规的输入和输出。您必须在主分支(master branch)上启用项目作用域之前解决这些问题。如果您不启用项目作用域，工作簿将继续像以前一样使用用户令牌(user token)运行。您将能够继续正常工作、编辑并在工作簿中运行构建。您仍然能够访问 Foundry API、使用超出项目作用域的导入数据集等。

项目作用域只能在主分支上启用。在主分支上启用项目作用域后，其他分支可能仍存在不合规的输入或输出。这些将列在相应分支的项目作用域对话框中。一旦启用了项目作用域，将无法通过 UI 禁用它。