ARISREPOSITORY APITECHNICAL INTRODUCTION

VERSION 10.0 - SERVICE RELEASE 16
OCTOBER 2021

This document applies to ARIS Version 10.0 and to all subsequent releases.
Specifications contained herein are subject to change and these changes will be reported insubsequent release notes or new editions.
Copyright © 2010 - 2021 Software AG, Darmstadt, Germany and/or Software AG USA Inc.,
Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.
The name Software AG and all Software AG product names are either trademarks orregistered trademarks of Software AG and/or Software AG USA Inc. and/or its subsidiaries
and/or its affiliates and/or their licensors. Other company and product names mentioned
herein may be trademarks of their respective owners.
Detailed information on trademarks and patents owned by Software AG and/or its
subsidiaries is located at https://softwareag.com/licenses.
Use of this software is subject to adherence to Software AG's licensing conditions and terms.
These terms are part of the product documentation, located athttps://softwareag.com/licenses and/or in the root installation directory of the licensed
product(s).
This software may include portions of third-party products. For third-party copyright notices,license terms, additional rights or restrictions, please refer to "License Texts, Copyright
Notices and Disclaimers of Third Party Products". For certain specific third-party license
restrictions, please refer to section E of the Legal Notices available under "License Terms andConditions for Use of Software AG Products / Copyright and Trademark Notices of Software
AG Products". These documents are part of the product documentation, located athttps://softwareag.com/licenses and/or in the root installation directory of the licensed
product(s).

REPOSITORY API TECHNICAL INTRODUCTION

Contents
1

Introduction ............................................................................................................................................. 1

2

General principles .................................................................................................................................. 2

3

Login/Logout .......................................................................................................................................... 3
3.1
3.2

Obtaining a UMC session token ............................................................................................. 3
Releasing a UMC session token ............................................................................................. 54

Get information about ARIS methodology ....................................................................................... 65

Get information on available databases ........................................................................................... 86

API Docs ComparePair ........................................................................................................................ 10
6.1
6.2
6.3
6.4

Get a list of database comparison pairs ............................................................................ 10
Create a database comparison pair .................................................................................... 12
Toggle the enable state of a database comparison pair ................................................ 14
Delete a database comparison pair .................................................................................... 15

7

Get an item ............................................................................................................................................. 17

8

Get group children ............................................................................................................................... 19

9

Get content of a model ....................................................................................................................... 20

10 Create an item ...................................................................................................................................... 22
11

Create model content ......................................................................................................................... 24

12 Delete model content ......................................................................................................................... 26
13 Attributes .............................................................................................................................................. 27
13.1
13.2
13.3
13.4
13.5

Retrieval .................................................................................................................................... 27
Creation..................................................................................................................................... 28
Updating or creation for existing item ............................................................................... 29
Deleting an attribute .............................................................................................................. 30
Styled values for text attributes ......................................................................................... 31

14 Assignments ......................................................................................................................................... 33
15 Model graphic ....................................................................................................................................... 34
16 Finding items in the database .......................................................................................................... 35
17 Paging .................................................................................................................................................... 38
18 Ordering the result ............................................................................................................................. 40
19 Generic queries .................................................................................................................................... 41
20 Legal information.................................................................................................................................44
20.1
20.2

Documentation scope............................................................................................................44
Support .....................................................................................................................................44I

REPOSITORY API TECHNICAL INTRODUCTION

1Introduction

This document provides additional information for accessing an ARIS repository via the ARISREST API. It should be considered as a supplement to the official API documentation available
on every running ARIS Connect Server and ARIS Design Server under
http://<servername:portal>/apidocs.

1

REPOSITORY API TECHNICAL INTRODUCTION

2

General principles
The ARIS RESTful APIs are designed to access an ARIS repository by apps typicallyrunning on mobile devices. It is not meant as a replacement for other ways to access an
ARIS repository, for example, the ARIS Report API. Therefore, it has various limitations
with respect to functionality that you might have expected.

Every call to the API is atomic: either the operation succeeds or fails.

Every call to the API requires a valid API cookie/token from ARIS User Management.



Many calls have obligatory and/or optional URL parameters. All parameter values must be
URL-encoded as they may contain special characters.



If URL parameters are passed that are unknown or not the correct ones for the specificmethod or misspelled, then they are silently ignored. This may lead to an unexpected
outcome of the requested operation.

Many calls require a database language as parameter. If not given, the fallback languageof the current database is used.



Many operations require an ARIS method filter GUID as parameter. If not given, a specificauto-selection mechanism chooses the right filter, like to a login on the Connect portal. It
is strongly recommended to pass the desired filter as parameter which is also much
faster.



The result objects may contain method data, for example, typename. Method data isdelivered in the language from the client’s HTTP header ("accept-language").
Alternatively, you can pass an optional URL parameter methodlanguage in order to set
the method language directly.



There is an absolute result size limit (depending on the license, typically 5,000 items).

Date parameters must be provided and are returned in UTC in the RFC 3339 Internet
format YYYY-MM-DD, and for timestamps in UTC in the RFC 3339 Internet Zulu time
format is needed YYYY-MM-DD'T'HH:MM:SS'Z', for example, 2014-01-22T08:22:55Z.

2

REPOSITORY API TECHNICAL INTRODUCTION

3

Login/Logout

For all API calls, a valid token from ARIS User Management (also known as UMC) is required.
The token must be obtained by calling a dedicated method from the UMC API. It is not allowed
to use a standard UMC token obtained by logging in to the Connect portal.
The token must be included in all subsequent API calls as URL parameter (umcsession) or
added as cookie to the HTTP request.

3.1

Obtaining a UMC session token

The endpoint for obtaining the UMC token is:
POST
http(s)://<servername:port>/umc/api/v1/tokens

Required URL parameters are:tenant

name

password

EXAMPLE

