UpStream’s Forms module allows you to connect UpStream to all three major WordPress forms plugins.
Additional articles about UpStream Forms:
In this article we look at how to use UpStream with Ninja Forms.
Getting Started
UpStream Forms is compatible with most recent versions of Ninja Forms. The setup process is the same for each one.
If you want, you can use UpStream Forms with multiple forms plugins at the same time (for example, Ninja Forms and WPForms). We will explain how to do this later.
Once you install Ninja Forms, you can install and activate UpStream Forms.
Preparing Your Ninja Forms Form For UpStream
If you haven’t created a form yet, the first thing you will need to do is to enable Ninja Forms “Dev Mode”. This allows you to see IDs and set other values that you’ll need for UpStream.
To enable “Dev Mode”, go to your WordPress admin dashboard, and then click *Ninja Forms -> Settings.*Then, scroll down and check the box marked “Form Builder ‘Dev Mode’” (marked red in the picture below).
Before using UpStream Forms, you must enable Dev Mode in Ninja Forms
Once you’ve done that you can create a form. In your WordPress admin dashboard, and click on Ninja Forms -> Add New. That will take you to a Wizard, which allows you to add a new form.
Once you have created the form, you will see a page where you can add fields:
The Ninja Forms creation page
On this page, you will add all of the fields that you want to populate into your project. You can click on the blue plus in order to add a field.
Setting Ninja Forms Field IDs
When you add a field, and click on the field, Ninja Forms will show you a properties page. On this properties page, there is an “Administration” section:
To use Ninja Forms with UpStream, you must enter a unique number in as the “Field Key” for each field. This will be the ID you use to refer to the field later.
Under “Administration”, there is a setting titled “Field Key”. This is where you will enter IDs for each field, which you will use with UpStream Forms.
The ID you enter under “Field Key” must be a positive integer, but you can set it to whatever you choose (as long as it’s unique). Make note of all of the IDs of the fields you create.
You can use most of main the fields available in Ninja Forms, although there are some specific rules for certain field types. We will look at those later.
For now, let’s create a basic form with one field — the Project Title. After starting the form, add one “Single Line Text” field to your form, and set the label to “Project Title” (as in the image above).
Getting Your Form ID
You will need the ID of the Ninja Forms form before you connecting your form to UpStream.
To do this, you will need to publish the form, and then click on the link icon at the top-right of the page (in the red box in the picture below):
Once you click on the link icon, you will see a properties page. Next to “Embed Your Form”, there is a field and a copy button. Clicking the copy button will copy the shortcode to your clipboard.
Click the “Copy” button and paste the shortcode somewhere you can see it. It should look like this:
[ninja_form id=’2′]
Make note of the number in single quotes (2 in the example above). That’s the form ID. You will need this, so write it down.
Connecting Your Ninja Forms Form To UpStream
In this section, we will take the simple form we created in the last section and connect it to UpStream, so that by submitting the form, a user can create a project with a title entered by the user.
After installing and activating the UpStream Forms addon, go to your WordPress dashboard, and then go to UpStream -> Forms. You will see a page like below.
After activating, you will see a page like this (although the Action XML field will be blank)
The Action XML field is where all of the magic happens. In that field, you can enter the rules that tell UpStream how to handle each Gravity Forms form field.
Let’s take a look at a very basic Action XML:
<upstream-forms-action>
<form id="1">
<project action="create" title="[1]" created-by="1">
</project>
</form>
</upstream-forms-action>
Every Action XML starts with an *<upstream-forms-action>*tag. You can see that this tag is opened on line 1 and closed on line 6.
Line 2 is where the rule begins. UpStream can handle multiple Ninja Forms (or WPForms, etc.) forms at the same time. For each form, UpStream expects a *<form>*tag. The *<form>*tag has an id parameter, which is the ID of the form.
In the last section, we explained where to find the form ID in Ninja Forms. Check above if you need help finding it.
Since our Ninja Forms form had the ID 2, we would enter that as the id parameter in our *<form>*tag.
Line 3 tells UpStream to create a new project. The *<project>*tag tells UpStream to create a new project when this Ninja form with ID 2 is submitted. The parameters titleand created-by are required, and tell UpStream what the title of the project should be, and who the creator should be.
The first part, *title=”[1]”,*sets the title of the new project to what the user entered in the Ninja Forms field with the ID 1. Remember, we set the ID for each field — you can check here for instructions on how to set the ID of each field.
The second part, created-by=”1″ sets the creator of the form to the WordPress user with ID 1 — admin.
So after the Ninja Forms form is submitted, the Action XML above will create a new project, and set the title of that project to whatever the user entered in the first Ninja Forms field.
You can also enter text, or multiple field values, into any of the attributes. For example, you could change the previous code to this:
<upstream-forms-action>
<form id="1">
<project action="create" title="Project [1] by [2]" created-by="1">
</project>
</form>
</upstream-forms-action>
This code would create a project like before, but the title would be set differently. It would use the values the user entered in fields ID 1 and 2, and turn them into a string.
For example, if the user entered “Gutenberg” in the field with ID 1, and “Mike” in the field with ID 2, the new project would get the title “Project Gutenberg by Mike”.
Setting Other Project Fields
You will obviously want to set more than just the project title. For example, you may want to set the description, start date, end date, or owner. To do this, you will add a *<field>*tag under the *<project>*tag in your XML.
Here’s an example:
<upstream-forms-action>
<form id="522">
<project action="create" title="[1]" created-by="1">
<field name="assignedTo" value="[15]"></field>
<field name="status" value="[5]"></field>
<field name="startDate" value="[2]"></field>
<field name="endDate" value="[3]"></field>
<field name="description" value="[7]"></field>
<field name="clientId" value="[8]"></field>
</project>
</form>
</upstream-forms-action>
Each of the field tags in the XML set the value of an individual project field. For example, the XML causes UpStream to set the description of the new project to whatever the user entered in your Ninja Forms field with ID 7.
You can find a full list of fields below.
Some fields, such as status or startDate/endDate require special setup in Ninja Forms in order to work. We will explain how to do that in a later section.
Adding Tasks, Milestones, Bugs, and Files
You can add tasks, milestones, bugs, and files to projects by adding tags under the <project> tag in your XML.
Here’s a simple example that creates a task, milestone, and bug in a project.
<form id="522">
<project action="create" title="[1]" created-by="1">
<field name="assignedTo" value="[15]"></field>
<field name="status" value="[5]"></field>
<field name="startDate" value="[2]"></field>
<field name="endDate" value="[3]"></field>
<field name="description" value="[7]"></field>
<field name="clientId" value="[8]"></field>
<milestone action="create" title="[11]" created-by="1">
<field name="description" value="[19]"></field>
</milestone>
<task action="create" title="[20]" created-by="1">
<field name="notes" value="[26]"></field>
</task>
<bug action="create" title="[31]" created-by="1">
<field name="description" value="[35]"></field>
</bug>
</project>
</form>
With this code, when the Ninja Forms form with ID 522 is submitted, a new project is created with a task, milestone, and bug.
The task name/title is set to what the user entered in the Ninja Forms field with ID 20. The task notes are set to whatever the user entered in the Ninja Forms field with ID 26.
A bug is created, with the bug title set to the Ninja Forms field with ID 31. The bug description is set to the Ninja Forms field with id 35.
And a milestone is created with the title set to Ninja Forms field ID 11, and the description set to Ninja Forms field ID 19.
Ninja Forms Field Types With UpStream Forms
There are a few things you need to know when building your form for UpStream Forms.
Many of the fields can transfer directly over to UpStream, but certain fields require special handling. Please read the following to ensure that you setup your form correctly.
Date Fields
If you add a Date field to your form, you need tomake sure that the “Format” is set to “YYYY-MM-DD”.
For any form fields, the format MUST be YYYY-MM-DD
Dropdown/Multiple Choice/Checkbox Fields
What you enter in dropdowns, multiple choice fields, or checkbox fields must match the value you set for a field in UpStream. This depends on the type of field you’re trying to set in UpStream:
UpStream Assigned User/Owner
You have three different options to set the assigned user or owner of a project, task, file, or bug.
To set the assigned user/owner by the WordPress user ID, you will need to create a dropdown, checkbox, or radio button group. Then, under “Options”, enter the person’s name in the first box, and their user ID in the second box.
You can see an example below:
Enter display names in the first field and user IDs in the second field
When you create your XML, you can refer to this field like this (change the number 4 to the ID of your field):
<field name=”assignedTo” value=”[4]”></field>
To set the assigned user/owner by email, do the same thing as above, except enter email addresses in the second boxes under the “Choices” setting in Gravity Forms.
To set the owner or assigned user by email, you can enter the email in the second box in Gravity Forms.
Once you have created the field, you can refer to it in the XML like this (change the number 4 to the ID of your field) :
<field name=”assignedTo:byEmail” value=”[4]”></field>
To set the assigned user/owner by WordPress username, you can enter that in the second box under “Choices” in Gravity Forms.
To set the assigned user by username, you can enter that in the second field.
You can reference that field in the XML like this (change the number 4 to the ID of your field) :
<field name=”assignedTo:byUsername” value=”[4]”></field>
UpStream Project Client ID
In UpStream, you can find client IDs by going to your WordPress dashboard and then going to Projects -> Clients. In the table, you will see the ID for each client.
To set a client ID for a project via a Ninja Forms form, you will need to enter integer client IDs in the second box under the “Options” setting in Ninja Forms. In order to do this, create a select or radio field.
Finally, enter the client name in the first box and the client ID in the second box for each option in the “Options” section:
Enter the client name in the first box and the client ID in the second box.
You can then reference the field in the XML like this (change the number 5 to the ID of your field):
<field name=”clientId” value=”[5]”></field>
UpStream Status
To create project, task, or bug status fields in Ninja Forms for use with UpStream, you can do the following.
First, go to Ninja Forms and create a select or radio button field (don’t use a checkbox, since you can’t have multiple statuses).
Next, go to your WordPress dashboard, and then go to UpStream -> Projects (or tasks, or bugs). On that page, you will see status options. You can see the page below:
Setting status options in UpStream for use with forms
For each status, copy the text under “Status Name”. Then, go to Ninja Forms, and in the “Options” section, enter the copied text in both the first AND second boxesof each option. See below for an example:
When you enter status options in Ninja Forms, you must enter the EXACT status name in both the first and second box
UpStream Bug Severity
To create a bug severity fields in Ninja Forms for use with UpStream, you can follow a similar procedure as above.
First, go to Ninja Forms and create a select or radio button field (don’t use a checkbox, since you can’t have multiple severities).
Next, go to UpStream and go to your WordPress admin, then UpStream -> Bugs. Scroll down, and you will see severity options.
Setting values for bug severity in UpStream for use with forms
For each option, copy the text under “Severity Name” intoboth the first and second boxes under “Options” section in Ninja Forms.
Color Fields
To set a color field via a Ninja Forms form, you will need to create a select or radio button field.
Then, you can enter a hex color definition (example: #FF00FF) in the second box under the “Options” setting in Ninja Forms. In order to do this, create a select or radio field.
Then, enter the color name (or however else you want to describe the color) in the first box and the hex color in the second box for each option in the “Options” section.
Project and Milestone Categories
Unlike WPForms, Ninja Forms does not allow for taxonomy fields. So you cannot auto-populate categories for projects or milestones.
Therefore, in order to create category or tag fields, you will need to manually enter category/tag names and IDs into your form. Use the instructions above for standard dropdowns in order to do this.
Enter the category name in the first box and the category ID in the second box
After creating the field, use it in your UpStream Forms XML just as you would use any other field, using the field name categoryIds.
Continue to Part 2 — References, Editing & Custom Fields.