VPVI-74...» The API uses JSON (javaScript Object Notation) as content type » Our team uses...

VPVI-74:Introduction to the new Web API for Vantagepoint

Michael DoblerPrincipal Technical Consultant, Deltek

Agenda1. Introduction

2. Connecting to the REST API

3. Available Methods

4. Reading Data

5. Writing Data

6. Working with JSON

7. Where to take it from here

8. Tips & Tricks

CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 2


Introduction


» We will create a simple ASP.net MVC core web site that can display project information and

insert contacts into Vantagepoint

» 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/deltekinsight2018)

» These are just concepts. The code does not include error handling or any security

considerations!

What do we cover in this session?

https://github.com/mdobler/deltekinsight2018


» With the move to Vantagepoint, the API technology changes from SOAP to REST

» For the time being the old SOAP visionws.asmx services are supported (to an

extend)

» You will have to move any old Vision API code to the new Vantagepoint REST

calls sooner or later

» New API can be used from many different clients (Jscript, PHP, Ruby, …)

» Still a work in progress, new features are added constantly

Overview


» The acronym REST stands for Representational State Transfer

» Each unique URL is a representation of some object.

» REST uses the standard Http “verbs”

» GET: retrieve the contents of the requested object (SELECT)

» POST: send an entity to a URI (UPDATE, INSERT)

» PUT: store an entity at a URI (INSERT)

» DELETE: request an entity to be removed

What is REST


Connecting to the REST API


» The authentication in Vantagepoint is token based

» Every REST API endpoint you access requires that you supply an access token in the

header of your request to verify that you are an authorized user.

» Authorization involves the following three steps:

» Generate a client secret based on your client ID.

» Use the secret to get an access token.

» Include the access token in all API requests.

Authentication in Vantagepoint


» Your application identifies itself to Vantagepoint by using the secret, which is a unique code that associates with your client ID. You only need to generate the secret once.

» To generate the secret:

» In the Navigation pane, select Utilities » Integrations » API Authorization.

» Click Generate Secret.

» Store the information for your application

Generate the Secret


» All communications to the REST

API will use a standard Http Client

» This code shows how to set it up

with the basic information needed

to communicate with Vantagepoint

Create a Http Client


» You have to submit a Http POST

request to the api/token endpoint

to obtain the access token:

Get the Access Token


» Once you have received a token by

the application, use the token to

make repeat calls to the REST API.

» The token is submitted as part of

the authentication header of the

Http Client

» Your code should check for an

expired token and then refresh it

when necessary instead of always

requesting a new one

Use an Authorized Client


» When refreshing your token always

send in the specific “refresh_token”

you received with the initial call to

the token provider.

» Use the newly returned bearer

token and refresh token for all

subsequent calls

Refresh Token


Reading Data


» GET information is usually submitted in the URI (the web address) itself and can look like

