boc management office standard restful services

BOC Management Office Standard RESTful Services

BOC Management Office RESTful Services

Author: BOC Group

© 2019, BOC Group /181

Table of contents

BOC Management Office Standard RESTful Services........................................................... 1

1 Introduction .................................................................................................................... 6

2 Architecture ................................................................................................................... 6

3 General Information ....................................................................................................... 7

4 Technical Overview ....................................................................................................... 7

5 Authentication ................................................................................................................ 9

5.1 Token Based Authentication .................................................................................. 9

5.2 Basic Authentication .............................................................................................11

6 Compatibility Changes between Versions .....................................................................11

7 Set Up Authenticated Access to BOC Management Office Product ..............................14

7.1 Install BOC Management Office Product ...............................................................14

7.2 Create Technical User in the Administration Toolkit ..............................................14

7.3 Assign Access Rights to the Administration Toolkit ...............................................15

7.4 Edit System Settings .............................................................................................16

7.5 Edit Settings for Standard RESTful Services .........................................................16

7.6 Standard RESTful Services – Tokens ...................................................................17

7.6.1 Rest Security Context .................................................................................................... 18

7.6.2 Cache Path .................................................................................................................... 19

7.7 Standard RESTful Services – Basic Auth ..............................................................19

7.7.1 Enable Basic Authentication .......................................................................................... 20

7.7.2 REST Scenarios ............................................................................................................ 20

7.8 Assign Web Module to all Users ...........................................................................20

7.9 Enable Basic Authentication for BOC Management Office Products .....................21

8 REST Service ...............................................................................................................22

9 Repository Read APIs ..................................................................................................23

9.1 Repositories ..........................................................................................................23

9.1.1 HATEOAS Links ............................................................................................................ 23

9.1.2 Repositories Result Example ........................................................................................ 23

9.2 Statistics ...............................................................................................................25

9.2.1 HATEOAS Links ............................................................................................................ 25


Author: BOC Group

© 2019, BOC Group /181

9.2.2 Statistic Result Example ................................................................................................ 26

9.3 Model Group .........................................................................................................27

9.3.1 HATEOAS Links ............................................................................................................ 28

9.3.2 Model Group Result Example ........................................................................................ 28

9.4 Object Group ........................................................................................................39

9.4.1 HATEOAS Links ............................................................................................................ 40

9.4.2 Object Group Result Example ....................................................................................... 40

9.5 Model ....................................................................................................................48

9.5.1 HATEOAS Links ............................................................................................................ 49

9.5.2 Model Result Example ................................................................................................... 49

9.6 Object ...................................................................................................................56

9.6.1 HATEOAS Links ............................................................................................................ 57

9.6.2 Object Result Example .................................................................................................. 57

9.7 Modelling Object ...................................................................................................64

9.7.1 HATEOAS Links ............................................................................................................ 65

9.7.2 Modelling Object Result Example.................................................................................. 65

9.8 Model/Object/Modelling Object Link ......................................................................71

9.8.1 HATEOAS Links ............................................................................................................ 71

9.8.2 URL Result Example ..................................................................................................... 72

9.9 Model Image Map .................................................................................................73

9.9.1 HATEOAS Links ............................................................................................................ 74

9.9.2 Image Map Result Example .......................................................................................... 74

9.10 Object Usage ........................................................................................................78

9.10.1 HATEOAS Links ............................................................................................................ 78

9.10.2 Object Usage Result Example ....................................................................................... 79

9.11 Object Relations....................................................................................................83

9.11.1 HATEOAS Links ............................................................................................................ 84

9.11.2 Object Relations Result Example .................................................................................. 84

9.12 Object Relation Endpoints .....................................................................................87

9.12.1 HATEOAS Links ............................................................................................................ 88

9.12.2 Object Relation Endpoint Result Example .................................................................... 88

9.13 Object Relation Endpoint Details ...........................................................................92

9.13.1 HATEOAS Links ............................................................................................................ 93


Author: BOC Group

© 2019, BOC Group /181

9.13.2 Object Relation Endpoint Details Result Example ........................................................ 93

10 Repository Write APIs ...................................................................................................98

10.1 Repository Objects ................................................................................................98

10.1.1 Create Object ................................................................................................................. 98

10.1.2 Delete Object ................................................................................................................. 99

10.1.3 Modify Object ............................................................................................................... 100

10.1.4 Move Object ................................................................................................................. 101

10.2 Object Group ...................................................................................................... 102

10.2.1 Create Object Group ................................................................................................... 102

10.2.2 Delete Object Group .................................................................................................... 103

10.2.3 Modify Object Group .................................................................................................... 103

10.3 Object Relations.................................................................................................. 106

10.3.1 Create Endpoint ........................................................................................................... 106

10.3.2 Update Endpoint .......................................................................................................... 108

10.3.3 Delete Endpoint ........................................................................................................... 109

11 Repository Search APIs .............................................................................................. 109

11.1 Search Queries ................................................................................................... 110

11.1.1 Performing a Generic Search Query ........................................................................... 110

11.1.2 HATEOAS Links .......................................................................................................... 111

11.1.3 Result Examples for a Simple Query........................................................................... 111

11.1.4 Filters Definition ........................................................................................................... 116

11.2 Search Jobs ........................................................................................................ 117

11.2.1 HATEOAS Links .......................................................................................................... 118

11.2.2 Prepare Query ............................................................................................................. 118

11.2.3 Fetch Query Result ...................................................................................................... 119

11.2.4 Delete Query Result .................................................................................................... 120

11.2.5 Example ....................................................................................................................... 120

12 User Read APIs .......................................................................................................... 125

12.1 User group .......................................................................................................... 125

12.1.1 HATEOAS Links .......................................................................................................... 126

12.1.2 User Group Result Example ........................................................................................ 126

12.2 Roles .................................................................................................................. 134

12.2.1 List of Role Grouping Items ......................................................................................... 134


Author: BOC Group

© 2019, BOC Group /181

12.2.2 List of Roles inside Grouping Item............................................................................... 136

12.2.3 Detailed Role Information ............................................................................................ 138

12.3 Users .................................................................................................................. 141

12.3.1 Get the Specified User ................................................................................................ 141

12.3.2 Users List ..................................................................................................................... 148

13 User Write APIs .......................................................................................................... 150

13.1 Users .................................................................................................................. 150

13.1.1 Create Users ................................................................................................................ 150

13.1.2 Delete Users ................................................................................................................ 153

13.1.3 Modify Users ................................................................................................................ 153

14 Error Handling ............................................................................................................ 158

15 Appendix .................................................................................................................... 158

15.1 Sample Implementation (Java): Programmatic Access ....................................... 158

15.2 Sample Implementation (Java): Authenticated REST call ................................... 159

15.3 Sample Implementation (Java): Using HTTP POST ............................................ 162

15.4 Sample Implementation (Java): Using HTTP POST to Create a New User ......... 163

15.5 Sample Implementation (Java): Using HTTP GET to Get Model Data ................. 166

15.6 Sample Implementation (Java): Using HTTP POST to Create a New Object ...... 170

15.7 Sample Implementation (Java): Using HTTP PATCH to Update an Existing Object 174

15.8 Sample Implementation (Java): Using HTTP POST to create a Relation between two Existing Objects ....................................................................................................... 177


Author: BOC Group

© 2019, BOC Group /181

1 Introduction BOC Management Office products offer a generic, extensible REST API that allows authenticated access to exposed functionality in the BOC Management Office product.

This document explains how use this REST API to:

• set up authenticated access to the REST interface of the BOC Management Office product and

• send requests to the BOC Management Office product.

Note: Access to the application programming interface (API) is limited to 500 requests per hour.

2 Architecture

The picture shows the basic architecture of a BOC Management Office product:

Fig. 1: Architecture of a BOC Management Office product


Author: BOC Group

© 2019, BOC Group /181

• Access to the database is handled by the application server. • The application server offers an (internal) SOAP web service interface via

which its functionality can be accessed. • This SOAP web service interface is used by the web server to communicate

and exchange data with the application server. • The data is then presented to the user in the browser. To gain access to this

data, a user has to be logged in to the web client. • The web server itself exposes a RESTful interface to the outside world which

can be used by external components to retrieve or manipulate data specific to the BOC Management Office product.

3 General Information

REST stands for Representational State Transfer and is an architectural style for distributed systems.

It does not define a communication protocol, it is not a web service standard, and it is not a deployable technology.

RESTful services are resource oriented and stateless, meaning each request is self-contained. The communication is based on a request/response structure.

HTTP methods are used to send requests:

• GET for reading / querying resources. GET requests by convention do not modify business resources on the server (GET requests will of course still modify technical resources such as log files)

• POST for creating or updating resources. • PUT for creating or overwriting resources. • DELETE for removing content. • PATCH for changing a part of a resource. • HEAD for requesting metadata of a resource. • OPTIONS for evaluating which methods are available for a resource.

For additional information about REST: http://en.wikipedia.org/wiki/Representational_state_transfer

4 Technical Overview

BOC Management Office RESTful services are based on “JAX-RS”, a programming language API which facilitates creating a RESTful interface. BOC Management Office products use JAX-RS’ reference implementation “Jersey”.

http://en.wikipedia.org/wiki/Representational_state_transfer


Author: BOC Group

© 2019, BOC Group /181

Jersey is very well documented. User guide: https://jersey.java.net/documentation/latest/index.html

API documentation: https://jersey.java.net/apidocs/latest/jersey/index.html

The addresses for RESTful services exposed by BOC Management Office products follow this pattern: http(s)://[Domain]:[Port]/[Product]/rest/[service path]

Where http(s)://[Domain]:[Port]/[Product]/rest/ is the fixed path and the part(s) afterwards are defined by the service.

Example

You are configuring ADONIS NP 8.0. You are running the ADONIS NP web application locally. The ADONIS NP web application exposes a REST service called “helloworld”. The URL should look like this:

"http://localhost:8000/ADONISNP8_0/rest/helloworld"

All registered services are listed in BOC Management Office products’ WADL description at .../rest/application.wadl.

Example

"http://localhost:8000/ADONISNP8_0/rest/application.wadl"

WADL is short for Web Application Description Language. For details, refer to:

http://en.wikipedia.org/wiki/Web_Application_Description_Language

https://wadl.java.net/

Important note: Accessing the WADL is only possible if the web application is operated in global debug mode. For information on how to activate global debug mode, please refer to the Web Client Administration Manual.

For testing purposes, the following URLs are always available: http://[Domain]:[Port]/[Product]/rest/connection http://[Domain]:[Port]/[Product]/rest/connection/auth (requires authentication - see below)

https://jersey.java.net/documentation/latest/index.html

https://jersey.java.net/apidocs/latest/jersey/index.html

http://en.wikipedia.org/wiki/Web_Application_Description_Language

https://wadl.java.net/


Author: BOC Group

© 2019, BOC Group /181

5 Authentication BOC Management Office RESTful services support two authentication mechanisms:

• Token based authentication: Each request is accompanied by Hashed security token to ensure validity of the request. Requests are executed in the context of a technical user.

• Basic authentication: Each request contains a header field of the form Authorization: Basic encodeBase64(username:password). Requests may be executed in the context of any standard product user.

5.1 Token Based Authentication

REST authentication is done using a security hash which is constructed from a public identifier of the client, a secret key of the client, a GUID and a timestamp of the request. This prevents that the REST functionality is used by unauthorized clients or that requests could be replayed or abused.

Each authenticated request to the REST API must contain following four headers in the request:

x-axw-rest-identifier

Shared identifier of the secret key defined for this client in the Administration Toolkit of the BOC product (see 7.6.1).

Example Value

Boc.rest.key.mfb.StandardRESTfulServices

x-axw-rest-guid

A GUID to ensure uniqueness of the request.

Generation Example

final String sGUID = UUID.randomUUID ().toString ();

aMethod.addHeader ("x-axw-rest-guid", sGUID);

Example Value d5dfba69-fab6-4156-9294-0c73ac20c5af

x-axw-rest-timestamp

The timestamp when the request was sent by the client. The header parameter 'x-axw-rest-timestamp' needs to be a UTC long value in milliseconds.

Generation Example

final long nDate = new Date ().getTime ();

final String sDate = String.valueOf (nDate);


Author: BOC Group

© 2019, BOC Group /181

aMethod.addHeader ("x-axw-rest-timestamp", sDate);

Example Value

1493365316885

x-axw-rest-token

Hashed security token to ensure validity of the request. For generation example, see below.

Example Value

QIYqykxHA2x+96qYf+S0w1suXswgtRMIquNMg6P6F3LAvbpwEB+23DD8iK1LVDsL6f2fIwxg+DK/pImDtowpeQ==

The algorithm for calculating the hashed security token consists of the following steps:

1. Get the secret key matching to the identifier sent via the x-axw-rest-identifier header.

2. Take all request parameter names and put them into a collection. 3. Take all request parameter values as strings and put them into the same

collection. 4. Take the header names x-axw-rest-identifier, x-axw-rest-guid and x-axw-rest-

timestamp and put them into the collection. 5. Take the values of the x-axw-rest-identifier, x-axw-rest-guid and x-axw-rest-

timestamp headers as well as the secret key and put them into the collection. 6. Sort this collection using Locale en_US. 7. Convert each item of the collection into a byte array using UTF-8 encoding.

(So in the end the whole collection should be converted from Collection<String> to Collection<byte[]>)

8. Append all items of the byte array collection into a single byte array in the order of their sorting.

9. Convert the secret key into a byte array using UTF-8 encoding. 10. Create a new HMac instance using SHA-512 algorithm. 11. Initialize the HMac instance using the secret key byte array. 12. Finalize the HMac using the byte array containing all parameters and

headers/parameters. 13. Get the resulting byte array of the HMac. 14. Convert the byte array into a Base64 encoded string using UTF-8 encoding.

For a sample implementation see section 15.2.


Author: BOC Group

© 2019, BOC Group /181

5.2 Basic Authentication

Each authenticated request to the REST API must include an Authorization request-header field with the request. The Authorization field contains the username and password separated by a single colon (":") character, within a base64 encoded string.

Example Value Authorization: Basic encodeBase64(guest:Password123)

Note: As the credentials are only encoded and not encrypted, this method is not any more secure as sending the credentials in clear text. Therefore, use HTTPS in conjunction with basic authentication. Install the BOC Management Office product according to the Installation Manual and configure SSL/TLS support on Tomcat.

Basic authentication does not support login to the web client using an Identity Management System (IDM). Users with a colon in the username cannot be used for sending requests.

6 Compatibility Changes between Versions

For security reasons, the handling for authenticated requests was improved (made stricter) and the internal libraries that are used for providing the REST interface were upgraded with ADONIS NP 4.5 or higher and ADOIT 7.5 or higher.

Due to these steps, the REST interface behaves in a stricter way in certain areas:

• The header parameter 'x-axw-rest-timestamp' needs to be a UTC long value in milliseconds - previously it was possible to send a string with arbitrary data:

Before 4.5/7.5 4.5/7.5 or higher ...

final String sDate = new Date ().toString ();


final Map <String, String []> aRequestParameters = new HashMap <String, String []> ();

aRequestParameters.put ("x-axw-rest-timestamp", new String [] {sDate});

...

final long nDate = new Date ().getTime ();

final String sDate = String.valueOf (nDate);


final Map <String, String []> aRequestParameters = new HashMap <String, String []> ();


Author: BOC Group

© 2019, BOC Group /181

... aRequestParameters.put ("x-axw-rest-timestamp", new String [] {sDate});

...

• Both the REST client and the method defined in the server part have to be more strict than before concerning the sent/consumed ContentType. This is especially the case for sending of data using FormParameters. In previous versions, a client could send FormParameters to a defined method on the server without specifying any ContentType and the server method also did not need to specify a consumed ContentType:

Before 4.5/7.5 4.5/7.5 or higher

Server-side code: @POST

@Path ("/user_form")

@Produces (MediaType.TEXT_PLAIN)

public static String createUserForm (@FormParam ("username") final String sUsername,

@FormParam ("password") final String sPassword)

{

return createUser (sUsername, sPassword);

}

Server-side code: @POST

@Path ("/user_form")

@Produces (MediaType.TEXT_PLAIN)

@Consumes (MediaType.APPLICATION_FORM_URLENCODED)

public static String createUserForm (@FormParam ("username") final String sUsername,

@FormParam ("password") final String sPassword)

{

return createUser (sUsername, sPassword);

}

Client code ...

final String sSecurityToken = getSecurityToken (SECRET, aRequestParameters);

aMethod.addHeader ("x-axw-rest-token", sSecurityToken);

Client code ...

final String sSecurityToken = getSecurityToken (SECRET, aRequestParameters);



Author: BOC Group

© 2019, BOC Group /181

aMethod.setEntity (new UrlEncodedFormEntity (aPostForm, "UTF-8"));

final CloseableHttpResponse aResponse = aClient.execute (aMethod);

...

aMethod.addHeader ("Content-Type", "application/x-www-form-urlencoded;charset=UTF-8");

aMethod.setEntity (new UrlEncodedFormEntity (aPostForm, "UTF-8"));

final CloseableHttpResponse aResponse = aClient.execute (aMethod);

...


Author: BOC Group

© 2019, BOC Group /181

7 Set Up Authenticated Access to BOC Management Office Product

The following steps are necessary in order to set up authenticated access to the REST interface of a BOC Management Office product:

7.1 Install BOC Management Office Product

• Install the BOC Management Office product according to the Installation Manual.

7.2 Create Technical User in the Administration Toolkit

Create the following technical user in the Administration Toolkit:

• User name: “Technical_StandardRESTfulServices” (and a password of your choice)

• Repository: Only (!) assign the repository to the user which holds the data to be queried.

• User groups: This user belongs to the default group. • System roles: If release workflows are licensed, and you want to use

repository write APIs, map the technical user to the “Administrator” roles: o ADONIS NP: Document Release Workflow and Model Release

Workflow o ADOIT: EA Workflow

• Trusted Login: Yes

Important note: You cannot activate “Trusted Login” during user creation. Only rights of already created users can be modified. Use the button “Create” in the “Create New User” tab to create the user before you activate “Trusted Login”.

Important note: Creating a technical user is necessary regardless of the authentication method, as it is required for loading the initial configuration.


Author: BOC Group

© 2019, BOC Group /181

Fig. 2: Create technical user in the Administration Toolkit

7.3 Assign Access Rights to the Administration Toolkit

If you want to use user write APIs, you must assign access rights to the Administration Toolkit to the user in whose context requests should be executed.

Note: This can either be a technical user (for token based authentication) or a standard product user (for basic authentication).

In order to do so:

1. Right-click the user in the User Catalogue, and then click Change access rights.

2. Switch to the Components tab. 3. The momentary rights status for the Administration Toolkit is shown in the

column Rights. Double-click here until you reach the status Access. 4. When asked whether the user shall receive global administration rights, click

No.


Author: BOC Group

© 2019, BOC Group /181

Fig. 3: Assign Access Rights to the Administration Toolkit

7.4 Edit System Settings

Now you have to define a few technical settings controlling the base functionality of the web client. In order to edit the System settings:

1. Open the Library Management and switch to the tab Component Settings. 2. Double-click the desired library to open the list of components available for

configuration. 3. Double-click Web Client, and then double-click System. 4. In the Base URL field, enter the URL where the web client can be reached

from other machines.

Example

You are configuring ADONIS NP 8.0. You are running the ADONIS NP web client on a machine with the IP 10.2.100.68. The URL should look like this:

"http://10.2.100.68:8000/ADONISNP8_0"

5. In the Technical Users field, select the technical user you created from the Available users list, i.e. “Technical_StandardRESTfulServices” (see Create Technical User in the Administration Toolkit).

6. Click OK.

7.5 Edit Settings for Standard RESTful Services

Now the Standard RESTful Services settings have to be adapted. In order to do so:


configuration. 3. Double-click Standard RESTful Services, and then double-click General. 4. Edit the settings in the Tokens tab and the Basic Auth tab.


Author: BOC Group

© 2019, BOC Group /181

5. Click OK when you have completed the settings.

7.6 Standard RESTful Services – Tokens

The following settings are available in the Tokens tab:

Fig. 4: Example of settings in the Tokens tab


Author: BOC Group

© 2019, BOC Group /181

7.6.1 Rest Security Context

You can edit the default REST security context, or click the Add context button to generate a new REST security context. A security context consists of the following parts:

• key • secret • technical user • REST scenarios

Note: BOC Management Office RESTful services support multiple security contexts. At least one security context is required.

When would you want to use multiple security contexts? For example, you can configure one security context that allows for modification of users, and another one with access to the repository. You can execute requests with access rights of different technical users. During execution, you can choose which of the predefined security contexts should be used.

Key (for authentication by target system)

This parameter represents the name of the key which is used for communication with the web application using authenticated REST APIs. Enter a descriptive name, e.g. “boc.rest.key.mfb.StandardRESTfulServices”.

Secret (for authentication by target system)

This parameter represents the secret value of the key which is used for communication with the web application using authenticated REST APIs. Click the Generate secret button to generate the value of the key.

Technical user

From the Available Users list, select the technical user you created, i.e. “Technical_StandardRESTfulServices” (see Create Technical User in the Administration Toolkit).

REST Scenarios

In this area, you can enable specific REST scenarios. If a scenario is not enabled, all requests to its endpoints will return a 403 FORBIDDEN status. Also, HATEOAS links to endpoints which are disabled won't be returned in other endpoints. For example, if you disable the user write APIs scenario, a user response will contain a HATEOAS delete link, but a request to this link using the same security context would return the status code 403 FORBIDDEN. This link would be processed only when using a security context with the scenario enabled.


Author: BOC Group

© 2019, BOC Group /181

The following REST scenarios are available:

• Repository Read APIs

Endpoints: repositories, statistics, model group, object group, model, object, modelling object, model/object/modelling object link, model image map, object usage, object relations, object relation endpoints, object relation endpoint details

• Repository Write APIs

Endpoints: repository objects, object group, object relations

• Repository Search APIs

Endpoints: search queries, search jobs

• User Read APIs

Endpoints: user group, roles, users

• User Write APIS

Endpoints: Users

7.6.2 Cache Path

This parameter is optional. Enter the absolute path to the directory in which cache files must be stored. The user under which the Apache Tomcat web server service is running must have write access to this directory.

Advantages of using this parameter:

• Model images (see section 9.5, with Accept:image/png) and model image maps (see section 9.9) are generated only once and then cached. Every time the model image or image map is requested, a check is performed if the model has changed. If there are no changes, the information is loaded from the file system. Otherwise, the cache is updated first. As a result, responses to these types of requests are faster and use fewer server resources.

• For search jobs (see section 11.2) the advantage is that created queries are saved in cache files and can be reused after a server restart. Without the cache path, queries are saved only in memory and are lost during restart.

7.7 Standard RESTful Services – Basic Auth

The following settings are available in the Basic Auth tab:


Author: BOC Group

© 2019, BOC Group /181

Fig. 5: Example of settings in the Basic auth tab

7.7.1 Enable Basic Authentication

Select this check box to enable basic authentication. All other options in this tab are inactive unless you select this check box.

If this check box is cleared, only token based authentication is possible.

Note: In addition to enabling basic authentication in the component settings, it must be enabled globally for the BOC Management Office product as well (see 7.9).

7.7.2 REST Scenarios

This area is identical in both the Tokens and Basic Auth tabs. Therefore, please refer to the corresponding description here.

7.8 Assign Web Module to all Users

Assign the following web module to all users so that the technical user can query the BOC Management Office product for data:

• Standard RESTful Services

In order to do so:


configuration. 3. Double-click Web Client, and then double-click Web Modules. 4. Activate the web module Standard RESTful Services for all users.

Author: BOC Group

© 2019, BOC Group /181

Fig. 6: Assign Web Module to all Users

Done! Restart the Apache Tomcat web server and the application server. You can send send requests to the BOC Management Office product now.

7.9 Enable Basic Authentication for BOC Management Office Products

For security reasons, basic authentication is turned off by default in BOC Management Office products. If you want to use BOC Management Office RESTful services with basic authentication, you need to customize a configuration file. In order to do so:

1. Shut down Apache Tomcat (if it is running). 2. Open the folder <Tomcat installation>\webapps\<WAR file

name>\WEB-INF\registry\rest and edit the file RESTAuthorization.xml. Look for a section similar to:



3. Remove the comment characters (). 4. Save the file and restart Apache Tomcat.


Author: BOC Group

© 2019, BOC Group /181

8 REST Service The REST service is deployed as part of the web application hosted in a Java Web Container and is available at the URL http(s)://<ip-or-host-name>:<port>/<product>/rest/<api-version>.

Read API responses must be extended with HATEOAS links to related resources.


Author: BOC Group

© 2019, BOC Group /181

9 Repository Read APIs

This section lists the repository read APIs available for the different resource types.

9.1 Repositories

Here is an API for retrieving a list of available repositories

HTTP Method GET URL path /rest/2.0/repos Request headers Accept: application/json and application/xml

Response A JSON document consisting of a list of available repositories

9.1.1 HATEOAS Links

# Description rel Position in response

Endpoint

1 Self link self root repos

2 Link to root model group of every repository

modelgroups repo modelgroups

3 Link to root object group of every repository

objectgroups repo objectgroups

4 Link to search of every repository

search repo search

5 Link to statistics of every repository

stats repo stats

9.1.2 Repositories Result Example

