Upgrading an Integration to a Later Endpoint


Upgrading an Integration to a Later Endpoint

This page provides information regarding upgrading existing integrations to consume a newer endpoint. The final section will demonstrate an example of what changes to an integration are involved when the targeted SDK Server is updated from Epic 2017.2 to Epic 2021.

When Should an Integration Upgrade to Consume a Newer Endpoint?

When an integration intends to utilize new functionality exposed only in later endpoints.
When an integration intends to conform to the most current business rules.
-In some scenarios where we feel enforcing a new business rule could cause existing integrations to break, we enforce that rule only in later endpoints.
When an integration is using an endpoint that is being retired.
-Epic SDK offers 4 years of backwards compatibility. After that period an endpoint is subject to being retired. We plan to retire the oldest endpoint per release, with the addition of a new one. Always maintaining a fixed amount.

SDK makes our best effort to provide backwards compatibility. In other words, to allow existing SDK integrations to execute without error after the targeted EpicSDK version is upgraded. We offer this to give customers more time to adapt. In other words, it prevents application developers being required to modify existing SDK integration immediately after the EpicSDK upgrade. We recommend using the latest endpoint as early as possible in order to ensure the current business rules are enforced and to give the maximum amount of time until that endpoint is retired. Integration developers need to consider that integrations may need to be deployed against various versions of EpicSDK. This may prevent integrations from upgrading to the latest endpoint.

How Should an Integration Upgrade to Consume a Newer Endpoint?

Obtain the Latest Proxy

When SDK is updated to a new version it contains a new endpoint with the most up to date interface that best reflects that version of Epic. To consume the latest endpoint, the newest proxy should first be obtained. For more information, refer to the Proxy page.

If for some reason SSL needs to be disabled, this can be accomplished by:

Navigating to X:\ASI\ASI.TAM\SDKServer\Software\Bin.
Launching ASI.SMART.Tools.WebConfiguration.exe.
Change SSL to 'OFF' save and close out the screen.

Scan Through the Important Changes

The Important Changes page lists functionality that is most likely to cause existing SDK integrations to require code changes. Certain changes are listed as being required only when upgrading past a specific endpoint. Read through the list to see if any of the changes corresponding to the upgraded endpoint apply to areas and methods that are used by the SDK applications. Special attention beyond merely upgrading the endpoint would be required in these cases.

Code the integrations to consume the desired endpoint

Code examples are shown below. In a few cases compile errors draw attention to what code needs to be updated, but not always. Further coding may be required to resolve any breaking changes found applicable in the previous step.

Run Tests

Of course it is safest to thoroughly test that the integration works and that more significant business rules adjustments that occur with the endpoint upgrade do not cause any issues.

Although, it is not expected, even minor business rule changes e.g. (different default) or minor defect fixes (e.g. spelling mistake) can cause an integration to break. To be safe, run the tests after upgrading the EpicSDKversion, even if code change are not required. Automated end-to-end test would alleviate the amount of effort.

Example Code Changes When Upgrading an Endpoint

When the SDK is updated and ready for Epic 2021 there are going to be some code changes. For example, in Epic 2017 we were using EpicSDK_2017_02Client, but in Epic 2021 we are going to use the new EpicSDK_2021_01Client.

Below you will find several sections of sample code. The objectives of these samples is to demonstrate the get method of Attachment/Clients in the SDK for Epic 2017, and to educate one on the differences in versions of Epic 2017 to Epic 2021. This program will be written in VB.NET using Visual Studio 2019.

Please consider the other Versioning documentation and the documentation of the methods and objects your code are using before upgrading actual code, the section below is only an example.

1. This is a simple form with basic attributes. The properties of the rich text box and buttons were kept as their default values apart from the size. The following controls exist:

a. A rich text box called RichTextBox1 (can be any size)

b. A button named Button1

c. A form called Form1 to hold the controls

