2021

Administrator Guide
API v5
iServer 2021 Administrator Guide – API v5

Product Release Information

Product: iServer

Document Release Number: 2.1

Document Release Date: 20 Oct 2021

Copyright © 2021 by Orbus Software

All Rights Reserved

No part of this publication may be reproduced, distributed, or transmitted in any form or by

any means, including photocopying, recording, or other electronic or mechanical methods,
without the prior written permission of the publisher, except in the case of brief quotations
embodied in critical reviews and certain other noncommercial uses permitted by
copyright law.

If you have any queries, you can contact the Orbus Software by email:
[email protected]

2
iServer 2021 Administrator Guide – API v5

Contents
1. iServer Repository API ..................................................................................................................................................... 5

1.1 Introduction to the Repository API .........................................................................................................................................5

1.2 Authenticating with the API ...........................................................................................................................................................5

1.3 Retrieving Repository Data (GET) ............................................................................................................................................6

1.3.1 GET List of Items by Type .....................................................................................................................................................6

1.3.2 GET Item by ID .................................................................................................................................................................................8

1.3.3 GET List of Relationships by Type ................................................................................................................................9

1.3.4 GET Relationship by ID .......................................................................................................................................................... 10

1.3.5 GET Related Items ....................................................................................................................................................................... 11

1.3.6 GET Attributes for an Item ................................................................................................................................................ 12

1.3.7 GET Attributes for a Relationship ............................................................................................................................... 12

1.3.8 GET Relationships between repository items by IDs ............................................................................. 13

1.3.9 GET Libraries .................................................................................................................................................................................... 14

1.3.10 GET the contents of a Folder ......................................................................................................................................... 14

1.3.11 GET Visio document page image ............................................................................................................................ 15

1.3.12 GET Visio document contents ...................................................................................................................................... 15

1.3.13 GET places where an Object is used .................................................................................................................... 16

1.3.14 GET Existing Users ...................................................................................................................................................................... 16

1.4 Creating Repository Data (POST) ......................................................................................................................................... 17

1.4.1 POST New Item ............................................................................................................................................................................. 17

1.4.2 POST New Relationship ........................................................................................................................................................ 18

1.4.3 POST a List View ........................................................................................................................................................................... 19

1.4.4 POST a Hierarchy View ....................................................................................................................................................... 20

1.4.5 POST a Library ............................................................................................................................................................................... 21

1.5 Updating Repository Data (PUT) ...........................................................................................................................................23

1.5.1 PUT Properties and Attributes for an Item ......................................................................................................23

1.5.2 PUT Properties and Attributes for a Relationship .................................................................................... 24

3
iServer 2021 Administrator Guide – API v5

1.5.3 PUT Attributes for an Item (V1) ................................................................................................................................... 25

1.5.4 PUT Attributes for a Relationship (V1) .................................................................................................................. 26

1.5.5 PUT System Properties for Objects (V1) .............................................................................................................. 27

1.5.6 PUT System Properties for Relationships (V1) ............................................................................................. 28

1.6 Deleting Repository Data (DELETE)............................................................................................................................... 29

1.6.1 DELETE Item by ID...................................................................................................................................................................... 29

1.6.2 DELETE Relationship by ID ................................................................................................................................................ 29

2. iServer Views API............................................................................................................................................................... 30

1.7 Introduction to the Views API................................................................................................................................................... 30

1.7.1 GET Views ......................................................................................................................................................................................... 30

3. Metamodel API..................................................................................................................................................................... 31

1.8 Introduction to the Metamodel API............................................................................................................................... 31

1.8.1 GET Attribute Configuration............................................................................................................................................ 31

1.8.2 GET Object Types ......................................................................................................................................................................32

1.8.3 POST an Object Type ............................................................................................................................................................32

1.8.4 GET Document Types ...........................................................................................................................................................32

1.8.5 GET Relationship Types...................................................................................................................................................... 34

1.8.6 POST a Relationship Type................................................................................................................................................ 34

1.8.7 PUT a Relationship Type ................................................................................................................................................... 35

1.8.8 POST an Attribute Type ...................................................................................................................................................... 35

1.8.9 POST Attribute Assignment ............................................................................................................................................ 37

4. Support and Resources ............................................................................................................................................ 38

1.9 Hypermedia Support ................................................................................................................................................................. 38

1.9.1 Repository API Status Codes........................................................................................................................................ 38

1.9.2 Request Encoding ................................................................................................................................................................... 39