Here is a GET request to get a repositories list in an XML representation:

REQUEST GET rest/2.0/repos

Accept: application/xml


Author: BOC Group

© 2019, BOC Group /181

RESPONSE HTTP/1.1 200 OK Content-Type: application/xml Content-Length: ... <xml version="1.0" encoding="UTF-8" standalone="yes"?> <response> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos" method="GET" rel="self"/> </rest_links> <repos> <repo id="{e1138bdc-4063-490e-95f8-986d18c79ac3}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/root" method="GET" rel="modelgroups"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/root" method="GET" rel="objectgroups"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/search" method="GET" rel="search"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/stats" method="GET" rel="stats"/> </rest_links> <name><![CDATA[Standard-Repository]]></name> </repo> ... </repos> </response>

Here is a GET request to get a repositories list in a JSON representation:


Accept: application/json

RESPONSE { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos", "method": "GET", "rel": "self" } ], "repos": [ { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/root", "method": "GET", "rel": "modelgroups" }, {


Author: BOC Group

© 2019, BOC Group /181

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/root", "method": "GET", "rel": "objectgroups" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/search", "method": "GET", "rel": "search" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/stats", "method": "GET", "rel": "stats" } ], "id": "{e1138bdc-4063-490e-95f8-986d18c79ac3}", "name": "Standard-Repository" }, ... ] }

9.2 Statistics

An API for retrieving basic stats of a repository.

HTTP Method GET URL path /rest/2.0/repos/{repo_id}/stats Identifiers

{repo_id}

The ID of the repository that is used to perform the request. The value must not contain brackets.

E.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... Request headers

Accept: application/json and application/xml

Response JSON/XML document consisting of basic statistic of a repository

9.2.1 HATEOAS Links

# Description rel Position in response Endpoint

1 Self link self root stats


Author: BOC Group

© 2019, BOC Group /181

9.2.2 Statistic Result Example

Here is a GET request that returns statistics of a repository in an XML representation:

REQUEST GET rest/2.0/repos/a9cb2ad3-a0fe-4bd8-a886-72b0581c2189/stats


RESPONSE HTTP/1.1 200 OK

Content-Type: application/xml

Content-Length: ...

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<stats models="74" objects="2776">

<rest_links>

<rest_link href="http://localhost/ADOxxWeb/rest/2.0/repos/a9cb2ad3-a0fe-4bd8-a886-72b0581c2189/stats" method="GET" rel="self"/>

</rest_links>

</stats>

Here is a GET request that returns statistics of a repository in a JSON representation:

REQUEST GET rest/2.0/repos/a9cb2ad3-a0fe-4bd8-a886-72b0581c2189/stats


RESPONSE {

"rest_links": [

{

"href": "http://localhost/ADOxxWeb/rest/2.0/repos/a9cb2ad3-a0fe-4bd8-a886-72b0581c2189/stats",

"method": "GET",

"rel": "self"

}

],


Author: BOC Group

© 2019, BOC Group /181

"models": 74,

"objects": 2776

}

9.3 Model Group

An API for retrieving a model group.

HTTP Method GET URL path /rest/2.0/repos/{repo_id}/modelgroups/{group-id}

/rest/2.0/repos/{repo_id}/modelgroups/{group-id}?icon=true&attribute={NAME_OF_ATTRIBUTE}&recursive=true Identifiers

{repo_id}


e.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... {group-id} The ID of the group to be retrieved, root for the root model group. Request headers


Accept-Language: ISO 639-1 language code

Parameters

The parameters and flags are optional.

Parameters should be inserted after the question mark, after {group-id}

There are two types of parameters available for the model group API.

1) Boolean flag

icon If this flag is set to true, the icon for a model is returned.

recursive If this flag is set to true, the whole tree is returned, beginning from the model group whose ID was specified as the group ID and including models and specified attributes.

2) Attribute of models contained in queried groups

attribute={Name_of_attribute} The response will have the specified attribute for all models which are contained in the queried model groups, unless the attribute has no value or the model does not contain the attribute.

The attribute will not be returned if it is not a part of always loaded attributes and visible attributes.


Author: BOC Group

© 2019, BOC Group /181

Only attributes that are marked as “always loaded” in the application library can be specified here.

The attributes can be configured in Administration Toolkit in the Metamodel Management -> Library View.

In 1) "LOADED_MODEL_ATTRIBUTES"

In 2) "VISIBLE_MODEL_ATTRIBUTES"

Response A JSON document consisting of ID, name, list of contained groups (ID and name), list of contained models (ID, type, name)

After the extension of the endpoint, the whole tree can be returned with contained models and subgroups

9.3.1 HATEOAS Links


Endpoint

1 Self link self group modelgroups


parent group modelgroups


self model models

4 Self link parent model modelgroups

5 Link to every subgroup self subgroup modelgroups

9.3.2 Model Group Result Example

Here is a GET request that returns model group information in an XML representation:


Author: BOC Group

© 2019, BOC Group /181

REQUEST GET rest/2.0/repos/e1c24623-3ece-494f-949c-135673cad8d9/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8


Accept-Language : en

RESPONSE HTTP/1.1 200 OK Content-Type: application/xml Content-Length: ... <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <response> <locale>en</locale> <group id="{8815ee31-5d82-4b4e-89e2-0add7b846ea8}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8" method="GET" rel="self"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/3b7034d4-a336-4ed5-bef2-363d7a48c55e" method="GET" rel="parent"/> </rest_links> <name><![CDATA[Roadtrip example]]></name> <subgroups> <group id="{00ee28fb-496e-4034-9157-006d3539e52a}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/00ee28fb-496e-4034-9157-006d3539e52a" method="GET" rel="self"/> </rest_links> <name><![CDATA[Organisation]]></name> </group> ... </subgroups> <models> <model id="{e0c87643-1925-4ec8-806a-be94d2e5ab3a}"> <name><![CDATA[HERE starts your roadtrip 1.00]]></name> <type><![CDATA[Company Map]]></type> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/models/e0c87643-1925-4ec8-806a-be94d2e5ab3a" method="GET" rel="self"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8" method="GET" rel="parent"/> </rest_links> </model> ... </models> </group> </response>


Author: BOC Group

© 2019, BOC Group /181

Here is a GET request that returns model group information in a JSON representation:

REQUEST GET rest/2.0/repos/e1c24623-3ece-494f-949c-135673cad8d9/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8



RESPONSE { "locale": "en", "group": { "id": "{8815ee31-5d82-4b4e-89e2-0add7b846ea8}", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/3b7034d4-a336-4ed5-bef2-363d7a48c55e", "method": "GET", "rel": "parent" } ], "name": "Roadtrip example", "subgroups": [ { "id": "{00ee28fb-496e-4034-9157-006d3539e52a}", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/00ee28fb-496e-4034-9157-006d3539e52a", "method": "GET", "rel": "self" } ], "name": "Organisation" }, ... ], "models": [ { "id": "{e0c87643-1925-4ec8-806a-be94d2e5ab3a}", "name": "HERE starts your roadtrip 1.00", "type": "Company Map", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/models/e0c87643-1925-4ec8-806a-be94d2e5ab3a", "method": "GET", "rel": "self" },


Author: BOC Group

© 2019, BOC Group /181

{ "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8", "method": "GET", "rel": "parent" } ] }, ... ] } }

Here is an XML response with additional parameters:

REQUEST GET rest/2.0/repos/6f68b2e6-c48e-4bc5-a803-90cda4d17cf5/modelgroups/00ee28fb-496e-4034-9157-006d3539e52a?recursive=true&icon=true&attribute=MFB_RWF_VERSION&attribute=MFB_RWF_STATE





Content-Length: ...

<response>

<locale>en</locale>

<group id="{8815ee31-5d82-4b4e-89e2-0add7b846ea8}">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8?recursive=true&icon=true&attribute=MFB_RWF_VERSION&attribute=MFB_RWF_STATE" method="GET" rel="self"/>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/3b7034d4-a336-4ed5-bef2-363d7a48c55e" method="GET" rel="parent"/>

</rest_links>

<name><![CDATA[Roadtrip example]]></name>

<subgroups>

<group id="{00ee28fb-496e-4034-9157-006d3539e52a}">

<rest_links>


Author: BOC Group

© 2019, BOC Group /181

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/00ee28fb-496e-4034-9157-006d3539e52a" method="GET" rel="self"/>

</rest_links>

<name><![CDATA[Organisation]]></name>

<subgroups/>

<models>

<model id="{a7e8862c-df3d-4003-8f05-119fc120a095}">

<name><![CDATA[Roadtrip - Organisation & Roles]]></name>

<type><![CDATA[Working Environment Model]]></type>

<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B13e35228-5297-4724-91b5-3e2e40258ff6%7D.png" rel="icon"/>

<attributes>

<attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="MFB_RWF_VERSION" attrType="STRING" xsi:type="string">

<name><![CDATA[Version]]></name>

<value/>

</attribute>

<attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="MFB_RWF_STATE" attrType="ENUM" xsi:type="string">

<name><![CDATA[State]]></name>

<value><![CDATA[Released]]></value>

</attribute>

</attributes>

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/models/a7e8862c-df3d-4003-8f05-119fc120a095" method="GET" rel="self"/>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/00ee28fb-496e-4034-9157-006d3539e52a" method="GET" rel="parent"/>

</rest_links>

</model>


Author: BOC Group

© 2019, BOC Group /181

...

</models>

</group>

...

</subgroups>

<models>

<model id="{e0c87643-1925-4ec8-806a-be94d2e5ab3a}">

<name><![CDATA[HERE starts your roadtrip 1.00]]></name>

<type><![CDATA[Company Map]]></type>

<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B14a6bed2-071f-42af-afc7-9b00e6ae97a2%7D.png" rel="icon"/>

<attributes>

<attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="MFB_RWF_VERSION" attrType="STRING" xsi:type="string">

<name><![CDATA[Version]]></name>

<value><![CDATA[1.00]]></value>

</attribute>

<attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="MFB_RWF_STATE" attrType="ENUM" xsi:type="string">

<name><![CDATA[State]]></name>

<value><![CDATA[Released]]></value>

</attribute>

</attributes>

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/models/e0c87643-1925-4ec8-806a-be94d2e5ab3a" method="GET" rel="self"/>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8" method="GET" rel="parent"/>

</rest_links>

</model>

...


Author: BOC Group

© 2019, BOC Group /181

</models>

</group>

</response>

Here is a JSON response with additional parameters:

REQUEST GET rest/2.0/repos/6f68b2e6-c48e-4bc5-a803-90cda4d17cf5/modelgroups/00ee28fb-496e-4034-9157-006d3539e52a?recursive=true&icon=true&attribute=MFB_RWF_VERSION&attribute=MFB_RWF_STATE



RESPONSE {

"locale": "en",

"group": {

"id": "{8815ee31-5d82-4b4e-89e2-0add7b846ea8}",

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8?recursive=true&icon=true&attribute=MFB_RWF_VERSION&attribute=MFB_RWF_STATE",

"method": "GET",

"rel": "self"

},

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/3b7034d4-a336-4ed5-bef2-363d7a48c55e",

"method": "GET",

"rel": "parent"

}

],

"name": "Roadtrip example",

"subgroups": [

{

http://localhost:7080/ADOxxWeb/rest/1.0/repos/e1c24623-3ece-494f-949c-135673cad8d9/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8

http://localhost:7080/ADOxxWeb/rest/1.0/repos/e1c24623-3ece-494f-949c-135673cad8d9/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8


Author: BOC Group

© 2019, BOC Group /181

"id": "{93380d01-64d1-4a75-bebd-35cc259d87c0}",

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/93380d01-64d1-4a75-bebd-35cc259d87c0",

"method": "GET",

"rel": "self"

}

],

"name": "Process flows",

"subgroups": [

{

"id": "{3a0513b9-84b1-4e50-9ec5-c7b2f320fcc0}",

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/3a0513b9-84b1-4e50-9ec5-c7b2f320fcc0",

"method": "GET",

"rel": "self"

}

],

"name": "Support processes",

"subgroups": [],

"models": [

{

"id": "{0d638c2a-ad77-4e63-8cd2-36edc594fa95}",

"name": "Make preparations for travel 1.00",

"type": "Business Process Diagram",

"icon": {

"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Baee098ea-071d-4150-8ce9-011eaf93643f%7D.png",

"rel": "icon"

},


Author: BOC Group

© 2019, BOC Group /181

"attributes": [

{

"name": "Version",

"metaName": "MFB_RWF_VERSION",

"attrType": "STRING",

"value": "1.00"

},

{

"name": "State",

"metaName": "MFB_RWF_STATE",

"attrType": "ENUM",

"value": "Released"

}

],

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/models/0d638c2a-ad77-4e63-8cd2-36edc594fa95",

"rel": "self",

"type": "GET"

},

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/3a0513b9-84b1-4e50-9ec5-c7b2f320fcc0",

"rel": "parent",

"type": "GET"

}

]

},

...

]

},


Author: BOC Group

© 2019, BOC Group /181

...

],

"models": []

},

{

"id": "{c036c85a-2b09-4c62-9169-1da992df71a8}",

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/c036c85a-2b09-4c62-9169-1da992df71a8",

"method": "GET",

"rel": "self"

}

],

"name": "Governance, Risk and Compliance",

"subgroups": [],

"models": [

{

"id": "{d7ff6821-84a9-4070-9f07-a932f8bcb8e9}",

"name": "Roadtrip - Risks and Control (Objectives)",

"type": "Analysis Model",

"icon": {

"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B472156d3-9f20-4c4c-af23-a23825bc0815%7D.png",

"rel": "icon"

},

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/models/d7ff6821-84a9-4070-9f07-a932f8bcb8e9",

"method": "GET",

"rel": "self"

},


Author: BOC Group

© 2019, BOC Group /181

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/c036c85a-2b09-4c62-9169-1da992df71a8",

"method": "GET",

"rel": "parent"

}

]

}

]

},

...

],

"models": [

{

"id": "{e0c87643-1925-4ec8-806a-be94d2e5ab3a}",

"name": "HERE starts your roadtrip 1.00",

"type": "Company Map",

"icon": {

"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B14a6bed2-071f-42af-afc7-9b00e6ae97a2%7D.png",

"rel": "icon"

},

"attributes": [

{

"name": "Version",

"metaName": "MFB_RWF_VERSION",


"value": "1.00"

},

{

"name": "State",

"metaName": "MFB_RWF_STATE",

"attrType": "ENUM",


Author: BOC Group

© 2019, BOC Group /181

"value": "Released"

}

],

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/models/e0c87643-1925-4ec8-806a-be94d2e5ab3a",

"method": "GET",

"rel": "self"

},

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8",

"method": "GET",

"rel": "parent"

}

]

},

...

]

}

}

9.4 Object Group

An API for retrieving an object group.

HTTP Method GET URL path /rest/2.0/repos/{repo_id}/objectgroups/{group-id}

/rest/2.0/repos/{repo_id}/objectgroups/{group-id}?icon=true&recursive=true Identifiers

{repo_id} The ID of a repository that is used to perform the request. The Value must not contain brackets. E.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/...

{group-id} The ID of the group to be retrieved, root for the root object group. Request headers


Author: BOC Group

© 2019, BOC Group /181



Parameters

The parameters and flags are optional.

Parameters should be inserted after the question mark, after {group-id}.

There are two Boolean flags: icon If flag is set to true the icon for an object is returned

recursive If this flag is set to true, the whole tree is returned, beginning from the model group whose ID was specified as group ID and including models and specified attributes.

Response A JSON document consisting of ID, name, list of contained groups (ID and name), list of contained objects (ID, type, name)

9.4.1 HATEOAS Links


Endpoint

1 Self link self group objectgroups


parent group objectgroups


self object objects

4 Self link parent object objectgroups

5 Link to every subgroup self subgroup objectgroups

9.4.2 Object Group Result Example

Here is a GET request that returns object group information in an XML representation:

REQUEST GET rest/2.0/repos/e1c24623-3ece-494f-949c-135673cad8d9/objectgroups/4b49163b-4cb5-452a-9a42-62ef359613f4



RESPONSE HTTP/1.1 200 OK Content-Type: application/xml


Author: BOC Group

© 2019, BOC Group /181

Content-Length: ... <response> <locale>en</locale> <group id="{3c944389-eb3d-438e-a2d8-7b1c7513144c}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c" method="GET" rel="self"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/09d41ec2-fdf5-4426-bb01-835a2dac97b6" method="GET" rel="parent"/> </rest_links> <name><![CDATA[02 CP Core Processes]]></name> <subgroups> <group id="{727abead-5e88-4f5b-b134-6727df15c4f7}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/727abead-5e88-4f5b-b134-6727df15c4f7" method="GET" rel="self"/> </rest_links> <name><![CDATA[CP.01 Advise Customer]]></name> </group> ... </subgroups> <objects> <object id="{1c2c8c45-f7f5-4779-9813-5d3dba117a8e}"> <name><![CDATA[CP.05 Investment Security Transactions]]></name> <class><![CDATA[Process]]></class> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/1c2c8c45-f7f5-4779-9813-5d3dba117a8e" method="GET" rel="self"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c" method="GET" rel="parent"/> </rest_links> </object> ... </objects> </group> </response>

Here is a GET request that returns object group information in a JSON representation:

REQUEST GET rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c



RESPONSE


Author: BOC Group

© 2019, BOC Group /181

{ "locale": "en", "group": { "id": "{3c944389-eb3d-438e-a2d8-7b1c7513144c}", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/09d41ec2-fdf5-4426-bb01-835a2dac97b6", "method": "GET", "rel": "parent" } ], "name": "02 CP Core Processes", "subgroups": [ { "id": "{727abead-5e88-4f5b-b134-6727df15c4f7}", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/727abead-5e88-4f5b-b134-6727df15c4f7", "method": "GET", "rel": "self" } ], "name": "CP.01 Advise Customer" }, ... ], "objects": [ { "id": "{1c2c8c45-f7f5-4779-9813-5d3dba117a8e}", "name": "CP.05 Investment Security Transactions", "class": "Process", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/1c2c8c45-f7f5-4779-9813-5d3dba117a8e", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c", "method": "GET", "rel": "parent" } ] }, ... ] } }


Author: BOC Group

© 2019, BOC Group /181

An XML representation with Boolean flags added:

REQUEST GET rest/2.0/repos/6f68b2e6-c48e-4bc5-a803-90cda4d17cf5/objectgroups/7e749f24-7a20-41e2-b3b2-132fd0d98392?icon=true&recursive=true



RESPONSE <response>

<locale>en</locale>

<group id="{3c944389-eb3d-438e-a2d8-7b1c7513144c}">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c?icon=true&recursive=true" method="GET" rel="self"/>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/09d41ec2-fdf5-4426-bb01-835a2dac97b6" method="GET" rel="parent"/>

</rest_links>

<name><![CDATA[02 CP Core Processes]]></name>

<subgroups>

<group id="{727abead-5e88-4f5b-b134-6727df15c4f7}">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/727abead-5e88-4f5b-b134-6727df15c4f7" method="GET" rel="self"/>

</rest_links>

<name><![CDATA[CP.01 Advise Customer]]></name>

<subgroups/>

<objects>

<object id="{50eeb619-a61a-49cf-b7d0-b36b3c3f8a37}">

<name><![CDATA[CP.01.02 Prepare and conduct consultation for Business Customers (BC)]]></name>

<class><![CDATA[Process]]></class>


Author: BOC Group

© 2019, BOC Group /181

<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Bfec6d1d3-e52b-4eb4-a2f9-4e29b7746ec2%7D.png" rel="icon"/>

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/50eeb619-a61a-49cf-b7d0-b36b3c3f8a37" method="GET" rel="self"/>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/727abead-5e88-4f5b-b134-6727df15c4f7" method="GET" rel="parent"/>

</rest_links>

</object>

...

</objects>

</group>

...

</subgroups>

<objects>

<object id="{1c2c8c45-f7f5-4779-9813-5d3dba117a8e}">

<name><![CDATA[CP.05 Investment Security Transactions]]></name>

<class><![CDATA[Process]]></class>

<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Bfec6d1d3-e52b-4eb4-a2f9-4e29b7746ec2%7D.png" rel="icon"/>

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/1c2c8c45-f7f5-4779-9813-5d3dba117a8e" method="GET" rel="self"/>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c" method="GET" rel="parent"/>

</rest_links>

</object>

...


Author: BOC Group

© 2019, BOC Group /181

</objects>

</group>

</response>

A JSON representation with Boolean flags added:

REQUEST GET rest/2.0/repos/6f68b2e6-c48e-4bc5-a803-90cda4d17cf5/objectgroups/7e749f24-7a20-41e2-b3b2-132fd0d98392?icon=true&recursive=true



RESPONSE { "locale": "en", "group": { "id": "{3c944389-eb3d-438e-a2d8-7b1c7513144c}", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c?icon=true&recursive=true", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/09d41ec2-fdf5-4426-bb01-835a2dac97b6", "method": "GET", "rel": "parent" } ], "name": "02 CP Core Processes", "subgroups": [ { "id": "{727abead-5e88-4f5b-b134-6727df15c4f7}",

http://localhost:8080/ADOxxWeb/rest/1.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c?icon=true&recursive=true



http://localhost:8080/ADOxxWeb/rest/1.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/09d41ec2-fdf5-4426-bb01-835a2dac97b6

http://localhost:8080/ADOxxWeb/rest/1.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/09d41ec2-fdf5-4426-bb01-835a2dac97b6


Author: BOC Group

© 2019, BOC Group /181

"rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/727abead-5e88-4f5b-b134-6727df15c4f7", "method": "GET", "rel": "self" } ], "name": "CP.01 Advise Customer", "subgroups": [], "objects": [ { "id": "{50eeb619-a61a-49cf-b7d0-b36b3c3f8a37}", "name": "CP.01.02 Prepare and conduct consultation for Business Customers (BC)", "class": "Process", "icon": { "href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Bfec6d1d3-e52b-4eb4-a2f9-4e29b7746ec2%7D.png", "rel": "icon" }, "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/50eeb619-a61a-49cf-b7d0-b36b3c3f8a37", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/727abead-5e88-4f5b-b134-6727df15c4f7", "method": "GET", "rel": "parent" }

http://localhost:8080/ADOxxWeb/rest/1.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/727abead-5e88-4f5b-b134-6727df15c4f7


http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Bfec6d1d3-e52b-4eb4-a2f9-4e29b7746ec2%7D.png


http://localhost:8080/ADOxxWeb/rest/1.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/50eeb619-a61a-49cf-b7d0-b36b3c3f8a37

http://localhost:8080/ADOxxWeb/rest/1.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/50eeb619-a61a-49cf-b7d0-b36b3c3f8a37




Author: BOC Group

© 2019, BOC Group /181

] }, ... ] }, ... ], "objects": [ { "id": "{1c2c8c45-f7f5-4779-9813-5d3dba117a8e}", "name": "CP.05 Investment Security Transactions", "class": "Process", "icon": { "href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Bfec6d1d3-e52b-4eb4-a2f9-4e29b7746ec2%7D.png", "rel": "icon" }, "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/1c2c8c45-f7f5-4779-9813-5d3dba117a8e", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c", "method": "GET", "rel": "parent" } ] }, ...



http://localhost:8080/ADOxxWeb/rest/1.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/1c2c8c45-f7f5-4779-9813-5d3dba117a8e

http://localhost:8080/ADOxxWeb/rest/1.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/1c2c8c45-f7f5-4779-9813-5d3dba117a8e

http://localhost:8080/ADOxxWeb/rest/1.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c

http://localhost:8080/ADOxxWeb/rest/1.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c


Author: BOC Group

© 2019, BOC Group /181

] } }

9.5 Model

An API for retrieving model properties or images.

HTTP Method GET URL path /rest/2.0/repos/{repo_id}/models/{model-id}?dpi={dpi}&attribute={attribute}&relation={relation}&embeddedFonts={embeddedFonts}&showAll={showAll} Identifiers

{repo-id}


E.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... {model-id} The ID of the model to be retrieved. The value must not contain brackets.

{dpi}

Optional. Defines the DPIs in which the image is generated. 300 by default. This parameter is relevant if the request header Accept had the value image/png.

Cached DPIs: 300, 150 and 72, images for any other value are generated at runtime.

Note: DPI should not be smaller or equal to zero.

{attribute}

Optional, defines the attributes of the model that may be returned in the results set. There can be multiple attributes within a request URL. If no attribute parameter is defined all attributes of the model are returned.

E.g. &attribute=CUSTOM_ATTRIBUTE&attribute=A_DESCRIPTION

{relation}

Optional, defines the relation of the model that may be returned in result. There can be many of them within a one request URL. If no relation parameter is defined then all relations of model are returned.

E.g. &relation=CUSTOM_RELATION&relation=RC_MANAGER {embeddedFonts}

Optional. Defines whether fonts should be embedded or not. False by default. This parameter is relevant for the header: Accept: image/svg+xml.

{showAll} Optional, if set to true returns all attributes and relations else only these visible in notebook. False by default.

Request headers Accept: application/json, application/xml, image/png and image/svg+xml


Response


Author: BOC Group

© 2019, BOC Group /181

A JSON or XML document consisting of ID, type, name, list of properties (name, value), list of objects (ID, class, name).

A PNG image if the request header Accept had the value image/png.

An SVG image if the request header Accept had the value image/svg+xml

9.5.1 HATEOAS Links


