logoBack to home screen

Using Velocity Templates - Request Body Examples

This page provides examples how to use REST services related to using templates. Currently, the following services are available:

  • Apply template - /tribefire-services/api/v1/access.adx.content.default/v1/convert/apply-template
  • Merge templates - /tribefire-services/api/v1/access.adx.content.default/v1/convert/merge-templates

Both of these endpoints only require a sessionId (see Authenticating to ADx via REST) and a request body with JSON data structure containing the following items:

  • Template specifications
  • IDs of the templates you work with (note that in ADx 2.x templates are treated as any other contents, hence the contentId in the examples below)
  • Information about action to be performed (resultAction - either NEW_CONTENT or CONTENT_REPRESENTATION)

See the examples below to get an idea of how the request body could look like.

Templates

Examples shown later in this page are based on the following Velocity templates, which you can copy to a text editor, save as .vm file, and upload to ADx:

Simple template with one variable (let's call it simple.vm):

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>ADx template</title>
  </head>
  <body>
    Hello ${replacement}!
  </body>
</html>

More complex template with a for loop (let's call it loop.vm):

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Complex ADx template</title>
</head>
<body>
  $simple
  #foreach( $entry in $list.getValues() )
    <li>$entry.get("name")</li>
  #end
</body>
</html>

Template Specification for Text Replacement

Use the JSON snippets below to develop your own text replacement body.

Text Replacement - Apply Template

This is an example of a request body where the source template has one variable - replacement. When you send the request below to /apply-template, a new document called ADx template will be generated, with Replacement text being assigned to replacement and rendered in the document.

{
  "contentId": "simple-vm-ID-goes-here",
  "templateSpecifications": [
    {
      "variables": {
        "replacement": "Replacement text"
      }
    }
  ],
  "priority": 0,
  "resultAction": "NEW_CONTENT",
  "targetName": "ADx template"
}

Text Replacement - Merge Templates

When you send the following request body to /merge-templates endpoint, two templates (identified by contentIds array) are merged into a new document. replacement variable in both templates is replaced by Replacement text.

{
  "contentIds": ["simple-vm-ID-goes-here", "simple-vm-ID-goes-here"],
  "templateSpecifications": [
    {
      "variables": {
        "replacement": "Replacement text"
      }
    }
  ],
  "priority": 0,
  "resultAction": "NEW_CONTENT",
  "targetName": "Merged Template"
}

Template Specifications with Map Records

These examples show how to use template specifications with a map record, which bundles multiple variables.

Apply Template

Examples below demonstrate how you could work with simple.vm and loop.vm via the /apply-template endpoint.

Simple Template

When we send the following request to /apply-template, target document will be rendered from simple.vm:

{
    "contentId": "simple-vm-ID-goes-here",
    "priority": 0,
    "resultAction": "NEW_CONTENT",
    "targetName": "ADx template",
    "templateSpecifications": [
        {
            "mapRecord": {
                "_type": "com.braintribe.model.record.MapRecord",
                "values": {
                    "replacement": "ADx replacement text"          
                }
            }
        }
    ]
}

Loop Template

When we send the following request to /apply-template, target document will be rendered from loop.vm:

{
    "contentId": "loop-vm-ID-goes-here",
    "priority": 0,
    "resultAction": "NEW_CONTENT",
    "targetName": "ADx template",
    "templateSpecifications": [
        {
            "mapRecord": {
                "_type": "com.braintribe.model.record.MapRecord",
                "values": {
                    "simple": "ADx templates",
                    "list": {
                        "_type": "com.braintribe.model.record.ListRecord",
                        "values": [
                            {
                                "_type": "com.braintribe.model.record.MapRecord",
                                "values": {
                                    "name": "ADx templates loop value 1"
                                }
                            },
                            {
                                "_type": "com.braintribe.model.record.MapRecord",
                                "values": {
                                    "name": "ADx templates loop value 2"
                                }
                            }
                        ]
                    }
                }
            }
        }
    ]
}

Merge Templates

Examples below demonstrate how you could work with simple.vm and loop.vm via the /merge-templates endpoint.

Simple Template

This request will merge two simple.vm templates into one document.

{
    "contentIds": [
        "simple-vm-ID-goes-here", "simple-vm-ID-goes-here"
    ],
    "priority": 0,
    "resultAction": "NEW_CONTENT",
    "targetName": "ADx template",
    "templateSpecifications": [
        {
            "mapRecord": {
                "_type": "com.braintribe.model.record.MapRecord",
                "values": {
                    "replacement": "ADx replacement text"          
                }
            }
        }
    ]
}

Loop Template

This request will merge two loop.vm templates into one document.

{
    "contentIds": [
        "loop-vm-ID-goes-here","loop-vm-ID-goes-here"
    ],
    "priority": 0,
    "resultAction": "NEW_CONTENT",
    "targetName": "ADx template",
    "templateSpecifications": [
        {
            "mapRecord": {
                "_type": "com.braintribe.model.record.MapRecord",
                "values": {
                    "simple": "ADx templates",
                    "list": {
                        "_type": "com.braintribe.model.record.ListRecord",
                        "values": [
                            {
                                "_type": "com.braintribe.model.record.MapRecord",
                                "values": {
                                    "name": "ADx templates loop value 1"
                                }
                            },
                            {
                                "_type": "com.braintribe.model.record.MapRecord",
                                "values": {
                                    "name": "ADx templates loop value 2"
                                }
                            }
                        ]
                    }
                }
            }
        }
    ]
}

Try It Out in Swagger

  1. Log in to ADx.

  2. On the landing page, click the API link under repository where you want to use template services:

    OpenAPI page opens.

  3. Consider switching to Swagger 2.0 before executing requests - it is more mature than OpenAPI, which is still in experimental phase.

  4. Expand endpoints under Conversion. You will find both /apply-template and /merge-templates.

  5. Click Try it out! to activate the fields.

  6. Paste your template specification into the Request body field.

  7. Click Execute and check the response. You should get the job duration in the response, and your service should be executed. Check ADx Explorer to verify that your content was indeed rendered or merged.