Needs

Note

Needs are available in version 2.x and higher.

The <needs> element lists all the necessary elements that will need to be executed first before the current element executes.

The following elements can contain a needs element:

Element	Description
watch	The needs list for a watch is a list of other watches that will need to be executed first. For more information, see Watch.
step	The needs list for a step is a list of other steps, in the same workflow, that will need to executed first. For more information, see Steps.

Structure

<needs>
    <need></need>
</needs>

Each need child element contains the <id> for the element that needs to be completed before this element can run.

The <id> element is optional for a <watch> element, but is required if is a need for another watch.

Examples

The first example has the following config file defined:

<watches>
    <watch>
        <path>C:\Temp\photos</path>
        <id>move-backup-photos-watch</id>
        <exclusions>                    
            <attributes>
                <attribute>System</attribute>
            </attributes>            
        </exclusions>
        <actions>
            <action>
                <triggers>
                    <trigger>Create</trigger>
                </triggers>              
                <type>Move</type>
                <source>[exactpath]</source>
                <destination>F:\Pictures\[fullpath]</destination>
                <verify>true</verify>
            </action>
        </actions> 
    </watch>
    <watch>
        <path>F:\Pictures</path>
        <id>create-photos-watch</id>     
        <needs>
            <need>move-backup-photos-watch</need>
        </needs>
        <workflows>
            <workflow>
                <triggers>
                    <trigger>Create</trigger>
                </triggers>
                <steps>
                    <step>
                        <id>create-picture-get-checksum</id>
                        <command>          
                            <path>C:\Tools\fv\fv.exe</path>                 
                            <arguments>-f "[exactpath]" -sf C:\Tools\fv\config.xml</arguments>
                        </command>
                    </step>
                </steps>
            </workflow>
        </workflows>
    </watch>
</watches>

In the above config, there are two watches defined: move-backup-photos-watch and create-photos-watch. The create-photos-watch needs the move-backup-photos-watch to run and complete before it can run. Once move-backup-photos-watch completes, the create-photos-watch will then run.

The following will happen with the above config:

1. All files moved to the C:\Temp\photos folder will be moved to the F:\Pictures folder and each file will be verified as per the move-backup-photos-watch watch.
2. Once all files have been moved, the command C:\Tools\fv\fv.exe f "[exactpath]" -sf C:\Tools\fv\config.xml will be run for each file to generate a checksum as per the create-picture-get-checksum step in the workflow in the create-photos-watch watch.

Expanding on the above example is this one:

<watches>
    <watch>
        <path>C:\Temp\photos</path>
        <id>move-backup-photos-watch</id>
        <exclusions>                    
            <attributes>
                <attribute>System</attribute>
            </attributes>            
        </exclusions>
        <actions>
            <action>
                <triggers>
                    <trigger>Create</trigger>
                </triggers>              
                <type>Move</type>
                <source>[exactpath]</source>
                <destination>F:\Pictures\[fullpath]</destination>
                <verify>true</verify>
            </action>
        </actions> 
    </watch>
    <watch>
        <path>F:\Pictures</path>
        <id>create-photos-watch</id>     
        <needs>
            <need>move-backup-photos-watch</need>
        </needs>
        <workflows>
            <workflow>
                <triggers>
                    <trigger>Create</trigger>
                </triggers>
                <steps>
                    <step>
                        <id>create-picture-get-checksum</id>
                        <command>          
                            <path>C:\Tools\fv\fv.exe</path>                 
                            <arguments>-f "[exactpath]" -sf C:\Tools\fv\config.xml</arguments>
                        </command>
                    </step>
                    <step>
                        <id>create-picture-gotify-send-message</id>
                        <needs>
                            <need>create-picture-get-checksum</need>
                        </needs>
                        <notification>
                            <url>[env:gotify_url]/message</url>
                            <method>POST</method>
                            <data>
                                <headers>
                                    <header>
                                        <name>X-Gotify-Key</name>
                                        <value>[env:gotify_key]</value>
                                    </header>
                                </headers>
                                <body>
                                    {
                                        "message": "[message]",
                                        "priority": 7,
                                        "title": "Pictures Folder"
                                    }            
                                </body>
                            </data>
                        </notification>                        
                    </step>
                    <step>
                        <id>create-picture-plex-refresh-library</id>
                        <needs>
                            <need>create-picture-get-checksum</need>
                        </needs>                 
                        <notification>
                            <method>GET</method>
                            <url>[env:plex_url]/library/sections/1/refresh?path=[urlenc:F:\Pictures\[path]]&amp;X-Plex-Token=[env:plex_token]</url>
                        </notification>                    
                    </step>                    
                </steps>
            </workflow>
        </workflows>
    </watch>
</watches>

The same watch dependency exists, but in the above example two additional steps have been added that have a need on the create-picture-get-checksum step in the workflow.

The flow of execution will now look like:

1. All files moved to the C:\Temp\photos folder will be moved to the F:\Pictures folder and each file will be verified as per the move-backup-photos-watch watch.
2. Once all files have been moved, the command C:\Tools\fv\fv.exe f "[exactpath]" -sf C:\Tools\fv\config.xml will be run for each file to generate a checksum as per the create-picture-get-checksum step in the workflow in the create-photos-watch watch.
3. After the create-picture-get-checksum step has completed, the create-picture-gotify-send-message and create-picture-plex-refresh-library steps in the workflow will then run because they have a need for the create-picture-get-checksum step to complete.