Endpoint

1 Self link self item models

2 Link to modelgroup with this model

parent item modelgroups

3 Link to the notebook (properties view)

notebookLink item link

4 Link to imagemap imageMap item imagemap

5 Link to each relation target

self target models/objects/modeling objects

6 Link to each contained object

self object modeling objects

9.5.2 Model Result Example

Here is a GET request that returns model information in an XML representation:

REQUEST GET rest/2.0/repos/bbb44e57-ab8e-451e-b89d-1c193e5ee2dd/models/6ae1d61c-f5da-4957-828c-8b7c61297ae6





Content-Length: ...


<response>

http://localhost:7080/ADOxxWeb/rest/1.0/repos/bbb44e57-ab8e-451e-b89d-1c193e5ee2dd/models/6ae1d61c-f5da-4957-828c-8b7c61297ae6


Author: BOC Group

© 2019, BOC Group /181

<locale>en</locale>

<item id="{09529521-202c-4fb7-b512-72edd299f339}" artefactType="DIAGRAM" metaName="MT_COMPANY_MAP">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/09529521-202c-4fb7-b512-72edd299f339" method="GET" rel="self" />

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/09529521-202c-4fb7-b512-72edd299f339/link" method="GET" rel="notebookLink" />

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/modelgroups/3b7034d4-a336-4ed5-bef2-363d7a48c55e" method="GET" rel="parent" />

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/09529521-202c-4fb7-b512-72edd299f339/imagemap" method="GET" rel="imageMap" />

</rest_links>

<name>

<![CDATA[companymap]]>

</name>

<type>

<![CDATA[Company Map]]>

</type>

<link href="http://localhost:8080/ADOxxWeb?t=view&at=1&classId=14a6bed2-071f-42af-afc7-9b00e6ae97a2&libObjID=14a6bed2-071f-42af-afc7-9b00e6ae97a2&vt=graphical&id=09529521-202c-4fb7-b512-72edd299f339" />

<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B14a6bed2-071f-42af-afc7-9b00e6ae97a2%7D.png" rel="icon" />

<attributes>

<attribute metaName="A_DESCRIPTION" attrType="STRING" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="string">

<name>

<![CDATA[Description]]>


Author: BOC Group

© 2019, BOC Group /181

</name>

<value></value>

</attribute>

...

</attributes>

<relations>

<relation metaName="RC_OWNER" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="reference">

<name>

<![CDATA[Process owner]]>

</name>

<targets />

</relation>

<relation metaName="SCOPE" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="reference">

<name>

<![CDATA[Scope]]>

</name>

<targets>

<target id="{f16bb57e-4402-4339-9242-7ee98e492149}" metaName="C_ORGANIZATIONAL_UNIT" direction="OUTGOING">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/f16bb57e-4402-4339-9242-7ee98e492149" method="GET" rel="self" />

</rest_links>

<name>

<![CDATA[Accounting/ balance sheet/ taxes]]>

</name>

<type>

<![CDATA[Organisational Unit]]>

</type>

<link href="http://localhost:8080/ADOxxWeb?t=nb&at=0&classId=26efd4bb-19a5-47f1-939f-520283f3c342&libObjID=26efd4bb-19a5-47f1-939f-


Author: BOC Group

© 2019, BOC Group /181

520283f3c342&id=f16bb57e-4402-4339-9242-7ee98e492149&rid=f16bb57e-4402-4339-9242-7ee98e492149" />

<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B26efd4bb-19a5-47f1-939f-520283f3c342%7D.png" rel="icon" />

</target>

</targets>

</relation>

...

</relations>

<objects>

<object id="{9624da5e-3265-4ea5-aae5-2c01f3bb95cb}" metaName="C_PROCESS">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/09529521-202c-4fb7-b512-72edd299f339/objects/9624da5e-3265-4ea5-aae5-2c01f3bb95cb" method="GET" rel="self" />

</rest_links>

<name>

<![CDATA[Process-d736d0fb]]>

</name>

<type>

<![CDATA[Process]]>

</type>

</object>

...

</objects>

</item>

</response>

Here is a GET request that returns model information in a JSON representation:

REQUEST GET rest/2.0/repos/bbb44e57-ab8e-451e-b89d-1c193e5ee2dd/models/6ae1d61c-f5da-4957-828c-8b7c61297ae6


http://localhost:7080/ADOxxWeb/rest/1.0/repos/bbb44e57-ab8e-451e-b89d-1c193e5ee2dd/models/6ae1d61c-f5da-4957-828c-8b7c61297ae6


Author: BOC Group

© 2019, BOC Group /181


RESPONSE {

"locale": "en",

"item": {

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/09529521-202c-4fb7-b512-72edd299f339",

"method": "GET",

"rel": "self"

},

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/09529521-202c-4fb7-b512-72edd299f339/link",

"method": "GET",

"rel": "notebookLink"

},

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/modelgroups/3b7034d4-a336-4ed5-bef2-363d7a48c55e",

"method": "GET",

"rel": "parent"

},

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/09529521-202c-4fb7-b512-72edd299f339/imagemap",

"method": "GET",

"rel": "imageMap"

}

],

"id": "{09529521-202c-4fb7-b512-72edd299f339}",

"name": "companymap",

"type": "Company Map",


Author: BOC Group

© 2019, BOC Group /181

"artefactType": "DIAGRAM",

"metaName": "MT_COMPANY_MAP",

"link": {

"href": "http://localhost:8080/ADOxxWeb?t=view&at=1&classId=14a6bed2-071f-42af-afc7-9b00e6ae97a2&libObjID=14a6bed2-071f-42af-afc7-9b00e6ae97a2&vt=graphical&id=09529521-202c-4fb7-b512-72edd299f339"

},

"icon": {

"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B14a6bed2-071f-42af-afc7-9b00e6ae97a2%7D.png",

"rel": "icon"

},

"attributes": [

{

"name": "Description",

"metaName": "A_DESCRIPTION",


"value": ""

},

...

],

"relations": [

{

"name": "Process owner",

"metaName": "RC_OWNER",

"targets": []

},

{

"name": "Scope",

"metaName": "SCOPE",

"targets": [

{

"rest_links": [


Author: BOC Group

© 2019, BOC Group /181

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/f16bb57e-4402-4339-9242-7ee98e492149",

"method": "GET",

"rel": "self"

}

],

"id": "{f16bb57e-4402-4339-9242-7ee98e492149}",

"name": "Accounting/ balance sheet/ taxes",

"type": "Organisational Unit",

"metaName": "C_ORGANIZATIONAL_UNIT",

"direction": "OUTGOING",

"link": {

"href": "http://localhost:8080/ADOxxWeb?t=nb&at=0&classId=26efd4bb-19a5-47f1-939f-520283f3c342&libObjID=26efd4bb-19a5-47f1-939f-520283f3c342&id=f16bb57e-4402-4339-9242-7ee98e492149&rid=f16bb57e-4402-4339-9242-7ee98e492149"

},

"icon": {

"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B26efd4bb-19a5-47f1-939f-520283f3c342%7D.png",

"rel": "icon"

}

}

]

},

...

],

"objects": [

{

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-


Author: BOC Group

© 2019, BOC Group /181

afab5dd9eb8e/models/09529521-202c-4fb7-b512-72edd299f339/objects/9624da5e-3265-4ea5-aae5-2c01f3bb95cb",

"method": "GET",

"rel": "self"

}

],

"id": "{9624da5e-3265-4ea5-aae5-2c01f3bb95cb}",

"name": "Process-d736d0fb",

"type": "Process",

"metaName": "C_PROCESS"

},

...

]

}

}

9.6 Object

An API for retrieving object properties.

HTTP Method GET URL path /rest/2.0/repos/{repo_id}/objects/{object-id}?attribute={attribute}&relation={relation}&showAll={showAll} Identifiers

{repo_id}


E.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... {object-id} The ID of the object to be retrieved.

{attribute}

Optional, defines the attributes of the object that may be returned in the results set. There can be multiple attributes within a request URL. If no attribute parameter is defined all attributes of the object are returned.


{relation}

Optional, defines the relation of the object that may be returned in result. There can be many of them within a one request URL. If no relation parameter is defined then all relations of object are returned.

E.g. &relation=CUSTOM_RELATION&relation=RC_MANAGER



Author: BOC Group

© 2019, BOC Group /181

Request headers



Response JSON/XML document consisting of ID, class, name, list of properties (name, value)

9.6.1 HATEOAS Links


Endpoint

1 Self link self item objects

2 Link to object group with this object

parent item objectgroups

3 Link to the notebook (properties view)


4 Link to object usage

usage item usage

5 Link to list of available incoming relations

incomingRelations item relations/incoming

6 Link to list of available outgoing relations

outgoingRelations item relations/outgoing



9.6.2 Object Result Example

Here is a GET request that returns object information in an XML representation:

REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9


Author: BOC Group

© 2019, BOC Group /181





Content-Length: ...


<response>

<locale>en</locale>

<item id="{059f3022-eb66-4080-a980-cd6d5fed1da9}" artefactType="REPOSITORY_OBJECT" metaName="C_PRODUCT">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9" method="GET" rel="self" />

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/link" method="GET" rel="notebookLink" />

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/usage" method="GET" rel="usage" />

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objectgroups/4b49163b-4cb5-452a-9a42-62ef359613f4" method="GET" rel="parent" />

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/relations/incoming" method="GET" rel="incomingRelations" />

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/relations/outgoing" method="GET" rel="outgoingRelations" />

</rest_links>

<name>

<![CDATA[product]]>


Author: BOC Group

© 2019, BOC Group /181

</name>

<type>

<![CDATA[Product]]>

</type>

<link href="http://localhost:8080/ADOxxWeb?t=nb&at=0&classId=198fcc2f-bf30-4b9a-85ca-153aee3a7891&libObjID=198fcc2f-bf30-4b9a-85ca-153aee3a7891&id=059f3022-eb66-4080-a980-cd6d5fed1da9&rid=059f3022-eb66-4080-a980-cd6d5fed1da9" />

<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B198fcc2f-bf30-4b9a-85ca-153aee3a7891%7D.png" rel="icon" />

<attributes>

<attribute metaName="A_DESCRIPTION" attrType="STRING" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="string">

<name>

<![CDATA[Description]]>

</name>

<value></value>

</attribute>

...

</attributes>

<relations>

<relation metaName="RC_RESPONSIBLE_PERSON_DEPUTY" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="reference">

<name>

<![CDATA[Responsible person (deputy)]]>

</name>

<targets />

</relation>

<relation metaName="RC_IS_APPLICATION_OWNER" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="reference">

<name>

<![CDATA[Responsible person]]>

</name>

<targets>


Author: BOC Group

© 2019, BOC Group /181

<target id="{04eabf24-ad6a-4e77-9b2c-dca0ac0c1e3d}" metaName="USER" direction="OUTGOING">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/04eabf24-ad6a-4e77-9b2c-dca0ac0c1e3d" method="GET" rel="self" />

</rest_links>

<name>

<![CDATA[user2]]>

</name>

<type>

<![CDATA[User]]>

</type>

<link href="http://localhost:8080/ADOxxWeb?t=nb&at=0&classId=0127098d-50f0-4d0e-a054-c19de9bc9b0a&libObjID=0127098d-50f0-4d0e-a054-c19de9bc9b0a&id=04eabf24-ad6a-4e77-9b2c-dca0ac0c1e3d&rid=04eabf24-ad6a-4e77-9b2c-dca0ac0c1e3d" />

<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B0127098d-50f0-4d0e-a054-c19de9bc9b0a%7D.png" rel="icon" />

</target>

</targets>

</relation>

...

</relations>

</item>

</response>

Here is a GET request that returns object information in a JSON representation:

REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9



RESPONSE


Author: BOC Group

© 2019, BOC Group /181

{

"locale": "en",

"item": {

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9",

"method": "GET",

"rel": "self"

},

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/link",

"method": "GET",


},

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/usage",

"method": "GET",

"rel": "usage"

},

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objectgroups/4b49163b-4cb5-452a-9a42-62ef359613f4",

"method": "GET",

"rel": "parent"

},

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/relations/incoming",

"method": "GET",

"rel": "incomingRelations"

},


Author: BOC Group

© 2019, BOC Group /181

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/relations/outgoing",

"method": "GET",

"rel": "outgoingRelations"

}

],

"id": "{059f3022-eb66-4080-a980-cd6d5fed1da9}",

"name": "product",

"type": "Product",

"artefactType": "REPOSITORY_OBJECT",

"metaName": "C_PRODUCT",

"link": {

"href": "http://localhost:8080/ADOxxWeb?t=nb&at=0&classId=198fcc2f-bf30-4b9a-85ca-153aee3a7891&libObjID=198fcc2f-bf30-4b9a-85ca-153aee3a7891&id=059f3022-eb66-4080-a980-cd6d5fed1da9&rid=059f3022-eb66-4080-a980-cd6d5fed1da9"

},

"icon": {

"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B198fcc2f-bf30-4b9a-85ca-153aee3a7891%7D.png",

"rel": "icon"

},

"attributes": [

{

"name": "Description",

"metaName": "A_DESCRIPTION",


"value": ""

},

...

],

"relations": [


Author: BOC Group

© 2019, BOC Group /181

{

"name": "Responsible person (deputy)",

"metaName": "RC_RESPONSIBLE_PERSON_DEPUTY",

"targets": []

},

{

"name": "Responsible person",

"metaName": "RC_IS_APPLICATION_OWNER",

"targets": [

{

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/04eabf24-ad6a-4e77-9b2c-dca0ac0c1e3d",

"method": "GET",

"rel": "self"

}

],

"id": "{04eabf24-ad6a-4e77-9b2c-dca0ac0c1e3d}",

"name": "user2",

"type": "User",

"metaName": "USER",


"link": {

"href": "http://localhost:8080/ADOxxWeb?t=nb&at=0&classId=0127098d-50f0-4d0e-a054-c19de9bc9b0a&libObjID=0127098d-50f0-4d0e-a054-c19de9bc9b0a&id=04eabf24-ad6a-4e77-9b2c-dca0ac0c1e3d&rid=04eabf24-ad6a-4e77-9b2c-dca0ac0c1e3d"

},

"icon": {

"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B0127098d-50f0-4d0e-a054-c19de9bc9b0a%7D.png",

"rel": "icon"


Author: BOC Group

© 2019, BOC Group /181

}

}

]

},

...

]

}

}

9.7 Modelling Object

An API for retrieving modelling object properties.

HTTP Method GET URL path /rest/2.0/repos/{repo_id}/models/{model-id}/objects/{object-id}?attribute={attribute}&relation={relation}&showAll={showAll} Identifiers

{repo-id} ID of repository that is used to perform the request. Value must not contain brackets.

E.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... {model-id} ID of the model to be retrieved. Value must not contain brackets. {object-id} ID of the modelling object to be retrieved

{attribute}

Optional, defines the attributes of the modelling object that may be returned in the results set. There can be multiple attributes within a request URL. If no attribute parameter is defined all attributes of the modelling object are returned.


{relation}

Optional, defines the relation of the modeling object that may be returned in result. There can be many of them within a one request URL. If no relation parameter is defined then all relations of modeling object are returned.

E.g. &relation=CUSTOM_RELATION&relation=RC_MANAGER


Request headers Accept: application/json


Response JSON/XML document consisting of ID, class, name, list of properties (name, value)


Author: BOC Group

© 2019, BOC Group /181

9.7.1 HATEOAS Links


Endpoint

1 Self link self item modeling objects

2 Link to model parent item models

3 Link to repository object

repositoryObject item objects

4 Link to the notebook


5 Link to each reation target


9.7.2 Modelling Object Result Example

Here is a GET request that returns modelling object information in an XML representation:

REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/objects/ad26cfc2-6910-4567-9c75-d1d51bd6b1cd





Content-Length: ...


<response>

<locale>en</locale>

<item id="{ad26cfc2-6910-4567-9c75-d1d51bd6b1cd}" artefactType="MODINST" metaName="C_SUB_PROCESS" repositoryObjectId="{691cfc46-a725-4908-9078-5c0b1cd9e98f}" modelId="{f3f94bf5-25f7-4510-9744-4dbe60c10611}">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-


Author: BOC Group

© 2019, BOC Group /181

afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/objects/ad26cfc2-6910-4567-9c75-d1d51bd6b1cd?showAll=true" method="GET" rel="self" />

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/objects/ad26cfc2-6910-4567-9c75-d1d51bd6b1cd/link" method="GET" rel="notebookLink" />

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611" method="GET" rel="parent" />

</rest_links>

<name>

<![CDATA[Subprocess]]>

</name>

<type>


</type>

<link href="http://localhost:8080/ADOxxWeb?t=view&at=6&classId=d9c71c3d-1d9f-435b-9a3b-b240549dfd5a&libObjID=d9c71c3d-1d9f-435b-9a3b-b240549dfd5a&vt=graphical&id=ad26cfc2-6910-4567-9c75-d1d51bd6b1cd&mid=f3f94bf5-25f7-4510-9744-4dbe60c10611" />

<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Bd9c71c3d-1d9f-435b-9a3b-b240549dfd5a%7D.png" rel="icon" />

<attributes>

<attribute metaName="IDENTIFICATION_OF_CHANGES" attrType="ENUM" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="string">

<name>

<![CDATA[Identification of changes]]>

</name>

<value>

<![CDATA[No change]]>

</value>

</attribute>

...

</attributes>


Author: BOC Group

© 2019, BOC Group /181

<relations>

<relation metaName="RC_OWNS" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="reference">

<name>

<![CDATA[Owns]]>

</name>

<targets />

</relation>

<relation metaName="RC_REFERENCED_EVENT_ONE" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="reference">

<name>

<![CDATA[Referenced event (behaviour = one)]]>

</name>

<targets>

<target id="{d829b111-24b9-4609-be1e-24d4478927aa}" metaName="C_END_EVENT" direction="OUTGOING">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/a5791dfd-04db-45ae-bebd-d1011b779de3/objects/d829b111-24b9-4609-be1e-24d4478927aa" method="GET" rel="self" />

</rest_links>

<name>

<![CDATA[Relación de negocio terminada]]>

</name>

<type>

<![CDATA[End Event]]>

</type>

<link href="http://localhost:8080/ADOxxWeb?t=view&at=6&classId=eb70fe51-7f1e-428f-9d5a-2fd15d318ee6&libObjID=eb70fe51-7f1e-428f-9d5a-2fd15d318ee6&vt=graphical&id=d829b111-24b9-4609-be1e-24d4478927aa&mid=a5791dfd-04db-45ae-bebd-d1011b779de3" />

<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Beb70fe51-7f1e-428f-9d5a-2fd15d318ee6%7D.png" rel="icon" />

</target>


Author: BOC Group

© 2019, BOC Group /181

</targets>

</relation>

...

</relations>

</item>

</response>

Here is a GET request that returns modelling object information in a JSON representation:

REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/objects/ad26cfc2-6910-4567-9c75-d1d51bd6b1cd



RESPONSE {

"locale": "en",

"item": {

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/objects/ad26cfc2-6910-4567-9c75-d1d51bd6b1cd",

"method": "GET",

"rel": "self"

},

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/objects/ad26cfc2-6910-4567-9c75-d1d51bd6b1cd/link",

"method": "GET",


},

{


Author: BOC Group

© 2019, BOC Group /181

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611",

"method": "GET",

"rel": "parent"

}

],

"id": "{ad26cfc2-6910-4567-9c75-d1d51bd6b1cd}",

"name": "Subprocess",

"type": "Subprocess",

"artefactType": "MODINST",

"metaName": "C_SUB_PROCESS",

"link": {

"href": "http://localhost:8080/ADOxxWeb?t=view&at=6&classId=d9c71c3d-1d9f-435b-9a3b-b240549dfd5a&libObjID=d9c71c3d-1d9f-435b-9a3b-b240549dfd5a&vt=graphical&id=ad26cfc2-6910-4567-9c75-d1d51bd6b1cd&mid=f3f94bf5-25f7-4510-9744-4dbe60c10611"

},

"icon": {

"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Bd9c71c3d-1d9f-435b-9a3b-b240549dfd5a%7D.png",

"rel": "icon"

},

"attributes": [

{

"name": "Identification of changes",

"metaName": "IDENTIFICATION_OF_CHANGES",

"attrType": "ENUM",

"value": "No change"

},

...

],

"relations": [

{

"name": "Referenced event (behaviour = one)",


Author: BOC Group

© 2019, BOC Group /181

"metaName": "RC_REFERENCED_EVENT_ONE",

"targets": [

{

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/a5791dfd-04db-45ae-bebd-d1011b779de3/objects/d829b111-24b9-4609-be1e-24d4478927aa",

"method": "GET",

"rel": "self"

}

],

"id": "{d829b111-24b9-4609-be1e-24d4478927aa}",

"name": "Relación de negocio terminada",

"type": "End Event",

"metaName": "C_END_EVENT",


"link": {

"href": "http://localhost:8080/ADOxxWeb?t=view&at=6&classId=eb70fe51-7f1e-428f-9d5a-2fd15d318ee6&libObjID=eb70fe51-7f1e-428f-9d5a-2fd15d318ee6&vt=graphical&id=d829b111-24b9-4609-be1e-24d4478927aa&mid=a5791dfd-04db-45ae-bebd-d1011b779de3"

},

"icon": {

"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Beb70fe51-7f1e-428f-9d5a-2fd15d318ee6%7D.png",

"rel": "icon"

}

}

]

},

{

"name": "Referenced aggregation",


Author: BOC Group

© 2019, BOC Group /181

"metaName": "RC_REFERENCED_AGGREGATION_M",

"targets": []

},

...

],

"repositoryObjectId": "{691cfc46-a725-4908-9078-5c0b1cd9e98f}",

"modelId": "{f3f94bf5-25f7-4510-9744-4dbe60c10611}"

}

}

9.8 Model/Object/Modelling Object Link

An API for retrieving the URL of a model or object or modelling object.

HTTP Method GET URL path /rest/2.0/repos/{repo_id}/models/{model-id}/link

/rest/2.0/repos/{repo_id}/objects/{object-id}/link

/rest/2.0/repos/{repo_id}/models/{model-id}/objects/{object-id}/link Identifiers

{repo-id}


E.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/...

{model-id} The ID of the model whose URL is to be retrieved. The value must not contain brackets.

{object-id} The ID of the object whose URL is to be retrieved. Request headers Accept: application/json and application/xml

Response A JSON or XML document consisting of the URL of a specific model or object.

9.8.1 HATEOAS Links


Endpoint


Author: BOC Group

© 2019, BOC Group /181

1 Self link self item link

2 Link to parent

parent item models/objects/modeling objects

9.8.2 URL Result Example

Here is a GET request that returns a model URL in an XML representation:

REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/link




Content-Length: ...

<xml version="1.0" encoding="UTF-8" standalone="yes"?>

<response>

<item>

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/link" method="GET" rel="self" />


</rest_links>

<link href="http://localhost:8080/ADOxxWeb?t=view&at=1&classId=aee098ea-071d-4150-8ce9-011eaf93643f&libObjID=aee098ea-071d-4150-8ce9-011eaf93643f&vt=graphical&id=f3f94bf5-25f7-4510-9744-4dbe60c10611" />

</item>

</response>

Here is a GET request that returns a model URL in a JSON representation:

REQUEST


Author: BOC Group

© 2019, BOC Group /181

GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/link


RESPONSE {

"item": {

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/link",

"method": "GET",

"rel": "self"

},

{


"method": "GET",

"rel": "parent"

}

],

"link": {

"href": "http://localhost:8080/ADOxxWeb?t=view&at=1&classId=aee098ea-071d-4150-8ce9-011eaf93643f&libObjID=aee098ea-071d-4150-8ce9-011eaf93643f&vt=graphical&id=f3f94bf5-25f7-4510-9744-4dbe60c10611"

}

}

}

9.9 Model Image Map

An API for retrieving the image map of a model. An image map consists of the coordinates behind the graphic representation of the model. You can find out exactly where objects lie and what size they have.

HTTP Method GET URL path


Author: BOC Group

© 2019, BOC Group /181

/rest/2.0/repos/{repo_id}/models/{model-id}/imagemap?dpi={dpi} Identifiers

{repo-id}


e.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/...

{model-id} The ID of the model whose imagemap is to be retrieved. The value must not contain brackets.

{dpi}

Optional, defines the DPIs in which the image is generated. 300 by default.

Cached DPIs: 300, 150 and 72, images for any other value are generated at runtime.

Note: DPI should not be smaller or equal to zero. Request headers Accept: application/json and application/xml


Response A JSON or XML document consisting of information about the model (ID, model, class ID, time of change, image - base64 encoded string) and list of contained modelling objects.

9.9.1 HATEOAS Links


Endpoint

1 Self link self item imagemap

2 Link to model parent item models

3 Self link to every model instance

self modelInstance modeling objects

4 Link to repository object of every model instance

repositoryObject modelInstance objects

9.9.2 Image Map Result Example

Here is a GET request that returns a model image map in an XML representation:

REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/imagemap




Author: BOC Group

© 2019, BOC Group /181



Content-Length: ...

<xml version="1.0" encoding="UTF-8" standalone="yes"?>

<response>

<model id="{f3f94bf5-25f7-4510-9744-4dbe60c10611}" type="MODEL" classId="{aee098ea-071d-4150-8ce9-011eaf93643f}" changeTime="1548842838183">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/imagemap" method="GET" rel="self" />


