Documenting Relationship in the Open Platforms Portal

This tutorial will teach you how to document relationships in the Open Platform Portal.

    Three types of relationship exists:
  • Re-use relationships: Strongest type of relationship between components: One directly reuses the others, or parts of the others.
  • Interoperability relationships: Strong type of relationship between components: proven interoperability between the two components or part of them.
  • Reference relationships: Weakest type of relationship between components: reference, similarity, and other relations between the two components or part of them.
  • Requires relationships: Relationship indicating that one component is required by the other to function correctly.
  • Latest version ID: 1.0
  • Tags: ,
  • Latest update: July 8, 2014
  • Developed by: inno for the BUTLER project and IERC AC1
  • Contact name: Bertrand Copigneaux
  • Relations:
    • Open Platforms Portal (more details)
      • Relation type: Reference relationship
      • Validation: This tutorial references the Open Platforms Portal, which is described as a tool. No validation / declarative.
      • Completeness of the relation: 100%

Intellectual property rights (IPR)

Creative Commons License

This work is licensed under a Creative Commons Attribution 4.0 International License.

Requirements

To document relationships you need to have access to the Open Portal back office. The back office of the portal is available at this address

To join the initiative and get credentials to loggin, please contact us through the contact form, indicating the organization you work for and/or the project(s) you're involved in.

How relationship work

Relationships are reciprocal (if you define a relationship between component A and B, the relationship will both show in A and B public pages in the Open Platform portal. However, on the back office, the relationship will only show and be editable in the component where it was initially defined

To enable a high level of reusability of your component it is very important to well document its relationships. It not only provide a useful way to discover your components, but also provide additional information necessary for the reuse of your component: such as which other component it is interoperable with, what use case or architecture model it is based upon and how it will fit in the end user ecosystem.

Defining a relationship

Relations are defined by a specific Custom Field in the description of each component.

Editing a component

To define a relationship between two component you need to edit one of the pages of the component in the back office.

  1. Open the Open Platforms Portal back office.
  2. Open the type of custom category of the component to which you wish to add a relationship.
  3. Search for the component to which you wish to add a relationship.
  4. Click Edit.
  5. tuto_relations0_edit

Selecting the component to which the relationship will point

  1. In the custom fields of the component you are editing, click on "Choose relation" to add a new relationship.
  2. tuto_relations1

  3. A pop up window will open in the back office listing recently edited components
  4. Select the category of the component you want to link this component to
  5. tuto_relations2

  6. Click "Filter" to show only the category of component you selected
  7. tuto_relations3

  8. You can search for specific term, to further refine your search for the right component.
  9. Be sure to click "Filter" to update the list
  10. tuto_relations4

  11. Check the checkbox next to the name of the component you want to link this component too
  12. tuto_relations5

  13. Click "Add to post and close".
  14. tuto_relations6

Documenting the relationship

Once you have selected the component to which you want to create a relationship, you can document the relationship.

  1. Define the type of relationship between the two component in the dropbox menu.
  2. tuto_relations8

      Three types of relationship exists:

    • Re-use relationships: Strongest type of relationship between components: One directly reuses the others, or parts of the others.
    • Interoperability relationships: Strong type of relationship between components: proven interoperability between the two components or part of them.
    • Reference relationships: Weakest type of relationship between components: reference, similarity, and other relations between the two components or part of them.
    • Requires relationships: Relationship indicating that one component is required by the other to function correctly.
  3. Describe the relationship and how it has been validated. It is important to provide as much information as possible to accurately describe the relationship (including the direction of the relationship if it is unidirectional). The description of the validation of the relationship can range from purely declarative to backed by plug-test, hackathon, common protocol uses, etc...
  4. tuto_relations9

  5. Define the completness of the relationship. The completness should be a percentage. The format expect a number between 0 and 100 without the "%" sign. The completness of the relationship is a self assessment, and is not expected to be a very accurate calculation, but rather an overall estimate of whether the relationship described is complete, or partial and to which extent.
  6. tuto_relations10

Publishing

To save and make visible your newly define relationship click Publish in the edition page of the component you are documenting

tuto_relations11

Service level

This tutorial is a first version, it will be updated as the Open Platform Portal evolves