1.10 Orbus Support .................................................................................................................................................................................. 40

1.11 Online Webinars, White Papers and Training ......................................................................................................... 40

4
iServer 2021 Administrator Guide – API v5

1. iServer Repository API

1.1 Introduction to the Repository API
The iServer Repository API provides inbound and outbound REST-based web-services for
interaction with iServer Repository content. The API lets you:

• Programmatically synchronize iServer repository content with external systems

• Use iServer as a data provider or data consumer for third-party systems
• Support objects, relationships, folders, and documents, as well as attributes
• Control permissions and version management of repository content

Note: Users of the API need an iServer User License. Please contact your system
administrator for more information.

Once the iServer Repository API is deployed to your environment, you can access online
Swagger API interface using the following URL:

https://{your API URL}/Api/swagger/ui/index

The Swagger online API documentation is available at the following URL by default:

https://{your API URL}/Api/swagger/docs/v4

1.2 Authenticating with the API

The iServer API v5 supports the following types of authentication:

• Azure AD authentication using OAuth2

For more information how to set up the iServer API to use Azure AD authentication, see
the OAuth2 Integration with iServer API document.

• Basic authentication with an iServer username and password

You need a valid iServer user account with permission to use the Repository API (a
profile feature permission)

Note: All content changed or created via the API will be done so under the
authenticated user’s account. Content retrieval will also be based on the
authenticated user’s permissions.

5
iServer 2021 Administrator Guide – API v5

1.3 Retrieving Repository Data (GET)

The GET methods allow you to request the details of a specified repository object,
document, folder, or relationship, including system and custom attributes, and related
items.

1.3.1 GET List of Items by Type

URI Format: GET /api/item

Request Body Elements

Name Required Parameter Description

Type

$filter yes Query Filter the items returned by specifying the object,
document, or folder type name using the
following syntax:

Type eq ‘type name’

Name eq ‘item name’

Library eq ‘library name’

Attributes/[attribute name] eq ‘attribute value’

You can also use ‘AND’ and ‘OR’ operators for

multiple filters.

$expand no Query Optionally insert ‘Attributes’ to return all attributes

for the item, or filter to return a names attribute
using the following:

Attributes($select={attribute name})

Example GET Requests:

• Get a list of ‘Actor’ type objects, returning the ‘Owner’ custom attribute:

https://bigbank.orbuscloud.com/api/item?$filter=Type%20eq%20'actor
'&$expand=Attributes(%24select%3DOwner)

• Get all ‘Process’ type objects with the Name equal to Process Name:

https://bigbank.orbuscloud.com/api/item?$filter=Name%20eq%Process
Name'%20and%20Type%20eq%20'Process'

6
iServer 2021 Administrator Guide – API v5

When using any OData parameters with attribute name values, please see the Request
Encoding section for more details.

7
iServer 2021 Administrator Guide – API v5

1.3.2 GET Item by ID

URI Format: GET /api/item/{id}

Request Body Elements

Name Required Parameter Description

Type

id yes Path Insert the items iServer ID

$expand no Query Optionally insert the word ‘Attributes’ to return all

attributes for the item, or filter to return a specific
attribute using the following:
Attributes($select={attribute name})

You can also expand ‘RelatedItems’ to return

related items and relationship information. You
can further expand relationship attributes using
the following input:

RelatedItems,Relationship($expand=Attributes)

Example GET Request: Get an item by specifying its ID and return all custom attributes:

https://bigbank.orbuscloud.com/api/item/9b9f968c-d063-477f-87b5-
03339ff24e6a?$expand=Attributes

8
iServer 2021 Administrator Guide – API v5

1.3.3 GET List of Relationships by Type

URI Format: GET /api/relationship

Request Body Elements

Name Required Parameter Description

Type

$filter no Query Optionally filter the items returned by specifying

the relationship’s Type, SourceItem/Library,
SourceItem/Type, TargetItem/Library, and/or
TargetItem/Type (e.g.: Type eq 'Association' or
Type eq 'Composition'), using the following syntax:

Type eq “[relationship type name]”

$expand no Query Optionally insert the word ‘Attributes’ to return all

attributes for the relationship, or filter to return a
names attribute using the following:
Attributes($select=[attribute name])

Optionally insert the word ‘sourceitem’ or

’targetitem’ to expand details of the pairs of the
relationship.

Example GET Request: Get a list of relationships of type ‘EXT: Work Package Contributes to
Goal’, and return all custom attributes:

https://bigbank.orbuscloud.com/api/relationship?$filter=Type%20eq%
20'EXT%3A%20Work%20Package%20contributes%20to%20Goal'&$expand=Attr
ibutes

9
iServer 2021 Administrator Guide – API v5

1.3.4 GET Relationship by ID

URI Format: GET /api/relationship/{id}

Request Body Elements

Name Required Parameter Description

Type

id yes Path Insert the relationship’s iServer ID.

$expand no Query Insert the word ‘Attributes’ to return all attributes for
the relationship, or filter to return a specific attribute
using the following: Attributes($select={attribute
name}).

Optionally insert the word ‘sourceitem’ or

’targetitem’ to expand details of the pairs of the
relationship.

Example GET Request: Return a specific relationship by its iServer ID and return all custom
attributes:

https://bigbank.orbuscloud.com/api/relationship/4cded933-08a2-
4202-b69f-6ce6d3487e4a?$expand=Attributes

10
iServer 2021 Administrator Guide – API v5

1.3.5 GET Related Items

URI Format: GET /api/item/{id}/relateditems

Request Body Elements

Name Required Parameter Description

Type

id yes Path Insert the object or document’s iServer ID

relationshipType no Query Leave this element blank to return all

related items, or filter related items by
specifying the {Relationship Type Name}

$expand no Query Optionally insert the word ‘Attributes’ to

return relationship attributes along with a
relationship.

Example GET Request: Return the related items of a source object, specifying its iServer ID,
and filtering related items by the ‘Work Package constitutes Work Package’ relationship
type. All custom attributes of related items are requested:

https://bigbank.orbuscloud.com/api/item/bbbe2223-6a24-409c-8452-
f4a2106382be/relateditems?relationshipType=TOGAF%3A%20Work%20Packa
ge%20constitutes%20Work%20Package&$expand=Attributes

11
iServer 2021 Administrator Guide – API v5

1.3.6 GET Attributes for an Item

URI Format: GET /api/item/{id}/attributevalues

Request Body Elements

Name Required Parameter Description

Type

id yes Path Insert the object or document’s iServer ID

Example GET Request: Return all the attributes of an ‘Actor’ object type by specifying its
iServer ID:

https://bigbank.orbuscloud.com/api/item/6ae42ff2-68bd-4cee-b47b-
0759e4ea59c0/attributevalues

1.3.7 GET Attributes for a Relationship

URI Format: GET /api/relationship/{id}/attributes

Request Body Elements

Name Required Parameter Description

Type

id yes Path Insert the relationship’s iServer ID.

Example GET Request: Return all attributes for a relationship by specifying the relationships
iServer ID:

https://bigbank.orbuscloud.com/api/relationship/00380dbb-ab1c-
4321-b599-92a88c608da0/attributes

12
iServer 2021 Administrator Guide – API v5

1.3.8 GET Relationships between repository items by IDs

URI Format: GET /api/relationship/{sourceId}/{targetId}

Request Body Elements

Name Required Parameter Description

Type

sourceId yes path Insert the iServer ID of the source item

targetId yes path Insert the iServer ID of the target item

relationshipType no query Optionally specify the metamodel name of

the relationship type (e.g.: ‘BPMN: Drill
Down’)

$expand no query Optionally expand attributes of

relationships by specifying 'SourceItem',
'TargetItem' or 'Attributes'

Example GET Request: Return all the relationships between two repository items by
specifying the iServer ID’s of each item (source and target items of the relationship):

https://bigbank.orbuscloud.com/api/relationship/298b2b68-a4b8-
493c-962c-a4da2059376e/94629db8-ee30-48e4-901e-153bdddfb299

13
iServer 2021 Administrator Guide – API v5

1.3.9 GET Libraries

URI Format: GET /api/libraries

Request Body Elements

Name Required Parameter Description

Type

$expand no Query Insert the word ‘Attributes’ to return all

attributes for the libraries, or filter to return
a named attribute using the following:

Attributes($select=[attribute name])

Example GET Request: Return a list of all libraries in the repository including their assigned
attributes:

https://bigbank.orbuscloud.com/api/libraries?$expand=Attributes

1.3.10 GET the contents of a Folder

URI Format: GET /api/folder/{id}/content

Request Body Elements

Name Required Parameter Description

Type

id yes Path Insert the folder or library’s iServer ID

$filter no Query Leave this element blank to return documents

and sub-folders, or enter {Document} to return
documents or {Folder} to return sub-folders