</rest_links>

<name>

<![CDATA[modelo]]>

</name>

<posInfo width="6455" height="3784" x="0" y="0" />

<modelInstances>

<modelInstances id="{ad26cfc2-6910-4567-9c75-d1d51bd6b1cd}" type="INSTANCE" classId="{d9c71c3d-1d9f-435b-9a3b-b240549dfd5a}" repositoryObjectId="{691cfc46-a725-4908-9078-5c0b1cd9e98f}">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/objects/ad26cfc2-6910-4567-9c75-d1d51bd6b1cd" method="GET" rel="self" />

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/691cfc46-a725-4908-9078-5c0b1cd9e98f" method="GET" rel="repositoryObject" />

</rest_links>

<name>



Author: BOC Group

© 2019, BOC Group /181

</name>

<posInfo width="634" height="321" x="1976" y="946" />

</modelInstances>

...

</modelInstances>

<image><![CDATA[iVBORw0KGgoAAAANSUhEUgAAFucAAA4+CAIAAABJ2+5FAAAACXBIW...]]></image>

</model>

</response>

Here is a GET request that returns a model image map in a JSON representation:

REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/imagemap



RESPONSE {

"item": {

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/imagemap",

"method": "GET",

"rel": "self"

},

{


"method": "GET",

"rel": "parent"

}

],


Author: BOC Group

© 2019, BOC Group /181

"id": "{f3f94bf5-25f7-4510-9744-4dbe60c10611}",

"name": "modelo",

"type": "MODEL",

"classId": "{aee098ea-071d-4150-8ce9-011eaf93643f}",

"width": 6455,

"height": 3784,

"x": 0,

"y": 0,

"modelInstances": [

{

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/objects/ad26cfc2-6910-4567-9c75-d1d51bd6b1cd",

"method": "GET",

"rel": "self"

},

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/691cfc46-a725-4908-9078-5c0b1cd9e98f",

"method": "GET",

"rel": "repositoryObject"

}

],

"id": "{ad26cfc2-6910-4567-9c75-d1d51bd6b1cd}",

"name": "Subprocess",

"type": "INSTANCE",

"classId": "{d9c71c3d-1d9f-435b-9a3b-b240549dfd5a}",

"repositoryObjectId": "{691cfc46-a725-4908-9078-5c0b1cd9e98f}",

"width": 634,

"height": 321,

"x": 1976,


Author: BOC Group

© 2019, BOC Group /181

"y": 946

}

],

"changeTime": 1548842838183,

"image": "iVBORw0KGgoAAAANSUhEUgAAFucAAA4+CAIAAABJ2+5FAAAACXBIW..."

}

}

9.10 Object Usage

An API for retrieving modelling instances of a repository object.

Note: Object usage is based on search which means that results may be slightly out of date if they were recently changed. There may be a delay of up to 30 seconds.

HTTP Method GET URL path /rest/2.0/repos/{repo_id}/objects/{object-id}/usage Identifiers

{repo-id}



{object-id} The ID of the object whose modelling instances are to be retrieved. The value must not contain brackets.

Request headers Accept: application/json and application/xml


Response A JSON or XML document with the total number of hits and a non-null array with result items. Each result item consists of information about the object (id, name, type, etc.).

9.10.1 HATEOAS Links


Endpoint

1 Self link self root usage

2 Link to repository object parent root objects


Author: BOC Group

© 2019, BOC Group /181

3 Link to every object usage self item objects

4 Link to parent model of every object usage

parent item models

9.10.2 Object Usage Result Example

Here is a GET request that returns object usage information in an XML representation:

REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/usage Accept: application/xml




Content-Length: ...


<response>

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/usage" method="GET" rel="self" />

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9" method="GET" rel="parent" />

</rest_links>

<hitsTotal>6</hitsTotal>

<locale>en</locale>

<items>

<item id="{11055484-7d95-4545-8c16-0708f2b2af8f}" artefactType="MODINST" metaName="C_PRODUCT">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/c2c01210-d767-46ec-ac40-0cfd3d0088b0/objects/11055484-7d95-4545-8c16-0708f2b2af8f" method="GET" rel="self" />


Author: BOC Group

© 2019, BOC Group /181

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/c2c01210-d767-46ec-ac40-0cfd3d0088b0" method="GET" rel="parent" />

</rest_links>

<name>

<![CDATA[product]]>

</name>

<type>

<![CDATA[Product]]>

</type>

<modelId>

<![CDATA[{c2c01210-d767-46ec-ac40-0cfd3d0088b0}]]>

</modelId>

</item>

<item id="{19529281-834e-4ef4-99cc-02b7e5fa34b9}" artefactType="MODINST" metaName="C_PRODUCT">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/c7715a8e-6487-4a8b-8ab2-9d34b00c41c7/objects/19529281-834e-4ef4-99cc-02b7e5fa34b9" method="GET" rel="self" />

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/c7715a8e-6487-4a8b-8ab2-9d34b00c41c7" method="GET" rel="parent" />

</rest_links>

<name>

<![CDATA[product]]>

</name>

<type>

<![CDATA[Product]]>

</type>

<modelId>

<![CDATA[{c7715a8e-6487-4a8b-8ab2-9d34b00c41c7}]]>

</modelId>


Author: BOC Group

© 2019, BOC Group /181

</item>

...

</items>

</response>

Here is a GET request that returns object usage information in a JSON representation:

REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/usage



RESPONSE {

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/usage",

"method": "GET",

"rel": "self"

},

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9",

"method": "GET",

"rel": "parent"

}

],

"hitsTotal": 6,

"locale": "en",

"items": [

{

"rest_links": [

{


Author: BOC Group

© 2019, BOC Group /181

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/c2c01210-d767-46ec-ac40-0cfd3d0088b0/objects/11055484-7d95-4545-8c16-0708f2b2af8f",

"method": "GET",

"rel": "self"

},

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/c2c01210-d767-46ec-ac40-0cfd3d0088b0",

"method": "GET",

"rel": "parent"

}

],

"id": "{11055484-7d95-4545-8c16-0708f2b2af8f}",

"name": "product",

"type": "Product",



"modelId": "{c2c01210-d767-46ec-ac40-0cfd3d0088b0}"

},

{

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/c7715a8e-6487-4a8b-8ab2-9d34b00c41c7/objects/19529281-834e-4ef4-99cc-02b7e5fa34b9",

"method": "GET",

"rel": "self"

},

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/c7715a8e-6487-4a8b-8ab2-9d34b00c41c7",


Author: BOC Group

© 2019, BOC Group /181

"method": "GET",

"rel": "parent"

}

],

"id": "{19529281-834e-4ef4-99cc-02b7e5fa34b9}",

"name": "product",

"type": "Product",



"modelId": "{c7715a8e-6487-4a8b-8ab2-9d34b00c41c7}"

},

...

]

}

9.11 Object Relations

An API for retrieving a list of both incoming and outgoing relations for objects that are supported by a parent artefact.

HTTP Method GET URL path /rest/2.0/repos/{repo_id}/objects/{object_id}/relations/{direction} Identifiers

{repo-id}


e.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... {object-id} The ID of the object. The value must not contain brackets. {direction} The direction of the relation. Can be incoming or outgoing. Request headers Accept: application/json and application/xml


Response A JSON or XML document containing a list of available relations for given object. Each entry contain meta name, ui name and an amount of existing endpoints.


Author: BOC Group

© 2019, BOC Group /181



Endpoint

1 Self link self root relations/{direction}

2 Parent link parent root objects

3 Link to every endpoint of relation

self relation relations/{direction}/{meta_name}

9.11.2 Object Relations Result Example

Here is a GET request that returns an outgoing relations list in an XML reprentation:

REQUEST GET rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing Accept: application/xml



Content-Length: ...


<response>

<locale>en</locale>

<rest_links>

<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing" method="GET" rel="self" />

<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5" method="GET" rel="parent" />

</rest_links>

<relations>

<relation metaName="RC_REFERENCED_IT_SYSTEM_MODEL">

<rest_links>

<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-


Author: BOC Group

© 2019, BOC Group /181

926c4b5cdbe5/relations/outgoing/RC_REFERENCED_IT_SYSTEM_MODEL" method="GET" rel="self" />

</rest_links>

<name>

<![CDATA[Referenced IT system model]]>

</name>

<numberOfEndpoints>

<![CDATA[0]]>

</numberOfEndpoints>

</relation>

<relation metaName="RC_RESPONSIBLE_FOR_OQ">

<rest_links>

<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_RESPONSIBLE_FOR_OQ" method="GET" rel="self" />

</rest_links>

<name>

<![CDATA[Responsible for open question]]>

</name>

<numberOfEndpoints>

<![CDATA[0]]>

</numberOfEndpoints>

</relation>

...

</relations>

</response>

Here is a GET request that returns an outgoing relations list in a JSON representation:

REQUEST GET rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing


RESPONSE


Author: BOC Group

© 2019, BOC Group /181

{ "locale": "en",

"rest_links": [

{

"href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing",

"method": "GET",

"rel": "self"

},

{

"href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5",

"method": "GET",

"rel": "parent"

}

],

"relations": [

{

"rest_links": [

{

"href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_REFERENCED_DOCUMENTS",

"method": "GET",

"rel": "self"

}

],

"relation": {

"metaName": "RC_REFERENCED_DOCUMENTS",

"name": "Referenced documents",

"numberOfEndpoints": 0

}

http://localhost:8000/ADONISNP6_0_1/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing



http://localhost:8000/ADONISNP6_0_1/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5

http://localhost:8000/ADONISNP6_0_1/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5

http://localhost:8000/ADONISNP6_0_1/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_REFERENCED_DOCUMENTS




Author: BOC Group

© 2019, BOC Group /181

},

{

"rest_links": [

{

"href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_CONNECTOR",

"method": "GET",

"rel": "self"

}

],

"relation": {

"metaName": "RC_CONNECTOR",

"name": "Connector",

"numberOfEndpoints": 0

}

},

...

]

}

9.12 Object Relation Endpoints

An API for retrieving incoming or outgoing relation endpoints.

HTTP Method GET URL path /rest/2.0/repos/{repo_id}/objects/{object_id}/relations/{direction}/{rel_name} Identifiers

{repo-id}


e.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... {object-id} The ID of the object. The value must not contain brackets. {direction} The direction of the relation. Can be incoming or outgoing. {rel_name} Meta name of the relation

http://localhost:8000/ADONISNP6_0_1/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_CONNECTOR




Author: BOC Group

© 2019, BOC Group /181



Response A JSON or XML document containing a list of endpoint relations of a specific type for the given object, basic information about "from" and "to" artefacts (id, metaName, ui name, type, and artefactType).



Endpoint

1 Self link self root relations/{direction}/{rel_name}

2 Parent link parent root relations/{direction}

3 Link to relation details of every relation

self relation relations/{direction}/{rel_name}/{artefact_id}

4 Link to artefacts of every relation

self from or to objects/models/modelInstance

9.12.2 Object Relation Endpoint Result Example

Here is a GET request that returns an outgoing relation endpoints list in an XML representation:

REQUEST GET rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_RISK_R Accept: application/xml



Content-Length: ...



Author: BOC Group

© 2019, BOC Group /181

<response>

<locale>en</locale>

<rest_links>

<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_RISK_R" method="GET" rel="self" />

<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing" method="GET" rel="parent" />

</rest_links>

<relations>

<relation>

<rest_links>

<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_RISK_R/17d70f5d-684a-4c3d-bb02-095a309f089d" method="GET" rel="self" />

</rest_links>

<from>

<id>

<![CDATA[{0c301f28-6f53-4145-afe2-926c4b5cdbe5}]]>

</id>

<metaName>

<![CDATA[C_APPLICATION]]>

</metaName>

<name>

<![CDATA[Internet search engine]]>

</name>

<type>

<![CDATA[Application]]>

</type>

<artefactType>

<![CDATA[REPOSITORY_OBJECT]]>

</artefactType>

<rest_links>


Author: BOC Group

© 2019, BOC Group /181

<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5" method="GET" rel="self" />

</rest_links>

</from>

<to>

<id>

<![CDATA[{17d70f5d-684a-4c3d-bb02-095a309f089d}]]>

</id>

<metaName>

<![CDATA[C_RISK]]>

</metaName>

<name>

<![CDATA[Riskno2]]>

</name>

<type>

<![CDATA[Risk]]>

</type>

<artefactType>


</artefactType>

<rest_links>

<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/17d70f5d-684a-4c3d-bb02-095a309f089d" method="GET" rel="self" />

</rest_links>

</to>

</relation>

...

</relations>

</response>


Author: BOC Group

© 2019, BOC Group /181

Here is a GET request that returns an outgoing relation endpoints list in a JSON representation:

REQUEST GET rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_RISK_


RESPONSE { "locale": "en", "rest_links": [ { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_RISK_R", "method": "GET", "rel": "self" }, { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing", "method": "GET", "rel": "parent" } ], "relations": [ { "rest_links": [ { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_RISK_R/17d70f5d-684a-4c3d-bb02-095a309f089d", "method": "GET", "rel": "self" } ], "from": { "id": "{0c301f28-6f53-4145-afe2-926c4b5cdbe5}", "metaName": "C_APPLICATION", "name": "Internet search engine", "type": "Application", "artefactType": "REPOSITORY_OBJECT",


Author: BOC Group

© 2019, BOC Group /181

"rest_links": [ { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5", "method": "GET", "rel": "self" } ] }, "to": { "id": "{17d70f5d-684a-4c3d-bb02-095a309f089d}", "metaName": "C_RISK", "name": "Riskno2", "type": "Risk", "artefactType": "REPOSITORY_OBJECT", "rest_links": [ { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/17d70f5d-684a-4c3d-bb02-095a309f089d", "method": "GET", "rel": "self" } ] } }, ... ] }

9.13 Object Relation Endpoint Details

An API for retrieving details of an incoming or outgoing relation endpoint.

HTTP Method GET URL path /rest/2.0/repos/{repo_id}/objects/{object_id}/relations/{direction}/{rel_name}/{artefact_id} Identifiers

{repo-id}




Author: BOC Group

© 2019, BOC Group /181

{object-id} The ID of the object. The value must not contain brackets. {direction} The direction of the relation. Can be incoming or outgoing. {rel_name} Meta name of the relation. {artefact_id} The ID of the relation target artefact. The value must not contain brackets. Request headers Accept: application/json and application/xml


Response A JSON or XML document containing a "from" and "to" relations artefact, with metaName, ui name, type and artefact type, and a list of endpoint attributes containing ui name, metaName, attribute type and value.



Endpoint

1 Self link self root relations/{direction}/{rel_name}/{artefact_id}

2 Relation endpoint patch link

patch root relations/{direction}/{rel_name}/{artefact_id}

3 Relation endpoint delete link

delete root relations/{direction}/{rel_name}/{artefact_id}

4 Parent link parent root relations/{direction}/{rel_name}

5 Link to each artefact

self "from" or "to" artefact

objects/models/modelInstance

9.13.2 Object Relation Endpoint Details Result Example

Here is a GET request that returns outgoing relation details (artefacts and attributes) in an XML representation:

REQUEST GET rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577 Accept: application/xml

RESPONSE


Author: BOC Group

© 2019, BOC Group /181

HTTP/1.1 200 OK


Content-Length: ...


<response>

<locale>en</locale>

<rest_links>

<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577" method="GET" rel="self" />

<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577" method="PATCH" rel="patch" />

<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577" method="DELETE" rel="delete" />

<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R" method="GET" rel="parent" />

</rest_links>

<relation>

<from>

<id>

<![CDATA[{15d40171-08aa-4497-a090-86826eba1ed3}]]>

</id>

<metaName>

<![CDATA[C_PRODUCT]]>

</metaName>

<name>

<![CDATA[ProductTest]]>

</name>

<type>

<![CDATA[Product]]>

</type>


Author: BOC Group

© 2019, BOC Group /181

<artefactType>


</artefactType>

<rest_links>

<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3" method="GET" rel="self" />

</rest_links>

</from>

<to>

<id>

<![CDATA[{22e0edf2-952e-4e56-a229-961b8ddc0577}]]>

</id>

<metaName>

<![CDATA[C_RISK]]>

</metaName>

<name>

<![CDATA[Riskno1]]>

</name>

<type>

<![CDATA[Risk]]>

</type>

<artefactType>


</artefactType>

<rest_links>

<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/22e0edf2-952e-4e56-a229-961b8ddc0577" method="GET" rel="self" />

</rest_links>

</to>

<attributes>


Author: BOC Group

© 2019, BOC Group /181

<attribute metaName="NAME" attrType="ADOSTRING" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="string">

<name>

<![CDATA[Name]]>

</name>

<value></value>

</attribute>

</attributes>

</relation>

</response>

Here is a GET request that returns outgoing relation details (artefacts and attributes) in a JSON representation:

REQUEST GET rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577


RESPONSE { "locale": "en", "rest_links": [ { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577", "method": "GET", "rel": "self" }, { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577", "method": "PATCH", "rel": "patch" }, "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577",


Author: BOC Group

© 2019, BOC Group /181

"method": "DELETE", "rel": "delete" }, { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R", "method": "GET", "rel": "parent" } ], "from": { "id": "{15d40171-08aa-4497-a090-86826eba1ed3}", "metaName": "C_PRODUCT", "name": "ProductTest", "type": "Product", "artefactType": "REPOSITORY_OBJECT", "rest_links": [ { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3", "method": "GET", "rel": "self" } ] }, "to": { "id": "{22e0edf2-952e-4e56-a229-961b8ddc0577}", "metaName": "C_RISK", "name": "Riskno1", "type": "Risk", "artefactType": "REPOSITORY_OBJECT", "rest_links": [ { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/22e0edf2-952e-4e56-a229-961b8ddc0577", "method": "GET", "rel": "self" } ] }, "attributes": [ {


Author: BOC Group

© 2019, BOC Group /181

"name": "Name", "metaName": "NAME", "attrType": "ADOSTRING", "value": "" } ] }

10 Repository Write APIs

This section lists the available repository write APIs.

10.1 Repository Objects

10.1.1 Create Object

An API for creating new repository objects. After execution, a new object resource with a unique ID will be created. If successful, a 201 status will be returned with the full resource body and a link to the new resource available in the "Location" header.

HTTP Method POST URL path /rest/2.0/repos/{repo_id}/objects Identifiers {repo_id} ID of the repository Body Content-type:application/json

The following properties can be set at root level: name, metaName, groupId, attributes.

• The "name" and "metaName" properties are required for object creation, otherwise a bad request (400) status is returned.

• The property "groupId" is optional, when not passed, the object will be created in the “_Unassigned” group.

• The property "attributes" is optional. NAME as an attribute is forbidden on object creation. • The Property "attributes" is a list of JSON objects. • The property "metaName" is required, "value" is required only if the attribute does not support

no value.

To set no value for a specific object attribute, the JSON attribute definition should have null value, e.g.

{


Author: BOC Group

© 2019, BOC Group /181

"name":"New Risk", "metaName":"C_RISK", "groupId":"{227f1a76-dd6f-4c03-aed9-36e07e82a14c}", "attributes": [ { "metaName": "A_DESCRIPTION", "value": "Description value to be set" }, { "metaName": "A_SHOW_SYMBOL_IF_COTROLS_EXIST", "value": true } ] } Request headers

Content-type: application/json


Content-Language: ISO 639-1 language code

Response A JSON or XML document with newly created object information (see Object result example). Response Headers

Location

A link to the newly created resource.

e.g. http:/ ... /rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/602021e6-8a47-4b10-a8b8-ed0c325f129c

10.1.2 Delete Object

An API for deleting object resources. If successful, a 204 status will be returned without any content. A 404 status will be returned in case when the resource does not exist. In case the resource is locked, the status 423 Locked will be returned.

In case there are no access rights to the object, a 403 Forbidden status will be returned. A 409 Conflict status will be returned in case the repository object is referenced in any model.

HTTP Method DELETE URL path /rest/2.0/repos/{repo_id}/objects/{object_id} Identifiers


Author: BOC Group

© 2019, BOC Group /181

{repo_id} ID of the repository {object_id} ID of the object Response: No content

10.1.3 Modify Object

An API for editing object attributes. If successful, a 200 status will be returned with the full resource body and a link to the resource available in the "Location" header. A 404 status will be returned in case the resource does not exist. In case the resource is locked, a status 423 Locked will be returned.

In case there are no access rights to the object, a 403 Forbidden status will be returned.

HTTP Method PATCH URL path /rest/2.0/repos/{repo_id}/objects/{object_id} Identifiers {repo_id} ID of the repository {object_id} ID of the object Body Content-type: application/json

A JSON object containing list of attributes that needs to be updated. Language dependent values will only be updated for the language which is passed in request header.

Note: To set no value of a specific object attribute, the JSON attribute value should be null, .e.g.

{ "attributes": [ { "metaName": "A_DESCRIPTION", "value": "New description value to be set" }, { "metaName": "A_SHOW_SYMBOL_IF_COTROLS_EXIST", "value": true } ] } Request headers


Author: BOC Group

© 2019, BOC Group /181




Response A JSON or XML document with the updated object (see Object result example). Response Headers

Location

Link to modified object

e.g. http:/ ... /rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/602021e6-8a47-4b10-a8b8-ed0c325f129c

10.1.4 Move Object

An API for changing the parent group of a repository object. If successful, a 200 status will be returned with the full resource body and a link to the resource available in the "Location" header. A 404 status will be returned in case the resource (object or target object group) does not exist. In case the resource is locked, a status 423 Locked will be returned.

In case there are no access rights to the object or target group, a 403 Forbidden status will be returned.

HTTP Method POST URL path /rest/2.0/repos/{repo_id}/objects/{object_id}/actions?type=move Identifiers {repo_id} ID of the repository {object_id} ID of the object Body Content-type: application/json

A JSON object containing the id of the group to which the resource should be relocated, .e.g.

{"groupId":"{96ced025-fc85-46a7-be44-eb29e6d5b5ad}"} Request headers Content-type: application/json and application/xml

Acceot-Language: ISO 639-1 language code Response A JSON or XML document with the moved object (see Object result example). Response Headers


Author: BOC Group

© 2019, BOC Group /181

Location

Link to the modified object

e.g.http:/.../rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/602021e6-8a47-4b10-a8b8-ed0c325f129c

10.2 Object Group

10.2.1 Create Object Group

An API for creating new object groups. If parentGroupId is not passed, the group will be created in the root object group.

HTTP Method POST URL path /rest/2.0/repos/{repo_id}/objectgroups Identifiers {repo_id} ID of the repository Body Content-type:application/json

JSON properties:

• Name • parentGroupId - (optional) ID of the parent group

Sample data:

{ "name": "groupName", "parentGroupId" : "{cb2fdc3c-0a36-40ea-9150-35c7f5662357}" } Request headers




Response A JSON or XML document with the created object group (see Object Group example). Response Headers

Location A link to the newly created resource.


Author: BOC Group

© 2019, BOC Group /181

e.g. http:/ ... /rest/2.0/repos/adff255a-9806-4e0b-8069-caeb2e59092e/objectgroups/96ced025-fc85-46a7-be44-eb29e6d5b5ad

10.2.2 Delete Object Group

An API for deleting object groups and sub groups. If successful, a 204 status will be returned without any content. A 404 status will be returned in case when the resource does not exist. In case the resource is locked, the status 423 Locked will be returned.

In case there are no access rights to the object group, a 403 Forbidden status will be returned. A 409 Conflict status will be returned in case the repository object is referenced in any model.

HTTP Method DELETE URL path /rest/2.0/repos/{repo_id}/objectgroups/{group-id}

/rest/2.0/repos/{repo_id}/objectgroups/{group-id}?recursive=true Identifiers {repo_id} ID of the repository {object_id} ID of the object Parameters Parameters should be inserted after the question mark, after {group-id}. Parameters are optional.

recursive (boolean)

Default false, if set to true then the whole tree beginning from the object group which ID was specified as group-id will be deleted.

Response: No content

10.2.3 Modify Object Group

APIs for modifying object groups.

Change Attributes

An API for modifying the name attribute of a group.

HTTP Method PATCH URL path /rest/2.0/repos/{repo_id}/objectgroups/{group_id} Identifiers {repo_id} ID of the repository {object_id} ID of the object


Author: BOC Group

© 2019, BOC Group /181

Body Content-type: application/json

A JSON object containing the “name” attribute. The name will only be updated for the language which is passed in request header.

Sample data:

{ "name":"newDefaultName" } Request headers




Response A JSON or XML document with the updated object group (see Object Group example). Response Headers

Location

A link to the modified object group.


Relocate Group

An API for moving an object group to another parent group.

HTTP Method POST URL path /rest/2.0/repos/{repo_id}/objectgroups/{group_id}/actions?type=move Identifiers {repo_id} ID of the repository {object_id} ID of the object Parameters To perform a group relocation, the mandatory parameter "type" with value "move" is required in the URL. The parameter should be inserted after the question mark, after ../actions. Body Content-type: application/json

A JSON object containing the "targetGroupId" property which is the ID of the new parent group.

Sample data:

{


Author: BOC Group

© 2019, BOC Group /181

"targetGroupId":"{96ced025-fc85-46a7-be44-eb29e6d5b5ad}" } Request headers




Response A JSON or XML document with the moved object group (see Object Group example). Response Headers

