Applicable with Version 2.5 Oct 2010
Help Version 2.5.123

Contents   Introduction   Concepts   User Help   Modeler Help   Browser Help
Administrator Help   Developer Help    Utility Help   Visio   Graphical Modeler

 
InspiredBg

The AGMCGI Interface

This section deals with the AGMCGI interface specifications. It gives a detailed description of each interface call, what information is required and what information is returned, as well as a detailed description of what Archi does when it receives the interface call.

Since this Interface uses CGI protocols, the CGI string passed to Archi should be in accepted CGI notation (i.e. Name/Value pairs separated by an ampersand character).

The following topics are covered:

Retrieve model type list from Archi (RMT)

Purpose

To allow an external system to retrieve a list of "Model Type" and "Meta Model Type" instances from Archi.

Required Input Parameters

  • Command (CMD)
  • Userid (UID)
  • Password (PWD)

Example CGI request:

    "http://localhost/Archi/ABTWSAC.EXE/ZZMSRequester?CMD=RMT&UID=Visio&PWD=Visio"

Example Archi Response

http://localhost/Archi/ABTWSAC.EXE/ZZMSRequester<meta http-equiv=""Pragma"" CONTENT=""no-cache"">

<meta http-equiv=""Expires"" CONTENT=""Fri, 28 May 200412:06:56 PM GMT"">

<!-- Generated by VisualAge Web Connection on 2004/06/03 at 12:06:56 PM -->

<HTML>

<HEAD>

<TITLE>Z Z M S Requester</TITLE>

</HEAD>

<BODY TITLE=""Archi response time (ZZMSRequester class): 0.09 secs"" >

<font face=Arial, size=1, color=""#000000"">

                <ZZMSREQUESTOR>

                                <MODELTYPELIST>             

                                                <INSTANCEMODELTYPELIST>

                                                                <MODELTYPE>ClassDiagram</MODELTYPE>

                                                                <MODELTYPE>ClassDiagram2</MODELTYPE>

                                                                <MODELTYPE>ModelWithAttributes</MODELTYPE>

                                                                <MODELTYPE>Static Structure</MODELTYPE>

                                                </INSTANCEMODELTYPELIST>           

                                                <METAMODELTYPELIST>

                                                                <MODELTYPE>TestMetaModel</MODELTYPE>

                                                                <MODELTYPE>TestMetaModel2</MODELTYPE>

                                                </METAMODELTYPELIST>

                                </MODELTYPELIST>            

                </ZZMSREQUESTOR>

</font>

</BODY>

</HTML>

 As you will notice from the XML, the Meta and Instance lists are wrapped into separate XML tags. 

Example Archi Error Response

    "http://localhost/Archi/ABTWSAC.EXE/ZZMSRequester<meta http-equiv=""Pragma"" CONTENT=""no-cache"">

    <meta http-equiv=""Expires"" CONTENT=""Fri, 28 May 200412:14:07 PM GMT"">

    <!-- Generated by VisualAge Web Connection on 2004/06/03 at 12:14:07 PM -->

    <HTML>

    <HEAD>

    <TITLE>Z Z M S Requester</TITLE>

    </HEAD>

    <BODY TITLE=""Archi response time (ZZMSRequester class): 0.0 secs"" >

    <font face=Arial, size=1, color=""#000000"">

    <ZZMSREQUESTOR>

    <ZZERROR>Invalid+logon...</ZZERROR>

    </ZZMSREQUESTOR>

    </font>

    </BODY>

    </HTML>

up 

Retrieve model list for mode type from Archi (RMS)

 

Purpose

To allow an external system to retrieve a list of "Model" instances for a particular "Model Type" instances from Archi.

Required Input Parameters

  • Command (CMD)
  • Userid (UID)
  • Password (PWD)
  • ModelTypeName (MT). NB: This name must be prefixed by "META: " if you are trying to retrieve instances for a "Meta Model Type"

Example CGI request:

