How To Use UpStream With Ninja Forms — Part 2

Part 2 of How To Use UpStream With Ninja Forms. Part 1 covers setup, connecting your form, and field types.

Attaching A Task To A Milestone

You can attach a milestone to a task by setting the milestoneId field of the task. This can be done in multiple ways.

If you have an existing milestone, and you want to attach a new task to it, you can set the milestoneId field just like you would set any other field. For example, you could create a dropdown or multiple choice field with the milestone ID as the value.

You can also use references, which are explained next.

Using References To Set Milestones for Tasks And Other Properties

When you create tasks, milestones, files, and bugs using a form, they are automatically added to the parent project from the UpStream Forms XML. However, this method doesn’t allow you to attach a milestone to a task. In this section, we explain how to use references to do this.

In the following example, we create a project, task, and milestone. Since the task and milestone are under the project in the XML, they will be created within the project.

<upstream-forms-action>
	<form id="522">
		<project action="create" title="[1]" created-by="1">
			<milestone action="create" title="[11]" created-by="1">
			</milestone>
			<task action="create" title="[20]" created-by="1">
			</task>			
		</project>
	</form>
</upstream-forms-action>

The problem with this is that since the *<milestone>*tag and the *<task>*tag go directly beneath the *<project>*tag, there is no way to attach a task to a milestone.

To resolve this problem, we added references. When you create a project, task, milestone, file, or bug, you can provide a reference code, which can be used later in the XML to refer to the created item.

Let’s look at the following rewrite of the code above:

<upstream-forms-action>
	<form id="522">
		<project action="create" title="[1]" created-by="1">
			<milestone action="create" title="[11]" created-by="1" ref="my_milestone">
			</milestone>
			<task action="create" title="[20]" created-by="1">
				<field name="milestoneId" value="{my_milestone.id}"></field>
			</task>			
		</project>
	</form>
</upstream-forms-action>

On line 4, we have added ref=”my_milestone”. When the milestone is created, it is assigned to the reference *my_milestone.*That reference can be used in any future value field in order to reference the properties of my_milestone.

The most common use of references is to link a milestone to a task. In line 7, we use the reference to my_milestone to set the milestoneId for the task.

To use a reference in a value field, you need to enclose it with curly brackets. You can use most (but not all) of the properties below with references. So you can do something like this:

<upstream-forms-action>
	<form id="522">
		<project action="create" title="[1]" created-by="1">
			<milestone action="create" title="[11]" created-by="1" ref="my_milestone">
			</milestone>
			<task action="create" title="[20]" created-by="1">
				<field name="title" value="{my_milestone.title}"></field>
				<field name="milestoneId" value="{my_milestone.id}"></field>
			</task>			
		</project>
	</form>
</upstream-forms-action>

That sets the title of the new task to the same title as the milestone, and attaches the task to the milestone.

Using Ninja Forms To Edit Existing Projects/Tasks/Etc.

In addition to creating projects, milestones, tasks, bugs, and files with forms, you can also make edits.

To do this, you will need to create an XML that tells UpStream Forms what to edit based on ID. For example, here’s how to set the title of a task that already exists:

The first thing you will need to do is find the IDs of the task and the parent project. You can find project IDs in the list in your WordPress dashboard -> Projects.

Finding a project ID for use in an UpStream Forms XML file

You can then find the IDs for tasks, milestones, files, and bugs next to the titles in edit project:

Finding the ID of a milestone, task, bug, or file in UpStream

Once you have all of the IDs, you can create the XML:

<upstream-forms-action>
	<form id="603">
		<project action="edit" id="600">
			<task action="edit" id="15dfd288c37033">
				<field name="title" value="[1]"></field>		
			</task>		
		</project>
	</form>
</upstream-forms-action>

In the example above, when the Ninja Forms form with ID 603 is submitted, UpStream Forms will find the project with ID 600, and then its child task with ID 15dfd288c37033. It will then set the title of that task to whatever the form submitter entered in field #1.

Note the differences between this XML and the ones above. On lines 3 and 4, instead of using *action=”create”,*we use action=”edit”. We also provide the id instead of a title. When you use the *action=”edit”*command, you must provide an id. Also, notice that the created-byattribute is no included in this XML (it is only used when creating new items).

List Of UpStream Object Properties

Project Fields

Task Fields

Milestone Fields

File Fields

Bug Fields

Using Custom Fields With Forms

To use UpStream custom fields with Ninja Forms, you will need to supply the slug for each field as the field name in the XML. You can find the slug in the custom fields list under Projects -> Custom Fields in your WordPress admin dashboard.

Use the slug for a custom field as its field name in your XML

Dropdowns

For dropdown or checkbox custom fields, you must enter the value in your Ninja Forms field, as opposed to the label. You can see the correct field in the image below.

When using a custom field, make note of the value

The value in the red box in the picture above must exactly match the value in the red box in the picture below:

In a checkbox, enter the name in the top box and the value that you set in UpStream in the second box

Note that you can set the label and value to the same thing when you create your dropdown Custom Field to help with setup.

User Fields

User custom fields work a lot like assignedToabove, but you can only use user IDs — not emails or user logins. If you choose allow multiselect within UpStream Custom Fields, this Ninja Forms field should be a checkbox or multiselect. Otherwise, it can be a dropdown or radio.

This field only accepts numerical user IDs, which you can find in WordPress. Here’s an example of the corresponding XML:

<upstream-forms-action>
	<form id="1054">
		<project action="create" title="p1" created-by="1">
			<task action="create" title="t1" created-by="1">
				<field name="user-check" value="[2]"></field>
			</task>			
		</project>		
	</form>
</upstream-forms-action>

Country Fields

The built in country field in Ninja Forms is NOTcompatible with UpStream.

To create a country field, you will need to create a multiselect or select with the 3 letter country code as the value for the form — not the country name. You can find the 3 letter country code here.

Here’s an example of the XML that you would use with the form above.

<upstream-forms-action>
	<form id="1054">
		<project action="create" title="p1" created-by="1">
			<task action="create" title="t1" created-by="1">
				<field name="country-check" value="[1]"></field>
			</task>			
		</project>		
	</form>
</upstream-forms-action>