Location

A link to the moved object group.

e.g. http:/ ... /rest/2.0/repos/adff255a-9806-4e0b-8069-caeb2e59092e/objectgroups/89ced025-fc85-46a7-bu44-eb29e6d5b5ad

Relocate Elements

An API for moving repository objects to another object group. In the event of an error, there is information about which element caused the error and which elements were successfully moved.

HTTP Method POST URL path /rest/2.0/repos/{repo_id}/objectgroups/{group_id}/actions?type=moveContainedElements Identifiers {repo_id} ID of the repository {object_id} ID of the object Parameters To perform a group relocation, the mandatory parameter "type" with value " moveContainedElements" is required in the URL. The parameter should be inserted after the question mark, after ../actions. Body Content-type: application/json

A JSON object containing the "targetGroupId" property which is the ID of the target group for moved objects and the "elementId" property which is a list of repository object ID elements.

Sample data:

{ "elementId":["{6768bc93-1c34-4143-94ea-60b685bdba97}", "{1c5dde0e-ec8d-42c3-9736-2ef65000be75}", "{76ced025-fc85-46a7-be44-eb29e6d5b5es}"], "targetGroupId":"{96ced025-fc85-46a7-be44-eb29e6d5b5ad}" }


Author: BOC Group

© 2019, BOC Group /181

Request headers




Response A JSON or XML document with the target object group (see Object Group example). Response Headers

Location

A link to the target object group to which objects were moved.


10.3 Object Relations

10.3.1 Create Endpoint

An API for creating a new incoming or outgoing endpoint.

HTTP Method POST URL path /rest/2.0/repos/{repo_id}/objects/{group_id}/relations/{direction}/{rel_name} Identifiers {repo_id} ID of the repository {group_id} ID of the object {direction} Direction of the relation. Can be incoming or outgoing. {rel_name} Meta name of the relation Body Content-type:application/json

A JSON object containing:

• toId (for outgoing direction) / fromId (for incoming direction) • attributes (optional)

o metaName o value

• modelId (if relation is between modelling instances)

The property "attributes" is a list of JSON objects. The property "metaName" is required, "value" is required only if the attribute does not support no value.


Author: BOC Group

© 2019, BOC Group /181

Sample data for outgoing:

{ "toId" : "{22e0edf2-952e-4e56-a229-961b8ddc0577}", "attributes" : [ { "metaName": "A_DESCRIPTION_CS", "value": "Description value to be set" }, { "metaName": "DENOMINATION", "value": "Rel name" } ] }

Sample data for incoming:

{ "fromId" : "{22e0edf2-952e-4e56-a229-961b8ddc0577}", "attributes" : [ { "metaName": "A_DESCRIPTION_CS", "value": "Description value to be set" }, { "metaName": "DENOMINATION", "value": "Rel name" } ] } Request headers




Response A JSON or XML document with the created relation (see Object relation endpoint details example). Response Headers


Author: BOC Group

© 2019, BOC Group /181

Location

A link to the newly created relation.

e.g. http:/.../rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/44f8be9e-93e5-4a69-bd14-6c69db4ee5b4/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577

10.3.2 Update Endpoint

An API for modifying attributes of an incoming or outgoing relation endpoint.

HTTP Method PATCH URL path /rest/2.0/repos/{repo_id}/objects/{group_id}/relations/{direction}/{rel_name}/{artefact_id} Identifiers {repo_id} ID of the repository {group_id} ID of the object {direction} Direction of the relation. Can be incoming or outgoing. {rel_name} Meta name of the relation {artefact_id} ID of the target artefact in relation Body Content-type:application/json

A JSON object containing:

• attributes o metaName o value

The property "attributes" is a list of JSON objects. The property "metaName" is required, "value" is required only if the attribute does not support no value.

Language dependent values will only be updated for the language which is passed in request header.

Sample data:

{ "attributes" : [ { "metaName": "NAME", "value": "New Relation Name" } ]


Author: BOC Group

© 2019, BOC Group /181

} Request headers




Response A JSON or XML document with the updated relation (see Object relation endpoint details example). Response Headers

Location

A link to the updated relation.

e.g. http:/.../rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/44f8be9e-93e5-4a69-bd14-6c69db4ee5b4/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577

10.3.3 Delete Endpoint

An API for deleting an incoming or outgoing relation endpoint.

HTTP Method DELETE URL path /rest/2.0/repos/{repo_id}/objects/{group_id}/relations/{direction}/{rel_name}/{artefact_id} Identifiers {repo_id} ID of the repository {group_id} ID of the object {direction} Direction of relation. Can be incoming or outgoing. {rel_name} Meta name of the relation {artefact_id} ID of the target artefact in relation Response: No content A JSON or XML document with the updated relation (see Object relation endpoint details example).

11 Repository Search APIs

This section lists the available repository search APIs.


Author: BOC Group

© 2019, BOC Group /181

11.1 Search Queries

Search queries have to be treated differently than the previous types of resources, as search queries are no actual resources that can be queried or modified.

11.1.1 Performing a Generic Search Query

An API for performing the query.

Important note: If no range is set (identifier {range-end}), 1000 objects are returned (from 0 to 999).

HTTP Method GET URL path /rest/2.0/repos/{repo_id}/search/?query={filters:[{filter_object},{}…]}&range-start={range-start}&range-end={range-end}&attribute={attribute} Identifiers

{repo_id}

The ID of the repository that is used to perform the search. The value must not contain brackets.


min = 1

max = 1

{query}

The search term that is used to perform the search. This parameter is passed as a JSON object called “filters” which is of type array. Each object on the array is a separate filter in terms of ado.query API.

e.g. …?query={"filters":[{className: "C_ACTOR"},{attrName: "A_DESCRIPTION", value: "This is a description", op: "OP_EQ"}]

filters: Filter object as defined by ado.query API. See section 11.1.4 for a summary.

min = 1

max = 1

{attribute}

Optional, defines the attributes of the result objects (models, objects) that may be returned in the results set. There can be multiple attributes within a request URL. If no attribute parameter is defined, all attributes from the query are returned.

e.g. &attribute=CUSTOM_ATTRIBUTE&attribute=A_DESCRIPTION

min = 0

max = many

{range-start}

Optional, defines the start of the range of results to be fetched from the total result. A default value is 0.

e.g. …range-start=0

min=0 max=1

{range-end}

Optional, defines the end of the range of results to be fetched from the total result. A default value is not configurable yet. -1 denotes all results. By default 1000 objects are returned (from 0 to 999).

e.g. …range-end=10

min=0 max=1

Request headers Accept: application/json or application/xml (dictates response format)



Author: BOC Group

© 2019, BOC Group /181

Response A JSON or XML object with properties representing metadata of the response (number of total hits, etc.) and a nonnull array with result items. Each result item should in turn contain its meta data and a nonnull array with its properties.



Endpoint

1 Self link self root search

2 Link to previous bundle of results(if existing)

previous root search

3 Link to next bundle of results(if existing)

next root search

4 Link to each result self item models/objects/modelling objects


self target models/objects/modelling objects

11.1.3 Result Examples for a Simple Query

Here is a GET request to fetch an object, requesting details in an XML representation:

REQUEST GET rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/search?query={"filters":[{className:"C_ROLE"},{attrName:"NAME", value: "Manager", op:"OP_LIKE"}]}&attribute=A_DESCRIPTION&attribute=RC_OWNER&range-start=0&range-end=99


Accept-Language : en RESPONSE HTTP/1.1 200 OK Content-Type: application/xml Content-Length: ...



Author: BOC Group

© 2019, BOC Group /181

<response> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/search?query=%7B%22filters%22%3A%5B%7BclassName%3A%22C_ROLE%22%7D%2C%7BattrName%3A%22NAME%22%2C+value%3A+%22Manager%22%2C+op%3A%22OP_LIKE%22%7D%5D%7D&attribute=A_DESCRIPTION&attribute=RC_OWNER&range-start=0&range-end=99" method="GET" rel="self"/> </rest_links> <hitsTotal>7</hitsTotal> <locale>en</locale> <rangeStart>0</rangeStart> <rangeEnd>7</rangeEnd> <items> <item id="{a6633d0b-d5cc-4b69-bbea-0873061212be}" artefactType="REPOSITORY_OBJECT" metaName="C_ROLE"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/a6633d0b-d5cc-4b69-bbea-0873061212be" method="GET" rel="self"/> </rest_links> <name><![CDATA[Audit Manager]]></name> <type><![CDATA[Role]]></type> <link href="http://localhost:8080/ADOxxWeb/?t=nb&at=0&id=a6633d0b-d5cc-4b69-bbea-0873061212be&classId=38c98349-4425-40f7-8712-2d90e014228c&repoid=e1138bdc-4063-490e-95f8-986d18c79ac3&rid=a6633d0b-d5cc-4b69-bbea-0873061212be"/> <icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B38c98349-4425-40f7-8712-2d90e014228c%7D.png" rel="icon"/> <attributes> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="A_DESCRIPTION" attrType="STRING" xsi:type="string"> <name><![CDATA[Description]]></name> <value/> </attribute> </attributes>

http://localhost:8080/ADOxxWeb/rest/1.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/search?query=%7B%22filters%22%3A%5B%7BclassName%3A%22C_ROLE%22%7D%2C%7BattrName%3A%22NAME%22%2C+value%3A+%22Manager%22%2C+op%3A%22OP_LIKE%22%7D%5D%7D&attribute=A_DESCRIPTION&attribute=RC_OWNER&range-start=0&range-end=99






http://localhost:8080/ADOxxWeb/rest/1.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/a6633d0b-d5cc-4b69-bbea-0873061212be


http://localhost:8080/ADOxxWeb/?t=nb&at=0&id=a6633d0b-d5cc-4b69-bbea-0873061212be&classId=38c98349-4425-40f7-8712-2d90e014228c&repoid=e1138bdc-4063-490e-95f8-986d18c79ac3&rid=a6633d0b-d5cc-4b69-bbea-0873061212be




http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B38c98349-4425-40f7-8712-2d90e014228c%7D.png


http://www.w3.org/2001/XMLSchema-instance


Author: BOC Group

© 2019, BOC Group /181

</item> <item id="{ad74e247-929b-4344-9380-7604dcee608a}" artefactType="REPOSITORY_OBJECT" metaName="C_ROLE"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/ad74e247-929b-4344-9380-7604dcee608a" method="GET" rel="self"/> </rest_links> <name><![CDATA[Private Customer Account Manager]]></name> <type><![CDATA[Role]]></type> <link href="http://localhost:8080/ADOxxWeb/?t=nb&at=0&id=ad74e247-929b-4344-9380-7604dcee608a&classId=38c98349-4425-40f7-8712-2d90e014228c&repoid=e1138bdc-4063-490e-95f8-986d18c79ac3&rid=ad74e247-929b-4344-9380-7604dcee608a"/> <icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B38c98349-4425-40f7-8712-2d90e014228c%7D.png" rel="icon"/> <attributes> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="A_DESCRIPTION" attrType="STRING" xsi:type="string"> <name><![CDATA[Description]]></name> <value/> </attribute> </attributes> </item> ... </items> </response>

Here is a GET request to fetch an object, requesting details in a JSON representation:

REQUEST GET rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/search?query={"filters":[{className:"C_ROLE"},{attrName:"NAME", value: "Manager", op:"OP_LIKE"}]}&attribute=A_DESCRIPTION&attribute=RC_OWNER&range-start=0&range-end=99



http://localhost:8080/ADOxxWeb/rest/1.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/ad74e247-929b-4344-9380-7604dcee608a


http://localhost:8080/ADOxxWeb/?t=nb&at=0&id=ad74e247-929b-4344-9380-7604dcee608a&classId=38c98349-4425-40f7-8712-2d90e014228c&repoid=e1138bdc-4063-490e-95f8-986d18c79ac3&rid=ad74e247-929b-4344-9380-7604dcee608a






http://www.w3.org/2001/XMLSchema-instance


Author: BOC Group

© 2019, BOC Group /181

RESPONSE { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/search?query=%7B%22filters%22%3A%5B%7BclassName%3A%22C_ROLE%22%7D%2C%7BattrName%3A%22NAME%22%2C+value%3A+%22Manager%22%2C+op%3A%22OP_LIKE%22%7D%5D%7D&attribute=A_DESCRIPTION&attribute=RC_OWNER&range-start=0&range-end=99", "method": "GET", "rel": "self" } ], "hitsTotal": 7, "locale": "en", "rangeStart": 0, "rangeEnd": 7, "items": [ { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/a6633d0b-d5cc-4b69-bbea-0873061212be", "method": "GET", "rel": "self" } ], "id": "{a6633d0b-d5cc-4b69-bbea-0873061212be}", "name": "Audit Manager", "type": "Role", "artefactType": "REPOSITORY_OBJECT", "metaName": "C_ROLE", "link": {









Author: BOC Group

© 2019, BOC Group /181

"href": "http://localhost:8080/ADOxxWeb/?t=nb&at=0&id=a6633d0b-d5cc-4b69-bbea-0873061212be&classId=38c98349-4425-40f7-8712-2d90e014228c&repoid=e1138bdc-4063-490e-95f8-986d18c79ac3&rid=a6633d0b-d5cc-4b69-bbea-0873061212be" }, "icon": { "href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B38c98349-4425-40f7-8712-2d90e014228c%7D.png", "rel": "icon" }, "attributes": [ { "name": "Description", "metaName": "A_DESCRIPTION", "attrType": "STRING", "value": "" } ] }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/ad74e247-929b-4344-9380-7604dcee608a", "method": "GET", "rel": "self" } ], "id": "{ad74e247-929b-4344-9380-7604dcee608a}", "name": "Private Customer Account Manager", "type": "Role", "artefactType": "REPOSITORY_OBJECT", "metaName": "C_ROLE", "link": {









Author: BOC Group

© 2019, BOC Group /181

"href": "http://localhost:8080/ADOxxWeb/?t=nb&at=0&id=ad74e247-929b-4344-9380-7604dcee608a&classId=38c98349-4425-40f7-8712-2d90e014228c&repoid=e1138bdc-4063-490e-95f8-986d18c79ac3&rid=ad74e247-929b-4344-9380-7604dcee608a" }, "icon": { "href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B38c98349-4425-40f7-8712-2d90e014228c%7D.png", "rel": "icon" }, "attributes": [ { "name": "Description", "metaName": "A_DESCRIPTION", "attrType": "STRING", "value": "" } ] }, ... ] }

11.1.4 Filters Definition

Filter objects may contain different properties depending on the used operator:

Operator Filters object

Empty Operator (OP_EMPTY) {attrName: "A_DESCRIPTION ", op: “OP_EMPTY”}

NoEmpty Operator (OP_NEMPTY)

{attrName: "A_DESCRIPTION ", op: “OP_NEMPTY” }

Like Operator (OP_LIKE) {attrName: "A_DESCRIPTION ", value: "string", op: “OP_LIKE”}

{attrName: "A_DESCRIPTION ", values: ["string1", "string2"], op: “OP_LIKE”}







Author: BOC Group

© 2019, BOC Group /181

Not Like Operator (OP_NLIKE) {attrName: "A_DESCRIPTION ", value: "string", op: “OP_NLIKE”}

Equal (OP_EQ) {attrName: "A_NEED_FOR_ACTION ", value: true, op: “OP_EQ”}

{attrName: "A_VALUE_AT_RISK ", value: [1, 2], op: “OP_EQ”}

NoEqual (OP_NEQ) {attrName: "A_NEED_FOR_ACTION ", value: true, op: “OP_NEQ”}

Greater (OP_GR) {attrName: "A_VALUE_AT_RISK ", value: 2, op: “OP_GR”}

Greater or equal (OP_GR_EQ) {attrName: "A_DESCRIPTION", value: "description", op: “OP_GR_EQ”}

Less (OP_LE) {attrName: "A_VALUE_AT_RISK ", value: 2, op: “OP_LE”}

Less or equal (OP_LE_EQ) {attrName: "A_DESCRIPTION", value: "description", op: “OP_LE_EQ”}

Regex Operator (OP_REGEX) {attrName: "A_DESCRIPTION", value: "^this is .*e$", op: “OP_REGEX”}

Range Operator (OP_RANGE) {attrName: "A_VALUE_AT_RISK", values: [1,3], op: “OP_RANGE”}

Not Range Operator (OP_NRANGE)

{attrName: "A_VALUE_AT_RISK", values: [1,3], op: “OP_NRANGE”}

Contains Any Operator (OP_CONTAINS_ANY)

{attrName: "APP", values:["v0", "v1", "v2"] op: “OP_CONTAINS_ANY”}

11.2 Search Jobs

An API for executing search queries using a POST job pattern. The request consists of three parts:

1. Prepare the query 2. Fetch the query result 3. Delete the query result


Author: BOC Group

© 2019, BOC Group /181

When you prepare the query, the search result is created temporarily as a resource on the server.



Endpoint

1 Self link self root search jobs

2 Link to delete the search job

delete root search jobs

3 Link to previous bundle of results(if existing)

previous root search jobs

4 Link to next bundle of results(if existing)

next root search jobs

5 Link to each result self item models/objects/modelling objects


self target models/objects/modelling objects

11.2.2 Prepare Query

First you have to prepare the query result on the server by executing a query. After execution, a new resource with a unique key will be created. If the preparation succeeds, a 201 status will be returned with a link to the new resource available in the "Location" header. The new resource is valid for one hour from the last access to it.

HTTP Method POST URL path /rest/2.0/repos/{repo_id}/search/jobs Identifiers

{repo_id}


e.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... Body Content-type:application/json


Author: BOC Group

© 2019, BOC Group /181

The search term that is used to perform the search. Passed as a JSON object called “filters” which is of type array. Each object on the array is a separate filter in terms of ado.query API. See chapter 11.1.4 for a summary.

