decidim 0.31.5 → 0.32.0.rc2

data/docs/modules/develop/pages/api/reference/components/debates/create.adoc

@@ -0,0 +1,58 @@
+= Create Debate
+== Input attributes
+
+When you want to add or create data in your debates component, you need to rely on the `DebateAttributes` type, which has the following input fields:
+
+[source]
+----
+• title                 (required) - String
+• description           (required) - String
+• taxonomies            (optional) - Taxonomy ids to assign to this debate
+----
+
+== Sample request
+
+The `CreateDebate` mutation allows authenticated users to create new debates in a Decidim debates component. This mutation uses the existing `CreateDebate` command from the controller.
+
+[source,graphql]
+----
+mutation createDebate($componentId: ID!, $input: CreateDebateInput!){
+  component(id: $componentId) {
+    ...on DebatesMutation{
+      createDebate(input: $input) {
+        id
+        title { translation(locale: "en") }
+        description { translation(locale: "en") }
+        taxonomies {
+          name { translation(locale: "en") }
+        }
+      }
+    }
+  }
+}
+----
+
+Example of submitted variables
+
+[source,json]
+----
+{
+  "componentId": 5,
+  "input": {
+    "locale": "en",
+    "attributes": {
+      "description": "Cities need more people, not more cars",
+      "taxonomies": [11],
+      "title": "More sidewalks and less roads"
+    }
+  }
+}
+----
+
+== Error Handling
+
+The most frequent errors that can be generated by this mutation are as follows:
+
+* xref:develop:api/reference/errors/unauthorized_mutation.adoc[Unauthorized Mutation Error - MUTATION_NOT_AUTHORIZED_ERROR]
+* xref:develop:api/reference/errors/attribute_validation_error.adoc[Attribute Validation Error - ATTRIBUTE_VALIDATION_ERROR]
+* xref:develop:api/reference/errors/unauthorized_object.adoc[Unauthorized Object Error - UNAUTHORIZED_OBJECT_ERROR]

data/docs/modules/develop/pages/api/reference/components/debates/update.adoc

@@ -0,0 +1,63 @@
+= Update Debate
+
+== Input attributes
+
+When you want to update data in your debates component, you need to rely on the `DebateAttributes` type, which has the following input fields:
+
+[source]
+----
+• title                 (required) - String
+• description           (required) - String
+• taxonomies            (optional) - Taxonomy ids to assign to this debate
+----
+
+== Sample request
+
+The `UpdateDebate` mutation allows authenticated users to update debates in a Decidim debates component. This mutation uses the existing `UpdateDebate` command from the controller.
+
+[source,graphql]
+----
+mutation updateDebate($componentId: ID!,$debateId: ID!, $input: UpdateDebateInput!){
+  component(id: $componentId) {
+    ...on DebatesMutation{
+      debate(id: $debateId){
+        update(input: $input) {
+          id
+          title { translation(locale: "en") }
+          description { translation(locale: "en") }
+          taxonomies {
+            name { translation(locale: "en") }
+          }
+        }
+      }
+    }
+  }
+}
+----
+
+Example of submitted variables
+
+[source,json]
+----
+{
+  "componentId": "5",
+  "debateId": "9",
+  "input": {
+    "locale": "en",
+    "attributes": {
+      "description": "Cities need more people, not more cars",
+      "taxonomies": [11],
+      "title": "More sidewalks and less roads"
+    }
+  }
+}
+----
+
+== Error Handling
+
+The most frequent errors that can be generated by this mutation are as follows:
+
+* xref:develop:api/reference/errors/unauthorized_mutation.adoc[Unauthorized Mutation Error - MUTATION_NOT_AUTHORIZED_ERROR]
+* xref:develop:api/reference/errors/attribute_validation_error.adoc[Attribute Validation Error - ATTRIBUTE_VALIDATION_ERROR]
+* xref:develop:api/reference/errors/unauthorized_object.adoc[Unauthorized Object Error - UNAUTHORIZED_OBJECT_ERROR]
+

