Merge API

WorkZone for Office enables you to customize content controls and merge them with information by using public API. Find more information here:

• Walkthrough: Binding Content Controls to Custom XML Parts
• Custom XML Parts Overview

To use public API, install the compiled version of WorkZone for Office and the following library assemblies:

Kmd.Wzfo.CustomXmlParts.Bootstrapper.dll

Kmd.Wzfo.CustomXmlParts.dll

Kmd.Wzfo.CustomXmlParts.Workzone.dll

Scanjour.Office.Services.Interfaces.dll

Scanjour.Office.ODataClient.dll

Scanjour.OData.Client.dll

Scanjour.Utils.dll

Kmd.Wzfo.CustomXmlParts.Bootstrapper.dll is the entry point library assembly. It contains WorkzoneCustomXmlPartBuilderFactory with method 'ICustomXmlPartBuilder Create(BuilderParameters parameters, IProtectedAddressesAcceptor protectedAddressesAcceptor)'

To generate data source for WorkZone for Office content controls, proceed with the following steps:

1. Create instance of ICustomXmlPartBuilder by running WorkzoneCustomXmlPartBuilderFactory.Create with appropriate arguments;
2. Build custom xml part

BuilderParameters

public class BuilderParameters
	{
		public BuilderParameters(Uri oDataEndpoint)
		{
			ODataEndpoint = oDataEndpoint;
			CredentialsProvider = new DefaultNetworkCredentialsProvider();
			CacheDuration = new TimeSpan(0, 0, 10, 0);
			CultureProvider = new ApplicationLocalizer();
		}
		public Uri ODataEndpoint { get; }
		public ICredentialsProvider CredentialsProvider { get; set; }
		public TimeSpan CacheDuration { get; set; }
		public ICultureProvider CultureProvider { get; set; }
		public bool UseOAuth { get; set; }
		public string AccessToken { get; set; }
	}

where:

• ODataEndpoint – OData endpoint for building xml part, for example, https://db01/OData;
• CredentialsProvider – Interface for getting OData credentials;
• CacheDuration – Duration of the cache that will be used by WorkZone for Office caching mechanism;
• CultureProvider – Extracts data of specific language for OData.
• AccessToken – Used in token-based authentication to allow an application to access an API if your organization uses OAuth2 for user authentication.
• UseOAuth – Enables using an access token for OAuth2 authentication if your organization uses such authentication.

IProtectedAddressesAcceptor

This interface is used to set rules for handling protected addresses. By default, its values are set to false, so that protected address fields are hidden on UI.

public interface IProtectedAddressesAcceptor
        {
        	bool AcceptCasePartyAddress(IParty party);
        	bool AcceptRecordPartyAddress(IParty party);
        	bool AcceptCaseOfficerAddress();
       		bool AcceptCaseResponsibleOuAddress();
       		bool AcceptRecordOfficerAddress();
       		bool AcceptRecordResponsibleOuAddress();
        }

ICustomXmlPartBuilder

You can use the build custom xml part as data source for WorkZone for Office content controls.

public interface ICustomXmlPartBuilder
        {
        	Task<string> BuildAsync(string recordId, IEnumerable<IParty> recordParties, IEnumerable<IReadCustomXmlMapping> contentControls);
        	Task<string> BuildAsync(string recordId, string caseId, IEnumerable<IParty> recordParties, IEnumerable<IReadCustomXmlMapping> contentControls);
        }

where:

• recordId – document ID that is used as a data context for building custom xml part.
• caseId – case ID that is used as a data context for building custom xml part.

In the upper BuildAsync method, case ID is retrieved from primary case metadata by using recordID. In the lower BuildAsync method, case ID is retrieved directly from caseID.

If you get AuthenticationException when using the BuildAsync method in the OAuth2 mode, it means that the current access token has expired and another one should be obtained.

IParty

For Merge API, this interface is used to describe case party properties, for example, case party role:

new PartyRole ("Afsender", "AP")
	public interface IParty
        {
        	string AddressKey { get; }
        	PartyRole Role { get; }
        }

IReadCustomXmlMapping

This interface contains information about Content Control for which we build custom xml data.

public interface IReadCustomXmlMapping
        {
        string XmlMappingPrefix { get; }
        string XmlMappingXPath { get; }
        string Tag { get; }
        ContentControlType Type { get; }
        }

Ensure that your client extracts correct data from content controls via Merge API and then merge the data with the instance of IReadCustomXmlMapping.