E.g. {"filters":[{className: "C_ACTOR"},{attrName: "A_DESCRIPTION", value: "This is a description", op: "OP_EQ"}] Response headers

Location

The Link to the newly created resource

E.g. http:/ ... /rest/2.0/repos/{repo_id}/search/jobs/8f8e30d8-f79c-4c03-b27e-de2742d95276

11.2.3 Fetch Query Result

After you have successfully prepared the query result on the server, the result or parts of it can be fetched using the resource ID.

HTTP Method GET URL path /rest/2.0/repos/{repo_id}/search/jobs/{key}?range-start={range-start}&range-end={range-end}&attribute={attribute}&input-key={input-key}&combine-type={combine-type} Identifiers

{repo_id}


e.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... {key} Key of the job query resource

{attribute}

Optional, defines the attributes of the result objects (models, objects) that may be returned in results set. There can be multiple attributes within a request URL. If no attribute parameter is defined, all attributes from the query are returned.

e.g. &attribute=CUSTOM_ATTRIBUTE&attribute=A_DESCRIPTION

{range-start}

Optional, defines the start of the range of results to be fetched from the total result. A default value is 0.

e.g. …range-start=0

{range-end}

Optional, defines the end of the range of results to be fetched from the total result. A default value is not configurable yet. -1 denotes all results. By default 1000 objects are returned (from 0 to 999).

e.g. …range-end=10

{input-key} Optional, key of the job query resource. If this parameter is set, filters of both queries are merged during execution - intersect combiner type used.

{combine-type}

Optional, defines type of multiple queries combiner. Available types:


Author: BOC Group

© 2019, BOC Group /181

diff,

union,

intersect (default combiner) Request headers Accept: application/json and application/xml

Accept-Language: ISO 639-1 language code Response A JSON or XML object with properties representing metadata of the response (number of total hits, etc.) and nonnull array with result items. Each result item should in turn contain its meta data and a nonnull array with its properties.

11.2.4 Delete Query Result

After you have fetched the relevant data, you should use the following API to delete the query result on the server. After execution, a query saved under the passed key will not be available anymore If the query succeeds, a 204 status will be returned without any content. A 204 status will also be returned in case a query saved under the passed key does not exist.

HTTP Method DELETE URL path /rest/2.0/repos/{repo_id}/search/jobs/{key} Identifiers

{repo_id}


E.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... {key} The key of the job query resource. Response: No content

11.2.5 Example

Here is an example request to fetch an object, requesting details in an XML representation:

REQUEST 1 POST rest/2.0/repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/search/jobs

Body:

{"filters":[{className: "C_ROLE"},{attrName: "NAME", value: "Expert", op: "OP_EQ"}]}


Author: BOC Group

© 2019, BOC Group /181

Response headers:

Location: rest/2.0/repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/search/jobs/8f8e30d8-f79c-4c03-b27e-de2742d95276Accept: application/xml

REQUEST 2 GET rest/2.0/repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/search/jobs/8f8e30d8-f79c-4c03-b27e-de2742d95276?attribute=A_DESCRIPTION&attribute=RC_OWNER&range-start=0&range-end=99 Accept: application/xml Accept-Language : en

RESPONSE HTTP/1.1 200 OK Content-Type: application/xml Content-Length: ... <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <response> <hitsTotal>1</hitsTotal> - total amount of hits (range is not considered) <locale>en</locale> - language specified for the query <rangeStart>0</rangeStart> - start index of the results that should be returned <rangeEnd>1</rangeEnd> - rangeStart value + amount of returned results <items> - list of response objects/models <item id="{3cb965c2-6d95-4694-8f21-16e6e6f2bbdf}" metaName="C_ROLE"> - object/model id and (language independent) type <name><![CDATA[Expert]]></name> - name of an object/model (language specific) <type><![CDATA[Role]]></type> - type of an object/model (language specific) <link href="http://localhost/ADOxxWeb/?t=nb&at=0&id=3cb965c2-6d95-4694-8f21-16e6e6f2bbdf&classId=38c98349-4425-40f7-8712-2d90e014228c&repoid=5ec4e2dc-82c4-41d3-ad69-620cded63d0e&rid=3cb965c2-6d95-4694-8f21-16e6e6f2bbdf"/> - direct url to an object/model


Author: BOC Group

© 2019, BOC Group /181

<icon href="http://localhost/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B38c98349-4425-40f7-8712-2d90e014228c%7D.png" rel="icon"/> - direct link to an object/model type icon and relation type <attributes> - list of item attributes <attribute xsi:type="string" metaName="A_DESCRIPTION" attrType="STRING"> - name of an attribute (language independent) and its value type <name><![CDATA[Description]]></name> - name of an attribute (language specific) <value><![CDATA[This is a description]]</value> - attribute value (language specific) </attribute> <attributes> <attribute xsi:type="string" metaName="A_IDENTIFICATION_OF_CHANGES_NCS" attrType="ENUM"> <name><![CDATA[Identification of changes]]></name> <value><![CDATA[No change]]</value> </attribute> <attributes> <attribute xsi:type="date" metaName="A_VALID_FROM_UTC" attrType="UTC"> <name><![CDATA[Valid from]]></name> <value><![CDATA[1970-01-01T01:00:00]]</value> </attribute> <attribute xsi:type="reference" metaName="RC_OWNER" attrType="RELATION"> <name><![CDATA[Process owner]]></name> <targets> - list of target objects/models <target id="{8fe990f8-245c-4b5c-b497-38defaab0172}" metaName="MT_BUSINESS_PROCESS_DIAGRAM_BPMN_20" direction="INCOMING"> - target object/model id, direction type and type (language independent) <name><![CDATA[BP Address change 1.00]]></name> - target object/model name (language specific) <type><![CDATA[Business Process Diagram]]></type> - target object/model type (language specific) <link href="http://localhost/ADOxxWeb/?t=nb&at=1&id=8fe990f8-245c-4b5c-b497-


Author: BOC Group

© 2019, BOC Group /181

38defaab0172&classId=aee098ea-071d-4150-8ce9-011eaf93643f&repoid=5ec4e2dc-82c4-41d3-ad69-620cded63d0e&rid=8fe990f8-245c-4b5c-b497-38defaab0172"/> <icon href="http://localhost/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Baee098ea-071d-4150-8ce9-011eaf93643f%7D.png" rel="icon"/> </target > </targets> </attribute> </attributes> </item> </items> </response>

Here is an example request to fetch an object, requesting details in a JSON representation:

REQUEST 1 POST rest/2.0/repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/search/jobs

Body:

{"filters":[{className: "C_ROLE"},{attrName: "NAME", value: "Expert", op: "OP_EQ"}]}

Response headers:

Location: rest/2.0/repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/search/jobs/8f8e30d8-f79c-4c03-b27e-de2742d95276

REQUEST 2 GET rest/2.0/repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/search/jobs/8f8e30d8-f79c-4c03-b27e-de2742d95276?attribute=A_DESCRIPTION&attribute=RC_OWNER&range-start=0&range-end=99 Accept: application/json Accept-Language : en

RESPONSE { "hitsTotal": 1, - total amount of hits (range is not considered) "locale": "en", - language specified for the query "rangeStart": 0, - start index of the results that should be returned "rangeEnd": 1, - rangeStart value + amount of returned results "items": [ - list of response objects/models { "id": "{3cb965c2-6d95-4694-8f21-16e6e6f2bbdf}", - object/model id "name": "Expert", - name of an object/model (language specific)


Author: BOC Group

© 2019, BOC Group /181

"type": "Role", - type of an object/model (language specific) "metaName": "C_ROLE", - type of an object/model (language independent) "link": { - direct url to an object/model "href": "http://localhost/ADOxxWeb/?t=nb&at=0&id=3cb965c2-6d95-4694-8f21-16e6e6f2bbdf&classId=38c98349-4425-40f7-8712-2d90e014228c&repoid=5ec4e2dc-82c4-41d3-ad69-620cded63d0e&rid=3cb965c2-6d95-4694-8f21-16e6e6f2bbdf" }, "icon": { - direct link to an object/model type icon "href": "http://localhost/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B38c98349-4425-40f7-8712-2d90e014228c%7D.png", "rel": "icon" - type of link relation }, "attributes": [ - list of item attributes { "name": "Description", - attribute name (language specific) "metaName": "A_DESCRIPTION", - attribute name (language independent) "attrType": "STRING", - attribute value type "value": "This is a description" - attribute value (language specific) },{ "name": "Identification of changes", "metaName": "A_IDENTIFICATION_OF_CHANGES_NCS", "attrType": "ENUM", "value": "No change" },{ "name": "Valid from", "metaName": "A_VALID_FROM_UTC", "attrType": "UTC", "value": "1970-01-01T01:00:00" },{ "name": "Process owner", "metaName": "RC_OWNER", "attrType": "RELATION", "targets": [ - list of target objects/models { "id": "{8fe990f8-245c-4b5c-b497-38defaab0172}",


Author: BOC Group

© 2019, BOC Group /181

"name": "BP Address change 1.00", - target object/model name (language specific) "type": "Business Process Diagram", - type of the object/model (language specific) "metaName": "MT_BUSINESS_PROCESS_DIAGRAM_BPMN_20", - type of the object/model (language independent) "direction": "INCOMING", - direction of a relation "link": { "href": "http://localhost/ADOxxWeb/?t=nb&at=1&id=8fe990f8-245c-4b5c-b497-38defaab0172&classId=aee098ea-071d-4150-8ce9-011eaf93643f&repoid=5ec4e2dc-82c4-41d3-ad69-620cded63d0e&rid=8fe990f8-245c-4b5c-b497-38defaab0172" }, "icon": { "href": "http://localhost/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Baee098ea-071d-4150-8ce9-011eaf93643f%7D.png", "rel": "icon" } } ] } ] } ] }

12 User Read APIs

This section lists the available user read APIs.

12.1 User group

An API for retrieving a user group.

HTTP Method GET URL path /rest/2.0/usergroups/{group-id}

/rest/2.0/usergroups/{group-id}?recursive=true Identifiers {group-id} The ID of the group to be retrieved, root for the root user group. Request headers




Author: BOC Group

© 2019, BOC Group /181

Parameters

There is one optional Boolean flag. It should be inserted after the question mark, after {group-id}.

recursive If this flag is set to true, the whole tree is returned, beginning from the user group whose ID was specified as group ID.

Response A JSON or XML document consisting of ID, name, list of contained groups (ID and name), list of contained users (ID, type, name)



Endpoint

1 Self link self group usergroups

2 Link to parent user group (if it exists) parent group usergroups

3 Link to every user that is included in the group

self user users

5 Link to every subgroup self subgroup usergroups

12.1.2 User Group Result Example

Here is a GET request that returns user group information in an XML representation:

REQUEST GET rest/2.0/usergroups/a18c6786-7f19-455e-b666-e51d9ade038e



RESPONSE HTTP/1.1 200 OK Content-Type: application/xml Content-Length: ... <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <response> <locale>en</locale> <group id="{a18c6786-7f19-455e-b666-e51d9ade038e}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/a18c6786-7f19-455e-b666-e51d9ade038e" method="GET" rel="self"/> </rest_links> <name><![CDATA[ADO_ROOT_OBJECT_GROUP]]></name> <subgroups> <group id="{227f1a76-dd6f-4c03-aed9-36e07e82a14c}"> <rest_links>


Author: BOC Group

© 2019, BOC Group /181

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/227f1a76-dd6f-4c03-aed9-36e07e82a14c" method="GET" rel="self"/> </rest_links> <name><![CDATA[ADOmoney Designer]]></name> </group> ... </subgroups> <users> <user id="{6e1ffeab-b246-47d1-909f-6fadf55d33ac}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/6e1ffeab-b246-47d1-909f-6fadf55d33ac" method="GET" rel="self"/> </rest_links> <loginName><![CDATA[Admin]]></loginName> <firstName/> <lastName/> </user> ... </users> </group> </response>

Here is a GET request that returns user group information in a JSON representation:

REQUEST GET rest/2.0/usergroups/a18c6786-7f19-455e-b666-e51d9ade038e



RESPONSE { "locale": "en", "group": { "id": "{a18c6786-7f19-455e-b666-e51d9ade038e}", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/a18c6786-7f19-455e-b666-e51d9ade038e", "method": "GET", "rel": "self" } ], "name": "ADO_ROOT_OBJECT_GROUP", "subgroups": [ { "id": "{227f1a76-dd6f-4c03-aed9-36e07e82a14c}", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/227f1a76-dd6f-4c03-aed9-36e07e82a14c", "method": "GET", "rel": "self"


Author: BOC Group

© 2019, BOC Group /181

} ], "name": "ADOmoney Designer" }, ... ], "users": [ { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/6e1ffeab-b246-47d1-909f-6fadf55d33ac", "method": "GET", "rel": "self" } ], "id": "{6e1ffeab-b246-47d1-909f-6fadf55d33ac}", "loginName": "Admin", "firstName": "", "lastName": "" }, ... ] } }

An XML representation with an additional parameter:

REQUEST GET rest/2.0/usergroups/a18c6786-7f19-455e-b666-e51d9ade038e?recursive=true





Content-Length: ...


<response>

<locale>en</locale>

<group id="{a18c6786-7f19-455e-b666-e51d9ade038e}">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/a18c6786-7f19-455e-b666-e51d9ade038e?recursive=true" method="GET" rel="self"/>

</rest_links>


Author: BOC Group

© 2019, BOC Group /181

<name><![CDATA[ADO_ROOT_OBJECT_GROUP]]></name>

<subgroups>

<group id="{227f1a76-dd6f-4c03-aed9-36e07e82a14c}">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/227f1a76-dd6f-4c03-aed9-36e07e82a14c" method="GET" rel="self"/>

</rest_links>

<name><![CDATA[ADOmoney Designer]]></name>

<subgroups>

<group id="{8dfc7c8d-1272-44bb-8213-e913833fdee1}">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/8dfc7c8d-1272-44bb-8213-e913833fdee1" method="GET" rel="self"/>

</rest_links>

<name><![CDATA[ADOmoney Designer Inner]]></name>

<subgroups>

...

</subgroups>

<users>

<user id="{c379b6df-b962-466a-bce3-63c4ec7cf9e3}">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/c379b6df-b962-466a-bce3-63c4ec7cf9e3" method="GET" rel="self"/>

</rest_links>

<loginName><![CDATA[User]]></loginName>

<firstName/>

<lastName/>

</user>

...

</users>

</group>

</subgroups>


Author: BOC Group

© 2019, BOC Group /181

<users>

<user id="{45209445-7dca-44b6-9ca4-c55f5efdda12}">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/45209445-7dca-44b6-9ca4-c55f5efdda12" method="GET" rel="self"/>

</rest_links>

<loginName><![CDATA[andrew]]></loginName>

<firstName><![CDATA[Andrew]]></firstName>

<lastName><![CDATA[Initiative]]></lastName>

</user>

...

</users>

</group>

...

</subgroups>

<users>

<user id="{6e1ffeab-b246-47d1-909f-6fadf55d33ac}">

<rest_links>

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/6e1ffeab-b246-47d1-909f-6fadf55d33ac" method="GET" rel="self"/>

</rest_links>

<loginName><![CDATA[Admin]]></loginName>

<firstName/>

<lastName/>

</user>

</users>

</group>

</response>

A JSON representation with additional parameters:

REQUEST


Author: BOC Group

© 2019, BOC Group /181

GET rest/2.0/repos/6f68b2e6-c48e-4bc5-a803-90cda4d17cf5/objectgroups/7e749f24-7a20-41e2-b3b2-132fd0d98392?icon=true&recursive=true



RESPONSE {

"locale": "en",

"group": {

"id": "{a18c6786-7f19-455e-b666-e51d9ade038e}",

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/a18c6786-7f19-455e-b666-e51d9ade038e?recursive=true",

"method": "GET",

"rel": "self"

}

],

"name": "ADO_ROOT_OBJECT_GROUP",

"subgroups": [

{

"id": "{227f1a76-dd6f-4c03-aed9-36e07e82a14c}",

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/227f1a76-dd6f-4c03-aed9-36e07e82a14c",

"method": "GET",

"rel": "self"

}

],

"name": "ADOmoney Designer",

"subgroups": [

{

"id": "{8dfc7c8d-1272-44bb-8213-e913833fdee1}",

"rest_links": [


Author: BOC Group

© 2019, BOC Group /181

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/8dfc7c8d-1272-44bb-8213-e913833fdee1",

"method": "GET",

"rel": "self"

}

...

],

"name": "ADOMoney Designer Inner",

"subgroups": [

...

],

"users": [

{

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/c379b6df-b962-466a-bce3-63c4ec7cf9e3",

"method": "GET",

"rel": "self"

}

],

"id": "{c379b6df-b962-466a-bce3-63c4ec7cf9e3}",

"loginName": "User",

"firstName": "",

"lastName": ""

},

...

]

},

...

],


Author: BOC Group

© 2019, BOC Group /181

"users": [

{

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/45209445-7dca-44b6-9ca4-c55f5efdda12",

"method": "GET",

"rel": "self"

}

],

"id": "{45209445-7dca-44b6-9ca4-c55f5efdda12}",

"loginName": "andrew",

"firstName": "Andrew",

"lastName": "Initiative"

},

...

]

},

...

],

"users": [

{

"rest_links": [

{

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/6e1ffeab-b246-47d1-909f-6fadf55d33ac",

"method": "GET",

"rel": "self"

}

],

"id": "{6e1ffeab-b246-47d1-909f-6fadf55d33ac}",

"loginName": "Admin",

"firstName": "",


Author: BOC Group

© 2019, BOC Group /181

"lastName": ""

},

...

]

}

}

12.2 Roles

APIs for retrieving information about roles.

12.2.1 List of Role Grouping Items

Here is an API for retrieving a list of grouping items containing roles.

Note: An example for a grouping item is the ADONIS NP-specific group “Model Release Workflow” which contains the roles “Administrator”, “Modeller” etc.

HTTP Method GET URL path /rest/2.0/roles Request headers Accept: application/json and application/xml

Response A JSON or XML document consisting of IDs of role grouping items. For roles which are not attached to any grouping item technical group with ID none is returned.

HATEOAS Links


1 Self link self root roles

2 Link to grouping item self item roles/id

Example Responses

Here is a GET request to get role grouping items information in an XML representation:

REQUEST


Author: BOC Group

© 2019, BOC Group /181

GET rest/2.0/roles


RESPONSE HTTP/1.1 200 OK Content-Type: application/xml Content-Length: ... <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <response> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles" method="GET" rel="self"/> </rest_links> <items> <item id="{3ad30848-5a75-484c-b27c-5ab621932dc9}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9" method="GET" rel="self"/> </rest_links> </item> <item id="none"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/none" method="GET" rel="self"/> </rest_links> </item> </items> </response>

Here is a GET request to get role grouping items in a JSON representation:



RESPONSE { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles", "method": "GET", "rel": "self" } ], "items": [ { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9", "method": "GET", "rel": "self" }


Author: BOC Group

© 2019, BOC Group /181

], "id": "{3ad30848-5a75-484c-b27c-5ab621932dc9}" }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/none", "method": "GET", "rel": "self" } ], "id": "none" } ] }

12.2.2 List of Roles inside Grouping Item

Here is an API for retrieving a list of roles contained in a specified grouping item.

HTTP Method GET URL path /rest/2.0/roles/{id} Identifiers

{id} The ID of the role grouping item to be retrieved, none for a technical grouping item containing roles which are not attached to any grouping item.



Response A JSON or XML document consisting of the ID of a grouping item and a list of roles assigned to this grouping item. Roles only contain information about grouping ID, meta name and name.

HATEOAS Links


1 Self link self root roles/id

2 Link to list of grouping items parent root roles

3 Link to role self role roles/id/name

Example Responses

Here is a GET request to get roles inside a grouping item in an XML representation:


Author: BOC Group

© 2019, BOC Group /181

REQUEST GET rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9



RESPONSE HTTP/1.1 200 OK Content-Type: application/xml Content-Length: ... <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <response id="{3ad30848-5a75-484c-b27c-5ab621932dc9}"> <locale>en</locale> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9" method="GET" rel="self"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles" method="GET" rel="parent"/> </rest_links> <roles> <role metaName="REVIEWER (B)" parentId="{3ad30848-5a75-484c-b27c-5ab621932dc9}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/REVIEWER%20%28B%29" method="GET" rel="self"/> </rest_links> <name><![CDATA[Reviewer (business)]]></name> </role> <role metaName="ADMIN" parentId="{3ad30848-5a75-484c-b27c-5ab621932dc9}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/ADMIN" method="GET" rel="self"/> </rest_links> <name><![CDATA[Administrator]]></name> </role> </roles> </response>

Here is a GET request to get roles inside a grouping item in a JSON representation:

REQUEST GET rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9



RESPONSE { "locale": "en", "response": "{3ad30848-5a75-484c-b27c-5ab621932dc9}", "rest_links": [ {


Author: BOC Group

© 2019, BOC Group /181

"href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles", "method": "GET", "rel": "parent" } ], "roles": [ { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/REVIEWER%20%28B%29", "method": "GET", "rel": "self" } ], "metaName": "REVIEWER (B)", "parentId": "{3ad30848-5a75-484c-b27c-5ab621932dc9}", "name": "Reviewer (business)" }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/ADMIN", "method": "GET", "rel": "self" } ], "metaName": "ADMIN", "parentId": "{3ad30848-5a75-484c-b27c-5ab621932dc9}", "name": "Administrator" } ] }

12.2.3 Detailed Role Information

Here is an API for retrieving detailed information about a specified role.

HTTP Method GET URL path /rest/2.0/roles/{id}/{name} Identifiers

{id} The ID of the role grouping item to be retrieved, none for a technical grouping item containing roles which are not attached to any grouping item.

{name} Meta name of the role. The name must be in encoded form and spaces must be represented as %20.


Author: BOC Group

© 2019, BOC Group /181



Response A JSON or XML document consisting of the ID of the meta name, ID of the grouping element, is role enabled, is system role, is role registered, is role relevant for metamodel rights and a list of users which are assigned to this role. Only basic user data are returned like ID, login name, first name and last name.

HATEOAS Links


1 Self link self role roles/id/name

2 Link to parent grouping item parent role roles/id

3 Link to user self user users

Example Responses

Here is a GET request to get detailed role information in a XML representation:

REQUEST GET rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/REVIEWER%20%28B%29



RESPONSE HTTP/1.1 200 OK Content-Type: application/xml Content-Length: ... <response> <locale>en</locale> <role metaName="REVIEWER (B)" parentId="{3ad30848-5a75-484c-b27c-5ab621932dc9}" enabled="true" system="false" registered="false" mmRights="false"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/REVIEWER%20%28B%29" method="GET" rel="self"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9" method="GET" rel="parent"/> </rest_links> <name><![CDATA[Reviewer (business)]]></name> <users> <user id="{45209445-7dca-44b6-9ca4-c55f5efdda12}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/45209445-7dca-44b6-9ca4-c55f5efdda12" method="GET" rel="self"/>


Author: BOC Group

© 2019, BOC Group /181

</rest_links> <loginName><![CDATA[andrew]]></loginName> <firstName><![CDATA[Andrew]]></firstName> <lastName><![CDATA[Initiative]]></lastName> </user> <user id="{4e27ebd4-796a-4614-abd6-0af61a48a94a}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/4e27ebd4-796a-4614-abd6-0af61a48a94a" method="GET" rel="self"/> </rest_links> <loginName><![CDATA[susan]]></loginName> <firstName><![CDATA[Susan]]></firstName> <lastName><![CDATA[Compliance]]></lastName> </user> </users> </role> </response>

Here is a GET request to get detailed role information in a JSON representation:

REQUEST GET rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/REVIEWER%20%28B%29



RESPONSE { "locale": "en", "item": { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/REVIEWER%20%28B%29", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9", "method": "GET", "rel": "parent" } ], "metaName": "REVIEWER (B)", "parentId": "{3ad30848-5a75-484c-b27c-5ab621932dc9}", "name": "Reviewer (business)", "enabled": true, "system": false, "registered": false, "mmRights": false, "users": [ { "rest_links": [


Author: BOC Group

© 2019, BOC Group /181

{ "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/45209445-7dca-44b6-9ca4-c55f5efdda12", "method": "GET", "rel": "self" } ], "id": "{45209445-7dca-44b6-9ca4-c55f5efdda12}", "loginName": "andrew", "firstName": "Andrew", "lastName": "Initiative" }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/4e27ebd4-796a-4614-abd6-0af61a48a94a", "method": "GET", "rel": "self" } ], "id": "{4e27ebd4-796a-4614-abd6-0af61a48a94a}", "loginName": "susan", "firstName": "Susan", "lastName": "Compliance" } ] } }

12.3 Users

APIs for retrieving information about users.

12.3.1 Get the Specified User

Here is an API for retrieving users by login name or ID.

HTTP Method GET URL path /rest/2.0/users/login/{login_name}?attribute={attribute}

/rest/2.0/users/id/{id_of_user}?attribute={attribute} Identifiers {user-id} or {login-name} The ID or login name of the user to be retrieved

{attribute}

Optional, defines the attributes of the user that may be returned in the results set. There can be multiple attributes within a request URL. If no attribute parameter is defined all attributes of the user are returned.


Author: BOC Group

© 2019, BOC Group /181

E.g. &attribute=FORENAME&attribute=EMAIL Request headers Accept: application/json and application/xml


Response A JSON or XML document consisting of all the basic information about the specified user: login name, ID, list of roles (ui name, meta name , mfbID and HATEOAS link to each), list of repositories (ID,name) to which user has access, does user have admin rights, is user a system user and user attributes.

HATEOAS Links


Endpoint

1 Self link self root users

2 Link to each user group in which user is registered

parent root usergroups

3 Link to each role of the user self user roles

Example Responses

Here is a GET request to get user information in an XML representation:

REQUEST GET rest/2.0/users/login/peter or rest/2.0/users/id/8a080580-fa71-4868-81b4-3bb03b972704



RESPONSE <response> <locale>en</locale> <user id="{8a080580-fa71-4868-81b4-3bb03b972704}" admin="false" system="false"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/login/peter" method="GET" rel="self"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/login/peter" method="DELETE" rel="delete"/> </rest_links> <loginName><![CDATA[peter]]></loginName> <roles> <role metaName="Common"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/none/Common" method="GET" rel="self"/>


Author: BOC Group

© 2019, BOC Group /181

</rest_links> <name><![CDATA[Design & Document]]></name> </role> <role metaName="MODELLER" parentId="{3ad30848-5a75-484c-b27c-5ab621932dc9}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/MODELLER" method="GET" rel="self"/> </rest_links> <name><![CDATA[Modeller]]></name> </role> <role metaName="REVIEWER (M)" parentId="{3ad30848-5a75-484c-b27c-5ab621932dc9}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/REVIEWER%20%28M%29" method="GET" rel="self"/> </rest_links> <name><![CDATA[Reviewer (methodical)]]></name> </role> <role metaName="Reader"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/none/Reader" method="GET" rel="self"/> </rest_links> <name><![CDATA[Read & Explore]]></name> </role> <role metaName="Reviewer"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/none/Reviewer" method="GET" rel="self"/> </rest_links> <name><![CDATA[Control & Release]]></name> </role> </roles> <repos> <repo id="{02388b8c-c8f3-4bd4-b9bb-a109bb4326b8}"> <name><![CDATA[Standard-Repository]]></name> </repo> </repos> <usergroups> <group id="{db977b96-c704-4926-9305-7e86043f885a}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/db977b96-c704-4926-9305-7e86043f885a" method="GET" rel="self"/> </rest_links> <name><![CDATA[Default group]]></name> </group> </usergroups> <attributes> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="FORENAME" attrType="STRING" xsi:type="string"> <name><![CDATA[First name]]></name> <value><![CDATA[Peter]]></value>


Author: BOC Group

© 2019, BOC Group /181

</attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="SURNAME" attrType="STRING" xsi:type="string"> <name><![CDATA[Last name]]></name> <value><![CDATA[Risk]]></value> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="MUST_CHANGE_PASSWORD" attrType="INTEGER" xsi:type="number"> <name><![CDATA[User must change the password]]></name> <value><![CDATA[1.0]]></value> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="ACCOUNT_DISABLED" attrType="INTEGER" xsi:type="number"> <name><![CDATA[Account disabled]]></name> <value><![CDATA[0.0]]></value> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="TELEPHONE_NUMBER" attrType="SHORTSTRING" xsi:type="string"> <name><![CDATA[Telephone number]]></name> <value/> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="DESCRIPTION" attrType="LONGSTRING" xsi:type="string"> <name><![CDATA[User-specific Information]]></name> <value/> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="EMAIL" attrType="STRING" xsi:type="string"> <name><![CDATA[Email]]></name> <value/> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="ROOM" attrType="SHORTSTRING" xsi:type="string"> <name><![CDATA[Room]]></name> <value/> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="TYPE_OF_OCCUPATION" attrType="SHORTSTRING" xsi:type="string"> <name><![CDATA[Type of occupation]]></name> <value/> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="FORM_OF_ADDRESS" attrType="SHORTSTRING" xsi:type="string"> <name><![CDATA[Form of address]]></name> <value/> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="INACTIVE_SINCE" attrType="UTC" xsi:type="date"> <name><![CDATA[Inactive since]]></name> <value><![CDATA[1970-01-01T00:00:00]]></value> </attribute> </attributes> </user> </response>

Here is a GET request to get user information in a JSON representation:


Author: BOC Group

© 2019, BOC Group /181

REQUEST GET rest/2.0/users/login/peter or rest/2.0/users/id/8a080580-fa71-4868-81b4-3bb03b972704



RESPONSE { "locale": "en", "user": { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/login/peter", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/login/peter", "method": "DELETE", "rel": "delete" } ], "id": "{8a080580-fa71-4868-81b4-3bb03b972704}", "loginName": "peter", "roles": [ { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/none/Common", "method": "GET", "rel": "self" } ], "metaName": "Common", "name": "Design & Document" }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/MODELLER", "method": "GET", "rel": "self" } ], "metaName": "MODELLER", "parentId": "{3ad30848-5a75-484c-b27c-5ab621932dc9}", "name": "Modeller" }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/REVIEWER%20%28M%29", "method": "GET", "rel": "self"


Author: BOC Group

© 2019, BOC Group /181

} ], "metaName": "REVIEWER (M)", "parentId": "{3ad30848-5a75-484c-b27c-5ab621932dc9}", "name": "Reviewer (methodical)" }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/none/Reader", "method": "GET", "rel": "self" } ], "metaName": "Reader", "name": "Read & Explore" }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/none/Reviewer", "method": "GET", "rel": "self" } ], "metaName": "Reviewer", "name": "Control & Release" } ], "repos": [ { "id": "{02388b8c-c8f3-4bd4-b9bb-a109bb4326b8}", "name": "Standard-Repository" } ], "usergroups": [ { "id": "{db977b96-c704-4926-9305-7e86043f885a}", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/db977b96-c704-4926-9305-7e86043f885a", "method": "GET", "rel": "self" } ], "name": "Default group" } ], "admin": false, "system": false, "attributes": [ { "name": "First name", "metaName": "FORENAME", "attrType": "STRING", "value": "Peter"


Author: BOC Group

© 2019, BOC Group /181

}, { "name": "Last name", "metaName": "SURNAME", "attrType": "STRING", "value": "Risk" }, { "name": "User must change the password", "metaName": "MUST_CHANGE_PASSWORD", "attrType": "INTEGER", "value": 1 }, { "name": "Account disabled", "metaName": "ACCOUNT_DISABLED", "attrType": "INTEGER", "value": 0 }, { "name": "Telephone number", "metaName": "TELEPHONE_NUMBER", "attrType": "SHORTSTRING", "value": "" }, { "name": "User-specific Information", "metaName": "DESCRIPTION", "attrType": "LONGSTRING", "value": "" }, { "name": "Email", "metaName": "EMAIL", "attrType": "STRING", "value": "" }, { "name": "Room", "metaName": "ROOM", "attrType": "SHORTSTRING", "value": "" }, { "name": "Type of occupation", "metaName": "TYPE_OF_OCCUPATION", "attrType": "SHORTSTRING", "value": "" }, { "name": "Form of address", "metaName": "FORM_OF_ADDRESS", "attrType": "SHORTSTRING", "value": "" }, { "name": "Inactive since", "metaName": "INACTIVE_SINCE",


Author: BOC Group

© 2019, BOC Group /181

"attrType": "UTC", "value": "1970-01-01T00:00:00" } ] } }

12.3.2 Users List

Here is an API for retrieving a flat users list.

HTTP Method GET URL path /rest/2.0/users Request headers Accept: application/json and application/xml

Response A JSON or XML document consisting of a flat list of users with basic info (ID and loginName).

HATEOAS Links


Endpoint

1 Self link self root users

2 Link to every user that is included in the list

self users users

Example Responses

Here is a GET request to get a users list in an XML representation:

