DE4A - User contributions [en-gb]

Use Case "Starting a Business in Another Member State" (DBA UC1)

2021-04-13T09:40:03Z

Ictu test: /* Common OOP TS components */

At the core of this use case is the fulfilment of procedural obligations to do business in another Member State, especially the initial registration of a company at an eProcedure portal (AT, NL and RO pilot scenarios), opening a branch and the assessment of tax duties in the destination Member State (in the Swedish pilot scenario). In this use case, a company representative authenticates to the eProcedure portal, registers the company at the portal and applies for a service.

This UC uses the [[Intermediation Pattern]] and the [[Subscription and Notification Pattern]].

==[[DBA UC1 definition|Definition]]==

=== Scope ===
[[File:Use_case_to_interaction_pattern_mapping.png|alt=|right|285x285px]]
The first use case ends with a subscription to receive notifications of business events of the company involved. From a logical process point of view, this is strongly intertwined with the company registration: subscribing to notifications follows directly after registration of the company at the eProcedure portal, before the process ends. Hence it is an integrated part of the first use case. From an [[Reference Interaction Patterns|interaction pattern perspective]], the subscription to notifications does not belong to the [[Intermediation Pattern|intermediation pattern]] but to the [[Subscription and Notification Pattern|subscription & notification pattern]]. The first part of the [[Subscription and Notification Pattern|subscription and notification pattern]] deals with managing subscriptions, the second part with sending notifications once a business event took place. So, the first use case spans two interaction patterns.

