Motions - OpenSlides/OpenSlides GitHub Wiki

The important parts of a motion are the title, text, amendment_paragraphs and reason. These fields hold the important content. All other fields are mostly for managing motions. All special fields described below are always bounded to the meeting, e.g. if something must be unique, it is unique within the meeting.

The title is a required field, but users will sort and relate to motions via their number, which is not an integer value, but a string (be careful there!). A number might be B 002. Numbers must be unique, but multiple empty numbers are allowed. To easily do automatic numbering, the actual integer value of the number is saved as number_value and only modifiable by the backend.

There is a sequence_number which just increases for each motion on creation and is like a counter for every motion per meeting. It cannot be changed.

The modified_final_version field can just be written by the client and has no special meaning to the server code. It contains the finished HTML of all merged change recommendations and amendments (more below).

The relations lead_motion_id and statute_paragraph_id define the type of a motion:

• Nothing set: A normal motion. Also named lead motion since they may have amendments.
• lead_motion_id is set. This motion is an amendment to the lead motion. The text/amendment_paragraphs describe changes to the lead motion.
• statute_paragraph_id is set. This motion is a statute amendment. The text describes changes to the statute paragraph.
• Both set: This is not possible at the moment.

It is allowed to create amendments of amendments and statute amendments if meeting/motions_amendments_of_amendments is true.

When creating an amendment, either text or amendment_paragraphs has to be given. This is determinated by meeting/motions_amendments_text_mode, but only for the client. The backend must accept both formats, regardless of meeting/motions_amendments_text_mode.

The text mode describes the way an amendment amends the text of the lead motion. If the field text is set, it is an alternate text, e.g. with some changes. If amendment_paragraphs is set, the given paragraphs are amended. All other paragraphs are still original. The complete diff and line-number algorithms are done in the client. The backend does not have to care about text diffing and text relations between motions.

Motions are organized within many structures. First, motions are sorted in a tree, named calllist. The tree is given via the field motion/sort_weight and relation motion/sort_parent_id (See Models#models-ordered-in-trees; here, no level field exists). This sorting is only changed by the user (motion.sort).

Motions can be assigned to one motion block (block for short). The relation is motion/block_id. Motions are not sorted within a block.

A motion can be assigned to one motion category (category for short). The relation is motion/category_id. The motions within a category are sorted in a list via the field motion/category_weight (motion_category.sort_motions_in_category)

Categories itself have a name and an optional prefix and are sorted in a tree-like fashion (motion_category.sort, Models#models-ordered-in-trees). The fields determining the tree are category/weight and the relation category/parent_id.

Workflows are used to manage different states of motions, so each workflow has many states. A motion is in exactly one workflow given by the motion's state (motion/state_id -> state/workflow_id). The workflow is set during creation or an update.

The states of one workflow build a graph: Each state has zero to many next states (state/next_state_ids), which must be from the same workflow. There is one first state, saved with the relation workflow/first_state_id in the workflow. A motion can change its state within all states of the workflow, but only go one step in the graph of states. This means setting the state can only be done to a next state or a previous state. A previous state is a state that has the current state as a next state. Also resetting the state to the first state is always possible.

States hold some information on how to handle motions:

• recommendation_label: If this field is set, the state can be used as an recommendation
• restrictions: This field holds a list of restrictions. These restrict who can see a motion (See motion-restrictions). There are 4 available restrictions:
  • motions.can_see_internal
  • motions.can_manage_metadata
  • motions.can_manage
  • is_submitter
• allow_support: If it is true, users can support a motion. This affects motion.set_support and motion.update.
• allow_create_poll: If it is true, a poll can be created for the motion. Affects only poll.create.
• allow_submitter_edit: If this is true, every change to a motion is forbidden, if the user has no manage perms. Users without manage perms can edit the motion, if they are submitters. This can be disallowed with this field. This is checked by the permission service.
• set_number: If this is true, the motion number is autogenerated if the motion changes its state into a state with set_number==True.
• show_state_extension_field and show_recommendation_extension_field: If one is true, the state allows for extra information to be saved per motion in motion/state_extension and motion/recommendation_extension. This is for the client: The extensions are shown behind the stateto give users additional information about the state.

A motion can have a recommendation, which is a recommendation for the next state in workflow to go. The system is activated, if meeting/motions_recommendations_by (for motions and amendments) and meeting/motions_statute_recommendations_by (for statute amendments) are not empty. This is only checked by the client.

A recommendation is also a state of the same workflow as the motions state, which is used to point to the favorable next state. Only states with the field recommendation_label set to a non-empty value can be used as recommendations. A recommendation can be set (motion.set_recommendation) to a recommendable state or reset to no state at all (motion.reset_recommendation). If a motion has a recommendation, it can be followed (motion.follow_recommendation), so the motions state is set to the recommendation. If the new state (the recommendation) has show_state_extension_field and show_recommendation_extension_field and an actual extension in motion/recommendation_extension, this value is copied into motion/state_extension.

The fields motion/state_extension and motion/recommendation_extension ("extension fields") are free-text fields where a user can give an extension to the recommendation. It is possible to link other models via fqids in the text. In the client, each [<fqid>] is replaced by the title for the linked model. To query the models via the autoupdate service, there must exist relations for them. The server extracts every fqid from the extension fields and sets them in {state|recommendation}_extension_reference_ids. This field can be queried by the client to receive all models needed to interpolate the extension fields.

On create, set state, reset state the number may be automatically set. The procedure to do so is described here for motion.create and here for motion.set_state. Note that motion.reset_state and motion.follow_recommendation are only special cases of motion.set_state, so the same logic applies there.

There is a special action, motion_category.number_motions, to autogenerate motion numbers for all motions in the category and every subcategory. Here is the description of how it works.