Main Nav

Hi all
 
I am currently documenting all existing interfaces between our systems in order to establish an interface catalog that could act as an aid in our initiative to implement a SOA/ESB.
I was wondering if anybody might have any suggestions as to a template I could use for this documentation.
Basically I'm thinking of a one-page document per interface that adequately describes the interface without going into too much low-level detail.
 
Any suggestions or advice would be most welcome.
 
Regards
 
Dirk Brand
 
University of Cape Town

###

UNIVERSITY OF CAPE TOWN

This e-mail is subject to the UCT ICT policies and e-mail disclaimer published on our website at http://www.uct.ac.za/about/policies/emaildisclaimer/ or obtainable from +27 21 650 9111. This e-mail is intended only for the person(s) to whom it is addressed. If the e-mail has reached you in error, please notify the author. If you are not the intended recipient of the e-mail you may not use, disclose, copy, redirect or print the content. If this e-mail is not related to the business of UCT it is sent by the sender in the sender's individual capacity.

###

********** Participation and subscription information for this EDUCAUSE Constituent Group discussion list can be found at http://www.educause.edu/groups/.

Comments

Hi Dirk,

We were just talking with a consultant about a template like this.  I don't know if he sent us any examples but I'll follow up and see.

Jim



This is something I’d be interested in as well. 

 

Mike

 

 

 

Mike Fary
Enterprise Data Architect

The University of Chicago

 

 

 

 

From: The EDUCAUSE ITANA Constituent Group Listserv [mailto:ITANA@listserv.educause.edu] On Behalf Of Jim Phelps
Sent: Thursday, March 22, 2012 7:54 AM
To: ITANA@listserv.educause.edu
Subject: Re: [ITANA] Interface catalog

 

Hi Dirk,

 

We were just talking with a consultant about a template like this.  I don't know if he sent us any examples but I'll follow up and see.

 

Jim

 

 

 

I also am looking at this as well and would be interested in examples.

 

Thank you!

Gordon

 

Gordon Suggs <suggs@xavier.edu>

Senior IT Architect

Xavier University (Cincinnati, OH)

 

From: The EDUCAUSE ITANA Constituent Group Listserv [mailto:ITANA@LISTSERV.EDUCAUSE.EDU] On Behalf Of Mike Fary
Sent: Thursday, March 22, 2012 8:57 AM
To: ITANA@LISTSERV.EDUCAUSE.EDU
Subject: Re: [ITANA] Interface catalog

 

This is something I’d be interested in as well. 

 

Mike

 

 

 

Mike Fary
Enterprise Data Architect

The University of Chicago

 

 

 

 

From: The EDUCAUSE ITANA Constituent Group Listserv [mailto:ITANA@listserv.educause.edu] On Behalf Of Jim Phelps
Sent: Thursday, March 22, 2012 7:54 AM
To: ITANA@listserv.educause.edu
Subject: Re: [ITANA] Interface catalog

 

Hi Dirk,

 

We were just talking with a consultant about a template like this.  I don't know if he sent us any examples but I'll follow up and see.

 

Jim

 

 

 

Dirk (et al) --

I think your vision of a "one-page document per interface" is a great start...

 

I would, however, suggest that rather than create separate interface-specific documents, consider taking a slightly different approach, by creating a small database application, to collect a "standardized" set of fields you determine to be relevant for your organization's interfaces.    Let the documents be created as "reports" from your interface-tracking database.

 

That way, you'll be able to create the "one-page" descriptive document for each interface, and also be able to use a query-oriented application to find/diagnose/troubleshoot interfaces with common characteristics across multiple contexts.

 