POST
http://<servername:port>/umc/api/v1/tokens?tenant=default&name=system&pas
sword=manager
Response:{}"csrfToken": "kZcIkOV2xrD3u3M5bKy9NvzY_TriwE1KmC6k6huUWxQ","token": "eyJhbGciOiJIUzI1NisImp0aSI6FjY "Remarks

All URL parameters must be urlencoded if they contain special characters like umlauts,
non-ASCII, etc.

3

REPOSITORY API TECHNICAL INTRODUCTION

A successful invocation returns a UMC cookie in the HTTP session and in its JSON
response body the UMC token as string. For subsequent API requests you can either
provide the cookie and hand over the token as URL parameter umcsession (do not forget
to urlencode the value).



The JSON response also contains a CSRF-token. This CSRF-token must be passed as URL
parameter csrfToken (urlencoded!) in subsequent requests if the REST API is called froma web browser environment (i.e. if the user-agent provided by the client indicates abrowser like Chrome or Mozilla).



As many subsequent API calls as desired can be carried out as long as the UMC maximum
session duration limits are not exceeded. These limits can be viewed/edited in theConnect Portal Administration:

When no more API requests will be sent for some time it is strongly recommended to
explicitly "logout" again in order to release the consumed ARIS license (see next section).

4

REPOSITORY API TECHNICAL INTRODUCTION

3.2

Releasing a UMC session token

When the UMC session is no longer required, it should be explicitly invalidated, thus releasing
the consumed ARIS license. The endpoint to use is:
DELETE https://<servername:port>/umc/api/tokens/<token>

EXAMPLE

DELETE
http://<servername:port>/umc/api/tokens/eyJhbGciOiJIUzI1NisImp0aSI6FjY

5REPOSITORY API TECHNICAL INTRODUCTION

4

Get information about ARIS methodology

GET http://<servername:port>/abs/api/methodology/modeltypes
This call returns a list with all available model types.

GET http://<servername:port>/abs/api/methodology/objecttypes
This call returns a list with all available object types.

GET http://<servername:port>/abs/api/methodology/cxnbasetypes
This call returns a list with all available connection base types.

GET http://<servername:port>/abs/api/methodology/symboltypes
This call returns a list with all available symbol types.

GET http://<servername:port>/abs/api/methodology/attributetypes
This call returns a list with all available attribute types.

GET http://<servername:port>/abs/api/methodology/attributevaluetypes
This call returns a list with all available attribute value types.

The calls support four optional URL parameters: pagesize and pagetoken to control thepaging (see Paging (page 38)), methodfilter to retrieve the types which are allowed in thisfilter, methodlanguage to specify the locale of the method types (see also General principles(page 2)).

EXAMPLE WITH METHOD FILTER AND LANGUAGE
GET
http://<servername:port>/abs/api/methodology/modeltypes?methodfilter=8e386410-e0e011de-242a-f28d40dfaca6&methodlanguage=en_US

The result is a list with the method types. For each method type is returned the name, type
number, API name and GUID.

6

REPOSITORY API TECHNICAL INTRODUCTION

EXAMPLE FOR A MODEL TYPE{}

"kind": "METHODTYPE","name": "BPMN allocation diagram (BPMN 2.0)","type": 252,
"apiname": "MT_BPMN_ALLOCATION_DIAGRAM","type_guid": ""EXAMPLE FOR AN OBJECT TYPE{}

"kind": "METHODTYPE","name": "Function","type": 22,"apiname": "OT_FUNC","type_guid": ""7

REPOSITORY API TECHNICAL INTRODUCTION

5

Get information on available databases

GET
http://<servername:port>/abs/api/databases?language=en&attributes=all
This call returns a list of all available databases for the current user. It is the same list that auser would see when opening ARIS Architect.
For each database, its name, main group GUID, and some interesting flags are returned. It isalso possible to retrieve the maintained attributes by using the URL parameter attributes.
You can find more about attributes in section Retrieval (page 27).

EXAMPLE FOR DATABASE ITEM{
"kind": "DATABASE","name": "United Motor Group","isversioned": true,"maingroup_guid": "4a713de0-5d02-11e3-0fda-fd81e986d7e2"}

Note: A license of type ARIS API Full Access, ARIS API System Access, ARIS API Read
Access or a sufficient ARIS product license is required for this operation.

GET
http://<servername:port>/abs/api/databases/United%20Motor%20Group?languag
e=en&attributes=all
This call returns more detailed information for the given database name: main-group GUID,
isversioned flag and ispublished flag, all maintained attributes in database language EN aswell as a list of all allowed method filters and database languages. Exactly one databaselanguage will have the flag isalternative = true which means that it will be used as the
fallback database language if a request does not pass the URL parameter language.
In case of a versionable database, the existing change lists are returned as well.

EXAMPLE FOR METHOD FILTER ITEM{
"kind": "METHODFILTER","guid": "dd838074-ac29-11d4-85b8-00005a4053ff","name": "Entire method","description": "All method content is available."}

8

REPOSITORY API TECHNICAL INTRODUCTION

EXAMPLE FOR DATABASE LANGUAGE ITEM{
"kind": "DBLANGUAGE","language": "en_US","isalternative": true}
EXAMPLE FOR CHANGELIST ITEM{
"kind": "CHANGELIST","changelist_number": 1,"user": "internal","description": "initial revision after restore from basic archive file.","submit_time": "2015-04-07T16:11:13Z"}

9

REPOSITORY API TECHNICAL INTRODUCTION

6

API Docs ComparePair

Note: The ComparePair feature is not part of the ARIS Repository REST API but is related to
CONNECT Portal Functionality. It is included here for convenience.

6.1

Get a list of database comparison pairs

GET/publishing/databaseComparePair

http://<servername:port>/abs/publishing/databaseComparePair

This call returns a list of all available database pairs.
EXAMPLE[]{"name": "A","user": null,"description": null,"sourceDatabaseName": "test_mv","sourceVersion": 1,"targetDatabaseName": "test_mv","targetVersion": 2,"enabled": true}

