OpenEA User Guide

1. Account and organisation access

Register or sign in using the account provided for your OpenEA installation. If you are new to an organisation, give its administrator your username and ask them to associate your account with the organisation and the appropriate security group. You will only see data and actions granted to your active profile.

Use the user menu in the upper-right corner to open your repositories and account-related pages. If your account belongs to more than one organisation, select the profile for the organisation whose data you want to work with.

2. How OpenEA organises information

• Organisation: the scope that owns and shares architecture data.
• Repository: a container for related models.
• Model: a versioned architecture workspace. It contains the definitions and the instances that use them.
• Concept: a type of thing represented in the model, such as Application, Person, or Business Capability.
• Relation: a reusable property or relationship name, such as has owner or depends on.
• Predicate: a rule that connects a subject concept, a relation, and an object concept. For example, Application (has owner) Person.
• Instance: a specific item of a concept, such as the application named Finance Portal.
• Slot: a value or link recorded for an instance through a predicate. A slot can connect to another instance or store a value.

In short: define concepts and the allowed predicates first, then create instances and fill in their slots.

3. Start a model

1. Open Repositories from the user menu.
2. Open the repository for your work. If you have permission and none exists, create a repository for the appropriate organisation.
3. Create a model in that repository. Give it a clear name, version, and description so other users can identify its scope.
4. Open the model. Its tabs provide access to model elements, reports, and analysis views where your permissions allow them.

Use separate model versions for meaningful snapshots or review cycles. The repository's model catalog lets you search model names, descriptions, versions, and repository names, and filter by review status.

4. Define the model structure

1. Create concepts. In the Concepts tab, add each kind of architecture element you need. Use specific names and descriptions; these labels will also help users choose the correct type when creating instances.
2. Create relations. In the Relations tab, define reusable names for properties or links, such as has owner, runs on, or depends on.
3. Create predicates. In the Ontology tab, connect a subject concept, relation, and object concept. For example, Application + has owner + Person describes which kinds of instances can be linked by that relation.
4. Review the graph. Use the model's Graph or Matrix view to inspect the structure and spot missing or unexpected links.

Plan the concepts and predicates before entering many instances. A predicate controls which concepts can be selected when users add a relationship.

5. Create and connect instances

1. From the model's Concepts tab, open the concept you want to instantiate and choose New instance.
2. Enter the instance's name and any other requested details, then save. Use a description or code when it helps people distinguish similar items.
3. Open the instance. Its detail page shows its concept and existing values or relationships.
4. Use the add buttons beside a predicate to add a permitted value or related instance. Choose an existing instance where the predicate describes a link, or enter a value where it describes a literal property.
5. Use the edit and delete controls beside an existing slot to correct or remove that value, if you have permission.

For example, create a Finance Portal instance under Application, then use its has owner predicate to link it to an instance of Person. You can browse all instances of a type from the concept, or browse the model's instance list where available.

6. Explore and analyse a model

• Graph: visualise model elements and relationships. Large models may be limited by the installation's graph settings.
• Matrix: inspect relationships in a tabular layout.
• Impact Analysis: follow related instances and their paths to understand potential impact.
• Path Finder: explore a path between instances.
• Gap Analysis: inspect gaps in the model using the available model-specific criteria.
• Filters: use the search controls on model element lists to narrow the displayed rows.

These views are based on the data and relationships in the selected model. If an analysis is empty or incomplete, first check that the relevant concepts, predicates, instances, and slots have been created.

7. Search, compare, and review versions

From a repository's model catalog, search by text or filter by review status. You can save a search for later use and, if permitted, share it with your organisation. Use Compare versions to inspect the differences between two model versions.

Where the review workflow is enabled:

1. A model starts as a Draft. Users with the required permission can edit it.
2. Submit the draft for review when it is ready. Its status becomes In review.
3. A reviewer can approve it or request changes with a comment. A returned model becomes Changes requested.
4. An Approved model version is read-only. To make changes, copy it to a new draft version and work in the copy.

The model detail page shows review history when available. If you do not see a review action, ask your organisation administrator whether your profile has the required permission.

8. Import and export

Use the model's Import action to upload a supported model or instance file. Select the format and knowledge set requested by the form, choose which element categories to include where those options are shown, and start the import. The application validates the file and reports task progress and any parser errors.

Use Export to download model data in a supported format. Available formats depend on the installed plugins and configuration; common formats include JSON, XML, Excel workbooks, and Essential Architecture files.

Imports and exports may run as background tasks. Check the task detail or task list for its current status. If an import fails, verify the file type, required sheets or fields, and compatibility with the selected knowledge set before trying again.

9. Reports

Open the model's Reports tab to create, preview, and run reports if your permissions allow it. Reports can use the provided templates or a custom Django template, depending on what the installation enables. A report can only access model data available to the current user; custom templates are rendered in a restricted context.

The model detail page also provides a model report action. Use preview to check a report before relying on its output.

10. Profiles and permissions

Access is scoped to an organisation and controlled by permissions granted through security groups associated with profiles. Depending on those permissions, you may be able to view an item but not create, edit, delete, import, export, run a report, or approve a model. Tabs and buttons can be hidden when the corresponding access is not granted.

Contact your organisation administrator if you cannot see an expected repository, model, action, or profile. Include the organisation, the item you were trying to access, and the action you expected to perform.

11. Common questions

I signed in but cannot see my organisation.

Ask an organisation administrator to associate your account with the correct organisation and security group, then select the appropriate profile.

I cannot add a relationship to an instance.

Check that a predicate connects the instance's concept to the intended target concept. Also confirm that your profile has create or update permission.

I cannot edit an approved model.

Approved versions are immutable. Copy the version to a new draft and make changes there.

An import or export is still running.

Open the corresponding task to check its status. Background tasks may take time depending on file size and the installation's task workers.

A tab or button is missing.

Some model views are only shown when their permissions are available. Ask your organisation administrator to review your profile's access.