Macros
Managing macros
Macros offer the possibility to encapsulate and reuse function chains. This allows the compact use of function chains and a central maintenance of these. Changes to a macro affect all profiles that use this macro. Macros can be defined system-wide or client-specific.
You can open the macro dialog via the target structure menu in the lower bar of the function area with option "Manage macros". Either to create the existing function chain as a new macro or to display the overview of all macros. Note: You can copy the ID of a macro in the opened macro.
Creating a new macro
Assume the following function chain.
If you want to create this function chain as a new macro, you will get the following dialogue.
(1) ID: The ID of the macro. Can be copied here.
(2) Description: Text that will later be displayed in the tooltip.
(3) Access: The macro is visible either system-wide or client-wide. Note: Cannot be changed after the first save.
(4) Exclude in export: With this option you can decide whether the macro should be ignored when exporting profiles or when transferring profiles with the Transport Manager.
(5) Functions: Here you can add further functions to the function chain (6). But to keep the example simple, we will not do that now.
(6) Functions contained in macro: The current function chain with all its individual functions. If you mark a function, the parameters of the function are displayed (as usual).
(7) Test macro: The macro can be tested here. If input parameters were used, see (8), you can specify test values for these.
(8) Index, Description, Test value: Optional input parameters (left window). See following section.
Creating input parameters for the macro
If you save the macro created above, you can already use it on fields and nodes. The example above, however, is very simple and not really helpful in this form. Often, as you are used to from most functions, you also want to use input parameters.
For this task, there is a special input parameter type "Parameter" for macros only, which you can select instead of any of the input parameters in the function chain. See the following example.
Example
Highlight parameter a of the first function in the chain, change the type to "Parameter" and change the value from "4" to "1". The value is the parameter index. However, in order for this to be used, an input parameter must be created.
Now use the context menu in the left window (9) and create a new input parameter, which has the index "1". Use test value "5". This test value will be used as the input value for this parameter if you click button "Test macro" (7).
As a result of the macro test, you should now get "23".
Using the macro
If you now use the macro on a node or field, it will look like this. You will see that the macro has one parameter (10). This is the parameter that you just created.
Calling a macro via HTTP (REST)
You can define for each macro whether it can be called via HTTP. The macro ID and macro parameters must then be specified in the HTTP request. See the following example.
Let's assume the following macro:
We see that the ID of the macro is "-948283363". The macro also has two parameters, "Date" and "Template". Note: The parameters are numbered here, starting with "1". In the HTTP request, the parameters are specified with letters, starting with "a".
Click on the "Configure HTTP access" button. The following dialogue box will then open (these settings can be overridden in individual macros):
As you can see, the formal structure of the URL is as follows:
|
https://<your-server>:<your-port>/dw/macro/v1/<macro-id>?<cid><further optional parameters> |
Parameters
|
Parameter |
Description |
|
macro-id |
(mandatory) The ID of the macro. |
|
cid |
(mandatory) The client ID. -1 is the default client. |
|
ttl sid rs |
(optional) Why use sessions? Sessions provide a kind of "memory" between multiple API calls. They enable more complex or multi-step data processing by avoiding the need to resend or recompute all data with every call. This makes workflows more efficient and flexible. ttl (time to live): sid (session ID): rs (remove session): |
Example request (GET)
|
https://localhost/dw/macro/v1/-948283363?a=24-10-03&b=yy-MM-dd&ttl=10&cid=-1 |
Note: You will see the macro ID and the two macro parameters as request parameters. Always use the value "-1" for the request parameter "cid".
Example response (always with MIME type application/json):
{ "sid": "-2a757ec1:192571c4108:-18fe.a61aa22d82067d80:-2a757ec1:192571c1cd5:-8000", "cid": "-1", "expiresAt": "Fri Oct 04 12:40:26 CEST 2024", "result": "Thu"}The result of the macro can be found in the "result" field, in this case "Thu" (the determined day).
Example request (POST)
|
https://localhost/dw/macro/v1/-275832567 |
The data must be specified as JSON in the body of the POST request. Body data:
{ "ttl" : "60", "a": "hello", "b" : "world", "cid": "-1"}Example response (always with MIME type application/json):
{ "sid": "-437190e:19253af2f0e:-6de.16a4526421da288d:-437190e:19253af0b75:-8000", "cid": "-1", "expiresAt": "Thu Oct 03 21:12:09 CEST 2024", "result": "hello-world"}Errors
In case of an error, HTTP status code 400 and the following JSON will be returned.
{ "error" : "Error message..."}REST variables
If you want to use variables in the macro, you cannot use "normal" variables because you are not in a profile when you call the macro via REST. However, you can create special variables that you can use for this purpose. See the corresponding context menu entry above.
Important note: Please note that although you can then call the macro "independently" via REST, the variables live in a specific profile. This means that in order to use the variables in REST calls, the profile must still exist and the variables must remain defined there.
Special case
If the variable "var__restapi_macro_resultJSON" is set to "true" in the macro with function save variable a(b) type-safe, the result is inserted "as is" in the "result" field of the JSON response, i.e. it is regarded as valid JSON and not set as a string.
Example:
Let's assume that the macro returns the following value: [‘Ford’, “BMW”, ‘Fiat’]
Response for var__restapi_macro_resultJSON=true:
{ ... "result": ["Ford", "BMW", "Fiat"]}Response for var__restapi_macro_resultJSON=false:
{ ... "result": "[\u0022Ford\u0022, \u0022BMW\u0022, \u0022Fiat\u0022]"}