Modify configuration of Alfabet REST API v2

The connection between ARIS and Alfabet is established by ARIS database attributes. The Alfabet REST API v2 interface is configured using the ARIS-ALFABET-mappingV2.xml configuration file and related Alfabet reports.

This file defines the general mapping for models, connections, and assignments. It handles the data transfer between ARIS and Alfabet using Alfabet RESTful API v2. Generally, Alfabet objects are mapped to ARIS objects. Alfabet object classes are mapped using the class name XML property. The import of all or single objects of an Alfabet object class is performed using the following import definition.

In contrast to Alfabet RESTful API v1 where two configuration files are required (ARIS-ALFABET-mapping.xml and ARIS-ALFABET-integration.xml), Alfabet RESTful API v2 uses only the ARIS-ALFABET-mappingV2.xml file and related Alfabet reports. In contrast to the ARIS-ALFABET-mapping.xml file, the ARIS-ALFABET-mappingV2.xml file contains only the Alfabet object classes and properties that will actually be imported. The file also contains mapping information and mapping usage for single-object mapping or bulk mapping.

For the <mapping> root element, the version property is specified with the value 2.

In the ARIS-ALFABET-mappingV2.xml file, the <table> element is replaced by <class>. The class and property names are no longer the table and table column names but the Alfabet object class and property names. The <psutable> and <psmtable> elements are also replaced by <class>. For PSU/PSM import, you must specify the attribute import-target="psu" or import-target="psm".

Example

<mapping version="2">

<class name="Application" import="both"> report="DataImportIntoARIS_Applications" arisgroupname="Applications" isgroup="true" aristype="ST_APPL_SYS_TYPE" overview-model="MT_APPL_SYS_TYPE_DGM,ST_APPL_SYS_TYPE" condition="Stereotype">

name

Alfabet object class name, for example, Application.

import

Specifies the kind of import for each <class>.

You can set either single-object import, bulk import, or both.

report

Alfabet report to request objects with the required and mapped data.

The reports make a set of used properties available and enable access to properties that are not defined in the current class, but that should become ARIS attributes of the imported object, such as lifecycle attributes of an Application system type object. If a referenced report is not available in Alfabet, the import log reports this issue. In this case, the import tries to fall back to the default import without using the report.

Alfabet reports supporting the default configuration are shipped with Alfabet releases 10.5p2 and later. You can adapt these reports in Alfabet or define your own reports.

arisgroupname

Name of the ARIS database group.

If specified and not empty, an ARIS database group with the specified value is created for the import of the class. All imported objects are stored in this group.

If arisgroupname is empty or not specified, no subgroup will be created.

isgroup

If true, creates a group for each imported object.

aristype

ARIS API name of the ARIS object type to be used. If an ARIS symbol type is specified here, the object type is derived from the symbol. In addition, the default symbol of the imported item is set to this symbol type.

overview-model

Creates an overview model of the specified type and places an occurrence of each class object that meets this condition in the model.

<filter property="ObjectState" value="Active" import="object"/>

filter

Filters on property values.

Filter conditions, such as mapping applications with property ObjectState = "Active", should be defined within the Alfabet report if possible.

If you use the <filter> element you can apply further filtering on ARIS side.

Filters are defined by the following properties:

  • property: the property providing the value for filtering.

  • value: the value of the property for allowed items.

  • import: import type where to apply the filter. Can be "object", "bulk", or "both" ("" is interpreted as "both").

property

Alfabet class property name, for example, ObjectState.

Value

Value of the property which marks objects that are supposed to be imported.

In this example, the ObjectState property value is Active.

import

Import type where to apply the filter. Values can be "object", "bulk", or "both" ("" is interpreted as "both").

<!-- Conditions for classifying objects -->

<condition value="BOT" arisgroupname="BOTs" aristype="ST_APPL_SYS_TYPE" overview-model="MT_APPL_SYS_TYPE_DGM,ST_APPL_SYS_TYPE"/>

condition

Defines a conditional mapping based on a property's value. The example above shows a mapping that is based on the Stereotype property. If the value is specified and corresponds to one of the values listed as a value in the condition elements below, it is mapped according to what the condition element defines, and NOT according to what the class element defines.

value

Property value specifying that this condition is to be applied.

arisgroupname

Optionally overwrites the default group name of the class element for items meeting this condition.

aristype

ARIS API name of the ARIS object type to be used. If an ARIS symbol type is specified here, the object type is derived from the symbol. In addition, the default symbol of the imported item is set to this symbol type.

overview-model

Creates an overview model of the specified type and places an occurrence of each class object that meets this condition in the model.

<condition value="TradingPartner" arisgroupname="Trading Partners" aristype="ST_APPL_SYS_TYPE" overview-model="MT_APPL_SYS_TYPE_DGM,ST_APPL_SYS_TYPE"/

<!-- Attribute mappings -->

<attr alfabet="Name" aris="AT_NAME"/>

alfabet

Name of the Alfabet property.

aris XML property

API name of the ARIS attribute.

An empty string (""): not mapped/ignored.

<attr alfabet="Version" aris="AT_REL_3"/>