2. The following code is going to get an Attachment (just the information about it, not the physical file) using an ActivityID and print out its own AttachmentID. The activity ID can be found using the Get_Activity method. This is going to look similar to what you’re doing in the Epic SDK 2017.

Copy

 1Public Class Form1
 2
 3
 4  Public EpicSDKClient As New EpicSDK_2021_01Client 'Here we are declaring the Client so we can use the get method
 5
 6  Public oGotAttachment As New Get_AttachmentResponse 'Here we are declaring the response so we can use the returned object
 7
 8  'Message  header is used to communicate and holds our key and data base name
 9
10  Public oMessageHeader As New NameOfYourProject.schemas.appliedsystems.com.epic.sdk._2009._07.MessageHeader
11
12  'The form load is where any code here will be executed as soon as the program loads.
13
14  Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
15
16    oMessageHeader.AuthenticationKey = "Key That is Unique To You"
17
18    oMessageHeader.DatabaseName = "Epic Database Name"
19
20  End Sub
21
22
23  'This code is executed when the button is clicked and in here we want to run the code inside
24
25  Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
26
27    GetAttachmentInfo() 'Runs the method
28
29  End Sub
30
31
32  'In this method our goal is to return the AttachmentID of a single attachment that the program finds Applied Epic SDK 2014
33
34  'The ActivityID is set to print out in the rich text box as soon as the user clicks the button
35
36  Public Sub GetAttachmentInfo()
37
38    Dim sActivityID As Integer = 65537
39
40    'This object is necessary to make sure that we are search for the right types please see the documentation above to see
41
42    'what your other options are.
43
44    Dim filter As New NameOfYourProject.schemas.appliedsystems.com.epic.sdk._2011._01._get.AttachmentFilter
45    filter.AttachmentAssociationType = NameOfYourProject.schemas.appliedsystems.com.epic.sdk._2013._11._account.AttachmentAssociationType.ActivityID
46    filter.AttachmentAssociationID = sActivityID
47
48    Dim pageNumber As Integer = 0 'This specifies the page of records to be returned out of possibly many pages.
49    Dim pageSize As Integer = 1
50    'Here we are going to use the get attachment result and assign it to get attachment, and in doing that we can use the get ‘attachment result to print out the information that we want.  In the Get_Attachment there are four parameters which ‘are a Message Header, and an ID as Integer, an object ActivityGetType that allows you to choose how you want to ‘look for the ‘Activity and a ViewType.
51
52    oGotAttachment.Get_AttachmentResult = EpicSDKClient.Get_Attachment(oMessageHeader, filter, Nothing, pageNumber, pageSize)
53
54    'Here we want to display the attachment ID of the first Item in the attachment result collection in the rich text box ‘control.
55
56    RichTextBox1.AppendText(oGotAttachment.Get_AttachmentResult(0).AttachmentID)
57
58  End Sub
59
60End Class

3. Now updating to Epic SDK 2021, all that has to change is to update the Client from the EpicSDK_2017_02Client to EpicSDK_2021_01Client within the same program.

a. In this example all that changes is the SDK Client. If Attachments was versioned, than the namespace that the objects are located in would change, but the attachments area was not versioned from Epic 2017 to Epic 2021.

Copy

 1Public Class Form1
 2
 3
 4  Public EpicSDKClient As New EpicSDK_2021_01Client 'Here we are declaring the Client so we can use the get method
 5
 6  Public oGotAttachment As New Get_AttachmentResponse 'Here we are declaring the response so we can use the returned object
 7
 8  'Message  header is used to communicate and holds our key and data base name
 9
