Import and export

Use the Import and Export functionality to move your project's attributes, attribute connector configurations, and policies between projects or environments. Import/Export files use the Authorization Hub JSON format.

Each artifact type has its own import and export actions, available in the Actions menu of its view:

• Dictionary for attributes
• Attribute connectors for attribute connector configurations
• Policies for ALFA policies

note

Domains, obligations, and advice cannot be imported or exported yet. File formats other than JSON are not supported.

How an import works

An import does not apply changes to the project directly. The imported items are saved to My workspace as pending changes, exactly as if you had created or edited them manually. From there you can review them, discard them, or save them to the project.

1. Open the view for the artifact type you want to import.
2. Open the Actions menu and select Import.
3. Drop a single .json file in the dialog, or browse for it.
4. Confirm the import and review the import results.
5. Open My workspace to review the pending changes, then save them to the project or discard them.

tip

Discarding your workspace after an import removes everything the import added, across all artifact types, along with any other changes you have pending.

note

An import run with M2M client credentials, through the API or a migration tool, is staged in the client's workspace, not in yours. A Project admin must save it to the project. Read Client workspaces for details.

An import is subject to the same rules as any other change made in the UI. Importing requires the Project editor or Project admin role, the same permission needed to make changes in My workspace. Exporting also requires the Project editor or Project admin role. Read the Project roles section for details.

Existing items

Imported items are matched against the project by name: attributes and attribute connectors by their fully qualified name (namespace plus name), and policies by file name. There is no option to choose how conflicts are handled:

• Items that do not exist in the project are staged as new.
• Items that already exist are staged as edits to the existing item. If you already have a pending change for the same item in My workspace, the import replaces it with the content of the file. If the file matches the published version, the item is no longer a pending change.
• For attributes and attribute connectors, a field that is empty in the file (for example, the description, or an attribute's category) is cleared in the staged edit. An attribute's cache profile is the exception: if it is empty in the file, the current cache profile is kept.
• Items that are identical to what is already in the project are not staged.

note

The UI requires every attribute to have a category. An attribute whose category was cleared by an import must get one again before it can be edited in the UI.

Items that could not be imported never become pending changes and appear only in the import results message.

Import results

After every import you see a message summarizing the import results (for example, how many items were created and edited). Anything that could not be imported is listed by name together with the reason, so you can fix the problem and import again. When nothing can be imported, the message lists the conflicting items and states that nothing was imported.

File validation

Authorization Hub validates every file before import. A file is rejected, and nothing is written to My workspace, when:

• it is not JSON or is not well-formed JSON
• it does not match the import format for that artifact type (for example, because it has no recognized sections)
• it contains fields that the import format does not define

The error states why the file was rejected so you can correct it and try again. The result is the same whether you import through the UI or the API.

note

Files exported from other products, such as ASM XML files, cannot be converted by import and are rejected.

Import and export by artifact type

Select the Import or Export tab under each artifact type for details.

Attributes

• Import
• Export

In the Dictionary, open the Actions menu (or use Import in the empty state) and follow the steps in How an import works. Imported attributes appear in the Dictionary with the orange draft indicator until you save them to the project.

• Cache profiles referenced by the file that don't exist in the project are created along with the attributes, and the results message counts them. Existing cache profiles are not updated.
• Imported attributes are always created as writable, even if the file marks them as read-only.
• If you import a change to an existing read-only attribute, it is staged, but saving it to the project is rejected because read-only attributes cannot be edited.

In the Dictionary, open the Actions menu and select Export to download all of the project's published attributes as a single JSON file. The file name starts with the project name.

• Changes still pending in My workspace are not included.
• Deprecated and deleted attributes are not exported.
• The Actions menu is unavailable while the export is running.

Attribute connectors

• Import
• Export

In the Attribute connectors list, open the Actions menu, select Import, and follow the steps in How an import works.

• Each attribute connector's attributes are matched to the target project's Dictionary by fully qualified name, including attributes pending in your My workspace. An attribute connector that references an attribute missing from the project is refused, and the import results list each refused connector and the missing attributes. The import never creates attributes itself.
• Import the attributes first, then the attribute connectors. If some attribute connectors were refused, import the missing attributes and import the file again.
• The success message shows how many attribute connectors were created and how many were edited.
• All seven attribute connector types are supported: Table, SQL, LDAP, HTTP, XML parser, JSON parser, and JWT parser.

In the Attribute connectors list, open the Actions menu and select Export to download all of the project's published attribute connectors as a single JSON file. The file name starts with the project name.

warning

The exported file contains attribute connector credentials, such as passwords and signature keys, in plain text. Store and share it as sensitive data.

To keep credentials out of exports, use environment variables instead of literal values in your attribute connector configurations. The export then contains only the variable reference.

• Changes still pending in My workspace are not included.
• The file contains the attribute connector configurations only. It does not include the definitions of referenced attributes.
• Deleted attribute connectors are not exported.
• The Actions menu is unavailable while the export is running.

tip

When moving a working setup to another project, import in this order: attributes, attribute connectors, then policies. Then review everything together in My workspace and save it to the project in one step.

Policies

• Import
• Export

In the Policies editor, open the Actions menu, select Import, and follow the steps in How an import works.

warning

Importing reloads open project files. Save or discard any unsaved changes in the editor before proceeding.

note

Importing policies doesn't import attributes. The target project's Dictionary is used, and attributes missing from it are not reported during import. They appear as errors in the Policies editor, so import the attributes first.

• Import never deletes policies. Published policies that aren't in the file are left as they are.
• New and changed policies are staged in My workspace, where you can review each one, use Compare changes, and then save or discard it.
• If every policy in the file is identical to the published one, nothing is imported.
• A file is rejected if two policies share the same file name, if a file name contains a folder path, or if a policy has no contents.

In the Policies editor, open the Actions menu and select Export to download the project's published policies as a single JSON file named <project>_policies_<timestamp>.json.

• The file contains each ALFA file's name and contents, and the policy package metadata (entry points and used attributes) needed by Domains.
• The Actions menu is unavailable while the export is running.

Audit and activity

Exports are recorded in the audit logs. The import itself isn't logged. The imported changes are recorded when they're saved to the project.

Imported changes are also recorded in the project's Activity feed once they are saved to the project.

Import and export through the API

You can also import and export through the API, for example to move a configuration between environments from a pipeline. The files are the same as those the interface produces.

Artifact	Export	Import
Attributes	GET /api/dictionary/attributes/export	POST /api/dictionary/attributes/import
Attribute connectors	GET /api/attribute-connectors/export	POST /api/attribute-connectors/import
Policies	GET /api/policy-package/{packageName}/export	POST /api/policy-package/{packageName}/import

• Exports return a JSON file. The suggested file name is in the Content-Disposition header: attributes_<timestamp>.json, attribute-connectors_<timestamp>.json, and policies_<timestamp>.json.
• Imports are multipart/form-data requests with a single JSON file in a part named file. Send the X-Project-Id header with every request.
• An import returns 202 and stages the changes in the caller's workspace, and returns a summary of what was created and edited. Promote the workspace to apply them.
• Import files are validated the same way as in the interface. Read File validation.

Read the endpoint references for the requests and responses, and My workspace and the API for how staged changes are promoted.