data/docs/modules/develop/pages/api/reference/components/debates.adoc

@@ -0,0 +1,9 @@
+= Debates
+
+In the debates module we are providing a few mutations that we find useful for day-to-day management of Decidim instance outside the admin.
+
+== For user/participants roles
+
+* xref:develop:api/reference/components/debates/create.adoc[Create Debate]
+* xref:develop:api/reference/components/debates/update.adoc[Update Debate]
+* xref:develop:api/reference/components/debates/close.adoc[Close Debate]

data/docs/modules/develop/pages/api/reference/components/meetings/close.adoc

@@ -0,0 +1,48 @@
+= Close Meeting
+
+To use the API to close any meeting that the user is authorized to close, you will need to use the following API request.
+
+[source,graphql]
+----
+mutation closeMeeting($componentId: ID!, $meetingId: ID!, $input: CloseMeetingInput!){
+  component(id: $componentId) {
+    ...on MeetingsMutation{
+      meeting(id: $meetingId) {
+        close(input: $input) {
+          id
+          closed
+          attendeesCount
+          closingReport { translation(locale: "en") }
+          closedAt
+        }
+      }
+    }
+  }
+}
+----
+
+Example of submitted variables
+
+[source,json]
+----
+{
+  "componentId": "9",
+  "meetingId": "2",
+  "input": {
+    "locale": "en",
+    "attributes": {
+      "closingReport": "Your closing report",
+      "attendeesCount": 12,
+      "proposalIds": ["1","2","3"]
+    }
+  }
+}
+----
+
+== Error Handling
+
+The most frequent errors that can be generated by this mutation are as follows:
+
+* xref:develop:api/reference/errors/unauthorized_mutation.adoc[Unauthorized Mutation Error - MUTATION_NOT_AUTHORIZED_ERROR]
+* xref:develop:api/reference/errors/attribute_validation_error.adoc[Attribute Validation Error - ATTRIBUTE_VALIDATION_ERROR]
+* xref:develop:api/reference/errors/unauthorized_object.adoc[Unauthorized Object Error - UNAUTHORIZED_OBJECT_ERROR]

data/docs/modules/develop/pages/api/reference/components/meetings/create.adoc