"http://localhost/Archi/ABTWSAC.EXE/ZZMSRequester?CMD=RMS&UID=Visio&PWD=Visio&MT=ModelWithAttributes"

Example Archi Response

http://localhost/Archi/ABTWSAC.EXE/ZZMSRequester<meta http-equiv=""Pragma"" CONTENT=""no-cache"">

<meta http-equiv=""Expires"" CONTENT=""Fri, 28 May 200412:17:17 PM GMT"">

<!-- Generated by VisualAge Web Connection on 2004/06/03 at 12:17:16 PM -->

<HTML>

<HEAD>

<TITLE>Z Z M S Requester</TITLE>

</HEAD>

<BODY TITLE=""Archi response time (ZZMSRequester class): 1.69 secs"" >

<font face=Arial, size=1, color=""#000000"">

<ZZMSREQUESTOR>

<MODELLIST>

<MODEL>Attrtest1</MODEL>

<MODEL>Attrtest2</MODEL>

</MODELLIST>

</ZZMSREQUESTOR>

</font>

</BODY>

</HTML> 

up 

Send Visual Object to Archi (UML2)

Purpose

To allow an external system to send information of a visual object to Archi in order to allow Archi to store the information..

Required Input Parameters

  • Command (CMD)
  • Userid (UID)
  • Password (PWD)
  • ModelName (MN)
  • ModelTypeName (MT) ). NB: This name must be prefixed by "META: " if you are trying to send information for a "Meta Model Type"
  • Visual Type Name (SV)
  • Visual X co-ordinate (XP)
  • Visual Y co-ordinate (YP)
  • Visual object height (HT)
  • Visual object width (WD)
  • Visual object Instance Name (NI)). NB: For a "Meta Model Type", this will be the Type Name.

Example CGI request:  

""http://localhost/Archi/ABTWSAC.EXE/ZZMSRequester?CMD=UML2&UID=Visio&PWD=Visio&MN=Attrtest2&MT=ModelWithAttributes&SV=Actor &XP=001.3417&YP=015.7687&WD=000.4000&HT=000.7500&NI=Actor One""

Example Archi Response

"http://localhost/Archi/ABTWSAC.EXE/ZZMSRequester<meta http-equiv=""Pragma"" CONTENT=""no-cache"">

<meta http-equiv=""Expires"" CONTENT=""Fri, 28 May 200412:22:48 PM GMT"">

<!-- Generated by VisualAge Web Connection on 2004/06/03 at 12:22:48 PM -->

<HTML>

<HEAD>

<TITLE>Z Z M S Requester</TITLE>

</HEAD>

<BODY TITLE=""Archi response time (ZZMSRequester class): 0.44 secs"" >

<font face=Arial, size=1, color=""#000000"">

<ZZMSREQUESTOR>

<MODELACTION>Created relationship between: Actor One and: Employee</MODELACTION>

<MODELACTION>Created relationship between: Actor One and: Attrtest2</MODELACTION>

<MODELACTION>Updated infonode attributes for infonode: Actor One-Attrtest2</MODELACTION>

</ZZMSREQUESTOR>

</font>

</BODY>

</HTML>

"

What Archi Does in the Background

