Node types and references
Use the Process Specification to combine one or more processes into a process module component. By convention:
- Use ComponentNameComponent for the local reference.
- Use Component name for the name.
For example, a component that calculates results would be called "Calculate results" with a local reference of "CalculateResultsComponent".
Put all the processes and the component in the same folder. Give the folder the same name as the component, but use lower_snake_case for the name of the folder.
Component reference
Leave the Reference field blank, except for components used as process types. Give these a reference in lower_snake_case (this should be the same reference as the containing folder). Where the Reference field is left blank, the component's local reference will be used, i.e. ComponentNameComponent.
Processes and sub-components
Structure components so that they include processes for all the required roles in one component, potentially more than one worker role, group role and control role. Each component should be self-contained as much as practical, within the boundaries of effective modularisation. Where a component has dependencies on other components, it should typically include those other components to ensure that the dependencies are met (except where this component is presented as an optional add-on to another component).
Use more than one level of component if necessary. This may be required where you are parameterising a generic component - you might one level that does not permit overrides where you parameterise the generic component, which you then include in a higher-level component.
Placeholders, options and bindings
Set options and bindings to satisfy all the placeholders in the contained processes.
- For placeholders that should not change, use the "private" object or binding reference prefixed with "private." to ensure that the placeholders are resolved when the component is actioned and cannot be overridden. The placeholders do not need the private prefix - they will automatically pick up private options and bindings when the component is retrieved. Remember that any option that references a private option or binding does itself have to be private, or the placeholder replacement will not work (otherwise the outer placeholder would be evaluated after the inner one has been discarded).
- For other placeholders, set options and bindings to suitable defaults. Only use role prefixes for fundamentally role-specific placeholders, but not for values that need to be referenced across multiple roles, or for which it is clearer to set without a role-specific prefix. It is possible to override a non-specific value with a role-specific value, but not the other way around, so if in doubt use non-specific values.
Form placeholders can be resolved to a form read from a node, using the "${form:bindingReference}" syntax. Provide suitable defaults in the component (not the process, except for step scripts). The form node binding reference needs to be different from the option property name.
Similarly for scripts, using the "${script:bindingReference}" syntax. Do this in the component, not in the process.
You can set an option to another placeholder. You can use the "private" object to promote a role-specific placeholder to something more specific.
For example, you might have a partner process which uses a "${greeting}" placeholder. You can translate this to a partner-specific greeting using:
{
"private": {
"partner": {
"greeting": "${partnerGreeting}"
}
},
"partnerGreeting": "Howdy, partner"
}The partner-specific "${greeting}" placeholder can now be set and overridden using the non-specific "partnerGreeting" option. Setting "greeting" to "${partnerGreeting}" is private, always applied, and not overridable. However, since it evaluated to a non-private, non-specific placeholder, that can now be overridden elsewhere.
Other than where necessary to use generic components, always set the permit overrides option in your component.
Role order
If you have two worker roles, then the owner role will need to send a process to the partner role. This can be achieved using the send step type, referring to the partner role's process definition and status rules.
For this to work, the partner role must be defined before the owner role.
You can do this by ensuring that the partner is the first-named role in the first component in the list.
To force this to happen, you can start the Elements list with an entry for Null, with the roles listed in order, i.e. "partner, owner".