Differences

This shows you the differences between two versions of the page.

--- planning:userguide:results_api [2018/08/21 17:28] – [Non-context based ResultsAPI functions] kerhart
+++ planning:userguide:results_api [2021/07/29 18:24] (current) – external edit 127.0.0.1
@@ Line 30: / Line 30: @@
 These are the recommended functions to be used when interfacing with the Planning App ResultsAPI, as they will ensure compatibility with past and future versions of the ResultsAPI.
-Context based ResultsAPI functions are signified by names prefixed with "api_" (e.g.: //api_generate_plan_summary_request//). These functions check the Thinknode Planning App version context that was used to publish (approve) or last edit the treatment plan and attempt to return a calculation_request for the Planning App version context that was captured in the treatment plan.
+Context based ResultsAPI functions are signified by names prefixed with "api_" (e.g.: //api_generate_plan_summary_request//). These functions check the Thinknode Planning App version context that was used to publish (approve) or last edit the treatment plan and attempt to return a calculation_request for the Planning App version context that was captured in the treatment plan. Since these functions check for the proper context within the provided treatment plan, it's safe to call these functions using any Planning App version that is newer than that of the treatment plan being used as input.
 /*The context based functions provide compatibility for treatment plans that have been created using past versions of the Planning App and thus may have differing ResultsAPI functions or functions with differing signatures. This is achieved by these functions:
@@ Line 51: / Line 51: @@
   * If the ResultsAPI function signature has changed, the calculation request will be constructed for the Planning ResultsAPI version that corresponds for the returned context ID.
-=== Processing a Function ===
+=== Function Usage ===
 These context based ResultsAPI functions return a special type of calculation request object that is not directly usable within a Thinknode META request as they contain the additional context data needed to ensure the desired calculation is performed with the appropriate Astroid Planning App version. The process of running a context based ResultsAPI request consists of the following steps:
-  * Submit the initial "api_*" function request as a normal (non-META) calculation
+  * Submit the initial "api_*" function request as a normal (non-META) calculation using the current Planning App context
   * Retrieve the result of the above calculation and get the context ID
-  * Perform a META request using the above context, setting the META Generator as the calculation object portion of the above "api_*" function result (if it's not null)
+  * Perform a META request using the above context, setting the META Generator as the request portion of the above "api_*" function result (if it's not null)
 ==== Non-context based ResultsAPI functions ====
@@ Line 66: / Line 66: @@
 ===== Example =====
-In the [[https://github.com/dotdecimal/astroid-script-library|.decimal astroid-script-library]] there is a script called //planning_results_api_example.py// that provides a basic example in calling and accessing the results API META functions.
+In the [[https://github.com/dotdecimal/astroid-script-library|.decimal astroid-script-library]] there is a script called //planning_results_api_example.py// that provides a basic example of calling and accessing the ResultsAPI using META functions.
 In this particular example the //api_generate_plan_summary_request// is the ResultsAPI function being called using the current Planning App context installed in the target Thinknode realm. The returned value contains the context ID of the Thinknode Planning App version which created the treatment_plan and the appropriate calculation request for that Planning App version for generating the //plan_summary//. The generator function and META request is submitted using the returned Planning App context ID from the ResultsAPI function. The result of the META request returns the extracted data to use in generating treatment plan reports.