==[[DBA UC1 major design decisions|Major design decisions]]==
* [[DBA UC1 major design decisions#Two Member State intermediation scenario|Two Member State intermediation scenario]]
* [[DBA UC1 major design decisions#Real eProcedures and simulated eProcedures|Real eProcedures and simulated eProcedures]]
* [[DBA UC1 major design decisions#Real data and fictitious data|Real data and fictitious data]]
* [[DBA UC1 major design decisions#eIDAS network and non-notified eIDs|eIDAS network and non-notified eIDs]]
* [[DBA UC1 major design decisions#Powers validation|Powers validation]]
* [[DBA UC1 major design decisions#Record matching|Record matching]]
* [[DBA UC1 major design decisions#Explicit request, preview & logging|Explicit request, preview & logging]]
* [[DBA UC1 major design decisions#Company registration evidence|Company registration evidence]]

==[[DBA UC1 process|Process]]==
The first version of the pilot process has been analysed and specified in the D4.5 deliverable. Subsequently, the processes have been further detailed by each of the pilot partners for their specific situation, required functionality has been specified, the processes have been aligned to the project start architecture (that has been designed after the delivery of D4.5), the solution architecture has been defined, national customisations and integration activities and gaps have been identified. This section specifies the interpretation of the [[Intermediation Pattern|reference pattern]] for the DBA pilot (see project start architecture).

Points of attention when comparing to the initial pilot process design from D4.5 and the Member State specific detailed process designs (based on the solution architecture):

* Use case 1 cannot be implemented fully with the intermediation pattern. The subscribing of a company for updates is not part of the intermediation pattern and will not be included in the first pilot iteration.
* The process “request authentication” (DE) in the DBA pilot includes also (1) requesting the identifying attributes of the company represented and (2) requesting a powers validation. This does not contradict to the reference pattern, but needs highlighting because of its importance for the DBA pilot.
* The process “provide authentication details” (user) in the DBA pilot includes also identifying the company that the user wants to represent. This may be done by entering the company identifier, by selecting the company from a list of companies the user has powers for or by directly selecting the mandate to use. In any case, the user’s powers to represent need to be validated. The implementation is Member State specific and does not need harmonisation for piloting.
* The process “establish user identity” (user) in the DBA pilot refers to record matching on the company represented as outlined in section 3.3.6.
* The process “redirect user to another channel” (user) in the DBA pilot means: allowing the user to register the company by using currently existing in-person or paper-based procedures.
* The process “determine procedural requirements” and “determine required cross-border evidence” have been simplified for the DBA pilot to reflect the decision to use just one evidence type. The procedural requirements and evidence to request are fixed in the scenario of each pilot partner.
* Saving and resuming the eProcedure (user) will not be supported in the DBA pilot.
* “Provide public service” in the DBA pilot initially means: registering the company at the eProcedure portal. Registering the company in all pilots’ scenarios is the pre-requisite for applying for eServices, like assessment of tax duties, filing tax and applying of a subsidy or grant.

==[[DBA UC1 data model|Data model]]==

* [[DBA UC1 data model#Data model diagram|Data model diagram]]
* [[DBA UC1 data model#Attribute specification|Attribute specification]]

==[[DBA UC1 components|Components]]==
=== Common eIDAS components ===
{| class="wikitable"
|Component
|Role
|Short description of its use
|-
|[[eIDAS connector]]
|eIDAS connector
|The component Member States implement to connect to the eIDAS network as a relying party. The connector accepts authentication requests from the service providers of the Member State and forwards the requests to the Member States that needs to authenticate the user. After authentication, the eIDAS connector receives the authentication results and sends them to the requesting service provider (relying party).

The eIDAS connector can be implemented using CEF’s reference software or a custom implementation compliant to the eIDAS interoperability specifications. The CEF reference software implements – besides the eIDAS SAML profile – also the JSON/REST eIDAS Light protocol to connect to national infrastructure.
|-
|[[eIDAS proxy]]
|eIDAS proxy
|The component Member States implement to allow authentication with their (notified) eID for services provided in other Member States. The eIDAS proxy receives authentication requests from relying Member States, coordinates authentication, retrieval of legal person attributes and powers validation. The eIDAS proxy then sends the result to the requesting eIDAS connector.

Just like the eIDAS connector, the eIDAS proxy can be implemented using CEF’s reference software or a custom implementation compliant to the eIDAS interoperability specifications. The CEF reference software implements – besides the eIDAS SAML profile – also the JSON/REST eIDAS Light protocol to connect to national infrastructure.
|-
|[[SEMPER extension]]
|eIDAS connector and

eIDAS proxy
|To be used in final pilot iteration only:

The eIDAS interoperability architecture as well as the CEF reference implementation allow for extension of eIDAS with additional – domain specific – attributes. The SEMPER project used this option to include attributes on the powers requested (‘powers validation request’) and the result of powers validation (‘the powers declaration’). The SEMPER extension leaves the eIDAS functionality untouched, but extends its use with an addition to the SAML profile and the Light protocol.
|}

=== Common OOP TS components ===
{| class="wikitable"
|Component
|Role
|Short description of its use
|-
|Evidence service locator (ESL) configuration file
|Data requestor and data transferor
|As the DBA pilot’s MVP uses just one type of evidence, with just one data provider per Member State (on NUTS0 level), there is no need for dynamic discovery of the data provider and its data services. For the DBA pilot it is sufficient to use a simple configuration file with the required elements (Member State and participant id).

The ESL configuration file is also called “Information desk configuration file”. The file will be integrated in the DE4A connector. It will be replaced by full Information Desk functionality in the second pilot iteration.
|-
|[[SMP]]
|Data requestor and data transferor

/ central
|For each evidence request and response, information on the receivers Access Point (URL) and its certificates are needed. Each Member State hosts an SMP for this purpose. Before sending a request or response, the sending party queries the SMP of the receiver to get this information. For initial testing purposes the SMP will be hosted centrally to ease implementation.
|-
|[[DNS]] & [[SML]]
|Data requestor and data transferor
|As there are multiple SMPs, the sending party needs to know where to find the SMP of the receiver to get the actual metadata. This location can be found in the centrally CEF-hosted DNS, that will be queried by the access point of the sending Member State.

DNS entries will be created from the registration of SMPs: the SML, which is also centrally hosted by CEF.
|-
|[[eDelivery AS4 Gateway]]
|Data requestor and data transferor
|This component – also referred to as eDelivery access point – handles the secure transfer of the data, including encryption and decryption as well as signing/sealing and validating signatures/seals.
|-
|[[Connector|DE4A Connector]]
|Data requestor and data transferor
|The DE4A connector is the reference software that data requestors and data transferors can use to connect to the OOP TS. This eases the work by abstracting the communication with the components. The DE4A connector handles all communication with the ESL configuration file, DNS & SML and AS4 gateway. The DE4A connector will include an AS4 gateway (Phase4). AT, NL and RO will use this integrated gateway.
|}

DBA UC1 components

2021-04-13T09:39:40Z

Ictu test: /* Common OOP TS components */

''Back to [[Use_Case_"Starting_a_Business_in_Another_Member_State"_(DBA_UC1)|main DBA UC1 page]]''

== Common eIDAS components ==
{| class="wikitable"
|Component
|Role
|Short description of its use
|-
|[[eIDAS connector]]
|eIDAS connector
|The component Member States implement to connect to the eIDAS network as a relying party. The connector accepts authentication requests from the service providers of the Member State and forwards the requests to the Member States that needs to authenticate the user. After authentication, the eIDAS connector receives the authentication results and sends them to the requesting service provider (relying party).

The eIDAS connector can be implemented using CEF’s reference software or a custom implementation compliant to the eIDAS interoperability specifications. The CEF reference software implements – besides the eIDAS SAML profile – also the JSON/REST eIDAS Light protocol to connect to national infrastructure.
|-
|[[eIDAS proxy]]
|eIDAS proxy
|The component Member States implement to allow authentication with their (notified) eID for services provided in other Member States. The eIDAS proxy receives authentication requests from relying Member States, coordinates authentication, retrieval of legal person attributes and powers validation. The eIDAS proxy then sends the result to the requesting eIDAS connector.

Just like the eIDAS connector, the eIDAS proxy can be implemented using CEF’s reference software or a custom implementation compliant to the eIDAS interoperability specifications. The CEF reference software implements – besides the eIDAS SAML profile – also the JSON/REST eIDAS Light protocol to connect to national infrastructure.
|-
|[[SEMPER extension]]
|eIDAS connector and

eIDAS proxy
|To be used in final pilot iteration only:

The eIDAS interoperability architecture as well as the CEF reference implementation allow for extension of eIDAS with additional – domain specific – attributes. The SEMPER project used this option to include attributes on the powers requested (‘powers validation request’) and the result of powers validation (‘the powers declaration’). The SEMPER extension leaves the eIDAS functionality untouched, but extends its use with an addition to the SAML profile and the Light protocol.
|}

== Common OOP TS components ==
{| class="wikitable"
|Component
|Role
|Short description of its use
|-
|Evidence service locator (ESL) configuration file
|Data requestor and data transferor
|As the DBA pilot’s MVP uses just one type of evidence, with just one data provider per Member State (on NUTS0 level), there is no need for dynamic discovery of the data provider and its data services. For the DBA pilot it is sufficient to use a simple configuration file with the required elements (Member State and participant id).

The ESL configuration file is also called “Information desk configuration file”. The file will be integrated in the DE4A connector. It will be replaced by full Information Desk functionality in the second pilot iteration.
|-
|[[SMP]]
|Data requestor and data transferor

/ central
|For each evidence request and response, information on the receivers Access Point (URL) and its certificates are needed. Each Member State hosts an SMP for this purpose. Before sending a request or response, the sending party queries the SMP of the receiver to get this information. For initial testing purposes the SMP will be hosted centrally to ease implementation.
|-
|[[DNS]] & [[SML]]
|Data requestor and data transferor
|As there are multiple SMPs, the sending party needs to know where to find the SMP of the receiver to get the actual metadata. This location can be found in the centrally CEF-hosted DNS, that will be queried by the access point of the sending Member State.

DNS entries will be created from the registration of SMPs: the SML, which is also centrally hosted by CEF.
|-
|[[eDelivery AS4 Gateway]]
|Data requestor and data transferor
|This component – also referred to as eDelivery access point – handles the secure transfer of the data, including encryption and decryption as well as signing/sealing and validating signatures/seals.
|-
|[[Connector|DE4A Connector]]
|Data requestor and data transferor
|The DE4A connector is the reference software that data requestors and data transferors can use to connect to the OOP TS. This eases the work by abstracting the communication with the components. The DE4A connector handles all communication with the ESL configuration file, DNS & SML and AS4 gateway. The DE4A connector will include an AS4 gateway (Phase4). AT, NL and RO will use this integrated gateway.
|}

Use Case "Starting a Business in Another Member State" (DBA UC1)

2021-04-13T09:39:16Z

Ictu test: /* Common OOP TS components */

At the core of this use case is the fulfilment of procedural obligations to do business in another Member State, especially the initial registration of a company at an eProcedure portal (AT, NL and RO pilot scenarios), opening a branch and the assessment of tax duties in the destination Member State (in the Swedish pilot scenario). In this use case, a company representative authenticates to the eProcedure portal, registers the company at the portal and applies for a service.

This UC uses the [[Intermediation Pattern]] and the [[Subscription and Notification Pattern]].

==[[DBA UC1 definition|Definition]]==

=== Scope ===
[[File:Use_case_to_interaction_pattern_mapping.png|alt=|right|285x285px]]
The first use case ends with a subscription to receive notifications of business events of the company involved. From a logical process point of view, this is strongly intertwined with the company registration: subscribing to notifications follows directly after registration of the company at the eProcedure portal, before the process ends. Hence it is an integrated part of the first use case. From an [[Reference Interaction Patterns|interaction pattern perspective]], the subscription to notifications does not belong to the [[Intermediation Pattern|intermediation pattern]] but to the [[Subscription and Notification Pattern|subscription & notification pattern]]. The first part of the [[Subscription and Notification Pattern|subscription and notification pattern]] deals with managing subscriptions, the second part with sending notifications once a business event took place. So, the first use case spans two interaction patterns.

==[[DBA UC1 major design decisions|Major design decisions]]==
* [[DBA UC1 major design decisions#Two Member State intermediation scenario|Two Member State intermediation scenario]]
* [[DBA UC1 major design decisions#Real eProcedures and simulated eProcedures|Real eProcedures and simulated eProcedures]]
* [[DBA UC1 major design decisions#Real data and fictitious data|Real data and fictitious data]]
* [[DBA UC1 major design decisions#eIDAS network and non-notified eIDs|eIDAS network and non-notified eIDs]]
* [[DBA UC1 major design decisions#Powers validation|Powers validation]]
* [[DBA UC1 major design decisions#Record matching|Record matching]]
* [[DBA UC1 major design decisions#Explicit request, preview & logging|Explicit request, preview & logging]]
* [[DBA UC1 major design decisions#Company registration evidence|Company registration evidence]]

==[[DBA UC1 process|Process]]==
The first version of the pilot process has been analysed and specified in the D4.5 deliverable. Subsequently, the processes have been further detailed by each of the pilot partners for their specific situation, required functionality has been specified, the processes have been aligned to the project start architecture (that has been designed after the delivery of D4.5), the solution architecture has been defined, national customisations and integration activities and gaps have been identified. This section specifies the interpretation of the [[Intermediation Pattern|reference pattern]] for the DBA pilot (see project start architecture).

Points of attention when comparing to the initial pilot process design from D4.5 and the Member State specific detailed process designs (based on the solution architecture):

* Use case 1 cannot be implemented fully with the intermediation pattern. The subscribing of a company for updates is not part of the intermediation pattern and will not be included in the first pilot iteration.
* The process “request authentication” (DE) in the DBA pilot includes also (1) requesting the identifying attributes of the company represented and (2) requesting a powers validation. This does not contradict to the reference pattern, but needs highlighting because of its importance for the DBA pilot.
* The process “provide authentication details” (user) in the DBA pilot includes also identifying the company that the user wants to represent. This may be done by entering the company identifier, by selecting the company from a list of companies the user has powers for or by directly selecting the mandate to use. In any case, the user’s powers to represent need to be validated. The implementation is Member State specific and does not need harmonisation for piloting.
* The process “establish user identity” (user) in the DBA pilot refers to record matching on the company represented as outlined in section 3.3.6.
* The process “redirect user to another channel” (user) in the DBA pilot means: allowing the user to register the company by using currently existing in-person or paper-based procedures.
* The process “determine procedural requirements” and “determine required cross-border evidence” have been simplified for the DBA pilot to reflect the decision to use just one evidence type. The procedural requirements and evidence to request are fixed in the scenario of each pilot partner.
* Saving and resuming the eProcedure (user) will not be supported in the DBA pilot.
* “Provide public service” in the DBA pilot initially means: registering the company at the eProcedure portal. Registering the company in all pilots’ scenarios is the pre-requisite for applying for eServices, like assessment of tax duties, filing tax and applying of a subsidy or grant.

==[[DBA UC1 data model|Data model]]==

* [[DBA UC1 data model#Data model diagram|Data model diagram]]
* [[DBA UC1 data model#Attribute specification|Attribute specification]]

==[[DBA UC1 components|Components]]==
=== Common eIDAS components ===
{| class="wikitable"
|Component
|Role
|Short description of its use
|-
|[[eIDAS connector]]
|eIDAS connector
|The component Member States implement to connect to the eIDAS network as a relying party. The connector accepts authentication requests from the service providers of the Member State and forwards the requests to the Member States that needs to authenticate the user. After authentication, the eIDAS connector receives the authentication results and sends them to the requesting service provider (relying party).

The eIDAS connector can be implemented using CEF’s reference software or a custom implementation compliant to the eIDAS interoperability specifications. The CEF reference software implements – besides the eIDAS SAML profile – also the JSON/REST eIDAS Light protocol to connect to national infrastructure.
|-
|[[eIDAS proxy]]
|eIDAS proxy
|The component Member States implement to allow authentication with their (notified) eID for services provided in other Member States. The eIDAS proxy receives authentication requests from relying Member States, coordinates authentication, retrieval of legal person attributes and powers validation. The eIDAS proxy then sends the result to the requesting eIDAS connector.

Just like the eIDAS connector, the eIDAS proxy can be implemented using CEF’s reference software or a custom implementation compliant to the eIDAS interoperability specifications. The CEF reference software implements – besides the eIDAS SAML profile – also the JSON/REST eIDAS Light protocol to connect to national infrastructure.
|-
|[[SEMPER extension]]
|eIDAS connector and

eIDAS proxy
|To be used in final pilot iteration only:

The eIDAS interoperability architecture as well as the CEF reference implementation allow for extension of eIDAS with additional – domain specific – attributes. The SEMPER project used this option to include attributes on the powers requested (‘powers validation request’) and the result of powers validation (‘the powers declaration’). The SEMPER extension leaves the eIDAS functionality untouched, but extends its use with an addition to the SAML profile and the Light protocol.
|}

=== Common OOP TS components ===
{| class="wikitable"
|Component
|Role
|Short description of its use
|-
|Evidence service locator (ESL) configuration file
|Data requestor and data transferor
|As the DBA pilot’s MVP uses just one type of evidence, with just one data provider per Member State (on NUTS0 level), there is no need for dynamic discovery of the data provider and its data services. For the DBA pilot it is sufficient to use a simple configuration file with the required elements (Member State and participant id).

The ESL configuration file is also called “Information desk configuration file”. The file will be integrated in the DE4A connector. It will be replaced by full Information Desk functionality in the second pilot iteration.
|-
|[[SMP]]
|Data requestor and data transferor

/ central
|For each evidence request and response, information on the receivers Access Point (URL) and its certificates are needed. Each Member State hosts an SMP for this purpose. Before sending a request or response, the sending party queries the SMP of the receiver to get this information. For initial testing purposes the SMP will be hosted centrally to ease implementation.
|-
|[[DNS]] & [[SML]]
|Data requestor and data transferor
|As there are multiple SMPs, the sending party needs to know where to find the SMP of the receiver to get the actual metadata. This location can be found in the centrally CEF-hosted DNS, that will be queried by the access point of the sending Member State.

DNS entries will be created from the registration of SMPs: the SML, which is also centrally hosted by CEF.
|-
|[[eDelivery AS4 gateway|eDelivery AS4 Gateway]]
|Data requestor and data transferor
|This component – also referred to as eDelivery access point – handles the secure transfer of the data, including encryption and decryption as well as signing/sealing and validating signatures/seals.
|-
|[[Connector|DE4A Connector]]
|Data requestor and data transferor
|The DE4A connector is the reference software that data requestors and data transferors can use to connect to the OOP TS. This eases the work by abstracting the communication with the components. The DE4A connector handles all communication with the ESL configuration file, DNS & SML and AS4 gateway. The DE4A connector will include an AS4 gateway (Phase4). AT, NL and RO will use this integrated gateway.
|}

Getting started

2021-04-13T09:32:39Z

Ictu test: /* Editing */

[[Category:wip]]
Welcome, new editor of the DE4A documentation wiki!

Before you beging adding content, you can familiarise yourself in on this page with some basic wiki rules and functionalities. All the tips and instructions listed below are also applied on this page, so feel free to copy syntax from the page source as needed.

''==> Additional help is available in the [[wikipedia:Help:Cheatsheet|Wiki cheat sheet]], the [[mediawikiwiki:Special:MyLanguage/Help:Contents|User's Guide]], and the [[mediawikiwiki:Special:MyLanguage/Manual:FAQ|MediaWiki FAQ]].''

==Ground rules==
'''#1 Create from search.''' When you want to create a new page, start by searching the wiki for existing content. If the search yields no results, you will be offered the option to create a new page. If you do, make sure your search was capitalised in Title Case.

'''#2 Page names in Title Case.''' Page names are capitalised using Wikipedia rules. When in doubt, use this [https://titlecaseconverter.com/|Title Case Converter] tool to find the correct capitalisation. Different letter cases produce different wiki pages. For example, "[[Interaction Patterns]]" and "[[Interaction patterns]]" will lead to two different pages (the former exists on the DE4A wiki, the latter does not and should not, as it does not follow the Title Case capitalisation rule).

'''#3 Ask for help.''' Don't hesitate to contact the [https://wiki.de4a.eu/index.php/Special:ActiveUsers?username=&groups%5B%5D=interface-admin&wpFormIdentifier=specialactiveusers|DE4A WP2 Team] for advice and support when or before adding your content to the wiki. We're here to think along and help.

== Creating and editing pages ==
===Starting a new page===
You can create a new page from a search or from a red link. In both cases, please observe the Title Case capitalisation rule (#2) above for naming the page. '''Page names cannot be edited anymore once created!'''

''==> For more details see [[mediawikiwiki:Help:Starting_a_new_page|Help:Starting a new page.]]''
===Editing===
You can edit the contents of a page with the Visual Editor or the Source Editor. The Visual Editor provides a direct visual way to edit pages based on the "what you see is what you get" principle. It contains a handy page searching function when inserting links. Visual editing is chosen by clicking the <kbd>Edit</kbd> tab at the top of a page (or on a section-edit link). The Source Editor can be used for additional functionality with such things as categories, hyperlinks, tables and columns, footnotes, inline citation, special characters and so on. You can access the Source Editor by clicking the <kbd>Edit source</kbd> tab at the top of a page (or on a section-edit link).

''==> For more help with the editing interfaces see [[mediawikiwiki:Help:Editing_pages|Help:Editing_pages]] and the [[mediawikiwiki:Help:VisualEditor/User_guide|Visual Editor User Guide]].''

====Links====
The most relevant two types of hypertext links in this wiki are internal links to other pages in the same wiki (commonly called "wikilinks") and external links to pages at other websites.

To create a so-called internal link to a page on the same wiki (a "wikilink"), use double square brackets wiki markup, <code><nowiki>[[like this]]</nowiki></code>. When you preview or save your changes, you will see a link that can be followed to the target page. If the page exists the link is displayed in blue; if the page does not exist, the link appears red (so the <code><nowiki>[[like this]]</nowiki></code> link is actually rendered [[like this]]). Following such a "redlink" to a missing page (whether or not it is actually red) will enable you to create the page.

To markup any arbitrary string of text (not necessarily a page title) as a link, use a "vertical bar" or "pipe" character, like this: <code><nowiki>[[Main Page|our project]]</nowiki></code> results in the link [[Main Page|our project]].

The first letter of the link target is usually not case-sensitive, meaning links can be capitalized or not (so How to contribute and how to contribute are equivalent). However, the case of every ''subsequent'' letter must match the target page exactly (so How to contribute and How To Contribute are ''not'' equivalent). Spaces in the page title may be represented as underscores (so How to contribute and How_to_contribute are again equivalent), but using underscores in links will make them visible in the page text (but this can be prevented by using a "pipe"). Please refer to '''rule #2''' above when naming pages to prevent creating duplicates.

If the page title you are linking to is that of the page you are editing, the result is not a hyperlink at all but simply bold text (for example, on this page the markup <code><nowiki>[[Getting started]]</nowiki></code> gives the result [[Getting started]]). If you're trying to create a wikilink to the current page, you probably want to link to a specific ''section'' or to an ''anchor'' within the page. You do that by adding a "#" before the section name: <code><nowiki>[[#Ground rules]]</nowiki></code> will lead to the [[#Ground rules]] section.

Please note that links open by default in the same browser tab.

''==> For more details see [[mediawikiwiki:Help:Links|Help:Links]]''.

====Formatting====

Formatting text to bold, italic, bulleted or numbered lists, tables etc. is most easily done in the Visual Editor.

If you prefer to use the Source Editor, you can format your text by using wiki markup. This consists of normal characters like asterisks, apostrophes or equal signs which have a special function in the wiki, sometimes depending on their position. For example, to format a word in italic, you include it in two pairs of apostrophes like <code><nowiki>''this''</nowiki></code>.

''==> For more details see [[mediawikiwiki:Help:Formatting|Help:Formatting]] and the [[wikipedia:Help:Cheatsheet|Wiki cheat sheet]]''.

====Sections====
A page can and should be divided into sections, using the section heading syntax. For each page with more than three section headings, a table of contents (TOC) is automatically generated.

Sections are created by creating their headings, as below.

<pre>
== Section ==
=== Subsection ===
==== Sub-subsection ====
</pre>

Please do not use only one equals sign on a side (<code><nowiki>= Heading =</nowiki></code>). This would cause a section heading to be as large as the page's name (title). The maximum number of equals signs is six. Heading names of sections (including subsections) should be unique on a page. Using the same heading more than once on a page causes problems.

Linking to a section within the same page is done with the <nowiki>[[#Section_name]]</nowiki> syntax. Linking to a section of another page on the same wiki is done by adding the "#" between the page name and the section name: <code><nowiki>[[Page_name#Section_name]]</nowiki></code>.

Section headers can be links to other pages: <code><nowiki>[[===This section also has it's own page that can be opened via this link===]]</nowiki></code>. The recommended practice is to place an excerpt, a summary or an overview of the dedicated page in the section content of the page being linked from.

==== Categories ====
In the DE4A wiki we use categories to indicate the status of a page:
{| class="wikitable"
|+Overview of DE4A wiki page categories
!Category
!Description
|-
|Wip
|Page labeled as work In progress, not yet ready for review.
|-
|Draft
|Page labelled as a draft, ready for review.
|-
|Released
|A reviewed and finished page.
|}
A category label can be added to a page by inserting <code><nowiki>[[Category:wip]]</nowiki></code> at the top of the page in the Source Editor.

A category page can be created the same way as other wiki pages; just add <code><nowiki>Category:</nowiki></code> before the page title. To avoid extra work, try searching within the wiki before creating a new category. The list of all categories can be found in the #List of pages section of the [[Special:SpecialPages#Lists of pages|Special Pages]] page.

== Uploading files ==

=== Files ===
Files can be uploaded via the Sidebar menu (Tools > Upload File) or while using the Visual Editor (Insert function). Files can be max 2MB in size and permitted file types are png, gif, jpg, jpeg, webp. Other files can be referenced via external links. Appropriate attention should be paid at all times to copyright and confidentiality considerations.

===Images===

The DE4A wiki includes an extension that makes it possible to display clickable image maps. An image map is a list of coordinates in a specific image, which hyperlinks areas of the image to multiple destinations (in contrast to a normal image link, in which the entire area of the image links to a single destination). For example, an application collaboration diagram may have each component or service hyperlinked to further information about that component or service. The intention of an image map is to provide an easy way of linking various parts of an image without dividing the image into separate image files.

== Special pages ==
Special pages are pages generated by the wiki software on demand for special purposes, usually related to project maintenance. They can be found in the Tools section of the Sidebar (located on the left side of every page). Useful DE4A wiki special pages include:

* [[Special:AllPages|All pages]]
* [[Special:ListFiles|Files]]
* [[Special:WantedPages|Wanted pages (red links)]]

Getting started

2021-04-13T09:32:18Z

Ictu test: /* Starting a new page */

[[Category:wip]]
Welcome, new editor of the DE4A documentation wiki!

Before you beging adding content, you can familiarise yourself in on this page with some basic wiki rules and functionalities. All the tips and instructions listed below are also applied on this page, so feel free to copy syntax from the page source as needed.

''==> Additional help is available in the [[wikipedia:Help:Cheatsheet|Wiki cheat sheet]], the [[mediawikiwiki:Special:MyLanguage/Help:Contents|User's Guide]], and the [[mediawikiwiki:Special:MyLanguage/Manual:FAQ|MediaWiki FAQ]].''

==Ground rules==
'''#1 Create from search.''' When you want to create a new page, start by searching the wiki for existing content. If the search yields no results, you will be offered the option to create a new page. If you do, make sure your search was capitalised in Title Case.

'''#2 Page names in Title Case.''' Page names are capitalised using Wikipedia rules. When in doubt, use this [https://titlecaseconverter.com/|Title Case Converter] tool to find the correct capitalisation. Different letter cases produce different wiki pages. For example, "[[Interaction Patterns]]" and "[[Interaction patterns]]" will lead to two different pages (the former exists on the DE4A wiki, the latter does not and should not, as it does not follow the Title Case capitalisation rule).

'''#3 Ask for help.''' Don't hesitate to contact the [https://wiki.de4a.eu/index.php/Special:ActiveUsers?username=&groups%5B%5D=interface-admin&wpFormIdentifier=specialactiveusers|DE4A WP2 Team] for advice and support when or before adding your content to the wiki. We're here to think along and help.

== Creating and editing pages ==
===Starting a new page===
You can create a new page from a search or from a red link. In both cases, please observe the Title Case capitalisation rule (#2) above for naming the page. '''Page names cannot be edited anymore once created!'''

''==> For more details see [[mediawikiwiki:Help:Starting_a_new_page|Help:Starting a new page.]]''
===Editing===
You can edit a page with the Visual Editor or the Source Editor. The Visual Editor provides a direct visual way to edit pages based on the "what you see is what you get" principle. It contains a handy page searching function when inserting links. Visual editing is chosen by clicking the <kbd>Edit</kbd> tab at the top of a page (or on a section-edit link). The Source Editor can be used for additional functionality with such things as categories, hyperlinks, tables and columns, footnotes, inline citation, special characters and so on. You can access the Source Editor by clicking the <kbd>Edit source</kbd> tab at the top of a page (or on a section-edit link).

''==> For more help with the editing interfaces see [[mediawikiwiki:Help:Editing_pages|Help:Editing_pages]] and the [[mediawikiwiki:Help:VisualEditor/User_guide|Visual Editor User Guide]].''

====Links====
The most relevant two types of hypertext links in this wiki are internal links to other pages in the same wiki (commonly called "wikilinks") and external links to pages at other websites.

To create a so-called internal link to a page on the same wiki (a "wikilink"), use double square brackets wiki markup, <code><nowiki>[[like this]]</nowiki></code>. When you preview or save your changes, you will see a link that can be followed to the target page. If the page exists the link is displayed in blue; if the page does not exist, the link appears red (so the <code><nowiki>[[like this]]</nowiki></code> link is actually rendered [[like this]]). Following such a "redlink" to a missing page (whether or not it is actually red) will enable you to create the page.

To markup any arbitrary string of text (not necessarily a page title) as a link, use a "vertical bar" or "pipe" character, like this: <code><nowiki>[[Main Page|our project]]</nowiki></code> results in the link [[Main Page|our project]].

The first letter of the link target is usually not case-sensitive, meaning links can be capitalized or not (so How to contribute and how to contribute are equivalent). However, the case of every ''subsequent'' letter must match the target page exactly (so How to contribute and How To Contribute are ''not'' equivalent). Spaces in the page title may be represented as underscores (so How to contribute and How_to_contribute are again equivalent), but using underscores in links will make them visible in the page text (but this can be prevented by using a "pipe"). Please refer to '''rule #2''' above when naming pages to prevent creating duplicates.

If the page title you are linking to is that of the page you are editing, the result is not a hyperlink at all but simply bold text (for example, on this page the markup <code><nowiki>[[Getting started]]</nowiki></code> gives the result [[Getting started]]). If you're trying to create a wikilink to the current page, you probably want to link to a specific ''section'' or to an ''anchor'' within the page. You do that by adding a "#" before the section name: <code><nowiki>[[#Ground rules]]</nowiki></code> will lead to the [[#Ground rules]] section.

Please note that links open by default in the same browser tab.

''==> For more details see [[mediawikiwiki:Help:Links|Help:Links]]''.

====Formatting====

Formatting text to bold, italic, bulleted or numbered lists, tables etc. is most easily done in the Visual Editor.

If you prefer to use the Source Editor, you can format your text by using wiki markup. This consists of normal characters like asterisks, apostrophes or equal signs which have a special function in the wiki, sometimes depending on their position. For example, to format a word in italic, you include it in two pairs of apostrophes like <code><nowiki>''this''</nowiki></code>.

''==> For more details see [[mediawikiwiki:Help:Formatting|Help:Formatting]] and the [[wikipedia:Help:Cheatsheet|Wiki cheat sheet]]''.

====Sections====
A page can and should be divided into sections, using the section heading syntax. For each page with more than three section headings, a table of contents (TOC) is automatically generated.

Sections are created by creating their headings, as below.

<pre>
== Section ==
=== Subsection ===
==== Sub-subsection ====
</pre>

Please do not use only one equals sign on a side (<code><nowiki>= Heading =</nowiki></code>). This would cause a section heading to be as large as the page's name (title). The maximum number of equals signs is six. Heading names of sections (including subsections) should be unique on a page. Using the same heading more than once on a page causes problems.

Linking to a section within the same page is done with the <nowiki>[[#Section_name]]</nowiki> syntax. Linking to a section of another page on the same wiki is done by adding the "#" between the page name and the section name: <code><nowiki>[[Page_name#Section_name]]</nowiki></code>.

Section headers can be links to other pages: <code><nowiki>[[===This section also has it's own page that can be opened via this link===]]</nowiki></code>. The recommended practice is to place an excerpt, a summary or an overview of the dedicated page in the section content of the page being linked from.

==== Categories ====
In the DE4A wiki we use categories to indicate the status of a page:
{| class="wikitable"
|+Overview of DE4A wiki page categories
!Category
!Description
|-
|Wip
|Page labeled as work In progress, not yet ready for review.
|-
|Draft
|Page labelled as a draft, ready for review.
|-
|Released
|A reviewed and finished page.
|}
A category label can be added to a page by inserting <code><nowiki>[[Category:wip]]</nowiki></code> at the top of the page in the Source Editor.

A category page can be created the same way as other wiki pages; just add <code><nowiki>Category:</nowiki></code> before the page title. To avoid extra work, try searching within the wiki before creating a new category. The list of all categories can be found in the #List of pages section of the [[Special:SpecialPages#Lists of pages|Special Pages]] page.

== Uploading files ==

=== Files ===
Files can be uploaded via the Sidebar menu (Tools > Upload File) or while using the Visual Editor (Insert function). Files can be max 2MB in size and permitted file types are png, gif, jpg, jpeg, webp. Other files can be referenced via external links. Appropriate attention should be paid at all times to copyright and confidentiality considerations.

===Images===

The DE4A wiki includes an extension that makes it possible to display clickable image maps. An image map is a list of coordinates in a specific image, which hyperlinks areas of the image to multiple destinations (in contrast to a normal image link, in which the entire area of the image links to a single destination). For example, an application collaboration diagram may have each component or service hyperlinked to further information about that component or service. The intention of an image map is to provide an easy way of linking various parts of an image without dividing the image into separate image files.

== Special pages ==
Special pages are pages generated by the wiki software on demand for special purposes, usually related to project maintenance. They can be found in the Tools section of the Sidebar (located on the left side of every page). Useful DE4A wiki special pages include:

* [[Special:AllPages|All pages]]
* [[Special:ListFiles|Files]]
* [[Special:WantedPages|Wanted pages (red links)]]