(We've found this to be really useful for tracking "shadow systems" and their interfaces, which have an interesting habit of popping onto your architectural radar when trying to implement [or retire!] major information systems, or perform upgrades.)

 

Here's a suggested starting set of 12 parameters [db "fieldnames"] to use for tracking interfaces, along with some considerations for each:

  • Interface ID (use some form of unique alphanumeric identifiers, if you'd like to assign a unique ID number to each interface)
  • Interface Name (use unique names, so no two interfaces have similar or identical names across different contexts)
  • Interface Type (use some form of unique descriptor, if you'd like to parse various types of interfaces/systems)
  • Interface OwnerName (who is actually ADMINISTRATIVELY RESPONSIBLE FOR that specific interface, in terms of keeping it active and working, and in terms of providing funding for ongoing support for that particular interface?  Do you need to keep the owner informed of all changes to the interface, and of its operational status? If so, how is that communication to be documented, and to whom is that information communicated?) 
  • Data Source (describe the system/specific-parameter from which information is being "extracted" by the interface)
  • Data Target (describe the system/specific-parameter into which information is being "inserted" by the interface)
  • Data Manipulation (describe the ways in which extracted data is "modified" or "manipulated" by the interface while in transit between the Source and the Target, including any timing-delays, character truncation, string manipulation or other "modification" that is performed on the data.  If there is NO data manipulation, clearly indicate that, so it's clear that there should be none.)
  • Interface Trigger (what event tells the interface to carry out its transactional functions?)
  • Frequency of Interface Update (is the interface trigger updated "upon change of source data" or "periodically?"  if it's triggered periodically, at what interval does the interface need to react -- hourly, daily, weekly, or some other interval or logical-trigger?  is it possible for the source data to change faster than the interface can update and verify?  is "near real-time" needed?)
  • Interface Transaction Handshake (How do you know when the interface has run/failed to run? Does some form of acknowledgment happen when the interface correctly executes or fails to do so?  If so, what is that acknowledgment, where is it stored, and does a previous transaction-acknowledgment get overwritten the NEXT time the interface makes a transaction or errors out?)
  • Access Control (Who has access rights to manually trigger or test the interface?  Who has access to read the log describing the interface's ongoing functioning? Who sets/grants/removes access rights to perform various interface-related functions?)
  • Interface Description (This is a place to capture any useful comments needed to describe the interface or its interaction with other parts of your systems, to describe how the interface data is used in your business processes, or to capture the contact information for owners, administrators or other support staff for each interface)

There are many different approaches to managing interfaces, but my recommendation would be to "keep it simple," and find the balance between "sufficient" detail and your team's ability to do the work of keeping the interface-catalog up to date.  Remember, just as someone has to "own" the individual interfaces, someone (most likely, you) will need to "own or delegate" the task of keeping the interface-catalog updated, to accurately reflect the current status of each interface.


In my experience, it's often the interfaces, rather than the connected-systems themselves, that present the most problems, due to the general inclination of folks to forget about the mostly-reliable parts of our infrastructure (like interfaces) that operate invisibly, until they no longer function as originally intended.    When that happens, it's good to have a quick reference sheet at your fingertips, to help you recall what's connected, and to identify who to ask for assistance when something stops working.

 

Summary: The above 12 data fields should give you a good one-page snapshot of each interface, and should provide you with enough information to track all the interfaces you have reasonably well.  It would make a good web-app, for those in need of quickly-accessible info about what interfaces are out there, and what they're supposed to connect.

 

regards, Michael

 

Michael Enstrom
Chair, Shadow Systems Advisory Group

University of Wisconsin System

Enterprise Business Intelligence Architect
University of Wisconsin-Milwaukee
1921 E. Hartford Ave.
Cunningham Hall Rm 211A
Milwaukee, WI 53211-3060
414-229-5093
enstrom@uwm.edu


 





From: "Dirk Brand" <Dirk.Brand@UCT.AC.ZA>
To: ITANA@LISTSERV.EDUCAUSE.EDU
Sent: Thursday, March 22, 2012 6:53:32 AM
Subject: [ITANA] Interface catalog

Hi all
 
I am currently documenting all existing interfaces between our systems in order to establish an interface catalog that could act as an aid in our initiative to implement a SOA/ESB.
I was wondering if anybody might have any suggestions as to a template I could use for this documentation.
Basically I'm thinking of a one-page document per interface that adequately describes the interface without going into too much low-level detail.
 
Any suggestions or advice would be most welcome.
 
Regards
 
Dirk Brand
 
University of Cape Town

###

UNIVERSITY OF CAPE TOWN

This e-mail is subject to the UCT ICT policies and e-mail disclaimer published on our website at http://www.uct.ac.za/about/policies/emaildisclaimer/ or obtainable from +27 21 650 9111. This e-mail is intended only for the person(s) to whom it is addressed. If the e-mail has reached you in error, please notify the author. If you are not the intended recipient of the e-mail you may not use, disclose, copy, redirect or print the content. If this e-mail is not related to the business of UCT it is sent by the sender in the sender's individual capacity.

###

********** Participation and subscription information for this EDUCAUSE Constituent Group discussion list can be found at http://www.educause.edu/groups/.

********** Participation and subscription information for this EDUCAUSE Constituent Group discussion list can be found at http://www.educause.edu/groups/.

Message from colleen.nagy@case.edu

Dirk, We have a spreadsheet for our ERP interfaces, so the information we are collecting in addition to what was suggested earlier. Which module of the ERP system? Is the source internal or external to the university? Is the target internal or external to the university? Is it encrypted and how? Is it a custom interface or delivered with the application? What tool is being used to create the file or is it a database link? Colleen -- Colleen Nagy Senior Director, Strategic Initiatives, Policy and Portfolio Management Information Technology Services Case Western Reserve University Crawford 522 Cleveland, OH  44106 216-368-8593 ********** Participation and subscription information for this EDUCAUSE Constituent Group discussion list can be found at http://www.educause.edu/groups/.
Message from rich.stevenson@umuc.edu

TOGAF has an interface catalog artifact - this sample/template is from a TOGAF certification class - it has some of the detail others have mentioned, and we used it as a jumping off point for our ERP upgrade.

********** Participation and subscription information for this EDUCAUSE Constituent Group discussion list can be found at http://www.educause.edu/groups/.

Many thanks for your very informative reply, Michael.
The 12 data fields you listed will form a great basis for a template I can use when gathering information from the various system owners.
I was also planning to eventually collate all the individual "one-page" documents into a single model; your suggestion of a database application for that is certainly a good one.
 
Regards
 
Dirk Brand
 
University of Cape Town

>>> Michael L Enstrom <enstrom@uwm.edu> 2012/03/22 05:28 PM >>>

Dirk (et al) --

I think your vision of a "one-page document per interface" is a great start...

 

I would, however, suggest that rather than create separate interface-specific documents, consider taking a slightly different approach, by creating a small database application, to collect a "standardized" set of fields you determine to be relevant for your organization's interfaces.    Let the documents be created as "reports" from your interface-tracking database.

 

That way, you'll be able to create the "one-page" descriptive document for each interface, and also be able to use a query-oriented application to find/diagnose/troubleshoot interfaces with common characteristics across multiple contexts.

 

(We've found this to be really useful for tracking "shadow systems" and their interfaces, which have an interesting habit of popping onto your architectural radar when trying to implement [or retire!] major information systems, or perform upgrades.)

 

Here's a suggested starting set of 12 parameters [db "fieldnames"] to use for tracking interfaces, along with some considerations for each:

  • Interface ID (use some form of unique alphanumeric identifiers, if you'd like to assign a unique ID number to each interface)
  • Interface Name (use unique names, so no two interfaces have similar or identical names across different contexts)
  • Interface Type (use some form of unique descriptor, if you'd like to parse various types of interfaces/systems)
  • Interface OwnerName (who is actually ADMINISTRATIVELY RESPONSIBLE FOR that specific interface, in terms of keeping it active and working, and in terms of providing funding for ongoing support for that particular interface?  Do you need to keep the owner informed of all changes to the interface, and of its operational status? If so, how is that communication to be documented, and to whom is that information communicated?) 
  • Data Source (describe the system/specific-parameter from which information is being "extracted" by the interface)
  • Data Target (describe the system/specific-parameter into which information is being "inserted" by the interface)
  • Data Manipulation (describe the ways in which extracted data is "modified" or "manipulated" by the interface while in transit between the Source and the Target, including any timing-delays, character truncation, string manipulation or other "modification" that is performed on the data.  If there is NO data manipulation, clearly indicate that, so it's clear that there should be none.)
  • Interface Trigger (what event tells the interface to carry out its transactional functions?)
  • Frequency of Interface Update (is the interface trigger updated "upon change of source data" or "periodically?"  if it's triggered periodically, at what interval does the interface need to react -- hourly, daily, weekly, or some other interval or logical-trigger?  is it possible for the source data to change faster than the interface can update and verify?  is "near real-time" needed?)
  • Interface Transaction Handshake (How do you know when the interface has run/failed to run? Does some form of acknowledgment happen when the interface correctly executes or fails to do so?  If so, what is that acknowledgment, where is it stored, and does a previous transaction-acknowledgment get overwritten the NEXT time the interface makes a transaction or errors out?)
  • Access Control (Who has access rights to manually trigger or test the interface?  Who has access to read the log describing the interface's ongoing functioning? Who sets/grants/removes access rights to perform various interface-related functions?)
  • Interface Description (This is a place to capture any useful comments needed to describe the interface or its interaction with other parts of your systems, to describe how the interface data is used in your business processes, or to capture the contact information for owners, administrators or other support staff for each interface)

There are many different approaches to managing interfaces, but my recommendation would be to "keep it simple," and find the balance between "sufficient" detail and your team's ability to do the work of keeping the interface-catalog up to date.  Remember, just as someone has to "own" the individual interfaces, someone (most likely, you) will need to "own or delegate" the task of keeping the interface-catalog updated, to accurately reflect the current status of each interface.


In my experience, it's often the interfaces, rather than the connected-systems themselves, that present the most problems, due to the general inclination of folks to forget about the mostly-reliable parts of our infrastructure (like interfaces) that operate invisibly, until they no longer function as originally intended.    When that happens, it's good to have a quick reference sheet at your fingertips, to help you recall what's connected, and to identify who to ask for assistance when something stops working.

 

Summary: The above 12 data fields should give you a good one-page snapshot of each interface, and should provide you with enough information to track all the interfaces you have reasonably well.  It would make a good web-app, for those in need of quickly-accessible info about what interfaces are out there, and what they're supposed to connect.

 

regards, Michael

 

Michael Enstrom
Chair, Shadow Systems Advisory Group

University of Wisconsin System

Enterprise Business Intelligence Architect
University of Wisconsin-Milwaukee
1921 E. Hartford Ave.
Cunningham Hall Rm 211A
Milwaukee, WI 53211-3060
414-229-5093
enstrom@uwm.edu


 





From: "Dirk Brand" <Dirk.Brand@UCT.AC.ZA>
To: ITANA@LISTSERV.EDUCAUSE.EDU
Sent: Thursday, March 22, 2012 6:53:32 AM
Subject: [ITANA] Interface catalog

Hi all
 
I am currently documenting all existing interfaces between our systems in order to establish an interface catalog that could act as an aid in our initiative to implement a SOA/ESB.
I was wondering if anybody might have any suggestions as to a template I could use for this documentation.
Basically I'm thinking of a one-page document per interface that adequately describes the interface without going into too much low-level detail.
 
Any suggestions or advice would be most welcome.
 
Regards
 
Dirk Brand
 
University of Cape Town

###

UNIVERSITY OF CAPE TOWN

This e-mail is subject to the UCT ICT policies and e-mail disclaimer published on our website at http://www.uct.ac.za/about/policies/emaildisclaimer/ or obtainable from +27 21 650 9111. This e-mail is intended only for the person(s) to whom it is addressed. If the e-mail has reached you in error, please notify the author. If you are not the intended recipient of the e-mail you may not use, disclose, copy, redirect or print the content. If this e-mail is not related to the business of UCT it is sent by the sender in the sender's individual capacity.

###

********** Participation and subscription information for this EDUCAUSE Constituent Group discussion list can be found at http://www.educause.edu/groups/.


###

UNIVERSITY OF CAPE TOWN

This e-mail is subject to the UCT ICT policies and e-mail disclaimer published on our website at http://www.uct.ac.za/about/policies/emaildisclaimer/ or obtainable from +27 21 650 9111. This e-mail is intended only for the person(s) to whom it is addressed. If the e-mail has reached you in error, please notify the author. If you are not the intended recipient of the e-mail you may not use, disclose, copy, redirect or print the content. If this e-mail is not related to the business of UCT it is sent by the sender in the sender's individual capacity.

###

********** Participation and subscription information for this EDUCAUSE Constituent Group discussion list can be found at http://www.educause.edu/groups/.

Generic list that we use includes the following.  May look to extend/change this based on the other replies in this thread.

Ceri

Interface

Characteristics of the interface to the Service. There may be more than one of these for any given Service.

  • Version
    • The version number of the interface, used to ensure the stability of the interface.
  • Endpoint(s)
    • Where the Service is exposed, e.g. the URL of the Service endpoint.
    • The protocol used by the endpoint, e.g. SOAP or REST.
    • The data-interchange format used by the endpoint, e.g. XML or JSON.
    • Any Service Level Agreements for this endpoint, for example:
      • Availability - any uptime guarantee or outage window
      • Timeliness - how "fresh" the data available via this endpoint is
  • Stability - this is a general control on whether the interface should be considered reliable or not; developers should undertake a Contract with the Service provider before consuming an interface that is not Committed. Categories likely to be:
    • Committed - the interface will not change across system developments or upgrades
    • Uncommitted/External - the interface is under internal development or is controlled by third parties (for example, an out-of-the-box Blackboard Service)
    • Not an Interface - this interface should not be used.
  • Data Classification - a general control on what level of protection the data available via this Service is subject to. The target way to do this may be to have this enforced by an ESB, but this may not be achievable in the short term. Categories may be:
    • Public
    • Mixed
    • Private

On 22 Mar 2012, at 11:53, Dirk Brand wrote:

Hi all
 
I am currently documenting all existing interfaces between our systems in order to establish an interface catalog that could act as an aid in our initiative to implement a SOA/ESB.
I was wondering if anybody might have any suggestions as to a template I could use for this documentation.
Basically I'm thinking of a one-page document per interface that adequately describes the interface without going into too much low-level detail.
 
Any suggestions or advice would be most welcome.
 
Regards
 
Dirk Brand
 
University of Cape Town

###

UNIVERSITY OF CAPE TOWN


This e-mail is subject to the UCT ICT policies and e-mail disclaimer published on our website at http://www.uct.ac.za/about/policies/emaildisclaimer/ or obtainable from +27 21 650 9111. This e-mail is intended only for the person(s) to whom it is addressed. If the e-mail has reached you in error, please notify the author. If you are not the intended recipient of the e-mail you may not use, disclose, copy, redirect or print the content. If this e-mail is not related to the business of UCT it is sent by the sender in the sender's individual capacity.


###

********** Participation and subscription information for this EDUCAUSE Constituent Group discussion list can be found at http://www.educause.edu/groups/.


-- 
Ceri Davies
Technical Solutions Architect
University IT
Cardiff University

********** Participation and subscription information for this EDUCAUSE Constituent Group discussion list can be found at http://www.educause.edu/groups/.

Close
Close


Annual Conference
September 29–October 2
View Proceedings

Events for all Levels and Interests

Whether you're looking for a conference to attend face-to-face to connect with peers, or for an online event for team professional development, see what's upcoming.

Close

Digital Badges
Member recognition effort
Earn yours >

Career Center


Leadership and Management Programs

EDUCAUSE Institute
Project Management

 

 

Jump Start Your Career Growth

Explore EDUCAUSE professional development opportunities that match your career aspirations and desired level of time investment through our interactive online guide.

 

Close
EDUCAUSE organizes its efforts around three IT Focus Areas

 

 

Join These Programs If Your Focus Is

Close

Get on the Higher Ed IT Map

Employees of EDUCAUSE member institutions and organizations are invited to create individual profiles.
 

 

Close

2014 Strategic Priorities

  • Building the Profession
  • IT as a Game Changer
  • Foundations


Learn More >

Uncommon Thinking for the Common Good™

EDUCAUSE is the foremost community of higher education IT leaders and professionals.