GET
/api/databaseComparePair(dbPairName)
http://<servername:port>/abs/publishing/databaseComparePair/A

Parameter
dbPairName = A// Name of the database pair

Gets a database pair for comparison by its name.
This call returns a single database pair if one is found.
The information detail is exactly the same as in get databaseComparePair.
No new information is provided.

10

REPOSITORY API TECHNICAL INTRODUCTION

EXAMPLE{"kind": "RESULT","request": "abs#getDatabaseComparePair","status": "OK","item_count": 1,"items": [ {"kind": "DATABASE","name": "A","user": null,"description": null,"sourceName": "test_mv","sourceVersion": 1,"targetName": "test_mv","targetVersion": 2,"enabled": false
} ]
}

11

REPOSITORY API TECHNICAL INTRODUCTION

6.2

Create a database comparison pairPOST
/api/databaseComparePair
http://<servername:port>/databaseComparePair?name=A&user=test&description=test%20de
scription&sourceDatabaseName=United%20Motor%20Group&sourceVersion=1&targetName=
United%20Motor%20Group&targetVersion=2

Parameter
databasePairName
user
description
sourceDatabaseNamesourceVersion
targetDatabaseNametargetVersion
enabled//Name of the database pair//Name of the responsible user
= ""//Description of the pair
= Test_mv //Name of the source database= 1//Version of the source database= Test_mv //Name of the target database= 2//Version of the target database= true//Enable the database pair

= ""

= A

This call returns a list of a newly created database pair.
For each pair a name, a short description, and the responsible user can be saved.
The unique name of the database pair is required.
The source database must be unique. The target database can be referenced in several pairs.
For source and target, the database and version must exist, but the databases do not need tobe published.
The versions do not have to be different either, but if the source and the target database are
the same, they can be exchanged.
Database pairs with the same name or the same source database overwrite older ones.

12

REPOSITORY API TECHNICAL INTRODUCTION

EXAMPLE{"kind": "RESULT","request": "abs#createDatabaseComparePair","status": "OK","item_count": 1,"items": [ {"kind": "DATABASE","name": "A","user": "","description": "","sourceName": "test_mv","sourceVersion": 1,"targetName": "test_mv","targetVersion": 2,"enabled": true
} ]
}

13

REPOSITORY API TECHNICAL INTRODUCTION

6.3

Toggle the enable state of a database comparison pair

PATCH
http://<servername:port>//abs/api/databaseComparePair/A

Parameter
dbPairName = A//Name of the database pairThis call returns the updated database pair.
This method toggles the enabled value of the database pair and is a simple way to change thestate in the background.

EXAMPLE{"kind": "RESULT","request": "abs#createDatabaseComparePair","status": "OK","item_count": 1,"items": [ {"kind": "DATABASE","name": "A","user": null,"description": null,"sourceName": "test_mv","sourceVersion": 1,"targetName": "test_mv","targetVersion": 2,"enabled": true
} ]
}

14

REPOSITORY API TECHNICAL INTRODUCTION

6.4

Delete a database comparison pair

DELETE/api/databaseComparePair
http://<servername:port>/abs/api/databaseComparePair

Parameter
sourceDatabaseNamesourceVersion
targetDatabaseNametargetVersion= test_mv= 1= test_mv= 2//Name of the source database//Version of the source database//Name of the target database//Version of the target database

http://<servername:port>/abs/api/databaseComparePair?sourceDatabaseName=test_mv&s
ourceVersion=1&targetName=test_mv&targetVersion=2

EXAMPLE{"kind": "RESULT","request": "abs#deleteDatabaseComparePair","status": "OK","item_count": 0,"items": []}This call returns null if everything is correct. Otherwise, all errors will be returned. The given
parameter searches and deletes all pairs. If the databases are the same, source and target areexchangeable. All found database pairs are deleted even if it should just be one in the firstplace.

DELETE/api/databaseComparePair/{dbPairName}
http://<servername:port>/abs/publishing/databaseComparePair/A

15

REPOSITORY API TECHNICAL INTRODUCTION

Parameter
databasePairName = A//Name of the database pair

Deletes a database pair with the pair name. Only one database name is required for this call.
This call returns null if everything is correct. Otherwise, all errors are returned. The given
parameter searches and deletes all pairs.

EXAMPLE{"kind": "RESULT","request": "abs#deleteDatabaseComparePair","status": "OK","item_count": 0,"items": []}16

REPOSITORY API TECHNICAL INTRODUCTION

7

Get an item

The ARIS API offers to retrieve groups, objects (definitions) and models. The desired item
must be identified by its ARIS GUID or a full CONNECT item-id (for example, c.process.United
Motor Group.CibrcP1SEdsnKQALzQzOTg.-1).
Identifying via group path + name is unsupported as this is possibly ambiguous.
EXAMPLE
GET
http://<servername:port>/abs/api/groups/United%20Motor%20Group/1191ae90-0
2f7-11dc-2729-000bcd0cce4e
By default, only the name attribute (AT_NAME) is included in the response. If you need more
attributes, the URL parameter attributes must be given. Possible values areall: all non-empty attributes

a comma-separated list of attribute type numbers, API names or type-GUIDs (all of thesecan be arbitrarily mixed)
Example: attributes = 1, AT_DESC, AT_AUTH// attribute name, description, author

Remarks
Connections are not supported.

Note: It is also possible to retrieve HTTP portal links that can be directly used in the browser
to access the item via the CONNECT portal. Add URL parameter withportallinks = true.

