Knowledge is profit!

ArchiGraph.MDM

Brief API description

API demo

Performance benchmark

ArchiGraph.MDMAPI overview

The more detailed info on the ArchiGraph.MDM API, and guidelines for data exchange adapters implementation may be found in the Technical Guide..

Transport level of data exchange between MDM and applications

The ArchiGraph.MDM API is implemented using XML packages exchange with client applications. Packages may be transported using various ways: with message queues, MQ (the preferable way, especially for high-load and high-fidelity architectures), SOA services, direct HTTP requests. Anyway, the packages and the sequence of their exchange does not depend on particular transport.

When the data exchange is performed with MQ queues, for MDM and each of the client applications two queues are created, for incoming and outgoing messages. Various queue managers may be used: from Apache ActiveMQ or Rabbit MQ to the IBM WebSphere MQ.

Messages routing is usually provided by the messages broker or ESB. It is responsible for transporting messages from outgoing queue of the sender to the incoming queues of all the receivers. Routing rules are set in the broker/ESB. They may rely on the packages attributes or content. Various broker/ESB solutions may be used, including Apache Synapse, WSO2 stack, or IBM WebSphere ESB.

Data exchange diagram

The core type of packages used in MDM data exchange are listed below:

MDM information exchange diagram

As we can see, client applications may query MDM with the requests of four principal types. Below we provide an overview of all those request and response types.

Also you can use ArchiGraph.MDM API demo to see how it is working.

DataModelRequest - data model structure request

CatalogRequest - request for all the objects of a specified class

EntityRequest - request for the particular object

ChangesRequest - request for editing an object

DataModel - dete model structure response

Package - particular objects information response

OperationResults - operation result response

InvalidPackage - request processing error response

DataModelRequest
data model structure request

Arguments: StartElement - root element of the target model fragment. If omitted, the whole model is returned.

Response: DataModel - a package containing description of the information model structure, including definitions of all its classes, attributes and relations.
In case of error, MDM returns the next package in response to this and all the other requests: InvalidPackage.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<DataModelRequest StartElement="Companies"/>

CatalogRequest
request for all the objects of a specified class

Arguments: Code - class identifier
Filters also may be specified (description is out of scope of this document, see Technical Guide)

Response: Package - package containing all the entities of a class specified.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<CatalogRequest Code="Companies" ></CatalogRequest>

EntityRequest
request for the particular object

Arguments: Code - idenfitier of the object to be retrieved.

Response: Package - package containing the requested object information.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<EntityRequest Code="JohnSmith" ></EntityRequest>

ChangesRequest
request for editing an object

Arguments: Package contains Item tags, which are described in the Package tag description. One request may contain information on several objects, for each one a separate Item tag shall be specified.

Response: OperationResults - operation result response.
After successful operation completion MDM sends a Package, which is received by all the client systems subscribed to the notifications on changes of the objects of the target type.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<ChangesRequest Originator="ERP" >
[Item tags]
</ChangesRequest>

Originator attribute contains sending system identifier, and may be used for routing. Destination attribute may contain identifiers of the target systems (if message is not a broadcast), which also has to be used by the broker or ESB for routing.


Now let's turn to the response packages srtucture.

DataModel
data model structure

Package contains several ObjectType packages, each of them describing particular class of the information model.

Below is the example, showing its structure

<?xml version="1.0" encoding="UTF-8"?>
<DataModel StartElement="Customers" Prefix="http://some-model.ru/instance">
<ObjectType Code="Companies" Name="Companies">
  <Parent ParentID="Organizations"/>
  <Attribute Type="Literal" AttributeID="Phone" Name="phone" DataType="xsd:string"
MinOccurence="1" MaxOccurence=""/> </ObjectType> <ObjectType Code="Persons" Name="Persons">   <Attribute Type="Literal" AttributeID="BirthDate" Name="birth date" DataType="xsd:date"
MinOccurence="1" MaxOccurence="1"/>   <Attribute Type="Reference" AttributeID="WorksIn" Name="works in">     <Target TargetId="Companies"/>   </Attribute> </ObjectType> </DataModel>

DataModel tag

The root tag of the package

Attributes:

  • StartElement - model fragment root element, if specified in the request
  • Prefix - the default prefix for entity idenfifiers. In all other packages the prefix is omitted, if it is equal to this prefix. One model can combine elements with different prefixes, in this case elements with other prefixes will be indicated with the full identifiers, such as: http://.../.../[element id].