When Archi receives this type of request, it performs the following operations:

  • Validate Userid and Password
  • Load ModelType into memory (if it doesn't already exist), this is used to map the Visual Type and Visual Instance Names to Archi Type and Instance names.

    If the ModeType name is prefixed by "META: ", Archi tries to load a "Meta Model Type", otherwise Archi assumes you want to send information for an Instance model.

At this point, execution splits depeding on whether we are working with a Meta or an Instance Model

For Meta Models:

  • Find the model instance.
  • Load the model instance XML into a memory object structure.
  • Update the XML with the new mapping information and save it.

For Instance Models:

  • Find the Model instance, if it doesn't exist do the following:
    • Create new Model Instance
  • Relate Model Instance to the relevant model type
  • Find the Archi nodetype based on the Mapping information in ModelType and the name of the Visual Type sent through in the request. If the Archi NodeType doesn't exist do the following:
    • Create a new NodeType
  • Find the a meta relationship between the "Model" type in Archi and the NodeType, if it doesn't exist create it using  the ModelItem as an infonode.
  • Find the relevant instance of the NodeType, if it doesn't exist create the new instance.
  • For each ADDITIONALMAPPING INFO, do the following
    • IF it is an Attribute mapping
      • Find the attribute in Archi, if it doesn't exist create it
      • Find the legal attribute between the NodeType and Attribute, if it doesn't exist create it.
      • Update the attribute value for the instance with the value received in the request.
    • If it is a relationship mapping
      • Find the target node type for this relationship, if it doesn't exist create it 
      • Find the reltype to use for this relationship, if it doesn't exist create it
      • Find the legal relationship between the nodetype, tarrgetnodetype and reltype, if it doesn't exist create it.
      • Find the target instance for this relationship, if it doesn't exist create it
      • Create the instance relationship.
  • Finally, create the relationship between the Archi instance and the model instance, and update the infonode with the relevant visual mapping information.

           

up 

Send Visual Relationship to Archi (UMR)

Purpose

To allow an external system to send information of a visual relationship between two objects to Archi in order to allow Archi to store the information..

Required Input Parameters

  • Command (CMD)
  • Userid (UID)
  • Password (PWD)
  • ModelName (MN)
  • ModelTypeName (MT) ). NB: This name must be prefixed by "META: " if you are trying to send information for a "Meta Model Type"
  • Visual Rel Type Name (SV)
  • Relationship Text (RX) NB: Text to appear on the relationship
  • The Node Instance Name to connect FROM (Or the NodeType name to connect from if it is a META model) (FN)
  • The visual object (e.g. Visio Master Name) to connect FROM  (FT)
  • The FROM connection point denoting the anchor that the visual connector is mapped from (FP)
  • The Node Instance Name to connect TO (Or the NodeType name to connect to if it is a META model) (TN)
  • The visual object (e.g. Visio Master Name) to connect TO  (TT)
  • The TO connection point denoting the anchor that the visual connector is mapped to (TP)
  • The RelType Name. This is only used for META models and is derived from the text on the FROM endpoint of the Binary Association Master (RN)
  • The Inverse RelType Name. This is only used for META models and is derived from the text on the TO endpoint of the Binary Association Master (IRN)

Example CGI request:

For an instance model:

/ZZMSRequester?CMD=UMR&UID=Visio&PWD=Visio&MN=RudolfTest&MT=ModelWithAttributes&SV=Dynamic Link&RX=M1 to M2&FN= Manual Two&FT=Manual&FP=3&TN=Manual One&TT=Manual&TP=4&RN=&IRN=

 

For an meta model:

/ZZMSRequester?CMD=UMR&UID=Visio&PWD=Visio&MN=TestMetaModel&MT=META: MMTest&SV=Binary Association&RX=*&FN=BusUnit &FT=Class&FP=10&TN=BusEvent&TT=Class&TP=9&RN=-Fires&IRN=-FiredBy

 

 

Example Archi Response

For an instance model:

<ZZMSREQUESTOR>

<MODELACTION>Created relationship from node: Manual Two using relType: AA_connects to to node: Manual One</MODELACTION>

<MODELACTION>Updated info node details: Manual Two-Manual One</MODELACTION>

</ZZMSREQUESTOR>

 

For an meta model:

<ZZMSREQUESTOR>

<MODELACTION>Created relationship between modeltype: MMTest and model: TestMetaModel</MODELACTION>

<MODELACTION>Updated Meta Model XML: TestMetaModel</MODELACTION>

</ZZMSREQUESTOR>

What Archi Does in the Background