$expand no Query Optionally insert the word ‘Attributes’ to return all

attributes for the documents and sub-folders

Example GET Request: Return all documents and sub-folders of a folder based on its ID:

https://bigbank.orbuscloud.com/api/folder/298b2b68-a4b8-493c-962c-
a4da2059376e/content

14
iServer 2021 Administrator Guide – API v5

1.3.11 GET Visio document page image

URI Format: GET /api/document/visiopage

Request Body Elements

Name Required Parameter Description

Type

documentName yes Query Insert name of a Visio document

library yes Query Insert name of a library where a Visio

document is stored

pageNumber yes Query Insert page number of a Visio document

that you want to preview

Example GET Request: Return a .png file for a page of a Visio document stored under
specified library:

https://bigbank.orbuscloud.com/api/document/visiopage?documentName
=Business%20Architecture&library=System%20Repository&pageNumber=2

1.3.12 GET Visio document contents

URI Format: GET /api/document/visiocontent

Request Body Elements

Name Required Parameter Description

Type

diagramId yes Query Insert the Visio document’s iServer ID

Example GET Request: Return the list of all objects and relationships that are used in a Visio
diagram by specifying the document’s ID in iServer:

https://bigbank.orbuscloud.com/api/document/visiocontent?diagramId
=94629db8-ee30-48e4-901e-153bdddfb299

15
iServer 2021 Administrator Guide – API v5

1.3.13 GET places where an Object is used

URI Format: GET /api/item/{objectId}/whereused

Request Body Elements

Name Required Parameter Description

Type

objectId yes Path Insert the object’s iServer ID

Example GET Request: Return a list of Visio diagrams that an object is used in, by specifying
object’s ID in iServer:

https://bigbank.orbuscloud.com/api/item/94629db8-ee30-48e4-901e-
153bdddfb299/whereused

1.3.14 GET Existing Users

URI Format: GET /api/user

Example GET Request: Return a list of all users existing in iServer:

https://bigbank.orbuscloud.com/api/user

16
iServer 2021 Administrator Guide – API v5

1.4 Creating Repository Data (POST)

These methods can be used to create new folders, objects and relationships, along with
attribute values. Documents are not supported using the POST methods as they need to be
created using native Office and Visio applications.

Note: If ‘Item Approval’ is enabled in iServer, all objects created via the API using
POST will be left in a draft, checked-out state in the repository.

Repository items with mandatory attributes are not currently supported by the API
POST methods.

1.4.1 POST New Item

URI Format: POST /api/item

Request Body Elements

Name Required Parameter Description

Type

Item yes Body Specify the Name, Type, and Library of the new
item using the following syntax:

“Name”: “item name”,

“Type”: “type name”,

“Library”: “library name”,

“Description”: “item description”,

“VersionName”: “item version number”,

“Attributes”: {“attribute name”: “attribute value”}

Note: Objects and Folders can only be created in Libraries, not in folders or sub-
folders.

17
iServer 2021 Administrator Guide – API v5

1.4.2 POST New Relationship

URI Format: POST /api/item/{sourceId}/relateditems/{targetId}

Request Body Elements

Name Required Parameter Description

Type

sourceId yes Path Insert the iServer ID of the source item

(relationship ‘from’) of the new relationship

targetId yes Path Insert the iServer ID of the target item

(relationship ‘to’) of the new relationship

relationshipType yes Query Enter the relationship type name to be used

Name for the new relationship

isReversed no Query Optionally reverse the relationship, switching

source and target items – the default is
false

Example POST Request: Create a new relationship between source and target objects or
documents by specifying their iServer ID’s. The relationship type to be used is ‘EXT: Work
Package contributes to Goal’:

https://bigbank.orbuscloud.com/api/item/bbbe2223-6a24-409c-8452-
f4a2106382be/relateditems/e634c7a8-8eef-453e-8422-
091d01fc1e1c?relationshipTypeName=EXT%3A%20Work%20Package%20contri
butes%20to%20Goal

18
iServer 2021 Administrator Guide – API v5

1.4.3 POST a List View

URI Format: POST /api/views/listview

Request Body Elements

Name Required Parameter Description

Type

createListView yes Body Required information to specify in the

Request createListViewRequest field needs to be
produced from matching version of iServer
Desktop. For this in iServer Desktop, create a
list view, navigate to it from the Views
Dashboard, and then produce an XML by
selecting Export.

Pass the exported XML as the

createListViewRequest parameter value.

