Expanding PI® API Calls with "modelProperties"
NOTE: This article uses Postman to generate queries using the PI® API Token. For a primer on generating a token, click here. To download Postman, click here.
Connecting to the PI API can be an extremely useful endeavor. However, often times one may find making multiple calls to PI endpoints in order to unearth "friendly data" such as names, descriptions, statuses, etc that normally don't show directly in work item queries. (Most have a GUID/32-digit alphanumeric that is the reference number for those items elsewhere in the database.)
IN ENGLISH: sometimes you just need stuff in one pass without having to do multiple queries to multiple endpoints. Enter "modelProperties".
Model Properties are a way to expand the designated queries by attaching related fields to a query. For example, I may want to get the Time Entries for a specific date range. Out of the box, I can use the time-entry/search endpoint, and it will give me back JSON of the time entries for a given range. Here's an example using startDate and endDate parameters
- https://[yourcompany].projectinsight.net/api/time-entry/search?startDate=3/10/2019&endDate=3/12/2019
The entries that come back resemble:
Unless you've already mapped User_Id in your calling application--who is this time entry for, exactly!? Just by looking at the User_Id, you have no idea. You would need to programmatically take that User_Id GUID and re-query the PI user/{id} endpoint.
Balderdash! That's what modelProperties are for!
By adding the Model Properties to the querystring, you can connect the friendly fields to your query in one shot. Taking the example above, I want to also include the "FirstName" and "LastName" labels in my query:
- https://[yourcompany].projectinsight.net/api/time-entry/search?startDate=3/10/2019&endDate=3/12/2019&modelProperties=Default,User;User:FirstName,LastName
... by adding the additional Item and fields from the User model, I can output those easily with my query. This is what you get with the additional User model params above:
Because the User_Id's match in both the Time Entry and the User records, the model outputs the friendly "FirstName" and "LastName" with the time entry! Voila! Automatic! Boom!
When you're constructing your Model Properties, be sure:
- "modelProperties=" is included in your querystring param
- Models - use Default followed by a comma-separated list of PI Items you want to combine
(Ex. modelProperties=Default,User,ExpenseCode) - Fields - use a ";" to separate the fields for each model
- Name the field, followed by a colon, followed by a comma-separated list of field names
For a complete list of models and their properties, click here.
Questions? Need us to do something for you? Contact me at:
kevin.perkins@projectinsight.com
Happy Coding!
Please sign in to leave a comment.
Comments
0 comments