@@ -0,0 +1,108 @@
+= Create Meeting
+
+== Input attributes
+
+When you want to add or create data in your meetings component, you need to rely on the `MeetingAttributes` type, which has the following input fields:
+
+[source]
+----
+• address               (optional) - String
+• available_slots       (optional) - Int
+• title                 (required) - String
+• description           (required) - String
+• end_time              (required) - DateTime
+• latitude              (optional) - coordinate
+• longitude             (optional) - coordinate
+• location_hints        (optional) - String
+• location              (optional) - String
+• online_meeting_url    (optional) - String
+• registration_terms    (optional) - String
+• registration_type     (required) - RegistrationTypeType
+• registration_url      (optional) - String
+• registrations_enabled (optional) - Boolean
+• start_time            (required) - DateTime
+• taxonomies            (optional) - Taxonomy ids to assign to this meeting
+• type_of_meeting       (required) - TypeOfMeeting
+----
+
+You may want to check the following input types:
+
+* http://nightly.decidim.org/api/docs/enum/typeofmeetingenum/[TypeOfMeetingEnum]
+* http://nightly.decidim.org/api/docs/enum/registrationtypeenum/[RegistrationTypeEnum]
+* http://nightly.decidim.org/api/docs/enum/iframeembedtypeenum/[IframeEmbedTypeEnum]
+* http://nightly.decidim.org/api/docs/enum/iframeaccesslevelenum/[IframeAccessLevelEnum]
+
+== Sample request
+
+The `CreateMeeting` mutation allows authenticated users to create new meetings in a Decidim meetings component. This mutation uses the existing `CreateMeeting` command from the controller.
+
+[source,graphql]
+----
+mutation createMeeting($componentId: ID!, $input: CreateMeetingInput!){
+  component(id: $componentId) {
+    ...on MeetingsMutation{
+      createMeeting(input: $input) {
+        id
+        title {
+          translation(locale: "en")
+        }
+        description {
+          translation(locale: "en")
+        }
+        address
+        taxonomies{
+          name {
+            translation(locale: "en")
+          }
+          children{
+            name{
+              translation(locale: "en")
+            }
+          }
+        }
+      }
+    }
+  }
+}
+----
+
+Example of submitted variables
+
+[source,json]
+----
+{
+  "componentId": 670,
+  "input": {
+    "locale": "en",
+    "attributes": {
+      "address": "Carrer de la Pau, 1, Barcelona",
+      "availableSlots": 10,
+      "description": "Cities need more people, not more cars",
+      "endTime": "2025-12-24T22:10:22Z",
+      "iframeAccessLevel": "ALL",
+      "iframeEmbedType": "NONE",
+      "latitude": 40.1234,
+      "location": "Somewhere",
+      "locationHints": "Near the main square",
+      "longitude": 2.1234,
+      "onlineMeetingUrl": "https://meets.example.org/abc-def",
+      "registrationTerms": "By registering you agree to the terms and conditions",
+      "registrationType": "ON_THIS_PLATFORM",
+      "registrationUrl": "https://example.org/register",
+      "registrationsEnabled": true,
+      "startTime": "2025-12-24T20:10:22Z",
+      "taxonomies": [1072],
+      "title": "More sidewalks and less roads",
+      "typeOfMeeting": "ONLINE"
+    }
+  }
+}
+----
+
+== Error Handling
+
+The most frequent errors that can be generated by this mutation are as follows:
+
+* xref:develop:api/reference/errors/unauthorized_mutation.adoc[Unauthorized Mutation Error - MUTATION_NOT_AUTHORIZED_ERROR]
+* xref:develop:api/reference/errors/attribute_validation_error.adoc[Attribute Validation Error - ATTRIBUTE_VALIDATION_ERROR]
+* xref:develop:api/reference/errors/unauthorized_object.adoc[Unauthorized Object Error - UNAUTHORIZED_OBJECT_ERROR]

data/docs/modules/develop/pages/api/reference/components/meetings/update.adoc

@@ -0,0 +1,95 @@
+= Update Meeting
+
+== Input attributes
+
+When you want to update your meetings component, you need to rely on the `MeetingAttributes` type, which has the following input fields:
+
+[source]
+----
+• address               (optional) - String
+• available_slots       (optional) - Int
+• description           (required) - String
+• end_time              (required) - DateTime
+• latitude              (optional) - coordinate
+• longitude             (optional) - coordinate
+• location_hints        (optional) - String
+• location              (optional) - String
+• online_meeting_url    (optional) - String
+• registration_terms    (optional) - String
+• registration_type     (required) - RegistrationTypeType
+• registration_url      (optional) - String
+• registrations_enabled (optional) - Boolean
+• start_time            (required) - DateTime
+• taxonomies            (optional) - Taxonomy ids to assign to this meeting
+• title                 (required) - String
+• type_of_meeting       (required) - TypeOfMeeting
+----
+
+You may want to check the following input types:
+
+* http://nightly.decidim.org/api/docs/enum/typeofmeetingenum/[TypeOfMeetingEnum]
+* http://nightly.decidim.org/api/docs/enum/registrationtypeenum/[RegistrationTypeEnum]
+* http://nightly.decidim.org/api/docs/enum/iframeembedtypeenum/[IframeEmbedTypeEnum]
+* http://nightly.decidim.org/api/docs/enum/iframeaccesslevelenum/[IframeAccessLevelEnum]
+
+== Sample request
+
+The `UpdateMeeting` mutation allows authenticated users to update meetings in a Decidim meetings component. This mutation uses the existing `UpdateMeeting` command from the controller.
+
+[source,graphql]
+----
+mutation updateMeeting($componentId: ID!, $meetingId: ID!, $input: UpdateMeetingInput!){
+  component(id: $componentId) {
+    ...on MeetingsMutation{
+      meeting(id: $meetingId) {
+        update(input: $input) {
+          id
+          title { translation(locale: "en") }
+        }
+      }
+    }
+  }
+}
+----
+
+Example of submitted variables
+
+[source,json]
+----
+{
+  "componentId": 670,
+  "meetingId": "2",
+  "input": {
+    "locale": "en",
+    "attributes": {
+      "address": "Carrer de la Pau, 1, Barcelona",
+      "availableSlots": 10,
+      "description": "Cities need more people, not more cars",
+      "endTime": "2025-12-24T22:10:22Z",
+      "iframeAccessLevel": "ALL",
+      "iframeEmbedType": "NONE",
+      "latitude": 40.1234,
+      "location": "Somewhere",
+      "locationHints": "Near the main square",
+      "longitude": 2.1234,
+      "onlineMeetingUrl": "https://meets.example.org/abc-def",
+      "registrationTerms": "By registering you agree to the terms and conditions",
+      "registrationType": "ON_THIS_PLATFORM",
+      "registrationUrl": "https://example.org/register",
+      "registrationsEnabled": true,
+      "startTime": "2025-12-24T20:10:22Z",
+      "taxonomies": [1072],
+      "title": "More sidewalks and less roads",
+      "typeOfMeeting": "ONLINE"
+    }
+  }
+}
+----
+
+== Error Handling
+
+The most frequent errors that can be generated by this mutation are as follows:
+
+* xref:develop:api/reference/errors/unauthorized_mutation.adoc[Unauthorized Mutation Error - MUTATION_NOT_AUTHORIZED_ERROR]
+* xref:develop:api/reference/errors/attribute_validation_error.adoc[Attribute Validation Error - ATTRIBUTE_VALIDATION_ERROR]
+* xref:develop:api/reference/errors/unauthorized_object.adoc[Unauthorized Object Error - UNAUTHORIZED_OBJECT_ERROR]