this (page breaks for easier readability:

»

Sending a GET to the API

http://localhost/Storm/vision/project/?order=name&lookuptype=wbs1&searchType=ALL&pagesize=100&offset=0&page=1&wbstype=WBS1&isLevelLock=false&fieldFilter=WBS1%2CName%2CClientName%2CProjMgr%2COrg%2CStatus


» Get an authorized API client (with

bearer token)

» Put together the GET request URI

» Send the GET URI to the API and

retrieve the HttpResponseMessage

» Process the response and extract

the entities sent by the API

Reading Project Data


» https://{yourserver}/api/project: this is the base URI for project information

» ?limit=10: limits the returned result set to the first 10 entries

» &wbstype=wbs1: only return the top level project

» &fieldfilter=WBS1%2CName%2CLongName: only return WBS1, Name and LongName

» &filterhash[i][…]=somevalue: creates a where clause in the API. All filterhash items with the same index belong together. There are multiple available properties to create the filter. The code contains a helper method to help you with this.

GET code explained


» The response contains a JSON array with all matching projects. You can work directly with

the JSON text or cast it into a matching class object

»

GET Response

[{

"WBS3": " ","WBS2": " ","LongName": "Albert Ballfour Cole Plaza Study","Name": "ABC Plaza Study","WBS1": "1999009.00"

}, {…}

]


Writing Data


» POST submits the entity information as part of its message content (not in the URI)

» The API uses JSON (javaScript Object Notation) as content type

» Our team uses Newtonsoft.Json to serialize and deserialize objects into that content type

Sending a POST to the API


» Get an authorized API client (with

bearer token)

» Put together the POST request URI

» Create a class object with the entity

information you want to send

» Post the information to the API

» Process the response and check if

it was successful

Reading Project Data


» The application retrieves a view model back from the call that matches the Contacts

definition in Vantagepoint. If your model does not match you will need to create the JSON

information manually

» https://{yourserver}/api/contact: this is the base URI for contact information

» The PostAsync method deserializes the object into JSON and adds it as content to the

POST message sent to the API

POST code explained


» The POST response contains the full JSON contact object

»

POST Response

[{

"Company": "","flName": "Michael Dobler","ContactID": "829541130BB249759346BCEBEE87706D","ClientID": "","CLAddress": "","Vendor": "",…,

}]


Executing a Stored Procedure


» To execute a custom stored procedure from the REST API, the stored procedure name

must start with “DeltekStoredProc_”

» You pass in the stored procedure name excluding the “DeltekStoredProc_” portion by calling

a post to https://{yourserver}/api/Utilities/InvokeCustom/{storedprocname}

» Parameters are passed in as a Dictionary<string, object> object in the content of the

POST

» If you return data from that stored procedure it will be sent as an XML document

Sending a Post to the API


» The sample code will call a stored procedure DeltekStoredProc_GetInvoiceInfo which will

return the main invoice info in the first <Table> structure and the section totals in the second

<Table1> structure

» There is a helper function that turns the returned XML structure in either a JSON object or a

list of dictionary objects.

» From there the view model is populated based on the (in this case) dictionary object.

Sample Code


» A very simple web page to display

the invoice section details

» Enter an existing invoice number

(including leading zeros)

» The stored procedure will return

two result sets: the first with one

row and all the main invoice info

» The second result set has the

section code and total amount per

section code

Sample Output


» Calling the stored procedure: provide the custom part of the stored procedure as part of the

request URI

» Create a dictionary with all parameters of the stored procedure and pass it as content to the

POST action

Sample Code Explained


» There are two helpers that parse the returned XML into JSON or a dictionary object

Parsing the returned XML into JSON


» There are two helpers that parse the returned XML into JSON or a dictionary object

Parsing the returned XML into a Dictionary


» Once it’s been transformed you can use one to populate your view model.

Inserting it into the view model


Available Methods


» You can find full Deltek

Vantagepoint 2.0 API reference

here:

https://api.deltek.com/Product/Vant

agepoint/api/

» It comes with detailed

documentation and code samples

in different languages

Online Help

https://api.deltek.com/Product/Vantagepoint/api/


Testing With Postman


» POSTMAN is a tool for API development and an be downloaded here:

https://www.getpostman.com/

» It is not a DELTEK product and is not supported by us but it will help you playing around

with our API

» Our API documentation page allows you to start Postman interactively

» You can set up a couple of default variables in a special Vantagepoint Environment and get

started immediately

Use POSTMAN to explore our APIs

https://www.getpostman.com/


Where to take it from here


» With the available documentation and the sample code there are plenty of scenarios where

you can use the new functionality in your company

» REST will allow you to pull data directly into your web site via jScript.

» Automated lead generation, pull prestige projects directly from Vantagepoint into your

website, push data from an Excel sheet into projects, …

Build your own integrations!


Additional Resources

Links and Downloads» All demos use the Vision/Vantagepoint

demo database which can be downloaded from the Deltek Support Site

» You can find all source code on GitHub:

https://github.com/mdobler/Insight2019

» Contact me on LinkedIn:

https://www.linkedin.com/in/mikedobler/

» Check out my blog for related topics:

http://www.steepvalley.net


https://github.com/mdobler/Insight2019

https://www.linkedin.com/in/mikedobler/

http://www.steepvalley.net/

Other Sessions» Creating Custom Reports for Vantagepoint

and Vision

» Wednesday, November 20

» 2:10 PM - 3:10 PM

» The New Vantagepoint Export Utility

» Wednesday, November 20

» 3:20 PM - 4:20 PM

» REPEAT: The New Vantagepoint Export Utility

» Thursday, November 21

» 10:50 AM - 11:50 AM


http://deltekinsight19iframe.azurewebsites.net/SessionDetail.aspx?id=561808



VPVI-74...» The API uses JSON (javaScript Object Notation) as content type » Our team uses...

Documents

Transcript of VPVI-74...» The API uses JSON (javaScript Object Notation) as content type » Our team uses...