When Archi receives this type of request, it performs the following operations:

  • Validate Userid and Password
  • Load ModelType into memory (if it doesn't already exist), this is used to map the Visual Type and Visual Instance Names to Archi Type and Instance names.

    If the ModeType name is prefixed by "META: ", Archi tries to load a "Meta Model Type", otherwise Archi assumes you want to send information for an Instance model.

At this point, execution splits depeding on whether we are working with a Meta or an Instance Model

For Meta Models:

  • Find the model instance.
  • Load the model instance XML into a memory object structure.
  • Update the XML with the new mapping information and save it.

For Instance Models:

  • Find the Model instance, if it doesn't exist do the following:
    • Create new Model Instance
  • Relate Model Instance to the relevant model type
  • Find the Archi RelType based on the Mapping information in ModelType and the name of the Visual Type sent through in the request. If the Archi RelType doesn't exist do the following:
    • Create a new RelType
  • Find the From Node in this relationship based on the Visual NodeType mapping and the instance name. If it doesn't exist return an error and quit.
  • Find the To Node in this relationship based on the Visual NodeType mapping and the instance name. If it doesn't exist return an error and quit.
  • Find the legal target in the meta-definition for the two NodeTypes in this relationship and the RelType itself. If it doesn't exist create it.
  • Set the infonode on the LegalTarget object based on the algorithm shown in 2.1.3 in this document.
  • Create the instance relationship for the From Node instance, To node instance, RelType and Infonode created, found or amended so far.
  • Update the "ModelInfo" XML  with the new connection points and the model text.

up 

Send Visual Attribute to Archi (AUD)

Purpose

To allow an external system to send information of an attribute belonging to a node instance or nodetype from a visual modeling tool to Archi.

In Visio, we use the "Custom Properties" section to find attributes and send them to Archi.

The primary difference between Meta and Instance modeling for this command is that attributes MUST be explicitly defined in the instance "Model Type" XML mapping, while they need not be defined at all in the meta "Meta Model Type" mapping.

Required Input Parameters

  • Command (CMD)
  • Userid (UID)
  • Password (PWD)
  • ModelName (MN)
  • ModelTypeName (MT) ). NB: This name must be prefixed by "META: " if you are trying to send information for a "Meta Model Type"
  • Visual Attribute Name (AN)
  • Attribute Value (AV). NB: For a "Meta Model Type", this will be the Attribute Type.
  • Visual object Instance Name (NI). NB: For a "Meta Model Type", this will be the Type Name.

Example CGI request:

For an instance model:

/ZZMSRequester?CMD=AUD&UID=Visio&PWD=Visio&MN=RudolfTest&MT=ModelWithAttributes&SV=Manual&AN=DurationMin& AV=0.0000 &NI=Manual One

 

For an meta model:

/ZZMSRequester?CMD=AUD&UID=Visio&PWD=Visio&MN=MMtest&MT=META: TestMetaModel&SV=Class &AN=Attribute1&AV=Single &NI=BusUnit"

Example Archi Response

For an instance model:

<ZZMSREQUESTOR>

<MODELACTION>Updated attribute value for attribute: AA_DurationMin and node: Manual One</MODELACTION>

</ZZMSREQUESTOR>

 

For an meta model:

<ZZMSREQUESTOR>

<MODELACTION>Created relationship between modeltype: TestMetaModel and model: MMTest</MODELACTION>

<MODELACTION>Updated Meta Model XML: MMtest</MODELACTION>

</ZZMSREQUESTOR>

What Archi Does in the Background