data/docs/modules/develop/pages/api/reference/components/meetings/withdraw.adoc

@@ -0,0 +1,36 @@
+= Withdraw Meeting
+
+To use the API to withdraw any meeting that the user has created, you will need to use the following API request.
+
+[source,graphql]
+----
+mutation withdrawMeeting($componentId: ID!, $meetingId: ID!){
+  component(id: $componentId) {
+    ...on MeetingsMutation{
+      meeting(id: $meetingId) {
+        withdraw(input: {}) {
+          id
+        }
+      }
+    }
+  }
+}
+----
+
+Example of submitted variables
+
+[source,json]
+----
+{
+  "componentId": "9",
+  "meetingId": "2"
+}
+----
+
+== Error Handling
+
+The most frequent errors that can be generated by this mutation are as follows:
+
+* xref:develop:api/reference/errors/unauthorized_mutation.adoc[Unauthorized Mutation Error - MUTATION_NOT_AUTHORIZED_ERROR]
+* xref:develop:api/reference/errors/validation_error.adoc[Validation Error - VALIDATION_ERROR]
+* xref:develop:api/reference/errors/unauthorized_object.adoc[Unauthorized Object Error - UNAUTHORIZED_OBJECT_ERROR]

data/docs/modules/develop/pages/api/reference/components/meetings.adoc

@@ -0,0 +1,10 @@
+= Meetings
+
+In the meetings module we are providing a few mutations that we find useful for day-to-day management of Decidim instance outside the admin.
+
+== For user/participants roles
+
+* xref:develop:api/reference/components/meetings/create.adoc[Create Meeting]
+* xref:develop:api/reference/components/meetings/update.adoc[Update Meeting]
+* xref:develop:api/reference/components/meetings/withdraw.adoc[Withdraw Meeting]
+* xref:develop:api/reference/components/meetings/close.adoc[Close Meeting]

data/docs/modules/develop/pages/api/reference/components/proposals/answer.adoc