<attr alfabet="Description" aris="AT_DESC"/>

<attr alfabet="ID" aris="AT_ID"/>

<attr alfabet="ObjectState" aris="AT_REM"/>

<attr alfabet="Evaluation_StartDate" aris="AT_EVALUATION_START"/>

<attr alfabet="Evaluation_EndDate" aris="AT_EVALUATION_END"/>

<attr alfabet="Pilot_StartDate" aris="AT_TO_BE_PHASED_IN_START"/>

<attr alfabet="Pilot_EndDate" aris="AT_TO_BE_PHASED_IN_END"/>

<attr alfabet="Production_StartDate" aris="AT_STANDARD_START"/>

<attr alfabet="Production_EndDate" aris="AT_STANDARD_END"/>

<attr alfabet="LimitedProduction_StartDate" aris="AT_LIMITED_STANDARD_START"/>

<attr alfabet="LimitedProduction_EndDate" aris="AT_LIMITED_STANDARD_END"/>

<attr alfabet="ShutDown_StartDate" aris="AT_TO_BE_PHASED_OUT_START"/>

<attr alfabet="ShutDown_EndDate" aris="AT_TO_BE_PHASED_OUT_END"/>

<!-- Connection mappings -->

<cxn property="NextVersiob" cxntype="CT_IS_PRED_OF" srctotarget="true" forceexist="true">

property XML property

Name of the Alfabet property. The property must be of the Reference or ReferenceArray type.

For more information, refer to the Documentation of the Alfabet Meta-Model (Alfabet reference manual).

cxntype

API name of the ARIS connection type.

Empty string (""): not mapped/ignored.

Value="-1": do not create a connection. Is allowed only if an assignment definition is available as a subelement.

srctotarget

Defines the direction of a connection.

Value true:

From class element to referenced element.

Value false:

From referenced element to class element.

forceexist

Specifies whether or not the import forces the target/source object of a referenced object to exist in the database. If the value is set to true, the target/source object will be created using the mapping definition of the referenced object. Only if the target/source object exists will a connection be imported. Whether the target object or the source object must exist depends on the value specified in the srctotarge XML property

The default value is false.

<assign type="all" model="MT_APPL_SYST_TYPE_DGN" add-parent="true" parent-symbol="ST_APPL_SYS_TYPE" child-symbol="ST_APPL_SYST_TYPE"/>

assign

Creates an assignment to a model either in addition to a connection, instead of a connection, or to a model if the referenced item is a model derived from an additional Alfabet object class.

type

Creates one assigned model per imported object. Cannot be used as class subordinate element.

model

API name for the model type of the ARIS model to be assigned, for example, MT_APPL_SYS_TYPE_DGM.

add-parent

Adds an occurrence of the superior object to the assigned model.

The default setting is false.

If you change it to true, an occurrence of the superior object will be added to the assigned model. Therefore, the parent-symbol attribute is mandatory.

parent-symbol

API name for the symbol type of the superior ARIS object used in the assigned model, for example, ST_APPL_SYS_TYPE.

Required only if the add-parent attribute is set to true.

child-symbol

API name for the symbol type of the ARIS object used in the assigned model, for example, ST_APPL_SYST_TYPE.

Not used if the referenced element is the model itself.

</cxn>

<cxn property="Domain" cxntype="CT_CAN_SUPP_1" srctotarget="true" forceexist="true">

<assign type="all" model="MT_APPL_SYS_TYPE_DGM" add-parent="true" parent-symbol="ST_APPL_SYS_TYPE" child-symbol="ST_IS_FUNC" />

</cxn>

<!-- Link for navigation to Alfabet -->

<link attribute="AT_ALFA_LINK_1" title="AT_ALFA_NAVI1" defaultvalue="Navigate to Application in Alfabet" >

link

Creates ARIS link attributes as a reference between ARIS and Alfabet.

attribute

API name for the attribute type of the ARIS link attribute to be used for navigating to the Alfabet object. By default, the Alfabet Link 1 (AT_ALFA_LINK_1) attribute type will be used for saving the URL to the Alfabet object.

title

API name for the attribute type of the ARIS link title attribute to be used. By default, the Alfabet Navigation 1 attribute type will be used for storing the link's title text.

This text is entered in the defaultvalue XML property. It is displayed for all languages that are not explicitly specified in the title locale XML property. The title is write protected in ARIS and is entered during the mapping to Alfabet or the ARIS - Alfabet synchronization report.

defaultvalue

Non-localized default text for the link's title text.

This text is displayed for all languages that are not explicitly specified in the title locale XML property. The title is write protected in ARIS and is entered during the mapping to Alfabet or the ARIS-Alfabet synchronization report.

<title locale="1033" value="Navigate to Application in Alfabet" />

locale

Locale ID (LCID) of the language in which the link title is transferred.

By default, the data is transferred in English (1033). If you have logged into the ARIS database in another language, for example, German, the values are written to the German attributes in English.

value

Localized title text.

</link>

<!-- Configuration of dialog for single-object mapping -->

<dialog-columns>

dialog-columns

Defines the Alfabet object class to be available in the Select Alfabet object dialog.

