VPVI-74...» The API uses JSON (javaScript Object Notation) as content type » Our team uses...
Transcript of VPVI-74...» The API uses JSON (javaScript Object Notation) as content type » Our team uses...
![Page 1: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/1.jpg)
VPVI-74:Introduction to the new Web API for Vantagepoint
Michael DoblerPrincipal Technical Consultant, Deltek
![Page 2: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/2.jpg)
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
![Page 3: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/3.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 3
Introduction
![Page 4: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/4.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 4
» 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?
![Page 5: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/5.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 5
» 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
![Page 6: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/6.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 6
» 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
![Page 7: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/7.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 7
Connecting to the REST API
![Page 8: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/8.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 8
» 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
![Page 9: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/9.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 9
» 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
![Page 10: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/10.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 10
» 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
![Page 11: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/11.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 11
» You have to submit a Http POST
request to the api/token endpoint
to obtain the access token:
Get the Access Token
![Page 12: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/12.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 12
» 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
![Page 13: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/13.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 13
» 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
![Page 14: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/14.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 14
Reading Data
![Page 15: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/15.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 15
» 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
![Page 16: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/16.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 16
» 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
![Page 17: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/17.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 17
» 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
![Page 18: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/18.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 18
» 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"
}, {…}
]
![Page 19: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/19.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 19
Writing Data
![Page 20: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/20.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 20
» 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
![Page 21: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/21.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 21
» 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
![Page 22: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/22.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 22
» 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
![Page 23: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/23.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 23
» The POST response contains the full JSON contact object
»
POST Response
[{
"Company": "","flName": "Michael Dobler","ContactID": "829541130BB249759346BCEBEE87706D","ClientID": "","CLAddress": "","Vendor": "",…,
}]
![Page 24: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/24.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 24
Executing a Stored Procedure
![Page 25: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/25.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 25
» 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
![Page 26: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/26.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 26
» 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
![Page 27: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/27.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 27
» 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
![Page 28: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/28.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 28
» 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
![Page 29: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/29.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 29
» There are two helpers that parse the returned XML into JSON or a dictionary object
Parsing the returned XML into JSON
![Page 30: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/30.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 30
» There are two helpers that parse the returned XML into JSON or a dictionary object
Parsing the returned XML into a Dictionary
![Page 31: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/31.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 31
» Once it’s been transformed you can use one to populate your view model.
Inserting it into the view model
![Page 32: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/32.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 32
Available Methods
![Page 33: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/33.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 33
» 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
![Page 34: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/34.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 34
Testing With Postman
![Page 35: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/35.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 35
» 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
![Page 36: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/36.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 36
Where to take it from here
![Page 37: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/37.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 37
» 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!
![Page 38: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/38.jpg)
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 38
Additional Resources
![Page 39: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/39.jpg)
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
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 39
![Page 40: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/40.jpg)
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
CONFIDENTIAL © Deltek, Inc. All Rights Reserved. 40
![Page 41: VPVI-74...» 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](https://reader036.fdocuments.net/reader036/viewer/2022062505/5ec5eb799ae48d212f430168/html5/thumbnails/41.jpg)