Team Server Automation

by Nov 18, 2020

This blog post describes how you can connect to and use the Team Server API.

When you work with ER/Studio Data Architect, you can easily automate some tedious tasks by using macros through the COM based automation interface.

Team Server provides a REST based API (REpresentational State Transfer; Application Programming Interface) to interact with it.

You can work with your Entities, Attributes, Tables, Views, etc, as well as manage (Create, Read, Update, Delete) your Glossaries and Business Terms, …

Accessing the Team Server’s REST API

To access the REST API resources, first you need to be authorized to do so.

To do this, you first need to register your client with the server. You don’t need to register your application with Idera (you don’t need to send an email to Idera anymore). You can simply generate two GUIDs (Globally Unique IDentifier; you can find lots of online tools on the web to generate them if you need too) for the fields clientId & secret.

I created a macro which allows you to do this registration from ER/Studio Data Architect:
Macro interface

Here it is:  wRegisterTS.zip

Installing the macro

You need to extract the content of the archive in the directory specified for the Macros in ER/Studio Data Architect. You can find the used folder in ER/Studio Data Architect options, by selecting the tab Directories:

Then you can see the newly added macro in ER/Studio Data Architect Macro tab:

If you don’t see it, you can right-click to select the item Refresh from the contextual menu.

Using the macro

To run it, right-click on the macro and select the item Run Macro. If you successfully registered, you should get a message like this one:
Application registered

Get an access token

Once you have registered, you need to get an access token. There are 3 different ways to get one. You can check the documentation to choose your preferred one. Personally, I recommend the first method if you’re implementing a website (e.g. intranet), or the second method if you’re creating a thick client. The third one should be avoid as you must specify the credentials in the URL (you can eventually create a dedicated username/password with restricted permissions to prevent sensible data leaks).

Access your resources

Once you have an Access Token, you can browse and manage your resources:
example

The above screenshot comes from an application written with Delphi ( wERS.zip). If you don’t have Delphi, you can find the binary in the subfolder: \Win64\Release of the attached archive. This application also uses ER/Studio Data Architect COM automation interface and this product needs to be installed or the tabs will be disabled.).

Beyond the API

The REST API provides access to many resources but not all the Team Server features are currently exposed through it. So, I was wondering how I can automate users actions…

My first thought was to update the database used by Team Server, directly to add some data (e.g. using a DBA solution like in the screenshot below):

DBArtisan

This is a really bad idea, because:

  • I can’t be 100% sure there’s no linked data elsewhere in the database and break the consistency thus possibly corrupting the data in the repository
    and
  • invalidate my support agreement with Idera

So, I have created another application which embeds a web browser. I can use it to authenticate and navigate Team Server but also add my own calls to the browser if I need to.

Let’s look at an example: If I want to relate a Term to other objects. Usually, we navigate to the Term, click, the Related ER Objects link, then the tab Relate to choose the objects:

Using the REST API, if I have already retrieved the objects I’m interested by, and added the terms, I know the IDs of my objects and terms…

If I look at the link used by the button to relate a term with an object, I see the URL is quite simple to understand: /term/object/relateObject.spg?termKey=847&objectKey=10522
The method, and the parameters with the IDs. So, if I call this method in a loop with different IDs, I can quickly associate my terms with any objects!

In the above screenshot, you can see the browser in the upper part, a list of IDs (Terms;Objects) and a button to start the loop…

The code is very small. I perform an asynchronous HTTP request (jQuery.Ajax; jQuery is already used by Team Server, so I don’t need to add the library itself) in a loop with the URL using the good IDs:

procedure TfrmMain.btnRelateClick(Sender: TObject);
var
  iLoop, iMax: Integer;
  sRow       : string;
  aIDs       : TArray<string>;
begin
  iMax             := Pred(mmoList.Lines.Count);
  pbFeedback.Value := 0;
  pbFeedback.Max   := mmoList.Lines.Count;
  for iLoop := 0 to iMax do
  begin
    sRow := mmoList.Lines[iLoop];
    aIDs := sRow.Split([';', ',', #9, ' ']);
    if Length(aIDs) = 2 then
    begin
      wbTS.EvaluateJavaScript(
        Format('$.ajax({url : "%s/term/object/%srelateObject.spg?termKey=%s&objectKey=%s"});',
               [edtURL.Text, IfThen(not cbRelateUnrelate.IsChecked, 'un'), aIDs[0], aIDs[1]]
        )
      );
    end;
    pbFeedback.Value := pbFeedback.Value + 1;
  end;
end;

The Delphi project is available here:  wTSRelateTerms.zip

Another solution would be to use some browsers plugins like TamperMonkey, GreaseMonkey, … to add your own code to execute with Team Server like the Glossary Tooltip does.

Summary

In this blog post, we used:

  • the ER/Studio Data Architect COM automation interface through a macro
    • to register to the Team Server API
  • the Team Server REST API
    • to authenticate
    • to browse and manage Team Server resources
  • the Team Server Web application through a custom browser
    • to automate users actions