Upgrading the SDK Version


Upgrading the SDK Version

Epic SDK offers a 3 years backward compatibility in order to help existing code work without any changes being required. When those 3 years are up a code upgrade will be required. This section will show an actual coding example of how that upgrade will look like when upgrading from Epic 2017.1 to Epic 2017.2. The same approach will work when upgrading from any version to the most recent one.

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.

Applied Epic 2017 R2

1. The version of the SDK will be the same as the version of Epic that is currently running on your system

a. Before starting, make sure that you are running Epic version 2017 R2. There are two ways to accomplish this:

i. Check Update Manager

ii. In Epic go to Help > About

b. When you’re done with Update Manager and updated to Epic 2017 R2 go to Updating SDK

Updating SDK

1. Once you have updated Epic to the latest version, we can now update the SDK

a. You can refer back to section Installation and Configuration > Install the Epic SDK to reinstall/updating the SDK

Running Proxies

1. Refer to Development - First Steps for instructions how to run proxies on your new version of Epic SDK

2. If for some reason you need to turn off SSL you need to go to X:\ASI\ASI.TAM\SDKServer\Software\Bin look for ASI.SMART.Tools.WebConfiguration.exe

3. Change SSL to OFF save and close out the screen

Code Changes

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

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 2017 R2. This program will be written in VB.NET 4.0 using Visual Studio 2010.

1. This is a simple form and the names of the 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_2017_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
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, oFilter, Nothing, pageNumber)
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 2017 R2, all that has to change is to update the Client from the EpicSDK_2017_01Client to EpicSDK_2017_02Client 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 2017 R2.

Copy

 1Public Class Form1
 2
 3
 4  Public EpicSDKClient As New EpicSDK_2017_02Client '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
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, oFilter, Nothing, pageNumber)
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 R2 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 SDkGenPro.schemas.appliedsystems.com.epic.sdk._2009._07._account._claim.PaymentExpenseGetType
44    claimGetType = SDkGenPro.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_2017_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 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 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 2017 R2 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 2017 R2
 6
 7      Public oSDK_2017_02Line As New
 8
 9      SDK2017R2._0Test.schemas.appliedsystems.com.epic.sdk._2017._02._account._policy.Line
10
11
12
13  'This is the Line Billing object in 2017 and prior
14
15      Public oSDK_2017_01Line As New
16
17      SDK2017R2._0Test.schemas.appliedsystems.com.epic.sdk._2011._01._account._policy.Line
18
19
20
21  'This method is a test method that just shows you the difference in the two versions
22
23  Public Sub TestSample()
24
25
26    'This version is new and notice that the tax option code is a string
27
28    oSDK_2017_02Line.BillingValue.TaxOptionCode = "P"
29
30
31    'This version is the older version and here the is taxable option is a boolean 
32
33    oSDK_2017_01Line.BillingValue.IsTaxable = True
34
35
36  End Sub
37
38
39End Class

Send comments on this topic to INTEGRATIONSERVICES@appliedsystems.com