TEAMS SR v1.3.3 – Import integration
2011.10.17
TEAMS SR v1.3.3 – Import integration
1. Contents
1.
Contents ........................................................................................................................................... 2
2.
Introduction ....................................................................................................................................... 3
3.
Principles .......................................................................................................................................... 3
4.
Steps involved for establishing import integration ............................................................................ 3
5.
4.1.
Define import and export ......................................................................................................... 3
4.2.
Generate XML-specification (XSD) ......................................................................................... 4
4.3.
Use middleware to map the two systems (XSLT) ................................................................... 6
4.4.
Test integration ........................................................................................................................ 7
4.5.
Establishing automatic schedule ............................................................................................. 7
Connecting to the web service ......................................................................................................... 7
5.1.
ClientCredentialType and authentication ................................................................................ 7
6.
Web service call ............................................................................................................................... 7
7.
Error messages from the web service .............................................................................................. 8
8.
Change Management ....................................................................................................................... 8
9.
Test client ......................................................................................................................................... 8
Page 2 of 10
TEAMS SR v1.3.3 – Import integration
2. Introduction
TEAMS SR supports import integration through web services. This document will describe how integration with
TEAMS works and what criteria that must be fulfilled for integration to be successful.
3. Principles
Integration
Databases/
Sources
Automatic /XML
3-layer
aplication
BEA
Windows Client
Web Client
User interface
- Administration tool
- End user GUI
- Internet Explorer 7
- Microsoft .NET 2.0/3.5
Manuell data entry
IIS Web Services
Logic
- Microsoft .NET 2.0
- Business rules
Oracle database
Database
- Stored procedures
TEAMS Sustainability Reporting (TEAMS SR) is a three-layer Service Oriented Application (SOA). It is a very
flexible tool where the structure is configured based on a customer’s specific needs. TEAMS treats data the
same whether it is manually input, imported, or pushed through middleware (integration). For a given data
input screen, TEAMS can publish a specific XML-specification sheet (XSD). Any data that fulfils this specification
may be pushed into TEAMS by middleware via a specific TEAMS web-service.
In accordance with industry standards TEAMS SR does not include tools for automatic import, but
communicates well with middleware where such functionality is an important part.
4. Steps involved for establishing import integration
All import integration with TEAMS SR should use TEAMS SR web-services through middleware. This is especially
important with transaction import, as importing through the web service ensures that all imported transactions
are calculated in the same way as manual transactions. The web service used for integration is the same web
service as the one used by the end user web client. Therefore no additional installation is required.
There are five steps involved in establishing integration with TEAMS SR.
1.
2.
3.
4.
5.
Define import and export
Generate XML-specification (XSD)
Use middleware to map the two systems (XSLT).
Test integration.
Establish automatic schedule.
4.1. Define import and export
Page 3 of 10
TEAMS SR v1.3.3 – Import integration
Import and Export is enabled on a per schema basis by creating import and export nodes in the
solution tree below the entry for a schema.
Figure 1: Creating an import menu item
Figure 2: A transaction entry with import and export menu items
4.2. Generate XML-specification (XSD)
TEAMS SR Modeler is the administrative tool used to configure and manage TEAMS SR. This tool is also used to
create specific XSD-files. In the solution tree, select the Export item of the schema you want to integrate. Press
the “Generate XSD” button in the lower right corner of the designer area.
Select a location to save the files in the save dialog, and click Save. TEAMS will save two files in the given
location:

The XSD file for the given schema
Page 4 of 10
TEAMS SR v1.3.3 – Import integration

