Real World Vision API Solutions

This is a transcript of my VI–66 session at 2017’s Deltek Insight

Agenda

• Introduction
• Getting started with the Windows Service
• Adding reading capabilities to the service
• Using the VisionAPIHelper library
• Implementing the Vision API calls
• Tips & Tricks

Introduction

What do we cover in this session

• We will create a Windows service that will read expense text files from a specific directory and then load this into Vision as an employee expense posting (not an expense report!)
• Due to time and presentation limitations we cannot go directly into Visual Studio. All code examples are screenshots
• If you want to review the code on your laptops download it from GitHub (https://github.com/mdobler/deltekinsight2017 in the VI67 folder)
• These are just concepts. The code does not include error handling or any security considerations

Assumptions

• You must have an very good understanding of the .NET programming language and C# specifically for this sample.
• You should know the basics about the Vision API or visited one of our other API introductory sessions.
• You should be somewhat familiar with Windows Services (although not the main concern of this sample)
• The code is targeting a single company/single currency demo database. Code changes are needed for multi company/multi currency scenarios.

Getting started with the Windows Service

Create the service (step 1)

• Start Visual Studio and create a new project of type “Windows Service (.NET Framework) called ExpenseService.

• Rename the Service1.cs file to ExpenseService.cs, switch to the code view and add the code for the timer execution

• Add a new class CronJob.cs to the project and add the (dummy) Run method

• Add a new Settings variable IntervalInSeconds of type int and value 3600 (once every hour) to your project

Adding reading capabilities to the service

Adding reading capabilities (step 2)

• In this step we will add the ability to read from a very specific file format to the service.
• The service will look for files of file type *.expense in a specific folder (set in the application settings).
• The file must contain a header row and detail rows with the following information: Employee, Transaction Date, Description, WBS1, WBS2, WBS3, Account Number, Amount, Billable Flag, Period and Company
• The field limiter is a pipe symbol (|)

Sample Expense File

Employee|TransDate|Description|WBS1|WBS2|WBS3|Account|Amount|Billable|Period|Company|
00001|2005-06-01|Flight to Boston|1998001.00| | |521.00|1420.00|X|200506||
00001|2005-06-01|Lunch|1998001.00| | |521.01|23.90|X|200506||
00001|2005-06-01|Marriott Courtyard|1998001.00| | |521.00|229.00|X|200506||
00002|2005-06-15|Flight to S.F.|2002005.00|1PD|SPD|521.00|980.00|X|200506||
00002|2005-06-15|Dinner with Guests|2002005.00|1PD|SPD|521.01|120.90|X|200506||
00002|2005-06-15|Fairmont|2002005.00|1PD|SPD|521.00|429.00|X|200506||

Expense Record Class

Cron Job Code

Using the VisionAPIHelper library

What is the VisionAPIHelper library

• The VisionAPIHelper library is a collection of methods and classes that make it easier to work with the Vision API
• We use these classes on a couple of projects ourselves. They speed up overall development time
• Things like connectivity, error handling, logging, API communication and so on have been encapsulated so you don’t have to deal with the raw methods of the API
• We won’t go into too much detail but feel free to explore the helper library on your own

Getting started with the library

• The library looks for specific bindings in the top level application’s web.config or app.config. Just copy the binding information into your app
• If you run unit tests then you will have to copy these bindings into the app’s app.config file as well!
• The application expects a binding called DeltekVisionOpenAPIWebServiceSoap and DeltekVisionOpenAPIWebServiceSoapSSL (for https connections) in your config file. These can be as simple or as detailed as you need them.
• See example on following slide

Simple Binding

Complex Binding

General Usage

• The easiest way of working with the helper class is to instantiate the VisionAPIRepository with all the connection information necessary (we usually store this in the app

Once the repository is initialized you can use the following methods to write to the Vision API:

• .GetRecordsByQuery(…) or GetRecordsByKey(…) returns a list of info center records as Xdocument. The procedure does automatic paging in the background to minimize message size.
• .SendDataToDeltekWithReturn(…) lets you update any info center and will return the newly saved data. This allows you to check for [AutoNumber] values, etc…
• .AddTransaction(…) lets you insert all types of transactions
• .PostTransaction(…) posts a specific transaction

Implementing the Vision API calls

Adding the “postToVision” functionality

• The CronJob process passes the records from the file to the postToVision method. This method sorts the data by employee and then creates a master record and detail records for each employee. These are then accumulated into one batch file.
• The process assumes that all records are posted to the same period and company
• The code uses the new XElement(…) approach to create the necessary structures to the XML document that will be sent to Vision.
• Please consult the xsd documents for the exact message structure (in …\web\xsd)

Create Message Structure

Save and Post in Vision

Tips, Tricks & Additional Resources

Tips and Tricks

• Create a specific user in Vision for API access only and make sure the user has the correct access rights
• Turning on https can be tricky
• Always (!!!) follow the sequence of fields in the schema when you create data records
• If the generic method will not work no matter what you do, try the specific method for that call
• Be careful with returning ALL data. You might run into issues where the returned message is too big. Increase maxReceivedMessageSize and maxStringContentLength in your App.Config

Vision API Test Bench

• This is a free service located at: http://visionapitestbench.steepvalley.net/
• Allows you to try to connect to your service, check connectivity and simple reads from info centers and UDICs and shows you code samples for VB.net and SOAP UI (for testing purposes)
• Writing and Stored Procedure Calls are currently turned off (security reasons) but you will still be able to check the code samples

Links and Downloads

All demos use the VisionDemo76 database which can be downloaded from the Deltek Support Site

• You can find all source code on GitHub:https://github.com/mdobler/insight2017
• Contact me on LinkedIn:https://www.linkedin.com/in/mikedobler/
• Check out my blog for related topics:https://steepvalley.net