Using the Client Library (Asi.Soa.ClientServices)

Access to iMIS SOA web services for most .NET programmers is through a client library. The client library assemblies provide an API for accessing and updating iMIS data, including service classes and methods, as well as the complete set of data, fault and message contract classes. The following client library assemblies contain the key elements of the client services:

• Asi.Soa.ClientServices.dll: The EntityManager and related classes (see .Net Manager classes, below) are the key objects used to access web services. The methods provided in the EntityManager class generally correspond to the operations that are available from the web services.
• Asi.Soa.ServiceModelEx.dll: This assembly provides the support for specifying the information and type of connection to the desired iMIS service.
• Asi.Contracts.dll: Most classes provided in this assembly represent the data objects that are used to access and return data from the service, including classes to define persons and organizations, addresses, membership group lists, orders, invoices, and so forth. This assembly also contains fault and exception data contracts that represent exceptions that might be generated by the SOA service.

The assemblies are dependent on the following assemblies which must be available when the client application is executed:

• Asi.Core.dll
• Autofac.dll
• Newtonsoft.Json.dll

Do the following to use a web client:

1. Create an instance of an EntityManager.
2. Populate the instance with login credentials and connection information.
3. Create and populate objects that will be required by your requested operation.
4. Execute the operation you need using the corresponding method on your EntityManager, trapping for errors. For example:

using System;
using Asi.Soa.Core.DataContracts;
using Asi.Soa.ClientServices;
using Asi.Soa.ServiceModelEx;

string error = string.empty;
try
{
  var uri = 
    new Uri(@"https://website/AsiSchedulerInstance/soa/");
  string userName = "username";
  string password = "password";
  var entityManager = new EntityManager(uri,
                                        userName,
                                        password, 
                                        EndpointType.Soap11);
  var query = new QueryData("Party")
  {
    Criteria = new CriteriaDataCollection 
    {
      CriteriaData.Equal("PartyId", "101")
    }
  };
  var result = entityManager.Find(query);
 
  foreach (PartyData party in result.Result)
    {
      Console.WriteLine("Party - Id: {0}, Name: {1}", 
                        party.PartyId, 
                        party.Name);
    }
}
catch (FaultException<ServiceNotAvailableFault> error)
{
  error = "Service not available.";
}
catch (MessageSecurityException)
{
  error = "Invalid Credentials";
}
catch (Exception error)
{
  error = String.Format("Other error: {0}.", error.Message);
}

ClientServices Caching

Caching data on the client improves the performance of iMIS application servers, particularly remote application servers. iMIS SOA includes calls to EntityManager to simplify caching, and many iParts make caching calls. However, only certain data should be cached, and then often only briefly.

To ensure that data is cached consistently and automatically for numerous entities, SOA uses policy-based caching, versus explicit WithCache calls (now deprecated and ignored). With policy-based caching, each data contract can carry a [CachingPolicy(cacheLifetime)] attribute.

In setting this attribute, keep in mind that caching data can create unexpected outcomes. The following are the lifetime values you can set:

Caching tips

• All high-level, entity-type contracts that you can query have a policy applied: they are registered and carry an [Entity] attribute.
• Contracts that are not marked are handled as DoNotCache.
• The EntityManager Update and Delete calls automatically remove cache values for you.
• Find (by query) calls cache both the Find calls and the underlying elements.
• Find calls include an optional refreshCache argument so that you can force a refresh of cache data, as needed.

Metadata caching

iMIS SOA provides a BOD-like structure for describing entity property characteristics, including prompts. Though the actual metadata is still thin in many areas, it would be relatively inexpensive to provide XML files that describe field-level characteristics of important entities. With metadata for important entities, it would be practical to create an SOA version of a smart control that would operate efficiently over-the-wire. This would improve consistency of application development.

Other caching

As mentioned previously, EntityManager provides caching for metadata and simple caching for FindAll operations, which are common for many simple table look-ups, parameter settings, and so forth. In addition, the cache manager provided in Asi.Soa.ServiceModelEx is available for ad hoc client caching.

As we go forward on implementing UI over web services, we will look for other needs for caching and create systematic approaches to it.

.NET Manager Classes

The following .NET manager classes help a .NET developer easily perform common operations on the entities they manage. We recommend taking advantage of these classes when working in .NET code.

• EntityManager – This is the primary object for initiating calls to the SOA service. It provides built-in operation methods, such as FindByIdentity or FindAll.
• CartManager – This class provides a wrapper for a cart, and a set of common operations to perform on the cart. The cart itself is a property of CartManager.
• ComboOrderManager – This class provides a wrapper for a combo order, and a set of common operations to perform on a combo order, for example, adding or removing order lines.
• CommerceManager – This class helps find commerce information, such as the price a given party will pay for an item.
• EventManager – This class provides a wrapper for an event, and a set of common operations to perform on the event. The event itself is a property of EventManager.
• MembershipManager – This class provides a set of common CRUD operations to perform for parties and users.

EntityManager Operations

For help initializing the EntityManager, see General authentication strategies by endpoint.

📘

Not all operations are supported for all entity types. The SOA service throws a FaultException with an "OperationNotSupportedFault:" message if the entity type does not support the operation.

The EntityManager object provides the following operations:

• Add – Add a new instance of an entity.
• Delete – Delete an instance of an entity, or mark the instance as deleted.
• Execute – Run an entity-specific extended operation.
• Find – Find entities filter by the supplied QueryData object.
• FindAll – Get all entities of a given type.
• FindByIdentity – Find an entity by its identity (primary key in many cases).
• FindChangeLogByIdentity – Get a change log.
• FindMetadataForEntity – Get the entity metadata.
• Update – Update an entity instance.
• Validate – Validate an entity instance.