REQUEST GET rest/2.0/users


RESPONSE <response> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users" method="GET" rel="self"/> </rest_links> <users> <user id="{4e27ebd4-796a-4614-abd6-0af61a48a94a}"> <rest_links>


Author: BOC Group

© 2019, BOC Group /181

<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/4e27ebd4-796a-4614-abd6-0af61a48a94a" method="GET" rel="self"/> </rest_links> <loginName><![CDATA[susan]]></loginName> </user> <user id="{a0f33384-3ac6-44ae-a898-8f855633bbbd}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/a0f33384-3ac6-44ae-a898-8f855633bbbd" method="GET" rel="self"/> </rest_links> <loginName><![CDATA[rich]]></loginName> </user> <user id="{d329114f-2ad3-415f-9bfe-8b8b4b182aba}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/d329114f-2ad3-415f-9bfe-8b8b4b182aba" method="GET" rel="self"/> </rest_links> <loginName><![CDATA[reader]]></loginName> </user> ... </users> </response>

Here is a GET request to get a users list in a JSON representation:

REQUEST GET rest/2.0/users


RESPONSE { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users", "method": "GET", "rel": "self" } ], "users": [ { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/4e27ebd4-796a-4614-abd6-0af61a48a94a", "method": "GET", "rel": "self" } ], "id": "{4e27ebd4-796a-4614-abd6-0af61a48a94a}", "loginName": "susan" },


Author: BOC Group

© 2019, BOC Group /181

{ "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/a0f33384-3ac6-44ae-a898-8f855633bbbd", "method": "GET", "rel": "self" } ], "id": "{a0f33384-3ac6-44ae-a898-8f855633bbbd}", "loginName": "rich" }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/d329114f-2ad3-415f-9bfe-8b8b4b182aba", "method": "GET", "rel": "self" } ], "id": "{d329114f-2ad3-415f-9bfe-8b8b4b182aba}", "loginName": "reader" }, ... ] }

13 User Write APIs

This section lists the available user write APIs.

13.1 Users

13.1.1 Create Users

An API for creating new users. After execution, a new user resource with a unique ID will be created. If successful, a 201 status will be returned with a link to the new resource available in the "Location" header.

HTTP Method POST URL path /rest/2.0/users Body Content-type:application/json

The structure of the passed JSON object must be consistent with the "user" object property of the User response (see here). In addition, the "password" string property is required at the root level.


Author: BOC Group

© 2019, BOC Group /181

The following properties can be set at root level: loginName, password, attributes, usergroups, repos, roles. The "loginName" and "password" properties are required for user creation, otherwise a bad request (400) status is returned. Other properties are optional.

The properties "repos", "usergroups", "roles" and "attributes" are lists of JSON objects. The property "id" is required for repos and usergroups the same as "metaName" for "attributes" and "roles".

A newly created user will be assigned to the default user group if no valid user group is passed within the body.

List of attributes available to set:

FORENAME, SURNAME, MUST_CHANGE_PASSWORD, ACCOUNT_DISABLED, TELEPHONE_NUMBER, DESCRIPTION, EMAIL, ROOM, TYPE_OF_OCCUPATION, FORM_OF_ADDRESS, INACTIVE_SINCE, LOGIN_MECHANISM, LDAP_GUID

To set no value for a specific user attribute the JSON attribute definition should have null value. Response Headers

Location A link to the newly created resource.

E.g. http:/ ... /rest/2.0/users/id/5945b96f-b2e8-4890-808c-14f383a66156

Example: User Creation Body

"loginName":"NewUser",

"password":"Password123++",

"repos":[

{

"id":"{02388b8c-c8f3-4bd4-b9bb-a109bb4326b8}"

}

],

"usergroups":[

{

"id":"{227f1a76-dd6f-4c03-aed9-36e07e82a14c}"

},

{

"id":"{8bac4bcd-dfbb-4f1f-bcbb-e3b546d95c91}"

}

],

"attributes": [


Author: BOC Group

© 2019, BOC Group /181

{

"metaName": "FORENAME",

"value": "FirstName"

},

{

"metaName": "SURNAME",

"value": "LastName"

},

{

"metaName": "MUST_CHANGE_PASSWORD",

"value": 1

},

{

"metaName": "ACCOUNT_DISABLED",

"value": 0

},

{

"metaName":"TELEPHONE_NUMBER",

"value":"123 456 789"

},

{

"metaName":"DESCRIPTION",

"value":"User description"

},

{

"metaName":"EMAIL",

"value":"mail@mail"

},

{

"metaName":"ROOM",

"value":"Room"

},

{

"metaName":"TYPE_OF_OCCUPATION",


Author: BOC Group

© 2019, BOC Group /181

"value":"Type of occupation"

},

{

"metaName":"FORM_OF_ADDRESS",

"value":"Form of address"

}

],

"roles":[

{

"metaName": "REVIEWER (M)",

"parentId": "{3ad30848-5a75-484c-b27c-5ab621932dc9}"

},

{

"metaName": "Reader"

}

]

}

13.1.2 Delete Users

An API for deleting user resources. If successful, a 204 status will be returned without any content.

HTTP Method DELETE URL path /rest/2.0/users/login/{login}

/rest/2.0/users/id/{user_id} Identifiers {login} Login of the user {user_id} ID of the user Response: No content Note: The users Admin and System cannot be deleted.

13.1.3 Modify Users

APIs for modifying user resources.


Author: BOC Group

© 2019, BOC Group /181

Update User Attributes

An API for editing user attributes. If successful, a 200 status will be returned with a full resource body.

HTTP Method PATCH URL path /rest/2.0/users/login/{login}

/rest/2.0/users/id/{user_id} Identifiers {login} Login of the user {user_id} ID of the user Body Content-type: application/json

A JSON object containing a list of attributes that need to be updated.

Note: To set no value of a specific user attribute, the JSON attribute value should be null .e.g.

PATCH /rest/2.0/users/login/{login}

Body of the PATCH request:

{ "attributes": [ { "metaName": "FORENAME", "value": "John" }, { "metaName": "SURNAME", "value": "Doe" } ] }

Request headers




Response A JSON or XML document with the updated object (see User result example).


Author: BOC Group

© 2019, BOC Group /181

Response Headers

Location A link to the modified user.

e.g. http:/ ... /rest/2.0/users/id/5945b96f-b2e8-4890-808c-14f383a66156

Assign User to User Group

An API for assigning users to user groups. If successful, a 201 status will be returned without any content.

HTTP Method POST URL path /rest/2.0/users/login/{login}/usergroups

/rest/2.0/users/id/{user_id}/usergroups Identifiers {login} Login of the user {user_id} ID of the user Body Content-type: application/json

JSON object containing usergroup id, e.g.

{ "groupId":"{6c81c50d-540f-4ed2-a453-372b1bec82d3}" } Response headers

Location Link to modified user


Remove User from User Group

An API for removing users from user groups. If successful, a 204 status will be returned without any content.

HTTP Method DELETE URL path /rest/2.0/users/login/{login}/usergroups/{group_id}

/rest/2.0/users/id/{user_id}/usergroups/{group_id} Identifiers {login} Login of the user {user_id} ID of the user


Author: BOC Group

© 2019, BOC Group /181

{group_id} ID of the user group Response: No content Response headers



Assign User to Repository

An API for assigning users to repositories. If successful, a 204 status will be returned without any content.

HTTP Method POST URL path /rest/2.0/users/login/{login}/repos

/rest/2.0/users/id/{user_id}/repos} Identifiers {login} Login of the user {user_id} ID of the user Body Content-type: application/json

A JSON object containing the ID of the repository, e.g.

{ "repoId":"{6c81c50d-540f-4ed2-a453-372b1bec82d3}" } Response headers



Remove User from Repository

An API for removing users from repositories. If successful, a 204 status will be returned without any content.

HTTP Method DELETE URL path /rest/2.0/users/login/{login}/repos/{repo_id}

/rest/2.0/users/id/{user_id}/repos/{repo_id} Identifiers {login} Login of the user {user_id} ID of the user


Author: BOC Group

© 2019, BOC Group /181

{repo_id} ID of the repository Response: No content Response headers



Assign User to User Role

An API for assigning users to user roles. If successful, a 204 status will be returned without any content.

HTTP Method POST URL path /rest/2.0/users/login/{login}/roles

/rest/2.0/users/id/{user_id}/roles Identifiers {login} Login of the user {user_id} ID of the user Body Content-type: application/json

A JSON object containing the role name and ID of the role grouping item (if it exists), e.g.

{"metaName": "REVIEWER(M)", "parentId": "{3ad30848-5a75-484c-b27c-5ab621932dc9}"} Response: No content Response headers



Remove User from User Role

An API for removing users from user roles. If successful, a 204 status will be returned without any content.

HTTP Method DELETE URL path /rest/2.0/users/login/{login}/roles/{id}/{name}

/rest/2.0/users/id/{user_id}/roles/{id}/{name} Identifiers {login} Login of the user {user_id} ID of the user


Author: BOC Group

© 2019, BOC Group /181

{id} ID of the role grouping item to be retrieved, none for technical grouping items containing roles which are not attached to any grouping item.

{name} Meta name of the role. The name must be in encoded form and spaces must be represented as %20.

Response: No content Response headers



14 Error Handling All REST APIs have to support these HTTP status codes:

15 Appendix

15.1 Sample Implementation (Java): Programmatic Access

Programmatic access to an available RESTful service can be established using any programming language providing the required API to access an HTTP or HTTPS URL.

The simplest way of consuming a RESTful service is by using an HTTP GET request (provided that the service is implemented to respond to HTTP GET requests). When using HTTP GET, parameters will simply be added to the URL.

The following is a basic example of accessing the public (no authentication required) connection test service with a small Java program. In this example, the service does not require any parameters.

import java.io.IOException; import org.apache.http.client.ClientProtocolException;

HTTP status codes 200 OK requested object representation returned in response body 201 Created resource was successfully created and link to it is returned in Location header 204 No Content request was successfully executed and there is no content in response 400 Bad request the request could not be understood by the server 401 Unauthorized authentication information does not map to an authorized client 403 Forbidden resource cannot be accessed 404 Not Found resource does not exist 409 Conflict Resource is referenced by another resource 423 Locked Resource is locked 500 Internal Server Error processing of the request failed


Author: BOC Group

© 2019, BOC Group /181

import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpGet; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.apache.http.util.EntityUtils; public class RESTClient {

private static final String CONNECTION_PATH = "http://localhost:8080/ADOxxWeb/rest/connection";

public static void main (final String [] args) throws ClientProtocolException, IOException

{ final CloseableHttpClient aClient = HttpClients.createDefault (); final HttpGet aMethod = new HttpGet (CONNECTION_PATH); final CloseableHttpResponse aResponse = aClient.execute (aMethod); try {

System.out.println ("Response From RESTful service: \n" + EntityUtils.toString (aResponse.getEntity (), “UTF-8”)); } finally {

aResponse.close (); }

} }

Running this example should provide a response similar to the following: Response From RESTful service: REST Connection Service Evaluation invoked @ Mon Feb 10 16:10:33 CET 2014

15.2 Sample Implementation (Java): Authenticated REST call

The following code shows how to perform authorized access using HTTP GET to the test service which is available at ../rest/connection/auth (e.g. http://localhost:8080/ ADOxxWeb /rest/connection/auth): import java.io.IOException; import java.io.UnsupportedEncodingException; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.security.NoSuchProviderException; import java.security.Security; import java.text.Collator; import java.util.ArrayList; import java.util.Collections; import java.util.Date; import java.util.HashMap; import java.util.List; import java.util.Locale; import java.util.Map;


Author: BOC Group

© 2019, BOC Group /181

import java.util.Map.Entry; import java.util.UUID; import javax.crypto.Mac; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import org.apache.commons.codec.binary.Base64; import org.apache.http.client.ClientProtocolException; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpGet; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.apache.http.util.EntityUtils; import org.bouncycastle.jce.provider.BouncyCastleProvider; public class AuthRESTClient {

private static final String CONNECTION_PATH = "http://localhost:8080/ADOxxWeb/rest/connection/auth";

public static void main (final String [] args) throws ClientProtocolException, IOException, InvalidKeyException, NoSuchAlgorithmException, NoSuchProviderException

{ final CloseableHttpClient aClient = HttpClients.createDefault (); final HttpGet aMethod = new HttpGet (CONNECTION_PATH); final long nDate = new Date ().getTime (); final String sDate = String.valueOf (nDate); final String sGUID = UUID.randomUUID ().toString (); final String sIdentifier = "boc.rest.key.mfb.StandardRESTfulServices"; final String sSecret = "2edb376a-88d7-4564-a4cb-9fcdd005c8179427ccbd-89eb-45ea-a3ed-69f0d7c38e94f723beea-f2bc-4007-a238-8d9a0c88f8ed22365ab7-ff76-440b-99f8-1dc862e1607d3b2c7138-cba5-4a1e-9a66-00595b2524206ffa0893-4d41-4ba5-a43a-e15b5c9292713b3f066f-2875-4bd0-a49b-a093085c15db1224fc34-6d4d-4c62-a0b1-4aae1dffff6ddb1255c1-ca9a-4d58-9bfd-235c9c9f879869ed9de3-d641-4425-85d2-6f0c7a5d162407be6866-cd04-4fb9-b132-116321cec844ac27c950-ba19-4018-bd93- 38ce70f3ea1c60aae62c-e620-4762-a7a0-39d7f0b6c677176cc895-04c6-4d44-8767-4277ee315cfcbed1341f"; aMethod.addHeader ("x-axw-rest-identifier", sIdentifier); aMethod.addHeader ("x-axw-rest-timestamp", sDate); aMethod.addHeader ("x-axw-rest-guid", sGUID); final Map <String, String []> aRequestParameters = new HashMap <String, String []>

(); aRequestParameters.put ("x-axw-rest-timestamp", new String [] {sDate}); aRequestParameters.put ("x-axw-rest-guid", new String [] {sGUID}); aRequestParameters.put ("x-axw-rest-identifier", new String [] {sIdentifier});


Author: BOC Group

© 2019, BOC Group /181

final String sSecurityToken = getSecurityToken (sSecret,

aRequestParameters);


final CloseableHttpResponse aResponse = aClient.execute (aMethod); try {

System.out.println ("Response From RESTful service: \n" + EntityUtils.toString (aResponse.getEntity (), “UTF-8”));

} finally {

aResponse.close (); } }

private static String getSecurityToken (final String sSecret,

final Map <String, String []> aDataMap) throws UnsupportedEncodingException,

NoSuchProviderException, NoSuchAlgorithmException, InvalidKeyException

{ final List <byte []> aContent = new ArrayList <byte []> (); final List <String> aAllParams = new ArrayList <String> (); for (final Entry <String, String []> aEntry : aDataMap.entrySet ()) {

aAllParams.add (aEntry.getKey ()); for (final String sValue : aEntry.getValue ()) {

aAllParams.add (sValue); }

} aAllParams.add (sSecret); final Collator aCollator = Collator.getInstance (Locale.US); Collections.sort (aAllParams, aCollator); for (final String aEntry : aAllParams) {

aContent.add (aEntry.getBytes ("UTF-8")); } final String PROVIDER_BOUNCYCASTLE = "BC"; final String SHA512 = "HMac/SHA512"; if (Security.getProvider (PROVIDER_BOUNCYCASTLE) == null) {

Security.addProvider (new BouncyCastleProvider ()); } final Mac aHmac = Mac.getInstance (SHA512, PROVIDER_BOUNCYCASTLE); final SecretKey aKey = new SecretKeySpec (sSecret.getBytes ("UTF-8"), SHA512);


Author: BOC Group

© 2019, BOC Group /181

aHmac.init (aKey); aHmac.reset (); int nSize = 0; for (final byte [] aEntry : aContent) {

nSize += aEntry.length; } final byte [] aAllParamsArray = new byte [nSize]; int nCount = 0; for (final byte [] aEntry : aContent) {

for (final byte aByte : aEntry) {

aAllParamsArray[nCount] = aByte; nCount++;

} } final byte [] aResult = aHmac.doFinal (aAllParamsArray); return new String (Base64.encodeBase64 (aResult), "UTF-8");

} } Running this example should provide a response similar to the following:

Response From RESTful service: Authorized Access Granted @ Mon Feb 10 16:54:40 CET 2014

Necessary Libraries:

The following libraries are required for this sample implementation:

• httpcore and httpclient: https://hc.apache.org/downloads.cgi • commons-logging: https://commons.apache.org/proper/commons-

logging/download_logging.cgi • commons-codec: https://commons.apache.org/proper/commons-

codec/download_codec.cgi • bcprov-jdk: https://www.bouncycastle.org/latest_releases.html

15.3 Sample Implementation (Java): Using HTTP POST

The examples so far showed how to access RESTful services using HTTP GET. Very often (usually when data needs to manipulated using a RESTful service), access is made using HTTP POST. In this case, the parameters sent with the request will not be part of the service URL but rather transported inside a form with the request.

The following code shows a simplified example of how to achieve this. In this example it is assumed that a service is available at

https://hc.apache.org/downloads.cgi

https://commons.apache.org/proper/commons-logging/download_logging.cgi

https://commons.apache.org/proper/commons-logging/download_logging.cgi

https://commons.apache.org/proper/commons-codec/download_codec.cgi

https://commons.apache.org/proper/commons-codec/download_codec.cgi

https://www.bouncycastle.org/latest_releases.html


Author: BOC Group

© 2019, BOC Group /181

http://localhost:8080/ADOxxWeb/rest/hello which can handle HTTP POST requests and requires the parameter “hello_param”: final HttpPost aMethod = new HttpPost ("http://localhost:8080/ADOxxWeb/rest/hello"); ... // Add headers here final List <NameValuePair> aPostForm = new ArrayList <NameValuePair> (); aPostForm.add (new BasicNameValuePair ("hello_param", "RESTClient")); final Map <String, String []> aRequestParameters = new HashMap <String, String []> (); for (final NameValuePair aEntry : aDataEntries) {

aRequestParameters.put (aEntry.getName (), new String [] {aEntry.getValue ()}); } ... // Add Request parameters here aMethod.setEntity (new UrlEncodedFormEntity (aPostForm)); final String sSecurityToken = getSecurityToken (sSecret, aRequestParameters); aMethod.addHeader ("x-axw-rest-token", sSecurityToken);

... // Execute request and print out response here

15.4 Sample Implementation (Java): Using HTTP POST to Create a New User

The following code shows how to create a user using HTTP POST: import java.io.IOException; import java.io.UnsupportedEncodingException; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.security.NoSuchProviderException; import java.security.Security; import java.text.Collator; import java.util.ArrayList; import java.util.Collections; import java.util.Date; import java.util.HashMap; import java.util.List; import java.util.Locale; import java.util.Map; import java.util.Map.Entry; import java.util.UUID; import javax.crypto.Mac; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import org.apache.commons.codec.binary.Base64;


Author: BOC Group

© 2019, BOC Group /181

import org.apache.http.client.ClientProtocolException; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpPost; import org.apache.http.entity.ContentType; import org.apache.http.entity.StringEntity; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.bouncycastle.jce.provider.BouncyCastleProvider; public class StandardRESTfulServicesClientPOSTUser { public static void main (final String [] args) throws ClientProtocolException, IOException, InvalidKeyException, NoSuchAlgorithmException, NoSuchProviderException { final CloseableHttpClient aClient = HttpClients.createDefault (); // Replace with your key final String sKey = "boc.rest.key.mfb.StandardRESTfulServices"; // Replace with your secret final String sSecret = "d4514a20-0913-4940-8403-f1f58d9fdba8e25bfb85-6066-4449-8970-d1556f126bfa741e2dec-765e-425f-92c7-2a9aef45ea594e947521-1ed7-4773-a244-f75957b5041ec73e334e-37db-4df0-8554-452b1d72208d0e002d92-1451-4513-ab6a-661952c64b8a69b5bb42-0bea-4905-926b-e1ec04e2912369998e61-a355-4f60-a86f-790af5ac4d4cf3d70a24-be75-4168-808c-94fa42d27be065c0e536-7272-48e0-9091-aea9b54ac34aff28734b-14b8-4ffb-99c5-2f28e1fff8ee2d2e01ca-d7b9-4a21-a5ce-0edd9dca9dc9f9986081-3496-4603-bc78-df27635d4c395761a988-9ca0-497c-920e-8621b393db46c166c5b8"; // Replace the path to your ADO* installation final String sPath = "http://HOST:8080/ADOXX/rest/2.0/users"; final StringBuilder aUserParams = new StringBuilder (); aUserParams.append ("{"); aUserParams.append ("\"loginName\":\"MyUser\","); aUserParams.append ("\"password\":\"Password123++\""); aUserParams.append ("}"); final Map <String, String []> aTokenParameters = new HashMap <String, String []> (); final HttpPost aMethod = new HttpPost (sPath); final long nDate = new Date ().getTime (); final String sDate = String.valueOf (nDate); final String sGUID = UUID.randomUUID ().toString (); aMethod.addHeader ("x-axw-rest-identifier", sKey); aMethod.addHeader ("x-axw-rest-timestamp", sDate); aMethod.addHeader ("x-axw-rest-guid", sGUID); aTokenParameters.put ("x-axw-rest-timestamp", new String [] {sDate}); aTokenParameters.put ("x-axw-rest-guid", new String [] {sGUID}); aTokenParameters.put ("x-axw-rest-identifier", new String [] {sKey});


Author: BOC Group

© 2019, BOC Group /181

// Construct the token final String sSecurityToken = createSecurityToken (sSecret, aTokenParameters); aMethod.addHeader ("x-axw-rest-token", sSecurityToken); // The headers controlling the return type and the language do not have to be considered for // token generation aMethod.addHeader ("Accept", "application/json"); aMethod.addHeader ("Accept-Language", "en"); final StringEntity aJSON = new StringEntity (aUserParams.toString (), ContentType.APPLICATION_JSON); aMethod.setEntity (aJSON); System.out.println ("Sending request to: " + sPath); final CloseableHttpResponse aResponse = aClient.execute (aMethod); try { System.out.println ("Request Status Code: " + aResponse.getStatusLine ().getStatusCode ()); } catch (final Exception aEx) { aEx.printStackTrace (); } finally { aResponse.close (); } } private static String createSecurityToken (final String sSecret, final Map <String, String []> aDataMap) throws UnsupportedEncodingException, NoSuchProviderException, NoSuchAlgorithmException, InvalidKeyException { final List <byte []> aContent = new ArrayList <byte []> (); final List <String> aAllParams = new ArrayList <String> (); for (final Entry <String, String []> aEntry : aDataMap.entrySet ()) { aAllParams.add (aEntry.getKey ()); for (final String sValue : aEntry.getValue ()) { aAllParams.add (sValue); } } aAllParams.add (sSecret); final Collator aCollator = Collator.getInstance (Locale.US); Collections.sort (aAllParams, aCollator);


Author: BOC Group

© 2019, BOC Group /181

for (final String aEntry : aAllParams) { aContent.add (aEntry.getBytes ("UTF-8")); } final String PROVIDER_BOUNCYCASTLE = "BC"; final String SHA512 = "HMac/SHA512"; if (Security.getProvider (PROVIDER_BOUNCYCASTLE) == null) { Security.addProvider (new BouncyCastleProvider ()); } final Mac aHmac = Mac.getInstance (SHA512, PROVIDER_BOUNCYCASTLE); final SecretKey aKey = new SecretKeySpec (sSecret.getBytes ("UTF-8"), SHA512); aHmac.init (aKey); aHmac.reset (); int nSize = 0; for (final byte [] aEntry : aContent) { nSize += aEntry.length; } final byte [] aAllParamsArray = new byte [nSize]; int nCount = 0; for (final byte [] aEntry : aContent) { for (final byte aByte : aEntry) { aAllParamsArray[nCount] = aByte; ++nCount; } } final byte [] aResult = aHmac.doFinal (aAllParamsArray); return new String (Base64.encodeBase64 (aResult), "UTF-8"); } }

15.5 Sample Implementation (Java): Using HTTP GET to Get Model Data

The following is a basic example of accessing the name and description of a model with the specified ID using a small Java program. import java.io.IOException; import java.io.UnsupportedEncodingException; import java.net.URLEncoder; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.security.NoSuchProviderException; import java.security.Security; import java.text.Collator; import java.util.AbstractMap; import java.util.ArrayList;


Author: BOC Group

© 2019, BOC Group /181

