Common Operations

Find

Method signature:

FindResultsData Find(QueryData query);

The two interesting structures here are the query and the returned find results.

Find is the first operation to learn in iMIS SOA.

Do the following to use Find:

1. Create an instance of a query object:
   a. (required) The query names the entity to be queried.
   b. (optional) Include a pager object instance to control how much data is returned and which page of data is requested.
   c. (optional) Include a collection of sort fields.
2. Call the Find operation.
3. Trap for errors.
4. Examine results.
5. The entities are returned in an IList collection.
6. The pager is updated with actual results. Page sizes are truncated to system maximums or set to default values, if not specified. The page total rows available and information on the current returned pages is available.

var query = new QueryData("PartySummary") { Pager = new PagerData { PageSize = 5 } };
query.AddCriteria(CriteriaData.StartsWith("LastName", requestedLastName));
 
// invoke the operation to get a list of PartySummary
FindResultsData results = entityService.Find(query);
 
// loop through the pages
while (results.Query.Pager.PageNumber < results2.Query.Pager.PageCount)
{
    Console.WriteLine("Page: {0}", results.Query.Pager.PageNumber);

    // the returned Parties will be in in the results.Results list.
    foreach (PartySummaryData partySummary in results.Result)
    {
        Console.WriteLine("Party: PartyId: {0}, Name: {1}", partySummary.PartyId, partySummary.Name);
    }

    results.Query.Pager.PageNumber++;
    results = entityService.Find(results.Query);
}

Add

Method signature:

ValidateResultsData Add(object entity);

Like Validate, Add returns a ValidateResultsData, including an updated entity instance that might include additional data (notably the identity properties), which should be updated.

Do the following to use Add:

1. Call the Add to send the entity instance you want to add.
2. Trap for errors.
3. Examine the returned ValidateResultsData for errors.

You can also examine the IsValid property to determine whether the results are valid. If not, examine the ValidationResultsSummary property, which lists all of the error and warning strings that you can view.

ValidateResultsData also includes the entity instance. Many Add operations can update the entity instance before it returns.

Update

Method signature:

ValidateResultsData Update(object entity);

Like Validate, Update returns a ValidateResultsData, including an updated entity instance that might include additional data (notably the identity properties) that should be updated. To use Update:

1. Call Update to send the entity instance you want to update.
2. Trap for errors.
3. Examine the returned ValidateResultsData for errors.

You can also examine the IsValid property to determine whether the results are valid. If not, examine the ValidationResultsSummary property, which lists all of the error and warning strings that you can view.

ValidateResultsData also returns the entity instance. Many Update operations can update the entity instance before it returns.

Delete

Method signature:

void Delete(object entity);

Delete returns no validation result, but it should throw a ValidationFault if it fails.

Do the following to use Delete:

1. Call Delete to send the entity instance you want to delete.
2. Trap for errors.

Execute

Method signature:

object Execute(ExecuteRequestBase request);

Execute is a method that some entity implementations provide for operations that go beyond the standard operation set, such as to provide for a special find or to trigger a posting. The argument is very specific to the implementation.

The request argument requires an instance of a class that derives from the ExecuteRequestBase abstract class. Any class that derives from ExecuteRequestBase must, at minimum, override the following properties:

• EntityTypeName – The indication to which the SOA entity request should be directed.
• OperationName – A directive to the entity concerning which specific processing should be performed.

Examples of pre-defined iMIS SOA classes that derive from ExecuteRequestBase include the following:

• ImportFileRequest – This class provides the ability to import data, contained in a file, into iMIS. The EntityTypeName and OperationName properties must be set to route the file import request to an SOA entity that understands the incoming data. Alternatively, you can specify ImportFileType as the EntityTypeName and one of the following values as the OperationName:

  • ImportFile – Lets you direct a file to a particular entity that creates the appropriate data that can be processed by the File Viewer for Web Services iPart (which utilizes an Execute method with the ImportBatchPostRequest). The FileTypeId property must be set to the appropriate value corresponding to a row in the ImportFileTypeRef database table.
  • ImportFilePassThrough – Lets you import an existing XML file, consisting of data contracts that are recognized by iMIS SOA, directly into the system with no additional processing, for eventual batch posting by the File Viewer for Web Services iPart.

• ImportBatchPostRequest – This causes data that was imported by way of an Execute method using an ImportFileRequest argument to be processed.

Do the following to use Execute:

1. Determine the correct ExecuteRequestBase subclass to use as an argument to the Execute method.
2. Call the Execute method.
3. Trap for errors.
4. Examine the return object as required. The returned object varies depending upon the Execute request that was performed.

QueryData

public class QueryData
{
    public QueryData(string entityTypeName) {}
    public QueryData() {}

    public string EntityTypeName { get; set; }
    public CriteriaDataCollection Criteria { get; set; }
    public PagerData Pager { get; set; }
    public SortFieldDataCollection SortFields { get; set; }

    public QueryData AddCriteria(CriteriaData criteriaData) {}
}

