 | |
Technical Guide | |
As new functionality is added to Applied Epic and the Applied Epic SDK, methods within the Applied Epic SDK may be added, changed, or deleted. New versions of the Applied Epic SDK are programmed with backward compatibility in mind so that in most instances they will not cause existing integration applications to cease working. In some cases, however, the changes are so great that they may have an impact. This section contains strategic considerations for creating integration programs that can easily adapt to change.
Versioning Considerations
1. The Applied Epic SDK conforms to the WS-I basic profile. This enables third parties to consume the Applied Epic SDK using any language that supports this standard (on any platform). For example, you can write your applications using VS 2008 and host on Windows, or you can write your applications using Java and host on Linux. While this is an advantage of the Applied Epic SDK, it also creates complications for coding for changes. For example, if you write your integration applications using Visual Studio 2005 or Java Metro Framework, you will need to regenerate the proxy every time a new property is added to one of the Applied Epic SDK data objects. If a new proxy is not generated, there will be a data loss, because both Visual Studio 2005 and Java Metro Framework nullify any new property whose information is not in the proxy. However, if you create your integration applications using Visual Studio 2008 (which uses the WCF framework), you do not need to generate a new proxy. It is imperative to investigate how the framework you choose will handle changes in the interface
2. This document assumes that third party applications are WCF clients. Given this, it is vital that third party developers consult the web service framework guides to determine if a change would cause problems for any language or platform they are using.
3. The WCF framework is the most flexible in handling changes in the Applied Epic SDK. Because of this, third party developers should consider writing WCF clients unless their business needs demand a different language, tool, or platform.
4. Upgrades to the Applied Epic SDK should be applied regularly, because Applied Epic SDK improvements and fixes are not applied retroactively but are added only to new versions of the Applied Epic SDK.
5. To maintain backward compatibility, we currently expose the previous 3 versions of the Applied Epic SDK. This will allow code written in the latest version (which is what we always recommend) to work for the longest amount of time possible without further changes. Once a version is retired, please refer to the Versioning - Upgrading the SDK Version for an example on how to upgrade existing code.
6. Note that when Update Manager is run to update Applied Epic, it updates the Applied Epic SDK at the same time. Before Update Manager is run for Applied Epic, review the release documentation for the Applied Epic SDK for any possible upgrades to the Applied Epic SDK that may affect your applications.
Breaking Backward Compatibility
There are certain situations where technical limitations will make it impossible to achieve complete backward compatibility when upgrading your system to a new version of Applied Epic. The following is a list of some of the situations which usually break backward compatibility:
A new required field is added to Applied Epic – this prevents backwards compatibility unless the field can be defaulted or existing data configuration logic can be used.
An existing field in Applied Epic becomes required – this prevents backwards compatibility unless the field can be defaulted.
A field is removed from a screen in Applied Epic – in some cases.
A field is removed from the Applied Epic product database – this prevents backwards compatibility unless a mapping table can be created, but this scenario is very unlikely to occur.
Multiple fields are combined – this prevents backwards compatibility only if the data is unable to be parsed.
A single field is split – this prevents backwards compatibility only if the data is unable to be parsed.
A data type change is made to a field in Applied Epic – this prevents backwards compatibility if there are issues with truncating the data or if there is tightened validation.
A new validation is added – this prevents backwards compatibility unless the data can be defaulted.
New parameters are added to a method – this prevents backwards compatibility unless the parameters can be defaulted.
How breaking changes are handled by Epic SDK
The Applied Epic SDK follows service oriented architecture (SOA). One of the principles of SOA is that once the service contract has been published, it will never change. Because of this, any modification that changes the behavior of a data object or method is considered a “breaking change” in that it breaks the existing contract and thus can only be included in a new contract. If everything were to be deemed “breaking”, there would be numerous versions that would eventually become not maintainable. To avoid this problem, we have deemed only a subset of changes as breaking changes. A “breaking change” is not a change in which backwards compatibility is impossible; it is simply a change that requires a new object or method call in order to take advantage of the new functionality.
The following types of changes may occur in any major or minor release and will not be considered breaking changes in Epic SDK but will cause problems for client programs:
1. Changes to business validations that may cause an insert or update to fail- For example, changes that force the user to close all activity before performing an update.
2. Input validation changes- For example, changing the maximum size of a field from 12 to 10 or changing the required values to be passed when doing a get type method call.
The following types of changes may occur in any major or minor release and will not be considered breaking changes in Applied Epic SDK but may cause problems to client programs, depending on the language and web service framework:
1. Adding a new optional property
2. Adding new values to get type and flag enums
The following changes will most likely occur in major releases and will be considered breaking changes in Applied Epic SDK and will cause problems for client programs:
1. Adding new required Applied Epic SDK properties
2. Making an existing optional property in Applied Epic SDK required
3. Removing or renaming a property
4. Changing the data type of a property
5. Removing or renaming values from get type enums
6. Removing a method
7. Adding additional parameters to an existing method
8. Changing an input parameter type and/or return type for a method
Epic SDK Versioning Procedure
The purpose of versioning in Applied Epic SDK is to be backward compatible and support existing third party applications. When a breaking change occurs, the service contract is versioned along with any data contracts that need to be changed. The new service contract:
1. Is exposed at a new endpoint address.
2. Contains all methods from the previous service contract (unless some method has been removed).
a. Depending on the type of breaking change, methods with the same name (between versions) may have a different method signature or return type.
b. All other methods will differ based on the address where the request is to be sent (this is usually transparent to the user when using Visual Studio).
Versioning Data Contracts
Data contracts are versioned when:
1. Adding new Applied Epic SDK required properties
2. Converting an existing optional property to required in Applied Epic SDK
3. Removing or renaming a property
4. Changing the data type of a property
5. Removing or renaming values from get type enums
Versioning of data contracts is done by using a different month and year on their namespace. The data contract names remain the same. As an example, the following shows that when the Client object is versioned, the name remains the same, but the namespace changes from:
http://MyWebSite.com/EPIC/SDK/2009/07/_account/
to:
http://MyWebSite.com/EPIC/SDK/2011/01/_account/
The year and month in the namespace are the expected release date of the service contract. All data contracts versioned during a release will have the same year and month combination.
Service Contract Versioning
A service contract is versioned whenever a data contract is versioned or the exposed method signature or return type changes. When this occurs:
1. The different versions of the service contract have a different month and year combination in the service contract namespace.
2. The binding namespace and name is changed.
3. The different versions are exposed on a different relative endpoint address. This address is chosen by suffixing the letter V with the year and month of the expected release date. This year and month always match the year and month used on versioned objects.
4. The service contract name is suffixed by the year and month of the expected release date (for example, EpicSDK_2011_01).
An example of how this code would look like is:
<endpoint address="v2011_01" binding="basicHttpBinding" bindingConfiguration="SSLBinding"
name="ServiceBinding_2011_01"
bindingNamespace="http://webservices.yourserver.com/epic/sdk/2011/01/"
contract="ASI.TAM.API.Web.EpicSDK.IService" />
As shown above, the namespace month/year of the service contract and data contracts versioned during a release are the same.
Guidelines and Best Practices for Versioning
There are a few guidelines and best practices that should be noted with the Applied Epic SDK versioning. We have broken them down into three categories.
1. Guidelines for consuming a versioned Applied Epic SDK with changes that will break client programs and are considered breaking changes by the Applied Epic SDK:
a. Refer to the Applied Epic SDK release notes for information on whether the service and data contracts were versioned.
b. Always use the latest Applied Epic SDK contract version when coding. All fixes and enhancements will be applied only to the latest contract. Old service contracts exist only to support backward compatibility for existing applications.
c. Avoid mixing service contract versions in code. As a good practice, all method calls within an application should target only one service contract. Because of this, code resembling the following should be avoided:
Dim oSDK_2019_01 as New EpicSDK_2019_01Client
Dim oSDK_2020_01 as New EpicSDK_2020_01Client
oSDK_2019_01.Insert_Client(…)
oSDK_2020_01.Get_Client(…)
d. Upgrade existing code that uses previous versions to the latest versions as soon as possible.
e. For easy code upgrades, consider using meaningful namespace aliases that include the year and month instead of hard coding them. The following is an example of hard-to-maintain code followed by an example of easy-to-maintain code:
i. Dim oClient As New _ SDKVersioningTest.schemas.appliedsystems.com.epic.sdk._2009._07._account.Client
ii. Imports SDKAcc_2009_07 = _ SDKVersioningTest.schemas.appliedsystems.com.epic.sdk._2009._07._account
Dim oClient As New SDKAcc_2009_07.Client
f. It is important to remember that not all breaking changes will be versioned. Sometimes it is impossible to support backward compatibility and hence all client applications that consume the method in question will need to be updated.
2. Guidelines to mitigate problems that will break client programs but are not considered breaking in the Applied Epic SDK
As previously discussed, problems that will break client programs but are not considered breaking for purposes of the Applied Epic SDK arise when business or input validations change. These occur due to changing business needs, changing government regulations, or fixes.
a. Read the Applied Epic SDK release notes. If any significant changes are made, consider running Update Manager only after the client programs are modified (or after impact is analyzed) to avoid any possible downtime.
b. Avoid hard coding input validations in the client applications. For example, let’s say we have a field called ID that requires exactly 10 characters. This condition is handled by the Applied Epic SDK, but it is possible to enforce this in the client application as well. The latter option may be more efficient in reducing a method call; however, if the size of the ID field changes to 11, the client application will not work properly until the correction is made. On the other hand, if these validations are handled by Applied Epic SDK, no change is needed for the client application. The user simply needs to be advised to send an ID of 11 characters in length.
c. If the business and security policy of the agency allows the user to modify any input property, consider exposing all properties to the user. For example, if the user is allowed to filter transactions based on any filter type, consider exposing all filter types. If filter types are defaulted internally and some filter type is made mandatory, the client application will not work properly until the applications are corrected. If these are defaulted on the UI and the user has an option to change them, the downtime can be avoided.
3. Guidelines to mitigate problems that may break client programs but are not considered breaking changes in the Applied Epic SDK:
Changes that may break client programs but are not considered breaking changes in the Applied Epic SDK are caused by the addition of new optional properties or enum values. When a new optional property is added, Get and Insert type methods should be unaffected; however, Update type methods may be affected. The effect on the Update type methods will result in data loss, since most frameworks do not support round tripping. For example, if a new property called Price is added and a value of 5.5 is sent during a Get type method call, asmx web service clients will nullify the data during an Update type method call (a zero will be returned, causing data loss). Insert type methods will remain unaffected, but client applications will not be able to make use of the new property unless the proxy is regenerated and client code is modified.
When new values are added to enums (the Applied Epic SDK uses enums only for collection flags and input get types) all Get, Insert, and Update type methods should work fine as long as the proxy is not regenerated. If proxies are regenerated, the whole client application may have to be recompiled since in some languages, like VB.NET, enum values are converted to integer values during compile time. The following steps should be considered to mitigate any potential issues:
a. Read the Applied Epic SDK release notes before running Update Manager to evaluate any risks.
b. For WCF clients, adding a new property will not cause any issues as long as IExtensibleDataObject is implemented (this is done by default when generating the proxy using svcutil).
c. For non WCF clients, consider regenerating the proxy and recompiling all associated client libraries and applications for every release.
d. If a proxy is regenerated, all libraries associated with the project that reference the Applied Epic SDK need to be recompiled to avoid problems when new enum values are added (this step may be avoided depending on how the language implements enum).
Example Code
The following is an example of an existing integration application consuming an the 2017_01 endpoint released in Epic SDK 2017 R1:
Line was versioned because SDK required different data types to reflect new functionality in later Epic versions (e.g. BillingValue.TaxOptionCode).1Imports SDK2017_01 = ASI.Tools.API.Documentation.SampleCode.schemas.appliedsystems.com.epic.sdk._2017._01 2 3Public Class VersioningSampleOne 4 5 Private Shared Sub CallMethods() 6 7 Dim oSDK_2017_01Client As New EpicSDK_2017_01Client 8 Dim oLine As New SDK2017_01._account._policy.Line 9 10 With oLine 11 .BillingValue = SDK2017_01._account._policy._line.Billing 12 'In Epic 2017 R1 IsTaxable property was type of Boolean 13 'The below code demonstrates how the property was used. 14 .BillingValue.IsTaxable = True 15 16 'Fill in other required fields 17 End With 18 19 Try 20 Dim iLineID As Integer = oSDK_2017_01Client.Insert_Line(oHeader, oLine) 21 oSDK_2017_01Client.Close() 22 Catch ex As Exception 23 oSDK_2017_01Client.Abort() 24 Throw 25 End Try 26 End Sub 27 28End Class
The following example shows how to move the above code to use the new 2021 endpoint after upgrading to Epic SDK 2021:
1Imports SDK2017_02 = ASI.Tools.API.Documentation.SampleCode.schemas.appliedsystems.com.epic.sdk._2017._02 2 3Public Class VersioningSampleTwo 4 Private Shared Sub CallMethods_2021_01() 5 6 Dim oSDK_2021_01Client As New EpicSDK_2021_01Client 7 Dim oLine As New SDK2017_02._account._policy.Line 8 With oLine 9 .BillingValue = New SDK2017_02._account._policy._line.Billing 10 'In Epic 2017 R2, the IsTaxable property renamed to TaxOptionCode. 11 'In addition, the type of Boolean was changed to String. 12 'After upgrading to 2017 R2 or beyond, applications that were utilizing the obsolete isTaxable property must be changed. 13 'The below line demonstrates how the code would be easily updated. 14 .BillingValue.TaxOptionCode = "P" 15 16 'Fill in other required fields 17 End With 18 Try 19 Dim iLineID As Integer = oSDK_2021_01Client.Insert_Line(oHeader, oLine) 20 oSDK_2021_01Client.Close() 21 Catch ex As Exception 22 oSDK_2021_01Client.Abort() 23 Throw 24 End Try 25 26 End Sub 27 28End Class