ObjectType tag

Contains information on a certain class

Attributes:

  • Code - class identifier
  • Name - readable class name

Parent tag

Indicates that this class is a subclass of another class. Each class may inherit an unlimited number of other classes.

Attributes:

  • ParentId - parent class identifier

Attribute tag

Describes an attribute which is applicable to some class' objects. Attributes are inherined recursively from all the super classes.

Attributes:

  • AttributeID - attribute identifier
  • Name - readable attribute name
  • Type - attribute value type: Literal for constant values (string, numbers etc), Reference for relations with other objects.
  • DataType - used for literal attributes, contains value type. One of the standard XSD data types has to be shown: integer, string, date, dateTime, boolean, double.
  • MinOccurence - a minimal nubmer of values which has to be specified for each object. Attribute is mandatory if MinOccurence=1.
  • MaxOccurence - a maximal nubmer of values which has to be specified for each object. MinOccurence and MaxOccurence attributes may be omitted.

Target tag

Indicates classes which can be a target for the reference.

Attributes:

  • TargetID - unique class identifier.

Package
particular entities information

Package contains one or more Item elements, each of them describing one entity. Package may combine information on entities of various types.

Each entity is described by:

  • Identifier - unique object code assigned by the MDM. Has the URI form, like http://some-domain.ru/prefix/object.
  • Name - the default property of all the elements, representing readable name of the element.
  • Types set - a list of classes to which an entity belongs.
  • Attributes set - a list of attribute values for this object. For literal attributes the value is shown, for references - the unique identifier of the referenced object. Attributes may have several values at the same time.

The package example:

<?xml version="1.0" encoding="UTF-8"?>
<Package>
  <Item Code="JohnSmith" Name="John Smith">
    <Type TypeId="Persons"/>
    <Type TypeId="Employees"/>
    <Attribute Type="Literal" AttributeId="BirthDate" Value="1970-01-01"/>
    <Attribute Type="Reference" AttributeId="WorksIn" Value="AlphaLLC"/>
  </Item>
</Package>
				

Package tag

Groups information on several objects

Attributes:

  • Destination - target systems identifiers for routing.

Item tag

Contains information on particular object

Attributes:

  • Code - object identifier
  • Name - object readable name
  • LocalCode - object temporary code assigned by the source system. In the OperationResults package sent in response the MDM will indicate the newly assigned global code of the object (if it is created), and a mapping between temporary code and the permament global one.

  • OperationID - unique identifier of the operation. It is referenced in response package.

Type tag

Lists classes for the current object. May be repeated.

Attributes:

  • TypeId - class identifier

Attribute tag

Contains information on the attribute value. May be repeated for each attribute.

Attributes:

  • Type - attribute value type: Literal for constant values (string, numbers etc), Reference for relations with other objects, and LocalCodeReference for the reference on other objects using temporary code (if several connected objects are created within one package).
  • AttributeID - attribute identifier
  • Value - attribute value

OperationResults
request processing result

A package contains one or more OperationResult elements, for each operation performed.

Package example:

<?xml version="1.0" encoding="UTF-8"?>
<OperationResults>
  <OperationResult OperationID="af3459889459" Code="af88811f-deb4-483d-a05f-dbd2f21a7bea" LocalCode="2"
Result="Success" Message="Object has been created"/>   <OperationResult OperationID="564dbaf455" LocalCode="12345" Result="Error" Message="Error creating object"/> </OperationResults>

OperationResults tag

Groups operations result information.

Attributes:

  • Destination - target systems identifiers for routing.

OperationResult tag

Contains information of the operation result.

Attributes:

  • OperationID - operation unique ID corresponding to the one indicated in the Item tag of the ChangeRequest package.
  • Code - unique global code assigned to the created object.
  • LocalCode - object temporary code as sent by the source system.
  • Result - operation result message ("Success" or "Error").
  • Message - extended operation result message.

InvalidPackage
answer to the invalid request

Indicates that the source system has sent an invalid package, or its processing has caused an error.

Package example:

<?xml version="1.0" encoding="UTF-8"?>
<InvalidPackage/>

InvalidPackage tag

Attributes:

  • Destination - target systems identifiers for routing.

Please refer to the Technical Guide for more detailed information.