Find Results

public class FindResultsData
{
    public QueryData Query { get; set; }
    public IList Result { get; set; }
}

Pager

public class PagerData : IExtensibleDataObject
{
    public int? PageNumber { get; set; }
    public int? PageSize { get; set; }
    public int? PageCount { get; set; }
    public int? TotalRowCount { get; set; }
}

The following is sample .NET code for the SortFieldData class:

public class SortFieldData
{
  public string PropertyName {}
  public SortOrderData? SortOrder {}
}

The following is sample .NET code for the SortOrderData class:

public enum SortOrderData
{
  Ascending,
  Descending
}

FindByIdentity

Method signature:

object FindByIdentity(IdentityData identity);

The interesting structure here is IdentityData.

IdentityData

IdentityData is largely a pointer to a unique entity instance. It contains the entity name and one or more identifying elements (usually just one). These elements usually correspond to a primary key.

public class IdentityData
{
    public IdentityData() {}
    public IdentityData(string entityTypeName, string element) {}
    public IdentityData(string entityTypeName, IEnumerable<string> elements) {}
    public string EntityTypeName { get; set; }
    public Collection<string> IdentityElements { get; set; }
}

Do the following to use to use FindByIdentity:

1. Construct an identifier.
2. Call the FindByIndentity operation.
3. Trap for errors.
4. If the entity existence exists, you will have the entity returned to you; otherwise, your return result will be null.

Validate

Method signature:

ValidateResultsData Validate(object entity);

The interesting structure here is the ValidateResultsData.

ValidateResultsData

public class ValidateResultsData : IExtensibleDataObject
{
    public object Entity { get; set; }
    public ValidationResultsData ValidationResults { get; set; }
    public bool IsValid { get; set; }
    public bool HasWarnings { get; set; }
}

ValidationResultsData

public class ValidationResultsData
{
    public ValidationResultDataCollection Errors { get; set; }
    public ValidationResultDataCollection Warnings { get; set; }
    public bool HasWarnings { get; }
    public bool IsValid  { get; }
    public string Summary {get;}
}

ValidationResultData

ValidationResultsData is a collection of errors and warnings. ValidateResultsData is used in several other places, and it is the general return message for error results for iMIS SOA.

public class ValidationResultData
{
    public string FieldName { get; set; }
    public string FieldValue { get; set; }
    public string Location { get; set; }
    public string Message { get; set; }
    public string FormattedMessage { get; }
}

Do the following to use Validate:

1. Call Validate to send the entity instance you want to validate.
2. Trap for errors.
3. Examine the retuned ValidateResultsData for errors.
   ValidateResultsData also includes the entity instance. Many validate operations might update the entity instance before it is returned. For example, validating an order (by way of the CartData contract) should return an order with all the details recalculated, plus any errors.

FindChangeLogByIdentity

Method signature:

FindResultsData FindChangeLogByIdentity(IdentityData identity);

Currently, FindChangeLogByIdentity is implemented for the Party entity only, but expect to see more use in future releases of iMIS.

Do the following to use FindChangeByIdentity:

1. Prepare an IdentityData instance for the entity needing the change log.
2. Call the FindChangeLogByIdentity operation.
3. Trap for errors.
4. Examine the returned results.

FindMetadataForEntity

Method signature:

EntityDefinitionData FindMetadataForEntity(string entityTypeName);

EntityDefinitionData contains metadata about the entity and its properties.

EntityDefinitionData

public class EntityDefinitionData
{
    public string EntityTypeName { get; set; }
    public string Description { get; set; }
    public EntityPropertyDefinitionDataCollection Properties { get; set; }
    public RelatedEntityDataCollection RelatedEntities { get; set; }
    public string SchemaVersion { get; set; }
}

EntityPropertyDefinitionData

EntityPropertyDefinitionData is a base abstract class. Specific types of properties will have additional metadata, such as string length and decimal positions.

public abstract class EntityPropertyDefinitionData
{
    public string Caption { get; set; }
    public object DefaultValue { get; set; }
    public string Description { get; set; }
    public string DisplayMask { get; set; }
    public bool IsCollection { get; set; }
    public bool IsIdentity { get; set; }
    public bool Logged { get; set; }
    public string Name { get; set; }
    public PropertyRenderingInformationData RenderingInformation { get; set; }
    public bool Required { get; set; }
    public abstract Type PropertyType { get; }
    public abstract string PropertyTypeName { get; set; }
    public bool Visible { get; set; }
}

Do the following to use FindMetadataForEntity:

1. Call the FindMetadataForEntity operation.
2. Trap for errors.
3. Examine the returned results.

FindAll (EntityManager only)

Method signature

public IList FindAll(string entityTypeName)
public IList FindAll(string entityTypeName, bool clearCache)

FindAll returns an IList of all the entity instances for a given entity. FindAll actually performs Find calls and any intermediate paging that might be needed.

Do the following to use FindAll:

1. Call the FindAll operation.
2. Trap for errors.
3. Examine the returned results.