10  Public oMessageHeader As New NameOfYourProject.schemas.appliedsystems.com.epic.sdk._2009._07.MessageHeader
11
12  'The form load is where any code here will be executed as soon as the program loads.
13
14  Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
15
16    oMessageHeader.AuthenticationKey = "Key That is Unique To You"
17
18    oMessageHeader.DatabaseName = "Epic Database Name"
19
20  End Sub
21
22
23  'This code is executed when the button is clicked and in here we want to run the code inside
24
25  Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
26
27    GetAttachmentInfo() 'Runs the method
28
29  End Sub
30
31
32  'In this method our goal is to return the AttachmentID of a single attachment that the program finds Applied Epic SDK 2021
33
34  'The ActivityID is set to print out in the rich text box as soon as the user clicks the button
35
36  Public Sub GetAttachmentInfo()
37
38    Dim sActivityID As Integer = 65537
39
40    'This object is necessary to make sure that we are search for the right types please see the documentation above to see
41
42    'what your other options are.
43
44    Dim filter As new  NameOfYourProject.schemas.appliedsystems.com.epic.sdk._2011._01._get.AttachmentFilter
45    filter.AttachmentAssociationType = NameOfYourProject.schemas.appliedsystems.com.epic.sdk._2013._11._account.AttachmentAssociationType.ActivityID
46    filter.AttachmentAssociationID = sActivityID
47
48    Dim pageNumber As Integer = 0 'This specifies the page of records to be returned out of possibly many pages.
49    Dim pageSize As Integer = 1
50    'Here we are going to use the get attachment result and assign it to get attachment, and in doing that we can use the get ‘attachment result to print out the information that we want.  In the Get_Attachment there are four parameters which ‘are a Message Header, and an ID as Integer, an object ActivityGetType that allows you to choose how you want to ‘look for the ‘Activity and a ViewType.
51
52    oGotAttachment.Get_AttachmentResult = EpicSDKClient.Get_Attachment(oMessageHeader, filter, Nothing, pageNumber, pageSize)
53
54    'Here we want to display the attachment ID of the first Item in the attachment result collection in the rich text box ‘control.
55
56    RichTextBox1.AppendText(oGotAttachment.Get_AttachmentResult(0).AttachmentID)
57
58  End Sub
59
60End Class

4. Although most methods won’t be affected by versioning there are a few methods that will be affected. This is a scenario where you will need to update your code because of versioning in the SDK and that’s where you have to know some key points.

a. The following code will be using the SDK Epic 2017 R1 Claim. The purpose of the following program is to get a claim payment expense.

Copy

 1Public Class Form1
 2
 3
 4  Public EpicSDKClient As New EpicSDK_2017_01Client 'Here we are declaring the Client so we can use the get method
 5
 6  'Message  header we use to communicate and holds our key and data base name
 7
 8  Public oMessageHeader As New SDkGenPro.schemas.appliedsystems.com.epic.sdk._2009._07.MessageHeader
 9
10  Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
11
12
13    'This is where we declare the key and name for the database were trying to access
14
15    oMessageHeader.AuthenticationKey = "Key That is Unique To You"
16
17    oMessageHeader.DatabaseName = " Epic Database Name"
18
19  End Sub
20
21
22  'This code is executed when the button is clicked and in here we want to run the code inside
23
24  Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
25
26
27    GetMethod() 'Runs the method below
28
29
30  End Sub
31
32
33  'In this method our goal is to return the payment expense associated to a single claim ID.
34
35  'Then display the check number in a rich text box.
36
37  Public Sub GetMethod()
38
39    Dim iClaimID As Integer = 65536
40
41    'This specifies that we want to query by Claim ID
42
43    Dim claimGetType As NameOfYourProject.schemas.appliedsystems.com.epic.sdk._2009._07._account._claim.PaymentExpenseGetType
44    claimGetType = NameOfYourProject.schemas.appliedsystems.com.epic.sdk._2009._07._account._claim.PaymentExpenseGetType.ClaimID
45
46    Dim sCheckNumber As String
47
48    'Query SDK to retrieve payment expenses by Claim ID
49
50    sCheckNumber = EpicSDKClient.Get_Claim_PaymentExpense(oMessageHeader, iClaimID, claimGetType).First.CheckNumber
51
52    'Display the check number in rich text box.
53
54    RichTextBox1.AppendText(sCheckNumber)
55
56
57  End Sub
58
59
60End Class