When Archi receives this type of request, it performs the following operations:

  • Validate Userid and Password
  • Load ModelType into memory (if it doesn't already exist), this is used to map the Visual Type and Visual Instance Names to Archi Type and Instance names.

    If the ModeType name is prefixed by "META: ", Archi tries to load a "Meta Model Type", otherwise Archi assumes you want to send information for an Instance model.

At this point, execution splits depending on whether we are working with a Meta or an Instance Model

For Meta Models:

  • Find the model instance.
  • Load the model instance XML into a memory object structure.
  • Update the XML with the new mapping information and save it.

For Instance Models:

  • Find the Model instance, if it doesn't exist do the following:
    • Create new Model Instance
  • Relate Model Instance to the relevant model type
  • Find the Archi NodeType based on the Mapping information in ModelType and the name of the Visual Type sent through in the request. If the Archi NodeType doesn't exist do the following:
    • Create a new NodeType
  • Find the Node Instance based on the Visual NodeType mapping and the instance name. If it doesn't exist create it.
  • Find the attribute in the Archi Meta Definition based on visual information  received and the mapping in the "Model Type". If it doesn't exist create it.
  • Find the legal attribute between the NodeType and the Attribute in the Archi meta definition, if it doesn't exist create it.
  • Update the attribute value with the value received in the request.

up 

Send Visual Attribute (On a relationship) to Archi (AUR)

Purpose

To allow an external system to send information of an attribute belonging to a relationship between to nodes from a visual modeling tool to Archi. 

This function is only available for Instance models at the moment, it will be made available for Meta models in a future release.

Required Input Parameters

  • Command (CMD)
  • Userid (UID)
  • Password (PWD)
  • ModelName (MN)
  • ModelTypeName (MT)
  • Visual Rel Type Name (SV)
  • The Node Instance Name to connect FROM (Or the NodeType name to connect from if it is a META model) (FN)
  • The visual object (e.g. Visio Master Name) to connect FROM  (FT)
  • The Node Instance Name to connect TO (Or the NodeType name to connect to if it is a META model) (TN)
  • The visual object (e.g. Visio Master Name) to connect TO  (TT)
  • Visual Attribute Name (AN)
  • Attribute Value (AV).

 

Example CGI request:

For an instance model:

/ZZMSRequester?CMD=AUR&UID=Visio&PWD=Visio&MN=RudolfTest&MT=ModelWithAttributes&SV=Dynamic Link&FN=Manual Two&FT= Manual&TN=Manual One&TT=Manual&AN=MyCustomProp&AV=Hello

For an meta model:

This feature is not available for meta models yet.

Example Archi Response

For an instance model:

<ZZMSREQUESTOR>

<MODELACTION>Created relationship from node: Manual Two using relType: AA_connects to to node: Manual One</MODELACTION>

<MODELACTION>Updated attribute value for attribute: MyCustomProp and node: Manual Two-Manual One</MODELACTION>

</ZZMSREQUESTOR>

For an meta model:

This feature is not available for meta models yet.

What Archi Does in the Background

When Archi receives this type of request, it performs the following operations:

  • Validate Userid and Password
  • Load ModelType into memory (if it doesn't already exist), this is used to map the Visual Type and Visual Instance Names to Archi Type and Instance names.
  • Find the Model instance, if it doesn't exist do the following:
    • Create new Model Instance
  • Relate Model Instance to the relevant model type
  • Find the Archi RelType based on the Mapping information in ModelType and the name of the Visual Type sent through in the request. If the Archi RelType doesn't exist do the following:
    • Create a new RelType
  • Find the From Node in this relationship based on the Visual NodeType mapping and the instance name. If it doesn't exist return an error and quit.
  • Find the To Node in this relationship based on the Visual NodeType mapping and the instance name. If it doesn't exist return an error and quit.
  • Find the legal target in the meta-definition for the two NodeTypes in this relationship and the RelType itself. If it doesn't exist create it.
  • Set the infonode on the LegalTarget object based on the algorithm shown in 2.1.3 in this document.
  • Find the attribute in the Archi Meta Definition based on visual information  received and the mapping in the "Model Type". If it doesn't exist create it.
  • Find the legal attribute between the InfoNode on the relationship  between the two NodeType and the Attribute in the Archi meta definition, if it doesn't exist create it.
  • Update the attribute value with the value received in the request.

up 

Retrieve Archi Model Request (RML)

Purpose

To allow an external system to retrieve complete information for a model from Archi. The information is returned in XML and differs between an Instancxe and a Meta Model

Required Input Parameters

  • Command (CMD)
  • Userid (UID)
  • Password (PWD)
  • ModelName (MN)
  • ModelTypeName (MT) . NB: This name must be prefixed by "META: " if you are trying to send information for a "Meta Model Type"
  • RetrieveOnlyWonRelatinships (ROR). NB: This switch tells Archi whether to retrieve all relationships between instances connected to a model, or only to retrieve those relationships that have modeling information for the current model (i.e. Relationships that have already been sent to Archi from Visio under this model name).
    This is useful for filtering out relationships that may already have existed in Archi between instances when a visual model was sent to Archi. If this is the case, retrieving the model without setting this switch to TRUE may result in some unexpected information cropping up in the visual representation.

Example CGI request:

/ZZMSRequester?CMD=RML&UID=Visio&PWD=Visio&MT=ModelWithAttributes&MN=RudolfTest&ROR=FALSE

Example Archi Response

For an instance model: 

AGMCGIInstanceXML

 

The illustration above shows sample XML returned when retrieving an Instance Model

 

For an meta model:

<ZZMSREQUESTOR>

                <MODELTYPE>ArchiMetaModelType</MODELTYPE>

                <NODETYPE>

                                <NODETYPENAME>Development+Tool+Type</NODETYPENAME>

                                <SMALLIMAGE>DevelopmentTool90x60.gif</SMALLIMAGE>

                                <BIGIMAGE>DevelopmentTool90x60.gif</BIGIMAGE>

                                <HYPERLINK></HYPERLINK>

                                <SELECTLISTINFO></SELECTLISTINFO>

                                <VISUALNAME>Class</VISUALNAME>

                                <XPOS>0</XPOS>

                                <YPOS>0</YPOS>

                                <HEIGHT>0</HEIGHT>

                                <WIDTH>0</WIDTH>

                                <LEGALATTRIBUTE>

                                                <ATTRIBUTENAME>Updated+on</ATTRIBUTENAME>

                                                <UNITOFMEASURE></UNITOFMEASURE>

                                                <TYPE>Archie2LastUpdated</TYPE>

                                                <SEQUENCE>100</SEQUENCE>

                                </LEGALATTRIBUTE>

                                <LEGALRELATIONSHIP>

                                                <RELATIONSHIPTYPE>

                                                                <DESCRIPTION>is+used+by</DESCRIPTION>

                                                                <INVERSEDESCRIPTION>uses</INVERSEDESCRIPTION>

                                                                <SMALLIMAGE>uses_isusedby.gif</SMALLIMAGE>

                                                                <BIGIMAGE>uses_isusedby.gif</BIGIMAGE>

                                                                <INVSMALLIMAGE>uses_isusedby.gif</INVSMALLIMAGE>

                                                                <INVBIGIMAGE>uses_isusedby.gif</INVBIGIMAGE>

                                                                <VISUALNAME>Binary+Association</VISUALNAME>

                                                </RELATIONSHIPTYPE>

                                                <LEGALTARGET>

                                                                <TARGET>Task+Type</TARGET>

                                                                <INFONODE></INFONODE>

                                                                <FROMCONNPOINT>0</FROMCONNPOINT>

                                                                <TOCONNPOINT>0</TOCONNPOINT>

                                                </LEGALTARGET>

                                </LEGALRELATIONSHIP>

                </NODETYPE>

</ZZMSREQUESTOR>

What Archi Does in the Background

When Archi receives this type of request, it performs the following operations:

  • Validate Userid and Password
  • Load ModelType into memory (if it doesn't already exist), this is used to map the Visual Type and Visual Instance Names to Archi Type and Instance names.
  • Find the Model instance, if it doesn't exist do the following:
    • Create new Model Instance
  • Export all information relating to the model instance to XML.