@@ -0,0 +1,82 @@
+= Answer Proposal
+
+Allows administrators to answer proposals with a status (accepted, rejected, or evaluating).
+
+This is an example on how to use the `addProposalAnswer` mutation. Please refer to the GraphQL documentation for the available fields:
+
+
+- https://nightly.decidim.org/api/docs/input_object/answerinput/[Answer Input]
+- https://nightly.decidim.org/api/docs/input_object/proposalattributes[Proposal Attributes]
+- https://nightly.decidim.org/api/docs/object/proposal[Proposal Type]
+
+```graphql
+mutation addProposalAnswer($componentId: ID!, $proposalId: ID!, $input: AnswerInput!){
+  component(id: $componentId) {
+    ...on ProposalsMutation{
+      proposal(id: $proposalId) {
+        answer(input: $input) {
+          // this is the proposal response
+        }
+      }
+    }
+  }
+}
+```
+
+Example of submitted variables
+```graphql
+{
+  "componentId": 9,
+  "proposalId": 2,
+  "input": {
+    "clientMutationId": "unique-client-id-123",
+    "attributes": {
+      "state": "accepted",
+      "cost": 10.0,
+      "answerContent": {
+         "en": "Some answer in English",
+         "ca": "Some answer in Catalan"
+      }
+    }
+  }
+}
+```
+
+=== HTTP Request Example
+
+Using cURL to make the GraphQL request:
+
+```bash
+curl -X POST https://your-decidim-instance.org/api \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_API_TOKEN" \
+  -d '{
+    "query": "mutation addProposalAnswer($componentId: ID!, $proposalId: ID!, $input: AnswerInput!){ component(id: $componentId) { ...on ProposalsMutation{ proposal(id: $proposalId) { answer(input: $input) { /* this is the proposal response */  } } } } }",
+    "variables": {
+      "input": {
+        "componentId": 9,
+        "proposalId": 2,
+        "input": {
+          "clientMutationId": "unique-client-id-123",
+            "attributes": {
+            "state": "accepted",
+            "cost": 10.0,
+            "answerContent": {
+              "en": "Some answer in English",
+              "ca": "Some answer in Catalan"
+            }
+          }
+        }
+      }
+    }
+  }'
+```
+
+=== Error Handling
+
+The most frequent errors that can be generated by this mutation are as follows:
+
+* xref:develop:api/reference/errors/unauthorized_mutation.adoc[Unauthorized Mutation Error - MUTATION_NOT_AUTHORIZED_ERROR]
+* xref:develop:api/reference/errors/unauthorized_object.adoc[Unauthorized Object Error - UNAUTHORIZED_OBJECT_ERROR]
+* xref:develop:api/reference/errors/not_found.adoc[Not Found Error - NOT_FOUND_ERROR]
+* xref:develop:api/reference/errors/attribute_validation_error.adoc[Attribute Validation Error - ATTRIBUTE_VALIDATION_ERROR]

data/docs/modules/develop/pages/api/reference/components/proposals/create.adoc