Example POST Request: Create a list view:

https://bigbank.orbuscloud.com/api/views/listview

19
iServer 2021 Administrator Guide – API v5

1.4.4 POST a Hierarchy View

URI Format: POST /api/views/hierarchyview

Request Body Elements

Name Required Parameter Description

Type

createHierarchy yes Body Required information to specify in the

ViewRequest createHierarchyViewRequest field needs to
be produced from matching version of
iServer Desktop. For this in iServer Desktop,
create a hierarchy view, navigate to it from
the Views Dashboard, and then produce an
XML by selecting Export.

Pass the exported XML as the

createHierarchyViewRequest parameter
value.

Example POST Request: Create a hierarchy view:

https://bigbank.orbuscloud.com/api/views/hierarchyview

20
iServer 2021 Administrator Guide – API v5

1.4.5 POST a Library

URI Format: POST /api/library

Request Body Elements

Name Required Parameter Description

Type

library yes Body Specify the Name and Folder Type of the
new library.

Optionally specify the Location ID (either

Folder or System Repository ID; if nothing is
specified, library will be created in the
System Repository), Description, Permissions
(by default, permissions applied to the
parent library/folder are applied to the new
library). Use the following syntax:

“Name”: “library name”,

“FolderType”: “folder type name”,

“LocationId”: “folder/System Repository ID”,

“Description”: “library description”,