In this example, the Application Alfabet object class is the source. All Alfabet objects of this class will be displayed.

<column alfabet="Version"/>

column alfabet

Defines columns and content to be displayed in the Select Alfabet object dialog.

In this example Version is the property name to be used as column title. All values of this property will be displayed in this column. Version refers to the attr subordinate element of the Application Alfabet object class, which is listed in the configuration file. You can use all other properties mapped via the attr subordinate element.

<newlink url="ExternalAccess.aspx?AccessType=ExternalAccess&UserType=Named&View=GraphicView:APP_CaptureApplications_Ex"/>

newlink url

Defines the link to Alfabet for creating new Alfabet objects. This Create Alfabet object link is available in the Select Alfabet object dialog.

Do not change this value:

"ExternalAccess.aspx?AccessType=ExternalAccess&amp;UserType=Named&amp;View=GraphicView:APP_CaptureApplications_Ex"

The value represents the static part of the link. The link will be assembled using this and the User interface URL value that you have specified when you connected the ARIS database to the Alfabet system.

</dialog-columns>

</class>

<class name="Domain" report="DataImportIntoARIS_Domains" import="bulk" linkarisonly="true" check-master="ARIS_GUID" aristype="OT_FUNC_CLUSTER">

linkarisonly

Affects items sourced from ARIS. These Alfabet objects have an ARIS GUID.

The default value is false.

If the value is true, links are created for ARIS items that still exist in the ARIS database, but neither items nor attributes are imported. The check-master table attribute is mandatory.

check-master

Checks for the existence of the provided Alfabet attribute, and searches the ARIS database for an object with this GUID. If available, the ARIS object is identified and used as the master instead of the Alfabet object, for example,

check-master="ARIS_GUID"

The attributes and properties of the master object are not overwritten by the import and a master is not removed if theobject has been deleted in Alfabet.

<link attribute="AT_ALFA_LINK_1" title="AT_ALFA_NAVI1" defaultvalue="Navigate to Domain in Alfabet">

<title locale="1033" value="Navigate to Domain in Alfabet"/>

</link>

</class>

...other & referenced classes

</mapping>

This file defines the general mapping for models, connections, and assignments. It handles the data transfer between ARIS and Alfabet using Alfabet RESTful API v2. Script administrators can adapt this file.

Alfabet interoperability is available for objects of the Application system type type by default. Objects can be mapped to Alfabet objects of the Application Alfabet object class. If you want to define other ARIS object types or Alfabet object classes, you must:

Adapt the related reports

Alfabet reports supporting the default configuration are shipped with Alfabet releases 10.5p2 and later. You can adapt these reports in Alfabet or define your own reports.

The report reduces the amount of data transferred from Alfabet to ARIS. The reports make a set of used properties available and enable access to properties that are not defined in the current class, but that should become ARIS attributes of the imported object, such as lifecycle attributes of an Application system type object. If a referenced report is not available in Alfabet, the import log reports this issue. In this case, the import tries to fall back to the default import without using the report.

Further information on the interface and on how to configure the data exchange is available in the related manual. The Alfabet reference manual of the ARIS - Alfabet Interoperability Interface can be found on the Alfabet installation media. You can also download it from Empower.

Adapt the ARIS-ALFABET-mappingV2.xml configuration file

Warning

After a program update all changes made to standard scripts and files are lost. If you adapt a duplicated file, the file will not be affected by the program update. Original XML files are overwritten and updated. After an update you must copy the adapted lines into the new XML file.

ARIS is supplied with numerous standard scripts. We generally recommend documenting all changes to scripts externally so that the documentation can be used to ensure that they are incorporated correctly during the update process.

Reports/Macros/Report templates and files

Do not make any changes to the standard scripts we supply. Always adapt copies of report, macro, and JS files, and any other files. There are exceptions, for example, the file atsall<language code>.js.

When updating ARIS, all ARIS standard scripts and files are overwritten and customer-specific changes to these files are discarded. Copied scripts and files and those you have created yourself are not overwritten.

If you have changed files we supplied but not copied them, before the update (updatesystemdb) they must be exported and then imported after the update. This enables you to retain your adapted standard scripts from the previous version. However, in this case you do not receive any corrections or updates to the files we supplied.

Semantic checks

We recommend creating custom rule types and custom profiles for semantic checks, in which the ARIS standard rule types and rules are referenced.

This is not possible for configurable rule types (relationship attribute rules, model attribute rules, object attribute rules, existence rules, and allocation rules). If you have added rules to these rule types, you must export the rule types before the update and then import them after the update.

Prerequisite

Procedure

  1. In ARIS Architect, click ARIS > Show Administration Administration.

  2. Click the group Evaluations > Reports in the Navigation bar.

  3. Open the IT Architecture category.

  4. Double-click the file ARIS-ALFABET-mappingV2.xml. The file opens in Script Editor.

  5. Add further entries or change entries related to the modifications made in the report, as required.

  6. Save the changes and close the file.

  7. Export the ARIS-ALFABET-mappingV2.xml file to a backup directory. After a program update, you can import the file to restore your modified configuration.

The configuration file is adapted.