A sample XML file showing the structure of an XML file for import. Note that the data
contents of the XML file will not be valid, as values of lookups are not picked from the
database. You need to either change this manually (for testing) or use a third party tool to
create the final XML file.
Figure 3: Sample input schema
The structure of the XML schema and XML file will be directly related to the input or master schema that is to
be integrated.
Figure 4: Sample XSD generated by TEAMS
Page 5 of 10
TEAMS SR v1.3.3 – Import integration
Figure 5: Sample XML file generated by TEAMS
4.2.1.Importing multiple transactions
The <Fuelconsumption> and </Fuelconsumption> tags can be repeated inside <TeamsSRSchemas> and
</TeamsSRSchemas> if you wish to import more than one transaction.
It is not possible to import more than one type of transaction in the same import.
4.2.2.Mappings of master data lookup
Lookups of master data are by default done by name. However, depending on the configuration, it
may be done on different fields. You can identify the mapping field for a give schema by looking at the
KeyField property of that given schema in the solution designer. If the solution is configured by
Emisoft, the imports will be documented in separate integration documentation with description of
each field.
Example:
In the schema above there is a lookup of Fuel. By selecting the master schema for fuel in the solution
tree and looking in the property grid, we see that the KeyField for the Fuels schema is Name. When
specifying the data of the <Name> tag in the XML, you should therefore use the name of that fuel. If,
on the other hand, Id was the key field, you should use the GUID of a fuel in the data.
Figure 6: Finding the KeyField in the property grid.
4.2.3.Mapping of units
Units are mapped by the unit name (not symbol).
4.3. Use middleware to map the two systems (XSLT)
Page 6 of 10
TEAMS SR v1.3.3 – Import integration
In principle an import/integration is a matter of merging two name-spaces ensuring a common understanding
of what is what. When this translation is established, the two systems may communicate. When Ids are used
for Key fields, additional lists from TEAMS may be retrieved export from TEAMS or through direct integration to
the TEAMS database.
One of the main challenges regarding integration is change management. When data from the external system
changes it should also be updated in TEAMS SR. By including the external transaction ID in the transfer, TEAMS
SR can retrieve and update the correct transaction. Therefore, if names are not unique or non existing, it is
common practice to include an external id in the import and use this as KeyField. This allows the integration to
not only import new data, but also update existing data in the database. If names are unique, no external id is
required.
Note that it is not currently permitted to omit tags from the XML.
4.4. Test integration
Testing the integration should always take place on a test database, never on the production database. If
required, Emisoft can supply a small test client for testing of connection between the external system and the
TEAMS web service.
Testing should continue with corrections until the transfer works satisfactory. If any scheduling by middle ware
is part of the solution, this should be established before testing and included in the test.
4.5. Establishing automatic schedule
The automatic schedule is established in the middle ware system and out of scope for this document.
5. Connecting to the web service
The web service for integration is available at the same web address as the TEAMS installation except
for the last part. If TEAMS is installed on the address http://mycompany/teamssr.html, then the web
service is found on the address http://mycompany/IntegrationService.svc.
5.1. ClientCredentialType and authentication
Authentication is based on what is registered in AD(Active Directory). ClientCredentialType defines
how the client is authenticated when connecting to the web service. If the web service and the client
calling the web service are on different domains, the client needs to identify itself with username and
password and clientCredentialType must be set to
clientCredentialType="Ntlm"
If the integration client and the web service are on the same domain, the client will be authenticated
through Active Directory and clientCredentialType should be as follows:
clientCredentialType="Windows"
Note: If you are connecting through C#, the clientCredentialType can be set by the following line of
code:
Binding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Ntlm;
6. Web service call
The WSDL for the import can be obtained from http://mycompany/IntegrationService.svc?wsdl
Page 7 of 10
TEAMS SR v1.3.3 – Import integration
The call for the web service has the following signature:
Success TeamsSRIntegrationService(string importName, string xmlstring, ClientContext cc)
Parameters:
ImportName: Name of the import. This is listed for each import in the attached integration document.
Xmlstring: The xml string which is to be imported. Remember to include all tags.
Cc: Client context. This parameter should be Null.
Return Type:
Success class type which contains IsSuccess (bool field) and list of error messages.
You can find the name of the import by selecting the import in the solution designer, and looking at the
Name field in the property grid.
Figure 7: Import name
7. Error messages from the web service
Error messages from the integration service are obtained in two ways: As return parameter from the
web service and stored in database. Errors related to connection and authentication will be returned in
the return type of the web service call. A list of these messages will be added to this document in a
later revision.
Error messages related to the import are stored in the database. In order to obtain these you need to
have database access to the TEAMS database where the web service is connected. The error list can
be created with the following query:
SELECT * FROM Sy_Errors ORDER BY LogDateTime DESC
The error message is provided in the Message column.
8. Change Management
There should It is important that relevant personnel are aware of the integration and what consequence
change might have. When master data or transactions used in calculations are changed, there is no automatic
recalculation of referring transactions. It is therefore vital to establish routines and responsibilities to handle
change to ensure that data imported are treated correctly.
9. Test client
Page 8 of 10
TEAMS SR v1.3.3 – Import integration
The test client is a very basic tool for testing connectivity between the client computer and the web
service.
Prior to using the integration tester, you need the following items.
1.
2.
3.
4.
A username and password on the domain where the TEAMS web service is installed
The name of an import
A valid XML string for import
Endpoint address (URL) to the web service
The integration client is provided as a zip file and does not require an installation. The zip file contains
5 files. The two in the table below are the ones that are important.
TeamsIntegrationClient
TeamsIntegrationClient.exe.
This is the Application file you should run
Config file where endpoint address and
clientCredentialType is set
Before you run TeamsIntegrationClient.exe you need to open TeamsIntegrationClient.exe.config in a
text editor and update two things:
1. Set the endpoint address
2. Set correct clientCredentialType in the file TeamsIntegrationClient.exe.config
See Chapter 5 on how to obtain this information.
The integration client has 6 fields: Domain name, User name, Password, Import name, XML File and
XSD string
Page 9 of 10
TEAMS SR v1.3.3 – Import integration





Domain name is the name of the domain where the integration service is installed.
User name and password are of a user that has access rights on the domain where
the integration service is installed.
Import name is the name of the import
XML File is the xml file to be imported. Make sure to include XML header as well as
all tags required by the XML schema. This includes <TeamsSRSchemas> and
</TeamsSRSchemas> and all tags between.
XSD File is the related XSD(XML Schema Definition)
If the import was successful, the integration client will respond with a message box
Page 10 of 10