Differences

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

--- planning:userguide:results_api [2018/08/21 17:10] – [Input Parameters] 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 47: / Line 47: @@
 The context based ResultsAPI functions return a //[[http://docs.apps.dotdecimal.com/planning_results_api/#context_based_calculation_request|context_based_calculation_request]]// that contains the Thinknode Planning App context ID used for the plan and an optional calculation_request that should be submitted using the returned context ID.
-The function uses the following logic to attempt to generate a compatible //calculation_request// for the Thinknode Planning App version context ID captured in the treatment plan. This request is created by the following logic:
+These functions use the following logic to attempt to generate a compatible //calculation_request// for the Thinknode Planning App version context ID captured in the treatment plan. This request is created by the following logic:
   * If the ResultsAPI function does not exist for the captured Planning App version, the optional<calculation_request> will be returned as null
   * 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.
+=== 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 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 request portion of the above "api_*" function result (if it's not null)
 ==== Non-context based ResultsAPI functions ====
-These functions are not recommended to be called from the ResultsAPI unless the caller wishes to recompute resulting data with a new Astroid version. These functions construct a request for the end data while not taking into account the captured Planning App context ID of the treatment plan.
+These functions are not recommended to be called directly unless the caller specifically wishes to recompute the resulting data with a new Astroid version. These functions construct a request for the end data while not taking into account the captured Planning App context ID of the treatment plan, therefore data upgrades and other changes may be applied to the inputs and outputs, such that the returned data may not exactly match that of the original treatment plan at the time of approval (publishing).
-Non-context based ResultsAPI functions are signified by not having "api_*" prefixed function names (e.g.: //generate_plan_summary_request//).
+Non-context based ResultsAPI function names are not prefixed with "api_" (e.g.: //generate_plan_summary_request//).
 ===== 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.