mapdata
Prototype:mapdata(interpretation, pattern, array_or_container)
Return type:data
Description: Returns a data container holding a JSON array. Thearray is a map across each element ofarray_or_container, modified byapattern. The map is either collected literally wheninterpretationisnone, or canonified wheninterpretation iscanonify,or parsed as JSON wheninterpretation isjson, or collected frompattern,invoked as a program, wheninterpretation isjson_pipe.
This function can accept many types of data parameters.
The$(this.k) and$(this.v) variables expand to the key and valueof the current element, similar to the waythis is available formaplist.
If the array or data container has two levels, you'll also be able touse the$(this.k[1]) variable for the key at the second level. Seethe example below for an illustration.
The order of the keys is not guaranteed. Use thesort() function ifyou need order in the resulting output.
Arguments:
interpretation: - Conversion to apply to the mapped string - one ofnonecanonifyjsonjson_pipe
pattern:string- Pattern based on $(this.k) and $(this.v) as original text - in the range:.*array_or_container:string- CFEngine variable identifier or inline JSON - in the range:.*
Example:
bodycommoncontrol{bundlesequence=>{"run"};}bundleagentrun{vars:"myarray[lookup][big]"string=>"lookup big";"myarray[lookup][small]"string=>"lookup small";# every item must parse as valid JSON when the interpretation is `json`"mapa_json"data=>mapdata("json",'{"key":"$(this.k)","key2":"$(this.k[1])","value":"$(this.v)"}',myarray);"mapa_json_str"string=>format("%S",mapa_json);# every item is just a string when the interpretation is `none`"mapa_none"data=>mapdata("none",'key=$(this.k),level2key=$(this.k[1]),value=$(this.v)',myarray);"mapa_none_str"string=>format("%S",mapa_none);"mycontainer"data=>parsejson('{"top":{"x":100,"y":200}}');# every item must parse as valid JSON when the interpretation is `json`"mapc_json"data=>mapdata("json",'{"key":"$(this.k)","key2":"$(this.k[1])","value":"$(this.v)"}',mycontainer);"mapc_json_str"string=>format("%S",mapc_json);# every item is just a string when the interpretation is `none`"mapc_none"data=>mapdata("none",'key=$(this.k),level2key=$(this.k[1]),value=$(this.v)',mycontainer);"mapc_none_str"string=>format("%S",mapc_none);reports:show_example::"mapdata/json on classic CFEngine array result:$(mapa_json_str)";"mapdata/none on classic CFEngine array result:$(mapa_none_str)";"mapdata/json on data container result:$(mapc_json_str)";"mapdata/none on data container result:$(mapc_none_str)";any::"Note that the output of the above reports is not deterministic,";"because the order of the keys returned by mapdata() is not guaranteed.";}Output: (whenshow_example is defined)
R: mapdata/json on classic CFEngine array result: [{"key":"lookup","key2":"big","value":"lookup big"},{"key":"lookup","key2":"small","value":"lookup small"}]R: mapdata/none on classic CFEngine array result: ["key=lookup, level 2 key = big, value=lookup big","key=lookup, level 2 key = small, value=lookup small"]R: mapdata/json on data container result: [{"key":"top","key2":"x","value":"100"},{"key":"top","key2":"y","value":"200"}]R: mapdata/none on data container result: ["key=top, level 2 key = x, value=100","key=top, level 2 key = y, value=200"]json_pipe
Thejson_pipe interpretation is intended to work with programs that take JSONas input and produce JSON as output. This is a standard tool convention in theUnix world. See the example below for the typical usage.
jq has a powerful programming language thatfits thejson_pipe interpretation well. It will take JSON input and productJSON output. Please read thejq manual andcookbook to get a feel for the power of this tool. When available,jq will offer tremendous data manipulationpower for advanced cases where the built-in CFEngine functions are not enough.
Example with json_pipe:
bodycommoncontrol{bundlesequence=>{"run"};}bundleagentrun{vars:"tester"data=>'{"x":100,"y":[true,"a","b"]}';# "jq ." returns the same thing that was passed in"pipe_passthrough"data=>mapdata("json_pipe",'$(def.jq).',tester);"pipe_passthrough_str"string=>format("%S",pipe_passthrough);# "jq .x" returns what was under x wrapped in an array: [100]"pipe_justx"data=>mapdata("json_pipe",'$(def.jq).x',tester);"pipe_justx_str"string=>format("%S",pipe_justx);# "jq .y" returns what was under y wrapped in an array: [[true,"a","b"]]"pipe_justy"data=>mapdata("json_pipe",'$(def.jq).y',tester);"pipe_justy_str"string=>format("%S",pipe_justy);# "jq .y[]" returns each entry under y *separately*: [true,"a","b"]"pipe_yarray"data=>mapdata("json_pipe",'$(def.jq).y[]',tester);"pipe_yarray_str"string=>format("%S",pipe_yarray);# "jq .z" returns null because the key "z" is missing: [null]"pipe_justz"data=>mapdata("json_pipe",'$(def.jq).z',tester);"pipe_justz_str"string=>format("%S",pipe_justz);# "jq" can do math too! and much more!"pipe_jqmath"data=>mapdata("json_pipe",'$(def.jq)1+2+3',tester);"pipe_jqmath_str"string=>format("%S",pipe_jqmath);reports:"mapdata/json_pipe passthrough result:$(pipe_passthrough_str)";"mapdata/json_pipe just x result:$(pipe_justx_str)";"mapdata/json_pipe just y result:$(pipe_justy_str)";"mapdata/json_pipe array under y result:$(pipe_yarray_str)";"mapdata/json_pipe just z result:$(pipe_justz_str)";"mapdata/json_pipe math expression result:$(pipe_jqmath_str)";}Output:
R: mapdata/json_pipe passthrough result: [{"x":100,"y":[true,"a","b"]}]R: mapdata/json_pipe just x result: [100]R: mapdata/json_pipe just y result: [[true,"a","b"]]R: mapdata/json_pipe array under y result: [true,"a","b"]R: mapdata/json_pipe just z result: [null]R: mapdata/json_pipe math expression result: [6]History: Was introduced in 3.7.0.canonify mode was introduced in 3.9.0. Thecollecting function behavior was added in 3.9. Thejson_pipe mode was added in 3.9. The delayed evaluation behavior was introduced in 3.10.
See also:maplist(),maparray(),canonify(),about collecting functions, anddata documentation.
- Overview
- Getting started
- Reference
- Components
- Functions
- accessedbefore
- accumulated
- ago
- and
- basename
- bundlesmatching
- bundlestate
- callstack_callers
- callstack_promisers
- canonify
- canonifyuniquely
- cf_version_after
- cf_version_at
- cf_version_before
- cf_version_between
- cf_version_maximum
- cf_version_minimum
- changedbefore
- classesmatching
- classfiltercsv
- classify
- classmatch
- concat
- countclassesmatching
- countlinesmatching
- data_expand
- data_readstringarray
- data_readstringarrayidx
- data_regextract
- data_sysctlvalues
- datastate
- difference
- dirname
- diskfree
- escape
- eval
- every
- execresult
- execresult_as_data
- expandrange
- file_hash
- fileexists
- filesexist
- filesize
- filestat
- filter
- findfiles
- findfiles_up
- findprocesses
- format
- getclassmetatags
- getenv
- getfields
- getgid
- getindices
- getuid
- getuserinfo
- getusers
- getvalues
- getvariablemetatags
- grep
- groupexists
- hash
- hash_to_int
- hashmatch
- host2ip
- hostinnetgroup
- hostrange
- hostsseen
- hostswithclass
- hubknowledge
- ifelse
- int
- intersection
- ip2host
- iprange
- irange
- isdir
- isexecutable
- isgreaterthan
- isipinsubnet
- islessthan
- islink
- isnewerthan
- isplain
- isreadable
- isvariable
- join
- lastnode
- laterthan
- ldaparray
- ldaplist
- ldapvalue
- length
- lsdir
- makerule
- maparray
- mapdata
- maplist
- max
- mean
- mergedata
- min
- network_connections
- none
- not
- now
- nth
- on
- or
- packagesmatching
- packageupdatesmatching
- parseintarray
- parsejson
- parserealarray
- parsestringarray
- parsestringarrayidx
- parseyaml
- peerleader
- peerleaders
- peers
- processexists
- product
- randomint
- read_module_protocol
- readcsv
- readdata
- readenvfile
- readfile
- readintarray
- readintlist
- readjson
- readrealarray
- readreallist
- readstringarray
- readstringarrayidx
- readstringlist
- readtcp
- readyaml
- regarray
- regcmp
- regex_replace
- regextract
- registryvalue
- regldap
- regline
- reglist
- remoteclassesmatching
- remotescalar
- returnszero
- reverse
- rrange
- selectservers
- shuffle
- some
- sort
- splayclass
- splitstring
- storejson
- strcmp
- strftime
- string
- string_downcase
- string_head
- string_length
- string_mustache
- string_replace
- string_reverse
- string_split
- string_tail
- string_trim
- string_upcase
- sublist
- sum
- sysctlvalue
- translatepath
- type
- unique
- url_get
- usemodule
- userexists
- validdata
- validjson
- variablesmatching
- variablesmatching_as_data
- variance
- version_compare
- Language concepts
- Masterfiles Policy Framework
- promises.cf
- .no-distrib/
- update.cf
- standalone_self_upgrade.cf
- cfe_internal/
- cfe_internal/CFE_cfengine.cf
- cfe_internal/core/
- cfe_internal/core/watchdog
- cfe_internal/core/watchdog/watchdog.cf
- cfe_internal/enterprise/
- cfe_internal/enterprise/federation/
- cfe_internal/enterprise/federation/federation.cf
- cfe_internal/recommendations.cf
- cfe_internal/update/
- cfe_internal/update/cfe_internal_dc_workflow.cf
- cfe_internal/update/cfe_internal_update_from_repository.cf
- cfe_internal/update/lib.cf
- cfe_internal/update/systemd_units.cf
- cfe_internal/update/update_bins.cf
- cfe_internal/update/update_policy.cf
- cfe_internal/update/update_processes.cf
- controls/
- controls/cf_agent.cf
- controls/cf_execd.cf
- controls/cf_hub.cf
- controls/cf_monitord.cf
- controls/cf_runagent.cf
- controls/cf_serverd.cf
- controls/def.cf
- controls/def_inputs.cf
- controls/reports.cf
- controls/update_def.cf
- controls/update_def_inputs.cf
- inventory/
- inventory/any.cf
- inventory/debian.cf
- inventory/freebsd.cf
- inventory/generic.cf
- inventory/linux.cf
- inventory/lsb.cf
- inventory/macos.cf
- inventory/os.cf
- inventory/redhat.cf
- inventory/suse.cf
- inventory/windows.cf
- lib/
- lib/autorun.cf
- lib/bundles.cf
- lib/cfe_internal.cf
- lib/cfe_internal_hub.cf
- lib/cfengine_enterprise_hub_ha.cf
- lib/commands.cf
- lib/common.cf
- lib/databases.cf
- lib/edit_xml.cf
- lib/event.cf
- lib/examples.cf
- lib/feature.cf
- lib/files.cf
- lib/guest_environments.cf
- lib/monitor.cf
- lib/packages.cf
- lib/paths.cf
- lib/processes.cf
- lib/reports.cf
- lib/services.cf
- lib/stdlib.cf
- lib/storage.cf
- lib/testing.cf
- lib/users.cf
- lib/vcs.cf
- modules/
- modules/mustache/
- modules/packages/
- modules/packages/vendored/
- modules/promises/
- modules/promises/cfengine.py
- modules/promises/cfengine.sh
- services/
- services/autorun/
- services/main.cf
- Macros
- Promise types
- Special variables
- All promise and body types
- Release notes
- Web UI
- Settings
- Health
- Hosts
- Alerts and notifications
- Custom actions for alerts
- Enterprise reporting
- Federated reporting
- Measurements app
- Hub administration
- Decommissioning hosts
- Extending Mission Portal
- Extending query builder in Mission Portal
- Adjusting schedules
- Backup and restore
- Configure a custom LDAP port
- Custom LDAPs certificate
- Custom SSL certificate
- Enable plain http
- Lookup license info
- Policy deployment
- Public key distribution
- Re-installing Enterprise hub
- Regenerate self signed SSL certificate
- Reset administrative credentials
- Debugging Mission Portal
- License
- Examples and tutorials
- Example snippets
- General examples
- Administration examples
- Measuring examples
- Software administration examples
- Commands, scripts, and execution examples
- File and directory examples
- File template examples
- Interacting with directory services
- Database examples
- Network examples
- System security examples
- System information examples
- System administration examples
- System file examples
- Windows registry examples
- File permissions
- User management examples
- Common promise patterns
- Aborting execution
- Change detection
- Check filesystem space
- Copy single files
- Create files and directories
- Customize message of the day
- Distribute ssh keys
- Ensure a process is not running
- Ensure a service is enabled and running
- Find the MAC address
- Install packages
- Mount NFS filesystem
- Restart a process
- Set up name resolution with DNS
- Set up sudo
- Set up time management through NTP
- Updating from a central policy server
- Tutorials
- JSON and YAML support in CFEngine
- Installing CFEngine Enterprise agent
- Managing local users
- Managing network time protocol
- Managing processes and services
- Package management
- Writing CFEngine policy
- Distributing files from a central location
- File editing
- Reporting and remediation of security vulnerabilities
- Masterfiles Policy Framework upgrade
- Tags for variables, classes, and bundles
- Custom inventory
- Dashboard alerts
- Integrating alerts with PagerDuty
- Integrating alerts with ticketing systems
- Integrating with Sumo Logic
- Rendering files with Mustache templates
- Reporting
- File comparison
- High availability
- Writing and serving policy
- Example snippets
- Resources
- FAQ
- Why knowledge management?
- Requesting a CFEngine Enterprise License
- Uninstalling / reinstalling
- Agent output email
- Debugging slow queries
- Enterprise Report Filtering
- Enterprise report collection
- Enterprise reporting database
- How can I tell what classes and variables are defined?
- How do I find the public key for a given host
- How do I fix trust after an IP change?
- How do I fix undefined body errors?
- How do I integrate custom policy?
- How do I pass a data type variable?
- Manual execution
- Mustache templating
- Unable to log into Mission Portal
- Users
- What is promise locking?
- Why are remote agents not updating?
- Why are some files inside masterfiles not being updated/distributed?
- Why does CFEngine install into /var/cfengine instead of following the FHS?
- Bootstrapping
- Tuning PostgreSQL
- What did CFEngine do?
- External resources
- Additional topics
- Best practices
- FAQ
- API
- Enterprise API examples
- Enterprise API reference
- Actions API
- Build API
- CMDB API
- Changes REST API
- Federated reporting configuration API
- File changes API
- Health diagnostic API
- Host REST API
- Import & export API
- Import & export compliance report API
- Inventory API
- LDAP authentication API
- Personal groups API
- Query REST API
- SQL schema
- SSH keys API
- Shared groups API
- Status and settings REST API
- Two-factor authentication API
- Users and access-control REST API
- VCS settings API
- Web RBAC API