import java.util.Collections; import java.util.Date; import java.util.HashMap; import java.util.List; import java.util.Locale; import java.util.Map; import java.util.Map.Entry; import java.util.UUID; import javax.crypto.Mac; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import org.apache.commons.codec.binary.Base64; import org.apache.http.client.ClientProtocolException; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpGet; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.apache.http.util.EntityUtils; import org.bouncycastle.jce.provider.BouncyCastleProvider; public class StandardRESTfulServicesClientGetModelData { public static void main (final String [] args) throws ClientProtocolException, IOException, InvalidKeyException, NoSuchAlgorithmException, NoSuchProviderException { final CloseableHttpClient aClient = HttpClients.createDefault (); // Replace with the ID of your repository final String sRepoID = "e1fd8ab4-8a4d-4c6f-969c-b300127db1e6"; // Replace with your key final String sKey = "boc.rest.key.mfb.StandardRESTfulServices"; // Replace with your secret final String sSecret = "d4514a20-0913-4940-8403-f1f58d9fdba8e25bfb85-6066-4449-8970-d1556f126bfa741e2dec-765e-425f-92c7-2a9aef45ea594e947521-1ed7-4773-a244-f75957b5041ec73e334e-37db-4df0-8554-452b1d72208d0e002d92-1451-4513-ab6a-661952c64b8a69b5bb42-0bea-4905-926b-e1ec04e2912369998e61-a355-4f60-a86f-790af5ac4d4cf3d70a24-be75-4168-808c-94fa42d27be065c0e536-7272-48e0-9091-aea9b54ac34aff28734b-14b8-4ffb-99c5-2f28e1fff8ee2d2e01ca-d7b9-4a21-a5ce-0edd9dca9dc9f9986081-3496-4603-bc78-df27635d4c395761a988-9ca0-497c-920e-8621b393db46c166c5b8"; // Replace with the ID of the model for which you want to get data final String sModelID = "4cdb6947-1b8b-49c2-9a87-ab5326f7c166"; // Replace the path to your ADO* installation String sPath = "http://HOST:8080/ADOXX/rest/2.0/repos/" + sRepoID + "/models/" + sModelID + "?"; final Map <String, String []> aTokenParameters = new HashMap <String, String []> ();


Author: BOC Group

© 2019, BOC Group /181

final List <Entry <String, String>> aRequestParameters = new ArrayList <Map.Entry <String, String>> (); aRequestParameters.add (new AbstractMap.SimpleEntry <> ("attribute", "NAME")); aRequestParameters.add (new AbstractMap.SimpleEntry <> ("attribute", "A_DESCRIPTION")); // Iterate through the search parameters and construct the URL for (final Entry <String, String> aParam : aRequestParameters) { final String sParamName = aParam.getKey (); final String sParamValue = aParam.getValue (); sPath += sParamName + "=" + URLEncoder.encode (sParamValue, "UTF-8") + "&"; // Add the parameter name and the parameter value to the map containing the parameters for the // token generation final String [] aValues = aTokenParameters.get (sParamName); if (aValues == null) { aTokenParameters.put (sParamName, new String [] {sParamValue}); } else { final String [] aNewValues = new String [aValues.length + 1]; for (int i = 0; i < aValues.length; ++i) { aNewValues[i] = aValues[i]; } aNewValues[aNewValues.length - 1] = sParamValue; aTokenParameters.put (sParamName, aNewValues); } } final HttpGet aMethod = new HttpGet (sPath); final long nDate = new Date ().getTime (); final String sDate = String.valueOf (nDate); final String sGUID = UUID.randomUUID ().toString (); aMethod.addHeader ("x-axw-rest-identifier", sKey); aMethod.addHeader ("x-axw-rest-timestamp", sDate); aMethod.addHeader ("x-axw-rest-guid", sGUID); aTokenParameters.put ("x-axw-rest-timestamp", new String [] {sDate}); aTokenParameters.put ("x-axw-rest-guid", new String [] {sGUID}); aTokenParameters.put ("x-axw-rest-identifier", new String [] {sKey}); // Construct the token final String sSecurityToken = createSecurityToken (sSecret, aTokenParameters); aMethod.addHeader ("x-axw-rest-token", sSecurityToken); // The headers controlling the return type and the language do not have to be considered for // token generation aMethod.addHeader ("Accept", "application/json"); aMethod.addHeader ("Accept-Language", "en");


Author: BOC Group

© 2019, BOC Group /181

System.out.println ("Sending request to: " + sPath); final CloseableHttpResponse aResponse = aClient.execute (aMethod); try { System.out.println ("Request Status Code: " + aResponse.getStatusLine ().getStatusCode ()); final String sResult = EntityUtils.toString (aResponse.getEntity (), "UTF-8"); System.out.println ("Response from RESTful service: " + sResult); } catch (final Exception aEx) { aEx.printStackTrace (); } finally { aResponse.close (); } } private static String createSecurityToken (final String sSecret, final Map <String, String []> aDataMap) throws UnsupportedEncodingException, NoSuchProviderException, NoSuchAlgorithmException, InvalidKeyException { final List <byte []> aContent = new ArrayList <byte []> (); final List <String> aAllParams = new ArrayList <String> (); for (final Entry <String, String []> aEntry : aDataMap.entrySet ()) { aAllParams.add (aEntry.getKey ()); for (final String sValue : aEntry.getValue ()) { aAllParams.add (sValue); } } aAllParams.add (sSecret); final Collator aCollator = Collator.getInstance (Locale.US); Collections.sort (aAllParams, aCollator); for (final String aEntry : aAllParams) { aContent.add (aEntry.getBytes ("UTF-8")); } final String PROVIDER_BOUNCYCASTLE = "BC"; final String SHA512 = "HMac/SHA512"; if (Security.getProvider (PROVIDER_BOUNCYCASTLE) == null) { Security.addProvider (new BouncyCastleProvider ());


Author: BOC Group

© 2019, BOC Group /181

} final Mac aHmac = Mac.getInstance (SHA512, PROVIDER_BOUNCYCASTLE); final SecretKey aKey = new SecretKeySpec (sSecret.getBytes ("UTF-8"), SHA512); aHmac.init (aKey); aHmac.reset (); int nSize = 0; for (final byte [] aEntry : aContent) { nSize += aEntry.length; } final byte [] aAllParamsArray = new byte [nSize]; int nCount = 0; for (final byte [] aEntry : aContent) { for (final byte aByte : aEntry) { aAllParamsArray[nCount] = aByte; ++nCount; } } final byte [] aResult = aHmac.doFinal (aAllParamsArray); return new String (Base64.encodeBase64 (aResult), "UTF-8"); } }

15.6 Sample Implementation (Java): Using HTTP POST to Create a New Object

The following code shows how to create a new object using HTTP POST. The object is created in the repository with the passed ID and the passed attributes contained in the variable aCreationParams are set. Replace repository ID, key, secret, classname and attribute names and values with data fitting your scenario. package Write; import java.io.IOException; import java.io.UnsupportedEncodingException; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.security.NoSuchProviderException; import java.security.Security; import java.text.Collator; import java.util.ArrayList; import java.util.Collections; import java.util.Date; import java.util.HashMap; import java.util.List; import java.util.Locale; import java.util.Map; import java.util.Map.Entry; import java.util.UUID; import javax.crypto.Mac;


Author: BOC Group

© 2019, BOC Group /181

import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import org.apache.commons.codec.binary.Base64; import org.apache.http.client.ClientProtocolException; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpPost; import org.apache.http.entity.ContentType; import org.apache.http.entity.StringEntity; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.bouncycastle.jce.provider.BouncyCastleProvider; public class StandardRESTfulServicesClientCreateObject { public static void main (final String [] args) throws ClientProtocolException, IOException, InvalidKeyException, NoSuchAlgorithmException, NoSuchProviderException { final CloseableHttpClient aClient = HttpClients.createDefault (); // Replace with the ID of your repository final String sRepoID = "a800755e-c679-4a03-84c7-2e9eee86de42"; // Replace with your key final String sKey = "boc.rest.key.mfb.StandardRESTfulServices"; // Replace with your secret final String sSecret = "d4514a20-0913-4940-8403-f1f58d9fdba8e25bfb85-6066-4449-8970-d1556f126bfa741e2dec-765e-425f-92c7-2a9aef45ea594e947521-1ed7-4773-a244-f75957b5041ec73e334e-37db-4df0-8554-452b1d72208d0e002d92-1451-4513-ab6a-661952c64b8a69b5bb42-0bea-4905-926b-e1ec04e2912369998e61-a355-4f60-a86f-790af5ac4d4cf3d70a24-be75-4168-808c-94fa42d27be065c0e536-7272-48e0-9091-aea9b54ac34aff28734b-14b8-4ffb-99c5-2f28e1fff8ee2d2e01ca-d7b9-4a21-a5ce-0edd9dca9dc9f9986081-3496-4603-bc78-df27635d4c395761a988-9ca0-497c-920e-8621b393db46c166c5b8"; // Replace with the path to your ADO* installation final String sPath = "http://HOST:8080/ADOXX/rest/2.0/repos/" + sRepoID + "/objects"; final StringBuilder aCreationParams = new StringBuilder (); aCreationParams.append ("{"); aCreationParams.append ("\"name\":\"New Object\","); // Replace C_CLASSNAME with the name of your class aCreationParams.append ("\"metaName\":\"C_CLASSNAME\","); aCreationParams.append ("\"attributes\":"); aCreationParams.append ("["); aCreationParams.append ("{"); // Replace A_STRING_ATTR with the name of your attribute aCreationParams.append ("\"metaName\":\"A_STRING_ATTR\","); aCreationParams.append ("\"value\":\"New Value\""); aCreationParams.append ("},"); aCreationParams.append ("{"); // Replace A_BOOLEAN_ATTR with the name of your attribute aCreationParams.append ("\"metaName\":\"A_BOOLEAN_ATTR\","); aCreationParams.append ("\"value\":true");


Author: BOC Group

© 2019, BOC Group /181

aCreationParams.append ("}"); aCreationParams.append ("]"); aCreationParams.append ("}"); final Map <String, String []> aTokenParameters = new HashMap <String, String []> (); final HttpPost aMethod = new HttpPost (sPath); final StringEntity aJSON = new StringEntity (aCreationParams.toString (), ContentType.APPLICATION_JSON); aMethod.setEntity (aJSON); System.out.println ("Sending request to: " + sPath); final long nDate = new Date ().getTime (); final String sDate = String.valueOf (nDate); final String sGUID = UUID.randomUUID ().toString (); aMethod.addHeader ("x-axw-rest-identifier", sKey); aMethod.addHeader ("x-axw-rest-timestamp", sDate); aMethod.addHeader ("x-axw-rest-guid", sGUID); aTokenParameters.put ("x-axw-rest-timestamp", new String [] {sDate}); aTokenParameters.put ("x-axw-rest-guid", new String [] {sGUID}); aTokenParameters.put ("x-axw-rest-identifier", new String [] {sKey}); // Construct the token final String sSecurityToken = createSecurityToken (sSecret, aTokenParameters); aMethod.addHeader ("x-axw-rest-token", sSecurityToken); // The headers controlling the return type and the language do not have to be considered for // token generation aMethod.addHeader ("Accept", "application/json"); aMethod.addHeader ("Accept-Language", "en"); final CloseableHttpResponse aResponse = aClient.execute (aMethod); try { System.out.println ("Request Status Code: " + aResponse.getStatusLine ().getStatusCode ()); } catch (final Exception aEx) { aEx.printStackTrace (); } finally { aResponse.close (); } } private static String createSecurityToken (final String sSecret,


Author: BOC Group

© 2019, BOC Group /181

final Map <String, String []> aDataMap) throws UnsupportedEncodingException, NoSuchProviderException, NoSuchAlgorithmException, InvalidKeyException { final List <byte []> aContent = new ArrayList <byte []> (); final List <String> aAllParams = new ArrayList <String> (); for (final Entry <String, String []> aEntry : aDataMap.entrySet ()) { aAllParams.add (aEntry.getKey ()); for (final String sValue : aEntry.getValue ()) { aAllParams.add (sValue); } } aAllParams.add (sSecret); final Collator aCollator = Collator.getInstance (Locale.US); Collections.sort (aAllParams, aCollator); for (final String aEntry : aAllParams) { aContent.add (aEntry.getBytes ("UTF-8")); } final String PROVIDER_BOUNCYCASTLE = "BC"; final String SHA512 = "HMac/SHA512"; if (Security.getProvider (PROVIDER_BOUNCYCASTLE) == null) { Security.addProvider (new BouncyCastleProvider ()); } final Mac aHmac = Mac.getInstance (SHA512, PROVIDER_BOUNCYCASTLE); final SecretKey aKey = new SecretKeySpec (sSecret.getBytes ("UTF-8"), SHA512); aHmac.init (aKey); aHmac.reset (); int nSize = 0; for (final byte [] aEntry : aContent) { nSize += aEntry.length; } final byte [] aAllParamsArray = new byte [nSize]; int nCount = 0; for (final byte [] aEntry : aContent) { for (final byte aByte : aEntry) { aAllParamsArray[nCount] = aByte; ++nCount; } } final byte [] aResult = aHmac.doFinal (aAllParamsArray);


Author: BOC Group

© 2019, BOC Group /181

return new String (Base64.encodeBase64 (aResult), "UTF-8"); } }

15.7 Sample Implementation (Java): Using HTTP PATCH to Update an Existing Object

The following code shows how to update an existing object using HTTP PATCH. The object is identified by the ID provided in the request URL and the attributes passed in the variable aUpdateParams are set. Replace repository ID, object ID, key, secret, attribute name and value with data fitting your scenario. package Write; import java.io.IOException; import java.io.UnsupportedEncodingException; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.security.NoSuchProviderException; import java.security.Security; import java.text.Collator; import java.util.ArrayList; import java.util.Collections; import java.util.Date; import java.util.HashMap; import java.util.List; import java.util.Locale; import java.util.Map; import java.util.Map.Entry; import java.util.UUID; import javax.crypto.Mac; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import org.apache.commons.codec.binary.Base64; import org.apache.http.client.ClientProtocolException; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpPatch; import org.apache.http.entity.ContentType; import org.apache.http.entity.StringEntity; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.bouncycastle.jce.provider.BouncyCastleProvider; public class StandardRESTfulServicesClientUpdateObject { public static void main (final String [] args) throws ClientProtocolException, IOException, InvalidKeyException, NoSuchAlgorithmException, NoSuchProviderException { final CloseableHttpClient aClient = HttpClients.createDefault ();


Author: BOC Group

© 2019, BOC Group /181

// Replace with the ID of your repository final String sRepoID = "a800755e-c679-4a03-84c7-2e9eee86de42"; // Replace with the ID of the object you want to update final String sObjectID = "3f6e11e4-fb53-408f-b2dd-1dc6c1d68ca2"; // Replace with your key final String sKey = "boc.rest.key.mfb.StandardRESTfulServices"; // Replace with your secret final String sSecret = "d4514a20-0913-4940-8403-f1f58d9fdba8e25bfb85-6066-4449-8970-d1556f126bfa741e2dec-765e-425f-92c7-2a9aef45ea594e947521-1ed7-4773-a244-f75957b5041ec73e334e-37db-4df0-8554-452b1d72208d0e002d92-1451-4513-ab6a-661952c64b8a69b5bb42-0bea-4905-926b-e1ec04e2912369998e61-a355-4f60-a86f-790af5ac4d4cf3d70a24-be75-4168-808c-94fa42d27be065c0e536-7272-48e0-9091-aea9b54ac34aff28734b-14b8-4ffb-99c5-2f28e1fff8ee2d2e01ca-d7b9-4a21-a5ce-0edd9dca9dc9f9986081-3496-4603-bc78-df27635d4c395761a988-9ca0-497c-920e-8621b393db46c166c5b8"; // Replace with the path to your ADO* installation final String sPath = "http://HOST:8080/ADOXX/rest/2.0/repos/" + sRepoID + "/objects/" + sObjectID; final StringBuilder aUpdateParams = new StringBuilder (); aUpdateParams.append ("{"); aUpdateParams.append ("\"attributes\":"); aUpdateParams.append ("["); aUpdateParams.append ("{"); // Replace A_STRING_ATTR with the name of your attribute aUpdateParams.append ("\"metaName\":\"A_STRING_ATTR\","); aUpdateParams.append ("\"value\":\"Updated Value\""); aUpdateParams.append ("}"); aUpdateParams.append ("]"); aUpdateParams.append ("}"); final Map <String, String []> aTokenParameters = new HashMap <String, String []> (); System.out.println (sPath); final HttpPatch aMethod = new HttpPatch (sPath); final StringEntity aJSON = new StringEntity (aUpdateParams.toString (), ContentType.APPLICATION_JSON); aMethod.setEntity (aJSON); final long nDate = new Date ().getTime (); final String sDate = String.valueOf (nDate); final String sGUID = UUID.randomUUID ().toString (); aMethod.addHeader ("x-axw-rest-identifier", sKey); aMethod.addHeader ("x-axw-rest-timestamp", sDate); aMethod.addHeader ("x-axw-rest-guid", sGUID); aTokenParameters.put ("x-axw-rest-timestamp", new String [] {sDate}); aTokenParameters.put ("x-axw-rest-guid", new String [] {sGUID}); aTokenParameters.put ("x-axw-rest-identifier", new String [] {sKey});


Author: BOC Group

© 2019, BOC Group /181

// Construct the token final String sSecurityToken = createSecurityToken (sSecret, aTokenParameters); aMethod.addHeader ("x-axw-rest-token", sSecurityToken); // The headers controlling the return type and the language do not have to be considered for // token generation aMethod.addHeader ("Accept", "application/json"); aMethod.addHeader ("Accept-Language", "en"); final CloseableHttpResponse aResponse = aClient.execute (aMethod); try { System.out.println ("Request Status Code: " + aResponse.getStatusLine ().getStatusCode ()); } catch (final Exception aEx) { aEx.printStackTrace (); } finally { aResponse.close (); } } private static String createSecurityToken (final String sSecret, final Map <String, String []> aDataMap) throws UnsupportedEncodingException, NoSuchProviderException, NoSuchAlgorithmException, InvalidKeyException { final List <byte []> aContent = new ArrayList <byte []> (); final List <String> aAllParams = new ArrayList <String> (); for (final Entry <String, String []> aEntry : aDataMap.entrySet ()) { aAllParams.add (aEntry.getKey ()); for (final String sValue : aEntry.getValue ()) { aAllParams.add (sValue); } } aAllParams.add (sSecret); final Collator aCollator = Collator.getInstance (Locale.US); Collections.sort (aAllParams, aCollator); for (final String aEntry : aAllParams) { aContent.add (aEntry.getBytes ("UTF-8")); }


Author: BOC Group

© 2019, BOC Group /181

final String PROVIDER_BOUNCYCASTLE = "BC"; final String SHA512 = "HMac/SHA512"; if (Security.getProvider (PROVIDER_BOUNCYCASTLE) == null) { Security.addProvider (new BouncyCastleProvider ()); } final Mac aHmac = Mac.getInstance (SHA512, PROVIDER_BOUNCYCASTLE); final SecretKey aKey = new SecretKeySpec (sSecret.getBytes ("UTF-8"), SHA512); aHmac.init (aKey); aHmac.reset (); int nSize = 0; for (final byte [] aEntry : aContent) { nSize += aEntry.length; } final byte [] aAllParamsArray = new byte [nSize]; int nCount = 0; for (final byte [] aEntry : aContent) { for (final byte aByte : aEntry) { aAllParamsArray[nCount] = aByte; ++nCount; } } final byte [] aResult = aHmac.doFinal (aAllParamsArray); return new String (Base64.encodeBase64 (aResult), "UTF-8"); } }

15.8 Sample Implementation (Java): Using HTTP POST to create a Relation between two Existing Objects

The following code shows how to create a relation between two existing objects using HTTP POST. The first object is identified by the ID provided in the request URL, the relation direction is identified by the keyword "outgoing" in the request URL and the relation class is identified by the relation class name within the request URL. The ID of the second object is contained as "toId" in the variable aRelationParams. Replace repository ID, object ID, toId, relation class, relation direction, key and secret with data fitting your scenario. package Write; import java.io.IOException; import java.io.UnsupportedEncodingException; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.security.NoSuchProviderException; import java.security.Security;


Author: BOC Group

© 2019, BOC Group /181

import java.text.Collator; import java.util.ArrayList; import java.util.Collections; import java.util.Date; import java.util.HashMap; import java.util.List; import java.util.Locale; import java.util.Map; import java.util.Map.Entry; import java.util.UUID; import javax.crypto.Mac; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import org.apache.commons.codec.binary.Base64; import org.apache.http.client.ClientProtocolException; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpPost; import org.apache.http.entity.ContentType; import org.apache.http.entity.StringEntity; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.bouncycastle.jce.provider.BouncyCastleProvider; public class StandardRESTfulServicesClientCreateRelation { public static void main (final String [] args) throws ClientProtocolException, IOException, InvalidKeyException, NoSuchAlgorithmException, NoSuchProviderException { final CloseableHttpClient aClient = HttpClients.createDefault (); // Replace with the ID of your repository final String sRepoID = "a800755e-c679-4a03-84c7-2e9eee86de42"; // Replace with the ID of the object you want to update final String sObjectID = "3f6e11e4-fb53-408f-b2dd-1dc6c1d68ca2"; // Replace with the name of the relation class of which you want to create a relation final String sRelClassName = "RC_REL_CLASS_NAME"; // Replace with your key final String sKey = "boc.rest.key.mfb.StandardRESTfulServices"; // Replace with your secret final String sSecret = "d4514a20-0913-4940-8403-f1f58d9fdba8e25bfb85-6066-4449-8970-d1556f126bfa741e2dec-765e-425f-92c7-2a9aef45ea594e947521-1ed7-4773-a244-f75957b5041ec73e334e-37db-4df0-8554-452b1d72208d0e002d92-1451-4513-ab6a-661952c64b8a69b5bb42-0bea-4905-926b-e1ec04e2912369998e61-a355-4f60-a86f-790af5ac4d4cf3d70a24-be75-4168-808c-94fa42d27be065c0e536-7272-48e0-9091-aea9b54ac34aff28734b-14b8-4ffb-99c5-2f28e1fff8ee2d2e01ca-d7b9-4a21-a5ce-0edd9dca9dc9f9986081-3496-4603-bc78-df27635d4c395761a988-9ca0-497c-920e-8621b393db46c166c5b8"; // Replace with the path to your ADO* installation final String sPath = "http://HOST:8000/ADOXX/rest/2.0/repos/" + sRepoID +


Author: BOC Group

© 2019, BOC Group /181

"/objects/" + sObjectID + "/relations/outgoing/" + sRelClassName; final StringBuilder aRelationParams = new StringBuilder (); aRelationParams.append ("{"); // Replace with the ID of the object you want to create a relation to aRelationParams.append ("\"toId\":\"{f1cb2932-05dc-44e0-a5dc-fe5d4f6e3795}\""); aRelationParams.append ("}"); final Map <String, String []> aTokenParameters = new HashMap <String, String []> (); final HttpPost aMethod = new HttpPost (sPath); final StringEntity aJSON = new StringEntity (aRelationParams.toString (), ContentType.APPLICATION_JSON); aMethod.setEntity (aJSON); final long nDate = new Date ().getTime (); final String sDate = String.valueOf (nDate); final String sGUID = UUID.randomUUID ().toString (); aMethod.addHeader ("x-axw-rest-identifier", sKey); aMethod.addHeader ("x-axw-rest-timestamp", sDate); aMethod.addHeader ("x-axw-rest-guid", sGUID); aTokenParameters.put ("x-axw-rest-timestamp", new String [] {sDate}); aTokenParameters.put ("x-axw-rest-guid", new String [] {sGUID}); aTokenParameters.put ("x-axw-rest-identifier", new String [] {sKey}); // Construct the token final String sSecurityToken = createSecurityToken (sSecret, aTokenParameters); aMethod.addHeader ("x-axw-rest-token", sSecurityToken); // The headers controlling the return type and the language do not have to be considered for // token generation aMethod.addHeader ("Accept", "application/json"); aMethod.addHeader ("Accept-Language", "en"); final CloseableHttpResponse aResponse = aClient.execute (aMethod); try { System.out.println ("Request Status Code: " + aResponse.getStatusLine ().getStatusCode ()); } catch (final Exception aEx) { aEx.printStackTrace (); } finally


Author: BOC Group

© 2019, BOC Group /181

{ aResponse.close (); } } private static String createSecurityToken (final String sSecret, final Map <String, String []> aDataMap) throws UnsupportedEncodingException, NoSuchProviderException, NoSuchAlgorithmException, InvalidKeyException { final List <byte []> aContent = new ArrayList <byte []> (); final List <String> aAllParams = new ArrayList <String> (); for (final Entry <String, String []> aEntry : aDataMap.entrySet ()) { aAllParams.add (aEntry.getKey ()); for (final String sValue : aEntry.getValue ()) { aAllParams.add (sValue); } } aAllParams.add (sSecret); final Collator aCollator = Collator.getInstance (Locale.US); Collections.sort (aAllParams, aCollator); for (final String aEntry : aAllParams) { aContent.add (aEntry.getBytes ("UTF-8")); } final String PROVIDER_BOUNCYCASTLE = "BC"; final String SHA512 = "HMac/SHA512"; if (Security.getProvider (PROVIDER_BOUNCYCASTLE) == null) { Security.addProvider (new BouncyCastleProvider ()); } final Mac aHmac = Mac.getInstance (SHA512, PROVIDER_BOUNCYCASTLE); final SecretKey aKey = new SecretKeySpec (sSecret.getBytes ("UTF-8"), SHA512); aHmac.init (aKey); aHmac.reset (); int nSize = 0; for (final byte [] aEntry : aContent) { nSize += aEntry.length; } final byte [] aAllParamsArray = new byte [nSize]; int nCount = 0; for (final byte [] aEntry : aContent) { for (final byte aByte : aEntry)


Author: BOC Group

© 2019, BOC Group /181

{ aAllParamsArray[nCount] = aByte; ++nCount; } } final byte [] aResult = aHmac.doFinal (aAllParamsArray); return new String (Base64.encodeBase64 (aResult), "UTF-8"); } }

boc management office standard restful services

Documents