PORTAL LINK EXAMPLES (FOR A MODEL){"kind": "LINK","method": "GET","href": "http://<servername:port>/#default/item/c.process.United Motor
Group.CibrcP1SEdsnKQALzQzOTg.-1","rel": "ITEM_MODEL"// CONNECT Item View},{
"kind": "LINK","method": "GET","href": "http://<servername:port>/#default/repository/a.model.United Motor
Group.CibrcP1SEdsnKQALzQzOTg.-1","rel": "REPO_MODEL"// CONNECT Repository View},
17

REPOSITORY API TECHNICAL INTRODUCTION{"kind": "LINK","method": "GET","href": "http://<servername:port>/#default/thinclient/c.process.United
Motor Group.CibrcP1SEdsnKQALzQzOTg.-1","rel": "TC_MODEL"// CONNECT Designer View},{
"kind": "LINK","method": "GET","href": "http://<servername:port>/abs/downloadClient/aris_database.jsp?configuration=ARIS&apps
erver=myserver&database=United%20Motor%20Group&guid=0a26eb70-fd52-11db-27
29- 000bcd0cce4e&language=en_US&tenant=default","rel": "DC_MODEL"// CONNECT Download client}

18

REPOSITORY API TECHNICAL INTRODUCTION

8

Get group children

A group usually contains children, that is, subgroups as well as models and objects.

GET
http://<servername:port>/abs/api/groups/United%20Motor%20Group/4a713de0-5
d02-11e3-0fda-fd81e986d7e2/children

This call returns all subgroups of the group identified by the given GUID or CONNECT item-ID.
If you additionally need the models and/or objects in the group, you can add the URL
parameters withmodels=true or withobjects=true.

GET
http://<servername:port>/abs/api/groups/United%20Motor%20Group/4a713de0-5
d02-11e3-0fda-fd81e986d7e2/children?withmodels=true&withobjects=true
RemarkIt also possible to retrieve an entire subtree by passing the URL parameter recursive=true.

Note
There is an absolute result size limit of 5,000 items (regardless of the page size you choose
and how many paging requests are sent). If a group contains more than 5,000 children, youwill not be able to retrieve them all.
Depending on the ARIS license, other size limits may apply.

19

REPOSITORY API TECHNICAL INTRODUCTION

9Get content of a model

The content of a model consists of occurrences (= model objects, model connections). They
can be retrieved in a getModel call by passing the URL parameter withcontent=true.

GET
http://<servername:port>/abs/api/models/United%20Motor%20Group/88ba40a0-c
fb6-11e0-2556-5c260a398437?withcontent=true
Remarks
Model objects/model connections are a blend of data from the occurrence and definitionlevels. They do not contain any graphical information, such as dimension (width, height), andno coordinates of positions and connection paths.

EXAMPLE FOR MODEL OBJECT ITEM{
"kind": "MODELOBJECT","occid": "(7wLHfY8btgy:u:L+6PmFOGfzQQ4:x:L+33+c)","guid": "d734eb6f-cf14-11e0-2556-5c260a398437","link": {"kind": "LINK","method": "GET","href": "http://<servername:port>/abs/api/objects/United Motor
Group/d734eb6f-cf14-11e0-25565c260a398437?language=en_US&methodfilter=dd838074-ac29-11d4-85b800005a4053ff","rel": "OBJECT"},"type": 239,
"typename": "Strategy","apiname":"OT_STAT","symbol": 1627,"symbolname": "Tactic",
symbol_apiname": "ST_TACTIC","attributes": [{"kind": "ATTRIBUTE","id": "6S4A4i43Hh0:p:L=1=1033:1:s","typename": "Name","type": 1,"apiname": "AT_NAME","language": "en_US","value": "Reduce operational costs in Supply Chain"
}
]
}

20

REPOSITORY API TECHNICAL INTRODUCTION

EXAMPLE FOR MODEL CONNECTION ITEM{
"kind": "MODELCONNECTION","occid": "(7wLHfY8btgy:u:L+-6xMo0A_0oEz:y:L+34+c)","type": 67,"typename": "encompasses","apiname": "CT_SUBS_1","source_guid": "c7ca78b0-abcf-11e0-7ee8-5c260a398437","target_guid": "289b0560-ac64-11e0-7ee8-5c260a398437","source_link": {"kind": "LINK","method": "GET","href": "http://<servername:port>/abs/api/objects/United Motor
Group/c7ca78b0abcf-11e0-7ee8-5c260a398437?language=en_US&methodfilter=dd838074-ac29-11d
4- 85b8-00005a4053ff","rel": "OBJECT"},"target_link": {"kind": "LINK","method": "GET","href": "http://<servername:port>/abs/api/objects/United Motor
Group/289b0560-ac64-11e0-7ee85c260a398437?language=en_US&methodfilter=dd838074-ac29-11d4-85b800005a4053ff","rel": "OBJECT"},"source_occid": "(7wLHfY8btgy:u:L+-7cJgUsuG4Td:x:L+33+c)","target_occid": "(7wLHfY8btgy:u:L+-2apRUFiN0WT:x:L+33+c)"}21

REPOSITORY API TECHNICAL INTRODUCTION

10Create an item

The API offers support for creating groups and objects. For objects, groups and models, it ispossible to create attributes (or more correctly formulated in ARIS terminology: it is possible
to maintain attributes with a value). You can add multiple attributes in the same call. For all
added attributes, the same database language will be used (from URL parameter language).
Furthermore, it is possible to create an assignment relationship between an existing object
and an existing model.

Note: The creation of models is not supported.

EXAMPLE
Create a new object of type 43 (OT_ORG_UNIT) with two attributes (AT_NAME and
AT_DESC). Database language = English; parent group =4a713de0-5d02-11e3-0fda-fd81e986d7e2 (= main group)

POST
http://<servername:port>/abs/api/objects/United%20Motor%20Group?language=
en&parent=4a 713de0-5d02-11e3-0fda-fd81e986d7e2
Request body:{"kind": "OBJECT","type": 43,"attributes": [{"kind": "ATTRIBUTE","type": 1,"value": "My first OrgUnit "},{"kind": "ATTRIBUTE","type": 9,"value": "This is the long description"
}
]
}

22

REPOSITORY API TECHNICAL INTRODUCTION

Remarks
The "kind" entries in the request body are redundant and not required.
There is a slight difference in the behavior whether creating an object or a group with aduplicate name.


If you create a new group with the name X and there is already a group X in the desiredparent group, then the new group will automatically be renamed to X(1).



If you create a new object with name X and there is already an object X in the desiredparent group, then the new object has the name X, so there are two objects with thename X.

23

REPOSITORY API TECHNICAL INTRODUCTION

11

Create model content

Models cannot be created via the ARIS Repository API, but you can create model objects andmodel connections. When creating a new connection, it is possible to use objects that are
created in the same request. As they do not have an ID yet, you must define a temporary
occ-id (starting with #) and use these temporary occ-ids when defining source and target of
the new connection.
EXAMPLE
PUT
http://<servername:port>/abs/api/models/United%20Motor%20Group/42ad5380-3
d0e-11e5-6479-22000b630ca4
Request body:{"modelobjects": [{"kind": "MODELOBJECT","occid": "#1","type" : 22,"symbol": 335,
"attributes": [{"kind": "ATTRIBUTE","type": 1,"value": "new function via model update"}]},{"kind": "MODELOBJECT","occid": "#2","type" : 18,"symbol": 1,"attributes": [{"kind": "ATTRIBUTE","type": 1,"value": "new event via model update"}]}],"modelconnections": [{"kind": "MODELCONNECTION","type": 44,"source_occid": "#1","target_occid": "#2"
}
]
}
24

REPOSITORY API TECHNICAL INTRODUCTION

RemarksWhen creating objects as shown above, a new definition object is created. If you want toreuse an already existing object, provide the GUID, for example,{"kind": "MODELOBJECT","occid": "#1","guid" : "4686bd20-3d0e-11e5-6479-22000b630ca4""type" : 22,"symbol": 335}

As model objects and model connections are created without any positional information,
they will be located one above the other in the upper left corner of the model. It is
possible to enforce an automatic layout of the model when it is opened for the first timein ARIS Architect/Designer by passing the URL parameter layoutonopen=true.

Note: A user with ARIS API Mobile Access license can only create one model object or one
model connection in a single request.

25

REPOSITORY API TECHNICAL INTRODUCTION

12Delete model content

Model objects or model connections can be deleted from a model via their occ-ids. If you
delete a model object, then all affected model connections are deleted automatically (no needto include them in the request).

DELETE
http://<servername:port>/abs/api/models/United%20Motor%20Group/1672a301-3
d1411e5-6479-22000b630ca4/objects?occid=(-7O3yxAzzRgN%3Au%3AL%2B-7RaSdNnA6hr%3Ax%3AL%2B33%2Bc)
Remarks

Occ-IDs often contain special characters. It is important to ensure properly urlencodedvalues.



In the request path, make sure to have /objects or /connections at the end, otherwise
the model itself will be deleted!

Note: A user with ARIS API Mobile Access license can only delete one model object or one
model connection in a single request (automatically deleted model connections are notcounted).

26

REPOSITORY API TECHNICAL INTRODUCTION

13

Attributes

Attributes are no top-level items and are tightly bound to their parent item (database, object,group, model). You can retrieve attributes only along with its parent item to which they
belong.
Attributes can be identified by an integer type number (for example, 1), the API name (forexample, AT_NAME) or a type GUID. These type identifiers can be freely mixed in the same
request and even in the same parameter, for example, in the URL parameter attributes.
Attributes are maintained in the database language as given by the URL parameter language.
If no such parameter is given, the default language of the current database is used.

RemarksCurrently, only a limited subset of attribute types is supported, especially integer, float,
text, timestamp, time, value attributes, binary.

Binary data must be sent as BASE64 encoded string.

13.1

Retrieval

You cannot retrieve an attribute on its own. You must retrieve the parent item (for example,
an object or a model to which the attribute belongs) by using an appropriate get-request andspecifying the attribute type(s) (URL parameter attributes) you want to have in the response.
If no attribute type is given, the value of the Name attribute (AT_NAME) is returned by default(but not in case of a database).

EXAMPLES
Get the model with GUID bf2a9d60-7cb8-11dc-2729-000bcd0cce4e with all maintained
attributes.
GET
http://<servername:port>/abs/api/models/United%20Motor%20Group/bf2a9d60-7
cb8-11dc-2729-000bcd0cce4e?language=en&attributes=all
Get the model with the attributes Name (AT_NAME, type number 1), Description (AT_DESC),
and Status (AT_STATE_1). Attributes can be specified by type numbers or API names/type
GUIDs. These can be freely mixed in a comma-separated list.

27

REPOSITORY API TECHNICAL INTRODUCTION

GET
http://<servername:port>/abs/api/models/United%20Motor%20Group/bf2a9d60-7
cb8-11dc-2729-000bcd0cce4e?language=en&attributes=1,AT_DESC,AT_STATE_1
Get the details of the database United Motor Group including all maintained attributes.
GET
http://<servername:port>/abs/api/databases/United%20Motor%20Group?languag
e=en&attributes=all

13.2

Creation

You can create an attribute for all items (except databases) together with its parent in thesame request.
EXAMPLE
Create an object with the two attributes name and description.

POST
http://<servername:port>/abs/api/objects/United%20Motor%20Group?language=
en &parent=4a713de0-5d02-11e3-0fda-fd81e986d7e2
Request body:{"kind": "OBJECT","type": 43,"attributes":[{"kind": "ATTRIBUTE","type": "AT_NAME","value": "I am an OrgUnit!"},{"kind": "ATTRIBUTE","type": 9,"value": "This is the long description"
}
]
}

28

REPOSITORY API TECHNICAL INTRODUCTION

13.3

Updating or creation for existing item

If you want to add a new attribute to an already existing item or if you want to update thevalue of an existing attribute, you must do an update operation (PUT) on the parent item (notsupported for a database item).
EXAMPLE
Update the name of an existing object and add the author attribute.

PUT
http://<servername:port>/abs/api/objects/United%20Motor%20Group/b7e90c5600cf-11e2-21d1-5c260a628455?language=en
Request body:{"attributes": [{"kind": "ATTRIBUTE","type": 1,"value": "Just renamed it"},{"kind": "ATTRIBUTE","type": "AT_AUTH","value": "I am the author"
}
]
}

29

REPOSITORY API TECHNICAL INTRODUCTION

13.4

Deleting an attribute

Deleting an attribute cannot be done via an update operation on the parent item. Instead, thededicated DELETE operation must be used (not supported for a database item). The type
numbers of the attributes to be deleted must be passed via the URL parameter
typenumbers.

DELETE
http://<servername:port>/abs/api/objects/United%20Motor%20Group/b7e90c5600cf- 11e2-21d1-5c260a628455/attributes?language=en&typenumbers=AT_DESC,
AT_AUTH
Remarks

Do not forget to have /attributes at the end of the URL path, otherwise you do a DELETE
on the parent object and it is gone!

The result of a successful delete operation is simply empty with STATUS = OK, forexample,{"kind": "RESULT","request": "abs#deleteObjectAttributes","status": "OK","item_count": 0,"items": []}Note: Only one attribute can be deleted in a single request for users with an ARIS API Mobile
Access license.

30

REPOSITORY API TECHNICAL INTRODUCTION

13.5

Styled values for text attributes

In ARIS, text attributes (for example, AT_DESC) can also have a styled value. If you want toretrieve text attributes with their styled value, you must set the URL parameter
withstyledtext = true. If the text attribute has got a valid styled value, it will be returned inaddition to the standard value field.

A typical response would be as follows:{"kind": "ATTRIBUTE","id": "2Nc1glOg_LN:p:L=9=1033:1:s","typename": "Description/Definition","type": 9,"apiname": "AT_DESC","language": "en_US","styled_value":"<html><body><pstyle=\"margin-left:0;margin-bottom:0;
margin-top:0\"><b>my&#32;updated</b>&#160;description</p></body></html>","value": "my updated description"}
The styled value is HTML starting with tags <html><body>.
It is also possible to set a styled value when creating or updating an attribute. Simply pass"styled_value" with a valid HTML string.

Remarks

The URL parameter withstyledtext is not required for write operations (POST, PUT).



If a write operation (POST, PUT) contains both value and styled_value, thenstyled_value has precedence and value is basically ignored. According to standard ARIS
behavior, value will then contain a plain-text representation of the HTML fromstyled_value.

Only a basic set of HTML is supported: <b>, <i>, <u>, <strike>, <ul>, <ol>, <li>, <br>, <p>,<span>, <div>.

31

REPOSITORY API TECHNICAL INTRODUCTION

For styling information (margin, color, font-family, size), use an inline style attribute, forexample,<span style=\"font-size:48pt;\"><span style=\"font-family:Kokila;\">Hello World</span></span>Unsupported HTML tags are silently ignored (only their text content will be considered).
Make sure to correctly escape JSON special characters, for example, \n must be escaped
as \\n and " as \".

If the HTML in styled_value does not contain any real formatting, a plain text value is set,for example,<html><body><p> My name is Bond. James Bond.</p></body></html>
Result"value": "My name is Bond. James Bond.""styled_value": null32

REPOSITORY API TECHNICAL INTRODUCTION

14

Assignments

An assignment is simply a link between an existing object and an existing model. With the
ARIS Repository API, you can create and delete assignments. It is not possible to retrieve a
specific assignment; assignments are always included automatically in the response when
you retrieve an object.

EXAMPLE
Create an assignment

POST
http://<servername:port>/abs/api/objects/United Motor
Group/6aa1b167-fac0-11de-55c7-001a6b3c820f/assignment/a39aefb0-fa1c-11db2729-000bcd0cce4e
objectGUID (source of assignment)
modelGUID (target of assignment)

EXAMPLE
Delete an assignment

DELETE
http://<servername:port>/abs/api/objects/United Motor
Group/6aa1b167-fac0-11de-55c7-001a6b3c820f/assignment/a39aefb0-fa1c-11db2729-000bcd0cce4e

33

REPOSITORY API TECHNICAL INTRODUCTION

15

Model graphic

The ARIS API does not provide positional information when retrieving a model with its
contents. But it is possible to get a model graphic. It has format PNG (Portable Network
Graphics) and is returned as a BASE64-encoded string. There are two optional URL
parameters maxwidth and maxheight that allow you to control the size (in image pixels) of
the generated graphic.

EXAMPLE
GET
http://<servername:port>/abs/api/models/United%20Motor%20Group/0a26eb70-f
d52- 11db-2729-000bcd0cce4e/graphic

34

REPOSITORY API TECHNICAL INTRODUCTION

16

Finding items in the database

It is possible to search for items according to several criteria that are AND-linked, that is, they
reduce the number of matching result items. You must pass the URL parameter kind to
declare what to search (model or object). In addition, you can define the desired type (=comma-separated list of object type numbers or model type numbers; API names or type
GUIDs are also supported) and optionally a filter criterion with respect to an attribute.

EXAMPLE
Find all models of type 13 (MT_EEPC), whose names start with Sale (written with small orlarge s).

GET
http://<servername:port>/abs/api/databases/United%20Motor%20Group/find?ki
nd=MODEL&typefilter=13&language=en&attrfilter=AT_NAME=Sale
RemarksAvailable item kinds: MODEL, OBJECT, GROUP

For all attributes: + (isMaintained), - (isNotMaintained)For numbers, the usual operators are available: =, !=, >, <, >=, <=For Boolean: = and !=For text attributes: =

Note: unequal (!=) is not supported because it may lead to full-table scans in theunderlying database index.

The parameter attrfilter may contain fully parenthesized expressions (parenthesis= { }),combined with operators AND, OR.



Date values must be given in UTC in the RFC 3339 Internet format YYYY-MM-DD, forexample, 2021-10-15

Timestamp values must be given in UTC in the RFC 3339 Internet Zulu time format
YYYY-MM- DD'T'HH:MM:SS'Z', for example, 2021-10-15T08:22:55Z

35

REPOSITORY API TECHNICAL INTRODUCTION

EXAMPLES FOR TIMESTAMP QUERIESAll objects changed in a given period of time
GET
http://<servername:port>/abs/api/databases/United%20Motor%20Group/find?ki
nd=OBJECT&language=en_US&attributes=all&attrfilter={AT_LAST_CHNG_2 >=2021-10-15T00:00:00Z} AND {AT_LAST_CHNG_2 <= 2021-10-15T09:00:00Z}All objects created in a given period of time
GET
http://<servername:port>/abs/api/databases/United%20Motor%20Group/find?ki
nd=OBJECT&language=en_US&attributes=all&attrfilter={AT_CREAT_TIME_STMP>= 2021-10-15T00:00:00Z} AND {AT_CREAT_TIME_STMP <= 2021-10-15T09:00:00Z}

SEARCHING FOR TEXT: EXAMPLES FOR THE VALUE OF ATTRFILTER
AT_NAME=
Jones
9= Human Resources// (9 = AT_DESC)
AT_AUTH // (AT_AUTH not maintained){AT_NAME = Jones} AND {AT_DESC = Human Resources}{{AT_NAME = Jones} OR {AT_DESC = Human Resources}} AND {AT_AUTH -}

Important: in case of a parenthesized expression, the search value must not contain{ or }. If the search value must contain a curly parenthesis, pass an escaped character, forexample, \} when searching for text attributes.

The normal search behavior is similar to that of standard search engines: Contents of text
attributes are token-based, that is, typical separators, such as blanks or dashes (-), areignored. If the text attribute contains tokens from the search value (regardless oforder/position), this is considered a match.
Example: Search expression AT_NAME = holder certificate
will find Holder Certificate and certificate holder and the certificate holder.



URL parameter matchcase: if true, searching will be case-sensitive and order of tokens isrelevant

36

REPOSITORY API TECHNICAL INTRODUCTION

URL parameter exactsearch: if true, only exact matches are returned; special charactersand notably the asterisk ( * ) are interpreted as simple character; in addition, the order of
the tokens is important.
Example: Search expression AT_NAME = holder certificate
will find Holder Certificate but not certificate holder and not The Holder Certificate.

Special search patterns for text (parameter exactsearch must be false):A* returns all strings that start with A (A must be a string of length >=2, the first two
characters must be letters or digits).



A*B returns all strings that start with A (A must be a string of length >=2, the first two
characters must be letters or digits) and end with B.

IMPORTANT NOTE
The search functionality described above is not intended to load large amounts of data froman ARIS repository. Therefore, there is a result size limit (typically 5,000 items, depending on
the user license). This limit is absolute, that is, it is independent on the page size you choose
and how many paging requests are sent.

Example: If a search query is sent to get all models of EPC type and the database contains
10,000 such models, then only the first 5,000 hits can be retrieved (for example, by sending
50 paging requests with page size 100).
In general, a search request that leads to several thousand hits should always be refined withmore concrete search criteria.

37

REPOSITORY API TECHNICAL INTRODUCTION

17

PagingTypically, when using the database-find operation from the previous chapter, many items will
be found and returned to the caller. A default page size of 100 is in effect. A different page
size can be indicated with the URL parameter pagesize.
If there are more items to be returned than the page size allows, the response will contain an
entry next_pagetoken. This indicates to the client that there is more data to load.
EXAMPLE
Requesthttp://<servername:port>/abs/api/databases/United%20Motor%20Group/find?ki
nd=MODEL&language=en&attrfilter=AT_NAME&wildcards=true&attrcriterion==S*
Response{"kind": "RESULT","request": "abs#find","status": "OK","item_count": "100","next_pagetoken": "1:100:guid","items": […
100 items here]}
In order to get the next page of results, the client must send the same request again and add
the page token.

GET
http://<servername:port>/abs/api/databases/United%20Motor%20Group/find?ki
nd=MODEL&language=en&attrfilter=AT_NAME&wildcards=true&attrcriterion==S*&pagetoken=1:100:guidResponse{"kind": "RESULT","request": "abs#find","status": "OK","item_count": "35","items": [… remaining 35 items here]}

The second response contains no entry next_pagetoken --> the client knows that there are
no more items to load.
38

REPOSITORY API TECHNICAL INTRODUCTION

Notes


The maximum allowed page size is 500. If a page size is given that is too large, it will besilently corrected to the allowed maximum.

Regardless of paging, there is an absolute result size limit (depending on the user license,
typically 5,000 items), for example, when using page size 500, at most 10 paging requests
will return data. If the total result set is larger, it is not possible to retrieve the remainder.

39

REPOSITORY API TECHNICAL INTRODUCTION

18

Ordering the result

If more than one item is returned by a request (for example, database-find), the items areordered by their GUID in ascending order. Ordering by GUID itself is normally useful but thisensures a stable result, especially with respect to paging.

You can pass the URL parameter orderby in order to indicate a different sorting, for example,…&orderby = name (order by attribute AT_NAME, ascending)…&orderby = -name(order by attribute AT_NAME, descending)
Other possible values:

modified (ascending)-modified (descending)path (group path starting at main group)

40

REPOSITORY API TECHNICAL INTRODUCTION

19

Generic queries

Generic queries try to offer a kind of graph-based retrieval of items. The syntax andfunctionality is based on the CONNECT Portal Designer query language which is used for thecontents of fact sheets.
Starting from a defined item (object or model identified by GUID/CONNECT item-id or a type
number), it is possible to add items that can be reached from the start item via a sequence offilter items.
The general properties of an item definition are as follows:

type

MODEL, OBJECT, CONNECTION, ASSIGNMENT, OCCURRENCE,
CONNECTIONOCCURRENCE

function

FILTER, TARGET(TARGET means that objects that match this item areadded to the result)(FILTER means that this item is only used for filtering; it isthe default value and therefore optional)

direction

IN, OUT (only allowed for type CONNECTION)

typenumcomma-separated list of type numbers, api-names, type-GUIDs

Remarks

Not all possible combinations will lead to sensible results! The syntax promises more thanwhat is implemented.



Item definitions normally contain other item definitions and thus form a nested path ofitems. Within a single path, only one item of function TARGET is allowed.



Although a generic query is of read-only nature, it must be sent as a POST request
because the query definition must be provided in the request body.

41

REPOSITORY API TECHNICAL INTRODUCTION

If the start item is an object, the request URL must be … /objects/<db>/query; in case ofmodels, it is …/models/<db>/query.

The request body must contain the query itself as a nested list of query item definitions.

EXAMPLE 1 (STARTING FROM OBJECT)
POST
http://<servername:port>/abs/api/objects/mydemodatabase/query
Request body:{"start_guids" : "a387cc60-3c34-11e5-216f-782bcb6367e0","items" : [{ "type" : "CONNECTION","direction" : "IN","items" : [{"type" : "OBJECT","typenum" : "6,43","function" : "TARGET"
}
]
}
]
}

Resultstart function (function_1), ast_1 (type 6) , orgUnit_1 (type 43) , orgUnit_2 (type 43)

42

REPOSITORY API TECHNICAL INTRODUCTION

EXAMPLE 2 (STARTING FROM MODEL)
POST
http://<servername:port>/abs/api/models/mydemodatabase/query
Request body:{"start_guids" : "0a26eb70-fd52-11db-2729-000bcd0cce4e","items" : [{"type" : "OCCURRENCE","items" : [{"type" : "OBJECT","typenum" : "22","function" : "FILTER"},{"type" : "CONNECTIONOCCURRENCE","items" : [{"type" : "CONNECTION","function" : "FILTER","direction" : "IN","items" : [{"type" : "OBJECT","typenum" : "43,6","function" : "TARGET"
}
]
}
]
}
]
}
]
}

Resultstart model, function Configure vehicle (type 22), application system type COT (type 6)

43

REPOSITORY API TECHNICAL INTRODUCTION

20
20.1

Legal information
Documentation scope

The information provided describes the settings and features as they were at the time of
publishing. Since documentation and software are subject to different production cycles, thedescription of settings and features may differ from actual settings and features. Information
about discrepancies is provided in the Release Notes that accompany the product. Please
read the Release Notes and take the information into account when installing, setting up, andusing the product.
If you want to install technical and/or business system functions without using theconsulting services provided by Software AG, you require extensive knowledge of the system
to be installed, its intended purpose, the target systems, and their various dependencies. Dueto the number of platforms and interdependent hardware and software configurations, we
can describe only specific installations. It is not possible to document all settings anddependencies.
When you combine various technologies, please observe the manufacturers' instructions,particularly announcements concerning releases on their Internet pages. We cannot
guarantee proper functioning and installation of approved third-party systems and do notsupport them. Always follow the instructions provided in the installation manuals of therelevant manufacturers. If you experience difficulties, please contact the relevant
manufacturer.
If you need help installing third-party systems, contact your local Software AG salesorganization. Please note that this type of manufacturer-specific or customer-specificcustomization is not covered by the standard Software AG software maintenance agreement
and can be performed only on special request and agreement.

20.2

SupportIf you have any questions on specific installations that you cannot perform yourself, contact
your local Software AG sales organization(https://www.softwareag.com/corporate/company/global/offices/default.html). To get
detailed information and support, use our websites.
If you have a valid support contract, you can contact Global Support ARIS at: +800
ARISHELP. If this number is not supported by your telephone provider, please refer to ourGlobal Support Contact Directory.

44

REPOSITORY API TECHNICAL INTRODUCTION

ARIS COMMUNITY
Find information, expert articles, issue resolution, videos, and communication with other ARIS
users. If you do not yet have an account, register at ARIS Community.

SOFTWARE AG EMPOWER PORTAL
You can find documentation on the Software AG Documentation website(https://empower.softwareag.com/). The site requires credentials for Software AG's ProductSupport site Empower. If you do not yet have an account for Empower, send an e-mail toempower@softwareag.com with your name, company, and company e-mail address andrequest an account.
If you have no account, you can use numerous links on the TECHcommunity website. For any
questions, you can find a local or toll-free number for your country in our Global Support
Contact Directory and give us a call.
TECHCOMMUNITY
On the TECHcommunity website, you can find documentation and other technicalinformation:
Use the online discussion forums, moderated by Software AG professionals, to ask
questions, discuss best practices, and learn how other customers are using Software AG
technology.



Access articles, code samples, demos, and tutorials.



Find links to external websites that discuss open standards and web technology.



Access product documentation, if you have TECHcommunity credentials. If you do not,you will need to register and specify Documentation as an area of interest.

EMPOWER (LOGIN REQUIRED)
If you have an account for Empower, use the following sites to find detailed information or
get support:


You can find product information on the Software AG Empower Product Support website.

To get information about fixes and to read early warnings, technical papers, andknowledge base articles, go to the Knowledge Center.

Once you have an account, you can open Support Incidents online via the eService
section of Empower.

To submit feature/enhancement requests, get information about product availability, anddownload products, go to Products.

45

REPOSITORY API TECHNICAL INTRODUCTIONSOFTWARE AG MANAGED LEARNINGS
Get more information and trainings to learn from your laptop computer, tablet or smartphone.
Get the knowledge you need to succeed and make each and every project a success withexpert training from Software AG.
If you do not have an account, register as a customer or as a partner.

46