Manage externalized files

4 minute read

Some entities have fields that contain the content of a file, for example, a script or a certificate. In the XML federated configuration, these files are embedded within the XML, which makes it hard to edit them. In a YAML configuration, the content of these files is stored in separate external files, which provides the following advantages:

• They can be easily read without unnecessary encoding.
• You can create and edit these files using a text editor (IDE) of your choice.
• Files and directory can have long names by default, but you can rename your external file as you wish.

For example, the following YAML file contains a field Set Backend message, which content is stored in a JSON file:

---
type: FilterCircuit
fields:
  name: Get organizationId
children:
- type: ChangeMessageFilter
  fields:
    name: Set Backend message
    outputContentType: application/json
    body: '{{file "Get organizationId - Set Backend message.json"}}' # the message has been externalized

Content of Get organizationId - Set Backend message.json:

{
  "name": "${targetName}",
  "serviceType": "rest",
  "description": "Streamed backend",
  "version": "1.0",
  "basePath": "https://${StreamsSSEVHOST}",
  "resourcePath": "/subscribers",
  "models": {},
  "consumes": [],
  "produces": [],
  "organizationId": "${backend.organizationId}"
}

File externalization is managed with the placeholder {{file "my_file" "file_option"}}:

• my_file is the name of the externalized file. The location can be:

  • Absolute, the path begins with /.
  • Relative to the directory of the YAML file referencing it. In the above example, both files are in the same directory.

• file_option can be:

  • empty: {{file "my_file"}}
  • binary: {{file "my_file" "binary"}}
  • pem: {{file "my_file" "pem"}}

Externalized files default naming scheme

During conversion from FED, externalized file names are generated as follows:

• The entities are named as in Policy Studio.