Now in this example, the get method parameters changed in the new version. Now instead of retrieving several payment expense objects, we return a container object that contains a list of those payment expense objects. We have to navigate slightly differently to retrieve the same information. The purpose of this change is to allow the API to better reflect the information being stored in Epic.

Copy

 1Public Class Form1
 2
 3
 4  Public EpicSDKClient As New EpicSDK_2021_02Client 'Here we are declaring the Client so we can use the get method
 5
 6  'Message  header we use to communicate and holds our key and data base name
 7
 8  Public oMessageHeader As New NameOfYourProject.schemas.appliedsystems.com.epic.sdk._2009._07.MessageHeader
 9
10  Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
11
12
13    'This is where we declare the key and name for the database were trying to access
14
15    oMessageHeader.AuthenticationKey = "Key That is Unique To You"
16
17    oMessageHeader.DatabaseName = " Epic Database Name"
18
19  End Sub
20
21
22  'This code is executed when the button is clicked and in here we want to run the code inside
23
24  Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
25
26
27    GetMethod() 'Runs the method below
28
29
30  End Sub
31
32
33  'In this method our goal is to return the payment expense associated to a single claim ID.
34
35  'Then display the check number in a rich text box.
36
37  Public Sub GetMethod()
38
39    Dim iClaimID As Integer = 65536
40
41    'This specifies that we want to query by Claim ID
42
43    Dim sCheckNumber As String
44
45    'Query SDK to retrieve payment expenses by Claim ID
46
47    sCheckNumber = EpicSDKClient.Get_Claim_PaymentExpense(oMessageHeader, iClaimID).First.PaymentExpenseItems.First.CheckNumber
48
49    'Display the check number in rich text box.
50
51    RichTextBox1.AppendText(sCheckNumber)
52
53
54  End Sub
55
56
57End Class

Explanation/Help/Tips

1. Method changes in the SDK Client (these actions will be noted in the code section documentation)

a. New methods are going to exist in new Clients. Refer to the Methods Technical Guide for more information on new methods.

i. Most of the time methods will be modified where they are requiring new parameters or they return different things.

2. Differences in Objects

a. Objects such as Clients and Activities are meant to mimic Epic workflows closely, but this is not always possible. SDK workflows may vary.

i. Always check your code to make sure that your attributes, parameters, and return objects matches methods you’re using.

ii. The object might return different parameters as far as IDs, Types, Names, etc.

iii. Properties Changes

3. There are times where it benefits the code to change property types

a. For example: in the following program we will show a section where this did occur. An Epic field that used to allow only boolean values will now allow 3 choices that are specified by strings. In SDK version 2017, the property was a boolean, and in the new SDK version 2021 it was necessary to change the property to a string to allow for 3 choices. values.

Copy

 1'This is a sample class that just shows the differences in the two versions
 2
 3Public Class Sample
 4
 5  'This is the Line Billing object in 2021
 6
 7  Public oSDK_2017_02Line As New SDK2017R2._0Test.schemas.appliedsystems.com.epic.sdk._2017._02._account._policy.Line
 8
 9  'This is the Line Billing object in 2017 and prior
10
11  Public oSDK_2017_01Line As New SDK2017R1._0Test.schemas.appliedsystems.com.epic.sdk._2011._01._account._policy.Line
12
13
14  'This method is a test method that just shows you the difference in the two versions
15
16  Public Sub TestSample()
17
18
19    'This version is new and notice that the tax option code is a string
20
21    oSDK_2017_02Line.BillingValue.TaxOptionCode = "P"
22
23
24    'This version is the older version and here the is taxable option is a boolean 
25
26    oSDK_2017_01Line.BillingValue.IsTaxable = True
27
28
29  End Sub
30
31
32End Class