“Permissions”: [

"ProfileName": "string",

"HasRead": true,

"HasModify": true,

"HasDelete": true,

"HasModifyContents": true,

"HasModifyRelationships": true

21
iServer 2021 Administrator Guide – API v5

Example POST Request: Create a library:

https://bigbank.orbuscloud.com/api/library?Name=Business%20Archite
cture &FolderType=library

22
iServer 2021 Administrator Guide – API v5

1.5 Updating Repository Data (PUT)

The PUT methods allow you to update custom attributes for objects, documents,
relationships and folders. A new PUT endpoint supporting a request body is available in API
v2, however the PUT endpoints used in API v1 are still available and tagged as legacy.

Note: If ‘Item Approval’ is enabled in iServer, all objects edited via the API using PUT
will be left in a draft, checked-out state in the repository. Repository items with
mandatory attributes are not currently supported by the API PUT methods.

1.5.1 PUT Properties and Attributes for an Item

URI Format: PUT /api/item

Request Body Elements

Name Required Parameter Description

Type

Item yes Body Specify the iServerID, Name, Description and

Attributes of the new item using the following
syntax:

“iServerID”: “iServerID”,

“Name”: “item name”,

“Description”: “item description”,

“VersionName”: “item version number”,

“Attributes”: {“attribute name”: “attribute value”}

Note: Remove sections in the body that are not being updated by the PUT request.
For example, ‘Name’ should not be included in the request body if it is not being
updated.

23
iServer 2021 Administrator Guide – API v5

1.5.2 PUT Properties and Attributes for a Relationship

URI Format: PUT /api/relationship

Request Body Elements

Name Required Parameter Description

Type

Item yes Body Specify the iServerID, Name, Description and

Attributes of the new item using the following
syntax:

“iServerId”: “iServerID”,

“Description”: “Relationship Description”,

“Attributes”: {“attribute name”: “attribute value”}

Note: Remove sections in the body that are not being updated by the PUT request.
For example, ‘Description’ should not be included in the request body if it is not
being updated.

24
iServer 2021 Administrator Guide – API v5

1.5.3 PUT Attributes for an Item (V1)

URI Format: PUT /api/item/{id}/attributevalues

Request Body Elements

Name Required Parameter Description

Type

Id yes Path Insert the iServer ID of the item you wish to

update. Objects, documents, and folders
are supported with this method

attributeName yes Query Provide a Name of the attribute you wish

to update

value no Query Optionally provide a new value for the

attribute – the value should align with the
data type and validation as configured in
the metamodel

Example PUT Request: Identify an item by its ID, and update the ‘Accountable Executive’
attribute and provide an attribute value of ‘John Smith’:

https://bigbank.orbuscloud.com/api/item/bbbe2223-6a24-409c-8452-
f4a2106382be/attributevalues?attributeName=PPM%3A%20Accountable%20
Executive%20&value=John%20Smith

25
iServer 2021 Administrator Guide – API v5

1.5.4 PUT Attributes for a Relationship (V1)

URI Format: PUT /api/relationship/{id}/attributevalues

Request Body Elements

Name Required Parameter Description

Type

Id yes Path Insert the iServer ID of the relationship you

wish to update

attributeName yes Query Provide a Name of the relationship attribute

you wish to update

value yes Query Provide a new value for the attribute – the
value should align with the data type and
validation as configured in the metamodel

Example PUT Request: Identify a relationship by its ID and update the ‘Owner’ attribute with
a value ‘Business Development’:

https://bigbank.orbuscloud.com/api/relationship/4f258f3c-8b4f-
4d72-9a46-
0067e1a11cde/attributevalues?attributeName=Owner&value=Business%20
Development

26
iServer 2021 Administrator Guide – API v5

1.5.5 PUT System Properties for Objects (V1)

URI Format: PUT /api/item/{id}

Request Body Elements

Name Required Parameter Description

Type

Id yes Path Insert the iServer ID of the object you wish to

update

propertyName yes Query Provide a Name of the system property you

wish to update (for example, “Description”)

value yes Query Provide a new value for the property – the
value should align with the data type and
validation as configured in the metamodel

Example PUT Request: Populate the text description of an object to state ‘a business-
critical application’:

https://bigbank.orbuscloud.com/api/item/4f258f3c-8b4f-4d72-9a46-
0067e1a11cde?propertyName=Description&value=A%20business%20critica
l%20application

27
iServer 2021 Administrator Guide – API v5

1.5.6 PUT System Properties for Relationships (V1)

URI Format: PUT /api/relationship/{id}

Request Body Elements

Name Required Description

Id yes Insert the iServer ID of the relationship you wish to

update

propertyName yes Provide a Name of the system property you wish to

update (for example, “Description”)

value yes Provide a new value for the property – the value should
align with the data type and validation as configured in
the metamodel

Example PUT Request: Populate the text description of a relationship to state ‘application
support for critical capability:

https://bigbank.orbuscloud.com/api/relationship/4f258f3c-8b4f-
4d72-9a46-
0067e1a11cde/Description?value=Application%20support%20for%20criti
cal%20capability

Note: The propertyName endpoint only supports the Description system property.
Please use the PUT endpoint supporting body (1.5.2) for additional properties.

28
iServer 2021 Administrator Guide – API v5

1.6 Deleting Repository Data (DELETE)

This method allows you to delete repository objects, documents, and folders.

Note: Items deleted via the API will not be purged from the repository.

1.6.1 DELETE Item by ID

URI Format: DELETE /api/item/{id}

Request Body Elements

Name Required Description

Id yes Insert the iServer ID for the document, object, or folder.

Example DELETE Request: Delete an item identified by its iServer ID:

https://bigbank.orbuscloud.com/api/item/94336f37-6c31-4bcb-b7a9-
cdec82545ed8

1.6.2 DELETE Relationship by ID

URI Format: DELETE /api/relationship/{id}

Request Body Elements

Parameter Required Description

Id yes Insert the iServer ID for the relationship.

Example DELETE Request: Delete a relationship identified by its iServer ID:

https://bigbank.orbuscloud.com/api/relationship/efea033f-1ce3-
4428-b04e-2ae371045093

29
iServer 2021 Administrator Guide – API v5

2. iServer Views API

1.7 Introduction to the Views API
The iServer Views API supports the retrieval of saved views within the repository, including
the view definitions and view results. The Views API lets you:

• Query pre-filtered repository content such as lists of applications with a high support
cost
• Drive reports and dashboards on your repository data with and API web data source

Note: Only list and hierarchy views are supported in API v2. Matrix views cannot be
retrieved.

1.7.1 GET Views

URI Format: GET /api/views/{collection}/{view}

Request Body Elements

Name Required Parameter Description

Type

collection yes Path Specify the name of the view collection. Ensure
special characters are encoded (see Request
Encoding)

view yes Path Specify the name of the List or Hierarchy view.
Ensure special characters are encoded (see
Request Encoding)

$expand no Query Return view results by expanding ‘Items’. Return

all levels of a Hierarchy View and attributes with
Items($expand=RelatedItems($levels=max),
Attributes)

Note: Always use $expand=items to return the content/results of the view.

Note: For hierarchy views, relationship attributes are returned too.

30
iServer 2021 Administrator Guide – API v5

3. Metamodel API
1.8 Introduction to the Metamodel API
The iServer Metamodel API supports retrieval of available object types, relationship types
and attribute assignment. This API lets you:

• Understand the metamodel structure without accessing the iServer client

• Programmatically retrieve the metamodel components such as which Object Types
can be created in a given Folder Type.
• Query available metadata fields before updating or creating a repository item (GET
attribute assignment)

1.8.1 GET Attribute Configuration

URI Format: GET /api/metaModel/attributes/{typeName}/{generalTypeName}

Request Body Elements

Name Required Parameter Description

Type

typeName yes Path Specify the metamodel type name (e.g.:

Actor)

generalTypeName yes Path Specify the type of metamodel item (e.g.:

Object, Document, Relationship, Folder)

dataTypes no Query Specify data type of attributes to show in

the response (e.g.: List, Text, Date, Integer,
Decimal, Boolean, RichText)

Example GET Request: Retrieve the attribute configuration for the ‘Actor’ object type:

https://bigbank.orbuscloud.com/api/metaModel/attributes/Actor/Obje
ct?dataTypes=List

31
iServer 2021 Administrator Guide – API v5

1.8.2 GET Object Types

URI Format: GET /api/metaModel/objectType

Request Body Elements

Name Required Parameter Description

Type

folderTypeName no Path Optionally specify the folder type name

to return a list of allowed Object Types

Note: To return a list of all object types in the metamodel, leave the folderTypeName
parameter blank.

Example GET Request: Retrieve a list of object types available in the ‘Training Area’ folder
type:

https://bigbank.orbuscloud.com/api/metaModel/objectType?folderType
Name=Training%20Area

1.8.3 POST an Object Type

URI Format: POST /api/metaModel/objectType

Request Body Elements

Name Required Parameter Description

Type

objectType yes Body Specify the Name of a new object type.

Optionally specify Description, Object
Type Color (by default, 1 which represents
Lochmara), Icon (by default, 6 which
represents Default Small icon), and
EnforceUniqueNaming (by default, True)

Example POST Request: Create a new object type with the name Actor:

https://bigbank.orbuscloud.com/api/metaModel/objectType?Name=Actor

1.8.4 GET Document Types

URI Format: GET /api/metaModel/documenttypeslist

Example GET Request: Retrieve a list of names of all document types existing in iServer:

32
iServer 2021 Administrator Guide – API v5

https://bigbank.orbuscloud.com/api/metaModel/documenttypelist

33
iServer 2021 Administrator Guide – API v5

1.8.5 GET Relationship Types

URI Format: GET /api/metaModel/relationshipTypes

Request Body Elements

Name Required Parameter Description

Type

sourceTypeName yes Query Specify the source items

metamodel type name

sourceGeneralTypeName yes Query Specify the type of metamodel

item (e.g.: Object, Document,
Relationship, Folder)

targetTypeName yes Query Specify the target items

metamodel type name

targetGeneralTypeName yes Query Specify the type of metamodel

item (e.g.: Object, Document,
Relationship, Folder)

Note: Any-to-any relationship types are not supported in API v2 and will not be
returned in the response.

Example GET Request: Retrieve a list of relationship types available between the ‘Actor’ and
‘Location’ Object Types:

https://bigbank.orbuscloud.com/api/metaModel/relationshipTypes?sou
rceTypeName=Actor&sourceGeneralTypeName=Object&targetTypeName=Loca
tion&targetGeneralTypeName=Object

1.8.6 POST a Relationship Type

URI Format: POST /api/metaModel/relationshipType

Request Body Elements

Name Required Parameter Description

Type

34
iServer 2021 Administrator Guide – API v5

relationshipType yes Body Specify Name, Source and Target Types,

and Direction descriptions. Optionally
specify other parameters

Example POST Request: Create a new relationship type and specify its pair:

https://bigbank.orbuscloud.com/api/metaModel/relationshipTypes?Nam
e=RT1&SourceType=Object&TargetType=Location

1.8.7 PUT a Relationship Type

URI Format: PUT /api/metaModel/relationshipType

Request Body Elements

Name Required Parameter Description

Type

relationshipType yes Body Specify the relationship type ID and the

properties that you want to update.

ForceUpdate may be set to define whether

the operation will be completed in case it
affects existing relationships

Example PUT Request: Update the name of existing relationship type:

https://bigbank.orbuscloud.com/api/metaModel/relationshipTypes?Id=
caca83a8-c372-496d-9000-b2d7e5338117&sourceType=Object&Name=RT2

1.8.8 POST an Attribute Type

URI Format: POST /api/metaModel/attributeType

Request Body Elements

Name Required Parameter Description

Type

attributeType yes Body Specify the Name of a new attribute type.

Optionally specify Description, Data Type (by

default, Text), Tooltip Text, Is Mandatory value,
Row Height (by default, 1), Default Value, Lower
Limit, Upper Limit, Sync with Visio, Visio Sync
Name (by default, Attribute Name), Profile

35
iServer 2021 Administrator Guide – API v5

Permissions for Read and Modify,

ListSourceType (by default, Custom),
ListValues (used when attribute list is set to
Custom)

Example POST Request: Create a new Boolean attribute type:

https://bigbank.orbuscloud.com/api/metaModel/attributeTypes?Name=
Details&DataType=Boolean

36
iServer 2021 Administrator Guide – API v5

1.8.9 POST Attribute Assignment

URI Format: POST /api/metaModel/attributes

Request Body Elements

Name Required Parameter Description

Type

attributeAssignments yes Body Specify the Name, General Type

(Object, Folder, Document, or
Relationship) for the attribute holder
type, and an array of Tabs, each
specifying a Tab Name and an array
of Attribute Type Names to assign;

if the Tab does not exist, it will be

created automatically

Example POST Request: Assign the Details attribute to an object type:

https://bigbank.orbuscloud.com/api/metaModel/attributes?Name=
Details&GeneralType=Object

Note: Upon creating an attribute that is not related to the current attribute type,
error is returned.

37
iServer 2021 Administrator Guide – API v5

4. Support and Resources

1.9 Hypermedia Support
The API implements the HAL pattern to provide responses with links to related resources
and, if desired, embedded objects. For example, an item from the iServer repository might
also have relationships to other items (related items). In this case a link to the related items
is provided, along with the option to embed them in the response using the $expand
parameter in the URL, (as seen in the GET examples in section 3).

HAL responses are only supported as JSON. In order for the API to provide a HAL response a
Request header of value application/hal+json must be specified.

1.9.1 Repository API Status Codes

The following table lists the response codes for API requests.

Status Code Message Description

200 Success Success with response body

201 Created Success with response body

400 Bad Request URL does not match the API in the system, or
the operation failed for unknown reasons – invalid
headers

401 Unauthorized User is not authorized to use the API

403 Forbidden The requested operation is not permitted for the user –
this error can be caused by access control failures, or
business rule, or data policy constraints

404 Not Found The requested resource does not exist – this can be
caused by access control constraints, or if the resource
does not exist.

406 Not The endpoint does not support the response format
Acceptable specified in the request Accept header

38
iServer 2021 Administrator Guide – API v5

1.9.2 Request Encoding

When using any OData parameters with attribute name values and other API requests, the
following attribute name characters should be substituted:

Spaces are replaced by ‘_x0020_’

For example, Actor Goal is replaced by ‘Actor_x0020_Goal’

Colons are replaced by ‘_x003A_’

For example, Cost:Applications is replaced by ‘Cost_x003A_Applications’

Semicolons are replaced by ‘_x003B_’

The following table lists all encoding required for special characters in certain API requests

Character Encoded

Dollar (“$”) _x0024_

Ampersand (“&”) _x0026_

Plus (“+”) _x002B_

Comma (“,”) _x002C_

Forward Slash (“/”) _x002F_

Colon (“:”) _x003A_

Semi-colon (“;”) _x003B_

Equals (“=”) _x003D_

Question mark (“?”) _x003F_

At symbol (“@”) _x0040_

Space _x0020_

39
iServer 2021 Administrator Guide – API v5

1.10 Orbus Support

Orbus support can assist with any technical iServer queries, as well as any queries with
iServer Communication and Integration modules. You can get in touch by:

• Sending an Email to [email protected]

• Using the integrated Orbus Ecosystem under Technical Support

If you do not have a support account, please email [email protected] to

request one.

If you have a support account but have lost the password, you can reset it here:
http://support.orbussoftware.com/access/help

Any queries or support issues with the iServer e-Learning, please contact Good e-Learning
at: [email protected]

For any other queries, please contact your dedicated Orbus Account Manager.

1.11 Online Webinars, White Papers and Training

A wide range of additional resources are also available on the support website, as well as
from the Orbus Ecosystem for registered users, including:

• Videos—training and guidance on a variety of topics. You can view the instructional
videos here: https://www.orbussoftware.com/resources/videos/
• White Papers—a large number of useful articles on a variety of topics related to
Enterprise Architecture and Business Process Analysis:
https://www.orbussoftware.com/resources/

40