@@ -0,0 +1,78 @@
+= Create Proposal
+
+== Input attributes
+
+When you want to add or create data in your proposals component, you need to rely on the `ProposalAttributes` type, which has the following input fields:
+
+[source]
+----
+• title       (required) - 15-150 characters
+• body        (required) - minimum 15 characters
+• address     (optional) - physical address (requires geocoding)
+• latitude    (optional) - coordinate
+• longitude   (optional) - coordinate
+• taxonomies  (optional) - Taxonomies ids to assign to this proposal
+----
+
+== Sample request
+
+The `CreateProposal` mutation allows authenticated users to create new proposals in a Decidim proposals component. This mutation delegates to the existing `Decidim::Proposals::CreateProposal` command used by the controllers.
+
+[source,graphql]
+----
+mutation createProposal($componentId: ID!, $input: CreateProposalInput!){
+  component(id: $componentId) {
+    ...on ProposalsMutation{
+      createProposal(input: $input) {
+        id
+        title {
+          translation(locale: "en")
+        }
+        body {
+          translation(locale: "en")
+        }
+        address
+        taxonomies{
+          name {
+            translation(locale: "en")
+          }
+          children{
+            name{
+              translation(locale: "en")
+            }
+          }
+        }
+      }
+    }
+  }
+}
+----
+
+Example of submitted variables
+
+[source,json]
+----
+{
+  "componentId": 9,
+  "input": {
+    "locale": "en",
+    "attributes": {
+      "title": "Install Bike Lanes on Main Street",
+      "body": "We propose adding dedicated bike lanes along Main Street to improve cyclist safety and encourage sustainable transportation.",
+      "address": "Main Street, Barcelona, Spain",
+      "latitude": 41.3851,
+      "longitude": 2.1734
+    }
+  }
+}
+----
+
+== Error Handling
+
+The most frequent errors that can be generated by this mutation are as follows:
+
+* xref:develop:api/reference/errors/unauthorized_mutation.adoc[Unauthorized Mutation Error - MUTATION_NOT_AUTHORIZED_ERROR]
+* xref:develop:api/reference/errors/invalid_locale_error.adoc[Invalid Locale Error - INVALID_LOCALE_ERROR]
+* xref:develop:api/reference/errors/validation_error.adoc[Validation Error - VALIDATION_ERROR]
+* xref:develop:api/reference/errors/attribute_validation_error.adoc[Attribute Validation Error - ATTRIBUTE_VALIDATION_ERROR]
+* xref:develop:api/reference/errors/unauthorized_object.adoc[Unauthorized Object Error - UNAUTHORIZED_OBJECT_ERROR]

data/docs/modules/develop/pages/api/reference/components/proposals/update.adoc

@@ -0,0 +1,66 @@
+= Update Proposal
+
+== Input attributes
+
+When you want to update data in your proposals component, you need to rely on the `ProposalAttributes` type, which has the following input fields:
+
+```
+• title       (required) - 15-150 characters
+• body        (required) - minimum 15 characters
+• address     (optional) - physical address (requires geocoding)
+• latitude    (optional) - coordinate
+• longitude   (optional) - coordinate
+• taxonomies  (optional) - Taxonomies ids to assign to this proposal
+```
+
+== Sample request
+
+The `UpdateProposal` mutation allows authenticated users to update proposals in a Decidim component. This mutation delegates to the existing `Decidim::Proposals::UpdateProposal` command.
+
+[source,graphql]
+----
+mutation updateProposal($componentId: ID!,$proposalId: ID!, $input: UpdateProposalInput!){
+  component(id: $componentId) {
+    ...on ProposalsMutation{
+      proposal(id: $proposalId) {
+        update(input: $input) {
+          id
+          title { translation(locale: "en") }
+          body { translation(locale: "en") }
+        }
+      }
+    }
+  }
+}
+----
+
+Example of submitted variables
+
+[source,json]
+----
+{
+  "componentId": 9,
+  "proposalId": "140",
+  "input": {
+    "locale": "en",
+    "attributes": {
+      "title": "Install Bike Lanes on Main Street",
+      "body": "We propose adding dedicated bike lanes along Main Street to improve cyclist safety and encourage sustainable transportation.",
+      "address": "Main Street, Barcelona, Spain",
+      "latitude": 41.3851,
+      "longitude": 2.1734,
+      "taxonomies": [123, 456]
+    }
+  }
+}
+----
+
+== Error Handling
+
+The most frequent errors that can be generated by this mutation are as follows:
+
+* xref:develop:api/reference/errors/unauthorized_mutation.adoc[Unauthorized Mutation Error - MUTATION_NOT_AUTHORIZED_ERROR]
+* xref:develop:api/reference/errors/invalid_locale_error.adoc[Invalid Locale Error - INVALID_LOCALE_ERROR]
+* xref:develop:api/reference/errors/validation_error.adoc[Validation Error - VALIDATION_ERROR]
+* xref:develop:api/reference/errors/attribute_validation_error.adoc[Attribute Validation Error - ATTRIBUTE_VALIDATION_ERROR]
+* xref:develop:api/reference/errors/unauthorized_object.adoc[Unauthorized Object Error - UNAUTHORIZED_OBJECT_ERROR]