Mercurial > prosody-modules

annotate mod_muc_members_json/README.md @ 6562:5da6fb562df9 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_unified_push: Fix push error handling (fixes #2000) Use the error object that send_iq() passes as an argument to it's reject callback instead of attempting and failing to do the parsing in the callback itself.
author kmq
date Mon, 06 Jul 2026 14:23:57 +0200
parents 459cb2c2789b
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5586
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 ---
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 labels:
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 - 'Stage-Beta'
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 summary: 'Import MUC membership info from a JSON file'
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5 ...
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 Introduction
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8 ============
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10 This module allows you to import MUC membership information from an external
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
11 URL in JSON format.
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
12
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
13 Details
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
14 =======
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
15
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16 If you have an organization or community and lots of members and/or channels,
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17 it can be frustrating to manage MUC affiliations manually. This module will
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
18 fetch a JSON file from a configured URL, and use that to automatically set the
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19 MUC affiliations.
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21 It also supports hats/badges.
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 Configuration
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24 =============
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26 Add the module to the MUC host (not the global modules\_enabled):
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28 Component "conference.example.com" "muc"
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
29 modules_enabled = { "muc_members_json" }
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31 You can define (globally or per-MUC component) the following options:
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33 Name Description
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34 --------------------- --------------------------------------------------
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
35 muc_members_json_url The URL to the JSON file describing memberships
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
36 muc_members_json_mucs The MUCs to manage, and their associated configuration
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
38 The `muc_members_json_mucs` setting determines which rooms will be managed by
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39 the plugin, and how to map roles to hats (if desired).
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40
5693
6696075e26e2 mod_muc_members_json: Fix typo in example and set correct syntax highlighter
Matthew Wild <mwild1@gmail.com>
parents: 5692
diff changeset
41 ``` lua
5586
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42 muc_members_json_mucs = {
5693
6696075e26e2 mod_muc_members_json: Fix typo in example and set correct syntax highlighter
Matthew Wild <mwild1@gmail.com>
parents: 5692
diff changeset
43 -- This configures hats for the myroom@<this MUC host> MUC
5586
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
44 myroom = {
6431
459cb2c2789b mod_muc_members_json: Support private MUCs, non-member affiliation grants, async storage, dry-run mode
Matthew Wild <mwild1@gmail.com>
parents: 5693
diff changeset
45 -- Set the MUC to private. In this case the MUC will be closed
459cb2c2789b mod_muc_members_json: Support private MUCs, non-member affiliation grants, async storage, dry-run mode
Matthew Wild <mwild1@gmail.com>
parents: 5693
diff changeset
46 -- to anyone who doesn't have one of the owner_roles, admin_roles
459cb2c2789b mod_muc_members_json: Support private MUCs, non-member affiliation grants, async storage, dry-run mode
Matthew Wild <mwild1@gmail.com>
parents: 5693
diff changeset
47 -- or member_roles specified below
459cb2c2789b mod_muc_members_json: Support private MUCs, non-member affiliation grants, async storage, dry-run mode
Matthew Wild <mwild1@gmail.com>
parents: 5693
diff changeset
48 private = true;
459cb2c2789b mod_muc_members_json: Support private MUCs, non-member affiliation grants, async storage, dry-run mode
Matthew Wild <mwild1@gmail.com>
parents: 5693
diff changeset
49
459cb2c2789b mod_muc_members_json: Support private MUCs, non-member affiliation grants, async storage, dry-run mode
Matthew Wild <mwild1@gmail.com>
parents: 5693
diff changeset
50 -- Specify privileges based on roles specified in the JSON
459cb2c2789b mod_muc_members_json: Support private MUCs, non-member affiliation grants, async storage, dry-run mode
Matthew Wild <mwild1@gmail.com>
parents: 5693
diff changeset
51 owner_roles = { "staff" };
459cb2c2789b mod_muc_members_json: Support private MUCs, non-member affiliation grants, async storage, dry-run mode
Matthew Wild <mwild1@gmail.com>
parents: 5693
diff changeset
52 admin_roles = { "moderator" };
459cb2c2789b mod_muc_members_json: Support private MUCs, non-member affiliation grants, async storage, dry-run mode
Matthew Wild <mwild1@gmail.com>
parents: 5693
diff changeset
53
459cb2c2789b mod_muc_members_json: Support private MUCs, non-member affiliation grants, async storage, dry-run mode
Matthew Wild <mwild1@gmail.com>
parents: 5693
diff changeset
54 -- If not specified, anyone listed in the JSON will be added
459cb2c2789b mod_muc_members_json: Support private MUCs, non-member affiliation grants, async storage, dry-run mode
Matthew Wild <mwild1@gmail.com>
parents: 5693
diff changeset
55 -- as a member. Otherwise, only the specified roles will
459cb2c2789b mod_muc_members_json: Support private MUCs, non-member affiliation grants, async storage, dry-run mode
Matthew Wild <mwild1@gmail.com>
parents: 5693
diff changeset
56 -- become members in this MUC.
459cb2c2789b mod_muc_members_json: Support private MUCs, non-member affiliation grants, async storage, dry-run mode
Matthew Wild <mwild1@gmail.com>
parents: 5693
diff changeset
57 member_roles = { "myteam" };
459cb2c2789b mod_muc_members_json: Support private MUCs, non-member affiliation grants, async storage, dry-run mode
Matthew Wild <mwild1@gmail.com>
parents: 5693
diff changeset
58
5692
aa94d5bb6b10 mod_muc_members_json: Expand example config and docs for clarity
Matthew Wild <mwild1@gmail.com>
parents: 5655
diff changeset
59 -- The optional field 'member_hat' defines a hat that will be
aa94d5bb6b10 mod_muc_members_json: Expand example config and docs for clarity
Matthew Wild <mwild1@gmail.com>
parents: 5655
diff changeset
60 -- added to any user that is listed in the members JSON
aa94d5bb6b10 mod_muc_members_json: Expand example config and docs for clarity
Matthew Wild <mwild1@gmail.com>
parents: 5655
diff changeset
61 -- (regardless of what roles they have, if any)
5586
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
62 member_hat = {
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63 id = "urn:uuid:6a1b143a-1c5c-11ee-80aa-4ff1ce4867dc";
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
64 title = "Cool Member";
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
65 };
5692
aa94d5bb6b10 mod_muc_members_json: Expand example config and docs for clarity
Matthew Wild <mwild1@gmail.com>
parents: 5655
diff changeset
66 -- The optional field 'team_hats' defines one or more hats
aa94d5bb6b10 mod_muc_members_json: Expand example config and docs for clarity
Matthew Wild <mwild1@gmail.com>
parents: 5655
diff changeset
67 -- that will be assigned to users that have the specified
aa94d5bb6b10 mod_muc_members_json: Expand example config and docs for clarity
Matthew Wild <mwild1@gmail.com>
parents: 5655
diff changeset
68 -- roles in the JSON.
aa94d5bb6b10 mod_muc_members_json: Expand example config and docs for clarity
Matthew Wild <mwild1@gmail.com>
parents: 5655
diff changeset
69 team_hats = {
aa94d5bb6b10 mod_muc_members_json: Expand example config and docs for clarity
Matthew Wild <mwild1@gmail.com>
parents: 5655
diff changeset
70 janitor = {
aa94d5bb6b10 mod_muc_members_json: Expand example config and docs for clarity
Matthew Wild <mwild1@gmail.com>
parents: 5655
diff changeset
71 id = "urn:uuid:ec32f550-7d5f-11ee-81ee-6b139cac3bf6";
aa94d5bb6b10 mod_muc_members_json: Expand example config and docs for clarity
Matthew Wild <mwild1@gmail.com>
parents: 5655
diff changeset
72 title = "Janitor";
aa94d5bb6b10 mod_muc_members_json: Expand example config and docs for clarity
Matthew Wild <mwild1@gmail.com>
parents: 5655
diff changeset
73 }
aa94d5bb6b10 mod_muc_members_json: Expand example config and docs for clarity
Matthew Wild <mwild1@gmail.com>
parents: 5655
diff changeset
74 }
5586
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
75 };
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
76 }
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
77 ```
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
78
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
79 JSON format
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
80 ===========
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
81
5655
1cae6133e315 mod_muc_members_json: Demonstrate support for more than one JID per list
Kim Alvefur <zash@zash.se>
parents: 5654
diff changeset
82 ``` json
5586
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
83 {
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
84 "members": [
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
85 {
5655
1cae6133e315 mod_muc_members_json: Demonstrate support for more than one JID per list
Kim Alvefur <zash@zash.se>
parents: 5654
diff changeset
86 "jids": [
1cae6133e315 mod_muc_members_json: Demonstrate support for more than one JID per list
Kim Alvefur <zash@zash.se>
parents: 5654
diff changeset
87 "user@example.com",
1cae6133e315 mod_muc_members_json: Demonstrate support for more than one JID per list
Kim Alvefur <zash@zash.se>
parents: 5654
diff changeset
88 "user2@example.com"
1cae6133e315 mod_muc_members_json: Demonstrate support for more than one JID per list
Kim Alvefur <zash@zash.se>
parents: 5654
diff changeset
89 ]
5586
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
90 },
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
91 {
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
92 "jids": ["user3@example.com"],
5654
31e56562f9bd mod_muc_members_json: Fix invalid JSON in README
Kim Alvefur <zash@zash.se>
parents: 5586
diff changeset
93 "roles": ["janitor"]
5586
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
94 }
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
95 ]
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
96 }
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
97 ```
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
98
5692
aa94d5bb6b10 mod_muc_members_json: Expand example config and docs for clarity
Matthew Wild <mwild1@gmail.com>
parents: 5655
diff changeset
99 The JSON format must be an object with a `members` array.
aa94d5bb6b10 mod_muc_members_json: Expand example config and docs for clarity
Matthew Wild <mwild1@gmail.com>
parents: 5655
diff changeset
100
aa94d5bb6b10 mod_muc_members_json: Expand example config and docs for clarity
Matthew Wild <mwild1@gmail.com>
parents: 5655
diff changeset
101 Each member must have a `jids` field, and optionally a `roles` field (both are
aa94d5bb6b10 mod_muc_members_json: Expand example config and docs for clarity
Matthew Wild <mwild1@gmail.com>
parents: 5655
diff changeset
102 arrays of strings).
5586
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
103
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
104 Compatibility
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
105 =============
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
106
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
107 ------- ------------------
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
108 trunk Works
6431
459cb2c2789b mod_muc_members_json: Support private MUCs, non-member affiliation grants, async storage, dry-run mode
Matthew Wild <mwild1@gmail.com>
parents: 5693
diff changeset
109 13.0 Works
5586
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
110 ------- ------------------
30b9f78b5058 mod_muc_members_json: New module to import MUC membership from a JSON URL
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
111