Using SOAP and NetTCP

Previous iMIS versions used Windows Communication Foundation (WCF) to access the web services.

While this is still supported for backward compatibility with existing third-party extensions, all third-party developers should now use the REST endpoint for new development.

Simple Object Access Protocol (SOAP) envelopes are used to communicate to the database with HTTP or NetTCP endpoints. The following is a simple example of accessing iMIS SOA using Microsoft C#:

// get PartyName (contact name) for Party (contact) Id 101

string partyId = "101";
var entityManager = new EntityManager();
var membershipManager = new MembershipManager(entityManager);
PartyData party = membershipManager.GetPartyByPartyId(partyId);
string partyName = party.Name;

Troubleshooting SOA

If you experience SOA connection problems, check the following:

Restart SOA and Internet Information Services (IIS) after all your changes are complete.
Verify that you ran the Multi-Instance Utility from the iMIS install directory. This configures the SOA service.
Determine if the web service is returning the correct Web Service Definition Language (WSDL). Go to the EntityService URL and check the WSDL address:
http://your_website/your_web_application_name/EntityService.svc
Inspect your SOA service using SOAP UI: http://www.soapui.org.

Setting up SOA for external access

If you need to set up SOA for external access, it is recommended that you set up a public domain name pointing to the application server (for example, imis.mysite.org) as early in the process as possible:

If you have to change the public domain name after implementation, rerun the Multi-Instance Utility to reconfigure and update the machines to point to the new URL.
Make sure that the URL is also accessible from the internal network so that the application server, web server, terminal server or desktops can also see the new domain (for example, imis.mysite.org).
You also need a publicly signed SSL certificate running on the server. Registering an SSL certificate simplifies this task.

Once you’ve got your domain you need to bind the domain to the site. You need to set up a host header in Internet Information Services (IIS).

Go into IIS and ensure that the website host headers point to your new domain for both HTTP and HTTPS. In IIS7 these are called Bindings.

If the SSL Binding is grayed out in IIS7, do the following:

Open Internet Information Services (IIS) Manager.
Edit the Site Bindings for the website to which you want to assign an SSL certificate. To get to Bindings in IIS7:
a. Select your website in IIS.
b. In the right navigation area of the Edit Site section, select Bindings….
Select https, and click Edit. Note that the Host name field is unavailable for editing.
Launch the Microsoft Management Console (MMC):
a. Go to Start > Run to open a command prompt
b. Type in MMC and press Enter.
c. From the console, click File > Add / Remove Snap-in.
d. Select Certificates from the available snap-ins list.
e. Click Add.
f. Select Computer account when prompted. Click Next.
g. Select Local computer when prompted.
h. Click Finish to add the snap-in to the MMC.
Locate your SSL certificate.
- Open the Certificates folder.
- For self-signed certificates (SELFSSL), look in Personal.
- For installed or purchased certificates, look in the folder where the certificate was originally installed.
Right-click on the certificate and select Properties.
Edit the Friendly name field so that the name starts with an asterisk *.
To verify that the Host name field is now available for editing, repeat steps #1 – 3.

Internet Information Server (IIS)

IIS6

To create a Self-Signed SSL Certificate for Windows 2003, you need to download the IIS 6 Resource kit and install the SelfSSL 1.0 program. The documentation included with the Resource kit describes the optional parameters that are available.

Sample command line entry

This entry is for creating and registering a self-signed certificate:

Selfssl /V:1000 /T

If the installation has more than one web site under IIS, run the command using the /S parameter and the site ID for the site you are trying to secure.

You might need to use the /N:cn parameter, which sets the IssuedTo property of your certificate.

IIS7

If you are running IIS 7, you can create a self-signed certificate for testing using the IIS user interface. See these example instructions.

Common Resources

Standard Data Types

iMIS SOA uses a few new core/primitive data types throughout the system:

MonetaryAmountData – A money amount that includes both a decimal amount and currency type. Use this type with all money amounts.
QuantityData – A quantity that includes a unit of measure. Use this type with all order entry quantities.
AternateIdData – A generic approach for alternate identifiers for parties, products, and so forth.
YearMonthDateData – A date specifically for year and month only.
EntityUpdateInformationData – A standard set of created/updated, by/on values. This is generally read-only, meaning never set by the client. The …by properties contain information that is useful for the UI, such as login ID, not GUIDs.

Most of these types have constructors and conversion methods to other data types.

Client Helper Classes

Once installed, iMIS SOA web services provides a complete WSDL description to web service consumers that fully describes the available operations and data structures (data contracts). Many programming tools are available that can create a proxy or client object to make data access easy through the generated object model.

With this in mind, there are basically three approaches for accessing the iMIS SOA Web Service API:

Use one of the provided access tool kits (recommended).
Create SOAP call code and handle the underlying XML documents by hand.
Generate a client proxy which fully describes the available operations and data contracts. This is known as a Service Reference in .NET.

Depending on the client environment, the first and second options are both good options. The first option is usually preferred as the provided toolkits add a few useful helper extensions that make data manipulation more convenient.

Test Client

The iMIS SOA Web Services includes an example client application which demonstrates several iMIS SOA Web Services patterns. The iMIS SOA Web Services also includes a client library which is recommended for access to the web services API. It is recommended that you install and become familiar with the sample client and the demonstration web service site before installing and testing your own web services server instance.

A test client is provided as a Visual Studio 2008 project. The test client includes:

A sample set user interface to facilitate and demonstrate searching for a list of contacts (Parties).
Ability to retrieve an individual party.
Ability to update a party.
Ability to reveal and display group participation, user define demographics and change log.

PHP Toolkit

iMIS SOA Web Service includes a PHP Toolkit. The toolkit provides a number of PHP class definitions, a web access client, and a number of examples that illustrate the use of the toolkit.