Using Universal Callbacks¶
This article discusses how to use the Universal content standard defined Callbacks. The callback plugin enables the ability to generate RESTful API calls to external REST services. It is very flexible and can be used a number of ways.
The Universal content utilizes a standard named Plugin
of callback
,
to parse and get configuration information from. This article will
describe how to set an example Callback and utilize these standard
extensible hooks in the Universal workflows and pipelines.
This solution will show the operator how to configure a Callback to fire
during the universal-discover-complete-callback
Stage, which is run
towards the end of the universal-discover
Workflow.
The process is the same for any of the standard extensible Callback stages in the Universal Workflows. Substituting the appropriate Callback configuration hook as defined in the correct Stage will allow you to create Callbacks that run at the various Callback Stages within a full Pipeline.
This example also initiates a simple GET
API call to your local DRP
Endpoint. Callbacks can use any of the RESTful verbs (eg GET, PUT, POST,
PATCH, etc.). Please refer to the rs_cp_callback
Documentation for additional information.
Solution¶
First, we will generate a Token to use in our Callback configuration,
which provides a limited amount of authorization permission to execute
the info
API call with only the GET
permission (read-only). This
Token by default will be valid for 1 month (ttl 1mo
). You will need to
save this Token to use it in the Callback configuration Authorization.
# generate Token for 'rocketskates' user only valid for 1 month,
# the 'info' API endpoint, and read-only
RS_USER="rocketskates"
TTL="1mo"
drpcli users token $RS_USER ttl $TTL scope info action get | jq -r .Token
The output of the above command is a valid JWT Token with scoped authorizations.
Now utilize the web Portal to complete the following tasks:
- goto the
Plugins
menu - select the Plugin with the name
callback
(this will not exist if theCallback
Plugin Provider has not been installed yet; see theCatalog
) - Add the param
callback/callbacks
to the Plugin -
Set the following JSON data structure to define the Callback: :
json { "universal-discover-complete": { "Headers": { "Accept": "application/json", "Authorization": "Bearer INSERT_GENERATED_TOKEN_FROM_ABOVE_HERE", "Content-Type": "application/json" }, "JsonResponse": true, "Method": "GET", "Retries": 3, "Timeout": 60, "Url": "https://127.0.0.1:8092/api/v3/info" } }
!!! note
The above block will not work, unless you insert a valid Token in the `Authorization` field in `Headers` - you will receive a `403 Forbidden` error in this event)
-
Save the
callback/callbacks
Param configuration - Save the updated
callback
Plugin configuration
Now when the Stage named universal-discover-complete-callback
is run,
this API call will be triggered.
The results of this can be viewed in the Job Log that is generated for
the callback-task
Task that ran on the given Machine. For this example
use case, the equivalent results of running drpcli info get
should be
displayed.
Additional Information¶
Running in other Universal Stages¶
This article uses the universal-discover-complete-callback
Stage as
the example trigger point for the Callback to execute. All Universal
Workflows contain a pre (or sometimes start) and complete Stage
that can trigger a custom Callback at that location in the Workflow.
To determine the correct name of the callback/callbacks
confgiruation
block to set on the callback
Plugin, select the specific Stage, view
the Params, and determine the value of the callback/action
Param.
For example; the universal-decommission
Workflow Stage
universal-decommission-start-callback
sets the callback/action
Param
value to universal-decommission-complete
. This is the name of the JSON
stanza configuration block to set to enable triggering the Callback
action at this point in the Workflow.
Here is how to get the Param configuration via the drpcli
command:
# get the callback action param configration value for the Stage
# named universal-decommission-start-callback
drpcli stages show universal-decommission-start-callback | jq -r '.Params."callback/action"'
Authorization¶
Authorization can be defined any number of ways. This article chooses to
show a more secure method via the use of a single use or service token.
This token will expire after 1 month, and additional attempts to use
this configuration will fail with a 403 Forbidden
error after it
expires.
There are other ways that the Callback plugin can be configured to handle authorization. Please see the rs_cp_callback documentation for more details.
Target API Url¶
The Url
specified by default should initiate the API call to your DRP
Endpoint via the loopback interface. It is possible that a local
OS/System firewall or filters may block this in some isolated cases.
JsonResponse Configuration¶
By default Callbacks will return a base64 encoded block for historical
reasons. The configuration value "JsonResponse": true
tells the system
to return a JSON data structure without base64 encoding it.
Source of Callback call¶
Callbacks are executed by the DRP Endpoint, and the API communication will originate from the DRP Endpoint as the source IP. Callbacks are not initiated by the target Machine that is executing the Pipeline/Workflow Tasks.
403 Forbidden¶
If the Task Job Log generates a 403 Forbidden
error, then the
Authorization
header is carrying a payload which does not contain the
correct Authorizations to run the info
REST call.
See Also¶
- rs_cp_callback Documentation
- Authentication rs_data_claim information
- rs_example_api_training_scenario
- time_units_for_tokens
Versions¶
v4.6.0 and newer of DRP Endpoint and Callback Plugin Provider
Keywords¶
universal, callbacks, plugin