Merge API
WorkZone for Office enables you to customize content controls and merge them with information by using public API. Find more information here:
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:
- Create instance of
ICustomXmlPartBuilder
by runningWorkzoneCustomXmlPartBuilderFactory.Create
with appropriate arguments; - 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.
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
.