Configure SmartPost PartyIdentifierSources

SmartPost uses PartyIdentifierSources instance to look up sender information such as CVR or CPR numbers.

This topic describes the implementation and function of the PartyIdentifierSources instance and how you can customize the configuration and/or extend it.

Design

The diagram below shows the core types which constitute the design of the Party IdentifierSources. The design complies with the factory design pattern.

Factory pattern implementation

IPartyIdentifierSource is the interface that exposes the specific implementation of a Party Identifier Source instance. The method GetPartyIdentifier will be called by the application, when a party identifier (CPR or CVR number) is to be retrieved from a contact identifier (contactID). The OData service context is provided as a parameter to support database access in the implementation.

ODataPartyIdentifierSource is a concrete implementation of the IPartyIdentifierSource interface. See ODataPartyIdentifierSource for more details.

The PartyIdentifierSourceFactory can create instances, which implement the IPartyIdentifierSource interface. The actual construction is done through a configuration, which is described in Configuration of the GetPartyIdentifier method. The configuration is provided to the factory as an XML element.

Utility method(GetPartyIdentifier)

The application requests that the factory provides a Party Identifier Source, which the application can then use to retrieve the party identifier from a contact identifier. The party identifier is retrieved in various ways depending on the name type of it. It is therefore useful to have one Party Identifier Source instance per name type that can provide a party identifier.

All this is contained in the static GetPartyIdentifier(string, ODataService)method in the IdentifierSourceUtilities class. Figure 2 shows an example of how this method can be used.

Use of the GetPartyIdentifier method in the IdentifierSourceUtilities class

Configuration of the GetPartyIdentifier method

The method is configured by the XML specified in the Process settings in WorkZone Configuration Management (Operation > Process Settings) or in the WZP_SETTING entity named PartyIdentifierSources (the module name is “WorkZone”). This XML is read and interpreted by the GetPartyIdentifier method. See Utility method(GetPartyIdentifier).

The standard configuration

The XML is interpreted as described below.

The following applies to the entire XML:

  • No namespaces are considered.
  • No schema is specified since the XML details depends on the implementations of the Party Identifier Sources.

For the root element, the following rules applies:

  • The name of the root element is not important.
  • All attributes on the root element are ignored.

The child elements of the root element are searched for the element with an attribute named name-type and which value matches the string parameter to the GetPartyIdentifier method. If no such match was found, then the method returns null. Otherwise the found child element is parsed to the factory, which now is responsible of creating a Party Identifier Source for that name type based on the XML element.

Configuration of a factory

As mentioned above, the XML element (configuration element) that matches the requested name type is parsed to the factory, in order to make it produce a Party Identifier Instance. The factory does this by reading the class attribute from the configuration element. The value of the class attribute must be the fully qualified class name of the requested Party Identifier Source implementation and the class must implement the interface of the IPartyIdentifierSource.

The factory then searches the class for a constructor, which matches one of the following signatures:

  • ctor(ODataService, XElement)
  • ctor(XElement, ODataService)
  • ctor(XElement)
  • ctor(ODataService)
  • ctor()

Where ODataService (FQCN = Scanjour.Process.OData.Client.Proxy.ODataService) is an OData access to the database and XElement (FQCN = System.Xml.Linq.XElement) is the XML element found by the factory.

The search is performed in the order shown above. Whenever a constructor is found, the parameters are provided and the constructor is called, so the Party Identifier Source instance is created and eventually returned by the factory.

The ODataService makes it possible for the Party Identifier Source constructor to search for additional information in the database.

The XElement can be used to retrieve implementation-specific configuration to the constructor.

ODataPartyIdentifierSource

The ODataPartyIdentifierSource class is a general-purpose implementation of the IPartyIdentifierSource interface.

The ODataPartyIdentifierSource can access any register in the database that is made available through OData. The register, the query, and where the value for the Party Identifier are described below.

Configuration

The ODataPartyIdentifierSource is configured by the XML element, which is provided by the factory.

A configuration example of the ODataPartyIdentifierSource

The attributes on the party-identifier-source are not used by the class, but have already been used by the factory. The XML element works more like a placeholder for the three inner XML elements.

It is the three inner XML elements, which configure the ODataPartyIdentifierSource.

register-name The name of the register on which the OData query will take offset.
query-template The template which is used to form the query. When the GetPartyIdentifier(string, ODataService) method is invoked, then two empty curled braces ({}) will be replaced by the contact identifier, which is the first parameter in the method.
field-name The name of the field in the result which content will be returned by the method. The field is expected to contain the code of the Party Identifier. E.g. NameCode.

The final OData query will be formed in the following way:

{base-uri}{register-name}{partial-query}

Where

{base-uri} is the URI to the data source – for example, http://db01/OData/

{register-name} - The content of the register-name element, for example Contacts.

{partial-query} - The content of the query-template element after the curled braces has been replaced by the name key. For example a query template can be:

?$filter=ID eq '{}'&$select=NameCode,NameType_Value

Remember that & in XML must be written as & - see example above.

If the name key is 36, the {partial-query} will then be:

?$filter=ID eq '36'&$select=NameCode,NameType_Value

Based on the above examples the final query will be:

http://db01/OData?$filter=ID eq '36'&$select=NameCode,NameType_Value

From the result of the query, the NameCode of the first entity will be used as Party Identifier.

Customized implementation

If the provided ODataPartyIdentifierSource is insufficient for making a customization, then a customized implementation will probably solve it.

To do so, you must make an assembly containing your customized Party Identifier Source. Add the assembly to the WorkZone Process package, and change the configuration in WZP_SETTINGS, so your class is used by the factory to create your Party Identifier Source.

Follow these steps:

  1. Create a Class Library project for the purpose. Beware of dependencies to other projects.
  2. Make the project reference the WorkZone.Dispatcher.Base assembly.
  3. In your project, create a file containing an empty class.
  4. Make your file use the WorkZone.Dispatcher.Base namespace.
  5. Make the class implement the IPartyIdentifierSource interface.
  6. Make a constructor to the class, that complies to one of the constructors described in Configuration of a factory.
  7. If required, then use the constructor to retrieve configuration information from the XML element or directly from the database using the ODataSerivice provided.
  8. Implement the GetPartyIdentifier method, so it complies with the interface.
  9. Write some tests that verifies your implementation.
  10. Compile and include your assembly in the WorkZone Process package.
  11. Change the configuration in WorkZone Configuration Management or WZP_SETTINGS so that your new Party Identifier Source is used by the correct name type(s) and to make the constructor receive the correct XML element (if required).
  12. Use Visual Studio to generate a new assembly with an updated set of proxy classes. The content of the new assembly must take offset in your customized data dictionary.
  13. Make your installation substitute the existing assembly with the newly generated assembly. Do this by copying the new assembly to “C:\Program Files (x86)\KMD\WorkZone\Process\Web\Services\Bin"
  14. Make an IISRESET.
  15. Test your creation.