Extensions

How to Enter the License Key for UpStream Extensions

Each UpStream extension requires a license key. This license key allows you to get updated versions of the extension with new features, security updates, and bug fixes. This guide to shows to how to find and enter your license key. Step #1. Install the extension If you’re not sure how to install extensions, read these instructions. Step #2. Get the license key - Login to your account here at UpStreamPlugin.com. Use the “Login” link in the main menu: - Click on the “Purchase History” link under “Account”. image - Click on the “View Details and Downloads” link for your purchase: image - Select your license key: image Step #3. Activate the License Key - Now go back to your WordPress site. Go to “UpStream” and then “Extensions”: image - Paste your license key into the extension box, and click “Activate”: UpStream license key valid - If the license key is valid, you’ll see the message “Activated”. - If the license key is not valid, you’ll see this message: image

What is an Extension in UpStream?

Extensions are plugins that provide extra features for UpStream. Is there a free version of UpStream? Yes, the main UpStream plugin is free to download from WordPress.org. This plugin contains many key features, and can be used successfully for your project management. Are extensions included with the free UpStream plugin? No, you must purchase and install the extensions: - Click here to purchase extensions. - Click here to see a list of all the available extensions. - Click here to see how to install extensions. Why do we sell extensions? First, we can’t include every possible feature in the free UpStream plugin. If we included every feature, the plugin would become large and overly-complex. Second, selling premium extensions is how the UpStream team make a living. Without the income from premium extensions, we wouldn’t be able to develop the free plugin. If you like UpStream, please consider supporting us by subscribing to an UpStream bundle.

How to Install UpStream Extensions

Extensions are WordPress plugins that add extra features to UpStream. This guide to shows to how to install extensions after you have purchased them. - Click here to purchase extensions. - Click here to read more about extensions. - Click here to see all the current extensions. This guide shows how to install UpStream on a normal WordPress site. Click here for multisite instructions. Step #1. Install the main UpStream plugin The main UpStream plugin is free to download from WordPress.org. Please make sure you have installed this plugin into your WordPress site. Click here to see how to install UpStream. If you have installed UpStream, you will see it in the “Plugins” area of your WordPress site: Download UpStream extensions Step #2. Download the extensions - Login to your account here at UpStreamPlugin.com. Use the “Login” link in the main menu: - Click on the “Your Downloads” link under “Account”. - You will see a large blue buttons for each extension. You do not need to install every extension. - Click on this button to download the extensions you want: image - A .zip file will download to your computer. This file will have a name similar to “UpStream-FrontendEdit-v1.3.4.zip”. Don’t unzip this file. Step #3. Install the Extension - Go to your WordPress site’s admin area. Go to “Plugins”, then “Add New”: add a new WordPress plugin - Click “Upload Plugin”: upload a plugin to WordPress - Click “Choose File”: Choose a file to upload to WordPress - Select the .zip file that is on your computer. - Click “Install Now”. - You’ll see a message telling you that the install was successful. - Click “Activate Plugin”: Successfully installed WordPress plugin Step #4. Add the License Key After you have installed the extension, we recommend adding your license key so you can easily get access to all updates and bug fixes. - Click here to see how to add your license key to an extension.

Do I Need to Install All the UpStream Extensions?

No, you do not. To get started, all you need is the main UpStream plugin from WordPress.org. That plugin provides key project management features and can be used with no extensions. The UpStream extensions provide extra features, but are not essential: - Calendar View is needed only if you want a calendar display of Tasks and Bugs. - Custom Fields is needed only if you need extra information on Projects, Tasks, and Bugs. - Copy Project is needed only if you need to create one project and duplicate it often. - Customizer is needed only if you want to change the design of your project’s frontend layout. - Email Notifications is needed only if you want to send reminders to users about due dates. - Frontend Edit is needed only if you want to edit projects via the frontend of your site. - Project Timeline is needed only if you want a Gantt chart for your projects.

How to Find the Current Version of UpStream and Extensions

It’s important to make sure you’re running the latest version of UpStream and any extensions you’re using. How do you know you’re running the latest version of UpStream and extensions? - The UpStream page on WordPress.org lists the latest version of the main UpStream plugin. latest WordPress version - On this website, visit the page for each UpStream extension to find the latest version: latest extension version

How to Change Your UpStream Extension License URL

UpStream extensions have license keys that allow you to use the extensions on a certain number of sites. If you want to change your license key to another site, you can take these steps: - Login to this site using your account details. - Go to “Account”, then “Your Purchase History”. image - Click the “View Licenses” link next to your purchase: image - Click the “Manage Sites” link next to an extension: image - You’ll now see the current “Site URL” for this license. - Click “Deactivate Site” to remove the old URL: image - Now you can enter your new site URL and click “Activate Site”: image

How do UpStream Site Licenses Work?

If you visit the Pricing page for UpStream you’ll see that Site Licenses are available. For example, some plans have Site License for 1 site, and other plans offer Site License for 10 sites. These Site Licenses allow you to get updates and support for registered sites. However, what does a Site License mean when you’re dealing with localhost environments, multisite networks, and subdomains / subfolders? In this article we’ll clarify how you can use Site Licenses. Site Licenses and Localhost You are welcome to use UpStream on your localhost or development environment, with no license needed. If your URL matches any of these patterns, no license is needed: - localhost - 10.0.0.0/8 - 172.16.0.0/12 - 192.168.0.0/16 - *.dev - .*local - dev.* - staging.* Site Licenses and WordPress Multisite A single Site License is all you need for WordPress multisite networks. It’s important to recognize that a WordPress multi-site network only has a single plugins directory, which is shared by all sites. So if a plugin is updated for one site, it is updated for all sites. In that sense, a single license can be used for an entire Network. However, the sub-site which activated the license will be the only site that can check for new updates. We recommend making a single site that controls and activates all licenses to prevent things getting unorganized, and forgetting which site activated which license. Site Licenses and Subdomains / Subfolders UpStream extensions and support are provided using Site Licenses. That is not the same as a Domain License, so if you have multiple sites installed across subfolders and subdomains, each site will require a unique Site License.

How to Upgrade Your UpStream License

Several different license are available if you want to use UpStream’s premium extensions and support. Each license offers support for a different number of sites and extensions. If you want to upgrade to a license that offers more sites and extensions, this guide will show you how. We full pro-rate your upgrades so if you initially paid $40 for your first license, you will receive a $40 discount on your upgrade. - Login to your account here at UpStreamPlugin.com. - Click “Your Purchase History”. UpStream Purchase History link - Click the “View Upgrades” link for the license you want to upgrade. UpStream license upgrade link - You will see your upgrade options. Click ‘Upgrade License” for the upgrade you want. Notice that the prices are automatically discounted using the full value of your earlier license payment. - You will now be in the UpStream checkout process. Complete the checkout process and your license will be automatically upgraded. Upgrade your UpStream license

How To Use UpStream With WPForms

image UpStream’s Forms module allows you to connect UpStream to all three major WordPress forms plugins. Additional articles about UpStream Forms: - Using UpStream with Gravity Forms - Using UpStream with Ninja Forms In this article we look at how to use UpStream with WPForms. Getting Started WPForms is available in both a full version and a free lite version. UpStream Forms is compatible with both versions of WPForms. 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. We will explain how to do this later. Once you install WPForms, you can install and activate UpStream Forms. Preparing Your WPForms Form For UpStream If you haven’t created a form yet, the first thing you will need to do is to to your WordPress admin dashboard, and click on WPForms -> 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: Adding fields to a form in WPForms Adding fields to a form in WPForms On this page, you will add all of the fields that you want to load into your project. You can click any of the blue buttons in order to add a field. When you add a field, WPForms will show you a field configuration page, which includes an ID number for each field. Make note of all of the IDs of the fields you create. The image below shows where you can find the ID: Finding the ID of a form field in WPForms Finding the ID of a form field in WPForms You can use most of the fields available in WPForms, 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). Make a note of the WPForms ID of the “Project Title” field, and then save the form. Then, click the Embed button at the top-right of the page. It will open a popup with a shortcode. Within the shortcode is the form ID (in the red box in the picture below). Make note of the ID number of the form. Finding the ID of a form in WPForms Finding the ID of a form in WPForms Connecting Your WPForms 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. Entering an XML into UpStream Forms Entering an XML into UpStream Forms 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 WPForms form field. Let’s take a look at a very basic Action XML: <upstream-forms-action> <form id="522"> <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 WPForms (or Gravity Forms, Ninja Forms, 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 WPForms, but for a refresher, you can find it when you click “Embed” in WPForms: image Since our WPForms form had the ID 522, 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 ths WPForms form with ID 522 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 WPForms field with ID 1. See above for instructions on how to get the ID of each WPForms field. The second part, created-by=”1″ sets the creator of the form to the WordPress user with ID 1 — admin. So after the WPForms 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 WPForms 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="522"> <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 WPForms 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 WPForms 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 WPForms 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 WPForms field with ID 20. The task notes are set to whatever the user entered in the WPForms field with ID 26. A bug is created, with the bug title set to the WPForm field with ID 31. The bug description is set to the WPForm field with id 35. And a milestone is created with the title set to WPForms field 11, and the description set to WPForms field 19. WPForms 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/Time Fields If you add a Date/Time field to your form, you need tomake sure that the “Format” is set to “Date” (not “Date and Time”), and under Advanced Options, “Date Format” is set to “m/d/Y”. Setting the date format in WPForms for use with UpStream Setting the date format in WPForms for use with UpStream 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 enter integer user IDs in the second box under the “Choices” setting in WPForms. In order to do this, scroll down to Advanced Options, and check “Show Values” (you can learn more about WPForms values here). Then, under “Choices” in WPForms, enter the person’s name in the first box, and their user ID in the second box. You can see an example below: Setting up form fields in WPForms for use with UpStream Setting up form fields in WPForms for use with UpStream 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 WPForms. Setting up assigned users by email in WPForms Setting up assigned users by email in WPForms 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 WPForms. Setting up assigned users by username in WPForms Setting up assigned users by username in WPForms 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 WPForms form, you will need to enter integer client IDs in the second box under the “Choices” setting in WPForms. In order to do this, create a dropdown or multiple choice field. Then scroll down to Advanced Options, and check “Show Values” (you can learn more about WPForms values here). Finally, enter the client name in the first box and the client ID in the second box for each option in the “Choices” section: Setting up client ID fields in WPForms Setting up client ID fields in WPForms 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 WPForms for use with UpStream, you can do the following. First, go to WPForms and create a dropdown or multiple choice field (don’t use a checkbox, since you can’t have multiple statuses). Under Advanced Options, make sure “Show Values” in not checked. 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 Setting status options in UpStream for use with forms For each status, copy the text under “Status Name”. Then, go to WPForms, and in the “Choices” box, enter the copied text. See below for an example: Creating a status field for use with UpStream statuses Creating a status field for use with UpStream statuses UpStream Bug Severity To create a bug severity fields in WPForms for use with UpStream, you can follow a similar procedure as above. First, go to WPForms and create a dropdown or multiple choice field (don’t use a checkbox, since you can’t have multiple severities). Under Advanced Options, make sure “Show Values” in not checked. 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 Setting values for bug severity in UpStream for use with forms For each option, copy the text under “Severity Name” into your “Choices” section in WPForms. Adding a bug severity field to WPForms Adding a bug severity field to WPForms Color Fields To set a color field via a WPForms form, you will need to create a dropdown or multiple choice field. Then, you can enter a hex color definition (example: #FF00FF) in the second box under the “Choices” setting in WPForms. In order to do this, create a dropdown or multiple choice field. Then scroll down to Advanced Options, and check “Show Values” (you can learn more about WPForms values here). Finally, 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 “Choices” section. Project and Milestone Categories WPForms allows for taxonomy fields. Using this, you can add projects or milestones to categories via a form. To create a project categories field, you can choose a dropdown, multiple choice, or checkbox field in WPForms. Then go to Field Options, and under Advanced Options, set the following: set Dynamic Choices to Taxonomy, and Dynamic Taxonomy Source to “Category” for projects, or “Milestone Categories” for milestones. Creating a categories field in WPForms for use with UpStream projects or tasks Creating a categories field in WPForms for use with UpStream projects or tasks After creating the field, use it in your UpStream Forms XML just as you would use any other field, using the field name categoryIds. 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. Continue to Part 2 — References, Editing & Custom Fields.

How To Use UpStream With WPForms — Part 2

Part 2 of How To Use UpStream With WPForms. Part 1 covers setup, connecting your form, and field types. 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 WPForms 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 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 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 WPForms 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 | Field | Description | Field Type | | --- | --- | --- | | title | The title of the project. | Single Line Text | | description | The description of the project. | Single Line Text or Paragraph Text | | status | The status of the project. You will need to set this field up using the instructions above. | Dropdown or Multiple Choice | | categoryIds | The IDs of the categories of this project. | Checkboxes, Dropdown, or Multiple Choice | | assignedTo | The WordPress user ID of the owner of the project. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | | assignedTo:byUsername | The WordPress username of the owner of the project. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | | assignedTo:byEmail | The email of the WordPress user to set as the owner of the project. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | | startDate | The start date of the project. | Date formatted as m/d/Y | | endDate | The end date of the project. | Date formatted as m/d/Y | | clientId | The client ID of the client to attach this project to. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | Task Fields | Field | Description | Required Data Type | | --- | --- | --- | | title | The title of the task. | Single Line Text | | notes | The notes for the task. | Single Line Text or Paragraph Text | | status | The status of the task. You will need to set this field up using the instructions above. | Dropdown or Multiple Choice | | assignedTo | The WordPress user ID of the owner of the task. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | | assignedTo:byUsername | The WordPress username of the owner of the task. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | | assignedTo:byEmail | The email of the WordPress user to set as the owner of the task. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | | milestoneId | The ID of the milestone this task is attached to. | Dropdown, Multiple Choice, or Reference | | startDate | The start date of the task. | Date formatted as m/d/Y | | endDate | The end date of the task. | Date formatted as m/d/Y | | progress | The numerical progress percentage. UpStream only accepts integer multiples of 5 between 0 and 100. (Example: 0, 5, 10, 15, …) | Numbers, Dropdown, or Multiple Choice | Milestone Fields | Field | Description | Required Data Type | | --- | --- | --- | | title | The title of the milestone. | Single Line Text | | notes | The notes for the milestone. | Single Line Text or Paragraph Text | | color | The color of the milestone. You will need to set this field up using the instructions above. | Dropdown or Multiple Choice | | categoryIds | The category IDs of the milestone. | Checkboxes, Dropdown, or Multiple Choice | | assignedTo | The WordPress user ID of the owner of the milestone. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | | assignedTo:byUsername | The WordPress username of the owner of the milestone. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | | assignedTo:byEmail | The email of the WordPress user to set as the owner of the milestone. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | | startDate | The start date of the milestone. | Date formatted as m/d/Y | | endDate | The end date of the milestone. | Date formatted as m/d/Y | File Fields | Field | Description | Required Data Type | | --- | --- | --- | | title | The title of the file. | Single Line Text | | description | The description of the file. | Single Line Text or Paragraph Text | | assignedTo | The WordPress user ID of the owner of the file. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | | assignedTo:byUsername | The WordPress username of the owner of the file. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | | assignedTo:byEmail | The email of the WordPress user to set as the owner of the file. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | | fileId | The WordPress media ID of the file. You will need to upload the file separately. | Dropdown, Multiple Choice, Number | Bug Fields | Field | Description | Required Data Type | | --- | --- | --- | | title | The title of the bug. | Single Line Text | | description | The description of the bug. | Single Line Text or Paragraph Text | | dueDate | The due date of the bug. | Date formatted as m/d/Y | | severity | | | | status | The status of the bug. You will need to set this field up using the instructions above. | Dropdown or Multiple Choice | | assignedTo | The WordPress user ID of the owner of the bug. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | | assignedTo:byUsername | The WordPress username of the owner of the bug . You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | | assignedTo:byEmail | The email of the WordPress user to set as the owner of the bug . You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | | fileId | The WordPress media ID of the attached file. You will need to upload the file separately. | Dropdown, Multiple Choice, Number | Using Custom Fields With Forms To use UpStream custom fields with WPForms, 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. image 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 WPForms field, as opposed to the label. You can see the correct field in the image below. image The value in the red box in the picture above must exactly match the value in the red box in the picture below: image 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 WPForms field should be a checkbox. Otherwise, it can be a dropdown or multiple choice. Here’s an example form with users in WPForms: image Creating a user form with WPForms. Note that a numerical user ID is used as the value. 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 When you create a country field in WPForms, you will need to provide the 3 letter country code as the value for the form — not the country name. You can find the 3 letter country code here. Like some of the other custom fields above, the WPForms field type you use depends on whether you have set up the custom field in UpStream Custom Fields to allow multiple selections. Setting up a country field in WPForms. Make sure you use the 3 letter country code as the value, and not the country name. Setting up a country field in WPForms. Make sure you use the 3 letter country code as the value, and not the country name. 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>

How To Use UpStream With Gravity Forms

image UpStream’s Forms module allows you to connect UpStream to all three major WordPress forms plugins. Additional articles about UpStream Forms: - Using UpStream with WPForms - Using UpStream with Ninja Forms In this article we look at how to use UpStream with Gravity Forms. Getting Started UpStream Forms is compatible with most recent versions of Gravity 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, Gravity Forms and WPForms). We will explain how to do this later. Once you install Gravity Forms, you can install and activate UpStream Forms. Preparing Your Gravity Forms Form For UpStream If you haven’t created a form yet, the first thing you will need to do is to to your WordPress admin dashboard, and click on Forms -> New Form. 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: Creating a form using Gravity Forms Creating a form using Gravity Forms On this page, you will add all of the fields that you want to populate into your project. You can click any of the blue buttons in order to add a field. When you add a field, and click on the field, Gravity Forms will show you a properties page, which includes an ID number for each field. Make note of all of the IDs of the fields you create. The image below shows where you can find the ID: The ID for each field shows up in the top bar in Gravity Forms The ID for each field shows up in the top bar in Gravity Forms You can use most of the fields available in Gravity 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). Make a note of the Gravity Forms ID of the “Project Title” field, and then save the form. Also, make note of the form ID, which is prominently displayed in orange at the top of the page: The ID of the form is in orange at the top of the page. The ID of the form is in orange at the top of the page. Connecting Your Gravity 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) 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 Gravity Forms (or Ninja Forms, 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 Gravity Forms. Check above if you need help finding it. Since our Gravity Forms form had the ID 1, 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 the form with ID 1 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 Gravity Forms field with ID 1. See above for instructions on how to get the ID of each Gravity Forms field. The second part, created-by=”1″ sets the creator of the form to the WordPress user with ID 1 — admin. So after the Gravity 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 Gravity 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 Gravity 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 Gravity 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 Gravity 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 Gravity Forms field with ID 20. The task notes are set to whatever the user entered in the Gravity Forms field with ID 26. A bug is created, with the bug title set to the Gravity Forms field with ID 31. The bug description is set to the Gravity Forms field with id 35. And a milestone is created with the title set to Gravity Forms field 11, and the description set to Gravity Forms field 19. Gravity 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 “Date Format” is set to “yyyy-mm-dd”. To add a date field, you must set the Date Format to yyy-mm-dd To add a date field, you must set the Date Format to yyy-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 enter integer user IDs in the second box under the “Choices” setting in Gravity Forms. In order to do this, you first need to check “Show Values” (see the red box in the image below). Then, under “Choices”, enter the person’s name in the first box, and their user ID in the second box. You can see an example below: You must set the values properly when creating dropdowns, checkboxes, etc. You must set the values properly when creating dropdowns, checkboxes, etc. 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. 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. 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 Gravity Forms form, you will need to enter integer client IDs in the second box under the “Choices” setting in Gravity Forms. In order to do this, create a dropdown or radio field. Then check “Show Values”. Finally, enter the client name in the first box and the client ID in the second box for each option in the “Choices” section: image You can then reference the field in the XML like this (change the number 4 to the ID of your field): <field name=”clientId” value=”[4]”></field> UpStream Status To create project, task, or bug status fields in Gravity Forms for use with UpStream, you can do the following. First, go to Gravity Forms and create a dropdown or radio button field (don’t use a checkbox, since you can’t have multiple statuses). This time, make sure “Show Values” is not checked. 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 Setting status options in UpStream for use with forms For each status, copy the text under “Status Name”. Then, go to Gravity Forms, and in the “Choices” box, enter the copied text. See below for an example: Setting up status with forms Setting up status with Gravity Forms UpStream Bug Severity To create a bug severity fields in Gravity Forms for use with UpStream, you can follow a similar procedure as above. First, go to Gravity Forms and create a dropdown or radio button field (don’t use a checkbox, since you can’t have multiple severities). Make sure “Show Values” is not checked. 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 Setting values for bug severity in UpStream for use with forms For each option, copy the text under “Severity Name” into your “Choices” section in Gravity Forms. Color Fields To set a color field via a Gravity Forms form, you will need to create a dropdown or radio button field. Then, you can enter a hex color definition (example: #FF00FF) in the second box under the “Choices” setting in Gravity Forms. In order to do this, create a dropdown or radio field. Then check “Show Values”. Finally, 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 “Choices” section. Project and Milestone Categories Unlike WPForms, Gravity 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. Adding a category field using Gravity Forms, you must enter category IDs in the value section Adding a category field using Gravity Forms, you must enter category IDs in the value section After creating the field, use it in your UpStream Forms XML just as you would use any other field, using the field name categoryIds. 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. Continue to Part 2 — References, Editing & Custom Fields.

How To Use UpStream With Gravity Forms — Part 2

Part 2 of How To Use UpStream With Gravity Forms. Part 1 covers setup, connecting your form, and field types. 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 Gravity 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 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 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 Gravity 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 | Field | Description | Field Type | | --- | --- | --- | | title | The title of the project. | Single Line Text | | description | The description of the project. | Single Line Text or Paragraph Text | | status | The status of the project. You will need to set this field up using the instructions above. | Dropdown or Radio | | categoryIds | The IDs of the categories of this project. | Checkboxes, Dropdown, Multi select, or Radio | | assignedTo | The WordPress user ID of the owner of the project. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byUsername | The WordPress username of the owner of the project. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byEmail | The email of the WordPress user to set as the owner of the project. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | startDate | The start date of the project. | Date formatted as yyyy-mm-dd | | endDate | The end date of the project. | Date formatted as yyyy-mm-dd | | clientId | The client ID of the client to attach this project to. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | Task Fields | Field | Description | Required Data Type | | --- | --- | --- | | title | The title of the task. | Single Line Text | | notes | The notes for the task. | Single Line Text or Paragraph Text | | status | The status of the task. You will need to set this field up using the instructions above. | Dropdown or Radio | | assignedTo | The WordPress user ID of the owner of the task. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byUsername | The WordPress username of the owner of the task. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byEmail | The email of the WordPress user to set as the owner of the task. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | milestoneId | The ID of the milestone this task is attached to. | Dropdown, Radio, or Reference | | startDate | The start date of the task. | Date formatted as yyyy-mm-dd | | endDate | The end date of the task. | Date formatted as yyyy-mm-dd | | progress | The numerical progress percentage. UpStream only accepts integer multiples of 5 between 0 and 100. (Example: 0, 5, 10, 15, …) | Number, Dropdown, or Radio | Milestone Fields | Field | Description | Required Data Type | | --- | --- | --- | | title | The title of the milestone. | Single Line Text | | notes | The notes for the milestone. | Single Line Text or Paragraph Text | | color | The color of the milestone. You will need to set this field up using the instructions above. | Dropdown or Radio | | categoryIds | The category IDs of the milestone. | Checkboxes, Dropdown, or Radio | | assignedTo | The WordPress user ID of the owner of the milestone. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byUsername | The WordPress username of the owner of the milestone. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byEmail | The email of the WordPress user to set as the owner of the milestone. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | startDate | The start date of the milestone. | Date formatted as yyyy-mm-dd | | endDate | The end date of the milestone. | Date formatted as yyyy-mm-dd | File Fields | Field | Description | Required Data Type | | --- | --- | --- | | title | The title of the file. | Single Line Text | | description | The description of the file. | Single Line Text or Paragraph Text | | assignedTo | The WordPress user ID of the owner of the file. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byUsername | The WordPress username of the owner of the file. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byEmail | The email of the WordPress user to set as the owner of the file. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | fileId | The WordPress media ID of the file. You will need to upload the file separately. | Dropdown, Multiple Choice, Number | Bug Fields | Field | Description | Required Data Type | | --- | --- | --- | | title | The title of the bug. | Single Line Text | | description | The description of the bug. | Single Line Text or Paragraph Text | | dueDate | The due date of the bug. | Date formatted as yyyy-mm-dd | | severity | The severity of the bug. You will need to set this field up using the instructions above. | Dropdown or Radio | | status | The status of the bug. You will need to set this field up using the instructions above. | Dropdown or Radio | | assignedTo | The WordPress user ID of the owner of the bug. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | | assignedTo:byUsername | The WordPress username of the owner of the bug . You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byEmail | The email of the WordPress user to set as the owner of the bug . You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | fileId | The WordPress media ID of the attached file. You will need to upload the file separately. | Dropdown, Radio, Number | Using Custom Fields With Forms To use UpStream custom fields with Gravity 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. image 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 Gravity 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 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: Enter the value in the box in red from the previous image in the box in this form Enter the value in the box in red from the previous image in the box in this form 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 Gravity Forms field should be a checkbox or multiselect. Otherwise, it can be a dropdown or radio. Here’s an example form with users in Gravity Forms : You must use user IDs with custom fields You must use user IDs with custom fields 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 When you create a country field in Gravity Forms, you will need to provide the 3 letter country code as the value for the form — not the country name. You can find the 3 letter country code here. Like some of the other custom fields above, the Gravity Forms field type you use depends on whether you have set up the custom field in UpStream Custom Fields to allow multiple selections. 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>

How to Use UpStream Time Tracking and Budgeting

UpStream Time Tracking and Budgeting provides a comprehensive solution for recording hours and budgets spent on projects, tasks, and bugs. image Once you install and activate Time Tracking, you will get a new box in each task and bug that allows you to enter time. The Time Tracking Interface When you create or edit a task, you will see a box like this on the front end: image In the WordPress admin interface, you will have to click on the Manage Time and Budget Recordslink under a task: image Once you click *Manage Time and Budget Records,*you see a popup that looks like this: image To create a new record, select the user for whom you want to create the record. Then, if you want to manually enter the time, just click the plus sign (see below, in the red box). If you want to use a timer, check of the Use Timer box and then click the plus sign. That will start a timer, which will count the number of hours since it was started. image You can then enter the budgeted amount and the amount spent, as well as a note in the Notes section. If you are using a timer, you can stop timing by clicking the small stop button next to the time record (see below, in the red box). image You can also delete any record by clicking on the Deleteicon next to the record. The total time, amount budgeted, and amount spent so far incurred in performing the task (or bug) shows up in the list of tasks (or bugs) on the front end, as you can see below: image Time also rolls up to the project level, as you can see here: image Setting Day Length To make numbers easier to read, in some cases, UpStream displays time as days and hours (like above). Days defined as working days. By default they are set to 8 hours long. So 3 days would be 24 hours (not 72 hours). You can change the number of working hours per day by going to the WordPress administrative dashboard, and selecting UpStream -> General, and setting the number under Work Hours Per Day: Setting work hours per day Note that when using a timer, every hour is recorded, so if you start the timer on Monday at 9:00 AM and end the timer on Tuesday at 9:00 AM, the timer will record 24 hours. Setting the Currency Symbol Before you begin, you will want to set the currency symbol to your local currency. By default, it is the dollar sign ($); however, you can use anything you want. To set it, go to the WordPress administrative dashboard, and select UpStream -> General, and enter the symbol under Currency Symbol: image Reporting If you have the UpStream Reporting module, you can run many different types of reports on tracked time. For any report, you can filter on time spent. For instance, you can view a report of all projects where the time spent is less than 20 hours by going to the Project Tablereport, and entering 20 as the maximum: Filtering reports by elapsed time. If you want to find all milestones with elapsed time between 50 and 100 hours, you can enter those numbers in the boxes instead. Note that you must enter a number of hours in the boxes — not days. Elapsed Time Chart In the Reporting module, there are elapsed time reports for projects, tasks, milestones, and bugs. After choosing filters, you will see a pie chart of objects (projects/tasks/etc), with the percentage of hours spent, like this: Elapsed time pie chart Amount Budgeted/Amount Spent Chart To see amounts budgeted or spent, you can run the Amount Budgeted or Amount Spent report. These reports are available for projects, milestones, bugs, and tasks. After choosing filters, you will see a pie chart of the percentage of the total spent on each task/project/milestone/bug. You can mouse over each item to see the amount spent. image

How To Use UpStream With Ninja Forms

UpStream’s Forms module allows you to connect UpStream to all three major WordPress forms plugins. Additional articles about UpStream Forms: - Using UpStream with WPForms - Using UpStream with Gravity 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 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 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. 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): image 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. image 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) 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 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 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. 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. 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. 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 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 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 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 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.

Updating UpStream Addons

UpStream addons need to be updated periodically in order to insure the latest features and bug fixes. Generally, this is an easy process, but sometimes there are problems. This guide will explain how to update your addons in either case. Automatically Updating In most cases, you will automatically be notified that your UpStream addon is out of date, in the same way other plugins work: you will see a message on your WordPress plugins page, like below. image You can then click the update now button, and the addon should automatically be updated. Troubleshooting An Update Error It you try to click update now, and you get an error message, your license key may have become corrupted. To fix this, go to your WordPress admin dashboard and click UpStream -> Extensions. You will see a list of your installed addons, with the license keys entered. Copy your license number down, and then click the change link. image Then, re-enter your license key and click *activate.*You should then be able to return to the plugins page and update your addons. If you have trouble, please let us know and we’d be happy to help. Don’t See An Update Message? Manually Update In rare cases, you may not see an update message on the plugins page. Instead, upon updating the main UpStream plugin, you may see a message like this: image When you see that message, you should first go to your plugins page and see if you can update your UpStream addons using the method above. However, if that doesn’t work, you will have to manually update the addon(s). To do that, use the following steps: 1. Click here and log in to your UpStream account. If you need help logging in, contact us. 2. Once you have logged in, click here to view your downloads. Download the addons that you need to update. These will be the latest versions. 3. Return to your WordPress site, and go to your plugins page. Then deactivate and delete the addons that you want to update. When deleting UpStream addons, you will not lose any data. NOTE: DO NOT DEACTIVATE OR DELETE THE MAIN UPSTREAM PLUGIN. THAT MAY CAUSE DATA LOSS. 4. Click on the Add New button at the top of the plugins page. This will take you to the add plugins page. 5. On the add plugins page, click Upload Plugin. Upload the ZIP files you downloaded in step 2. 6. Click Install Now to install the addon, and then Activate to activate it. 7. Repeat steps 4-6 for all of the addons you need to update. If you need any help updating your addons, please contact us!

Using Advanced Permissions

image UpStream’s advanced permissions extension allows you to define nearly any scenario, and set your permissions to match. To do this, you create an XML document and enter it in the Advanced Permissions configuration section under UpStream settings. Remember, we’re here to help — you can contact us at any time if you need help with the XML. Getting Started with Advanced Permissions After you’ve installed the Advanced Permissions add-on, to get started with Advanced Permissions, go to your WordPress dashboard and select UpStream -> Advanced Permissions. You will see a radio button, “Enable Advanced Permissions,” and a large code entry field, “Permissions XML.” By default, Advanced Permissions is disabled, and the standard permissions model is active. Once you’ve created your permissions XML, you can set “Enabled Advanced Permissions” to “Enabled” to use the permissions XML. The UpStream permissions XML format is pretty simple. If you’re not familiar with XML, you can learn about it here. Here is the basic structure: <upstream-permissions> <role slug="upstream_client_user"> <object type="project" client-id="223" allow="create,edit,delete,view"> </object> </role> <user username="mike"> <object type="project" assigned-to="me" allow="create,edit,delete,view"> </object> </user> </upstream-permissions> In order to make the most of UpStream Advanced Permissions, you should install the free Members plugin for WordPress. This allows you to create and view roles, which you can use in Advanced Permissions. UpStream Advanced Permissions XML Structure Top Level Tags Each UpStream permissions XML document must start with an <upstream-permissions> tag. Within the <upstream-permissions> tag, you define users, and then under each user definition, you enter permissions rules. A user definitions can be one of the following: - To set permissions for any user with a certain role, you can use the <role> tag. The syntax is <role slug="(enter slug here)"> You can find the slug for a role using the Members plugin in Users -> Rolesunder the “Role” heading. (Note, this is different from the “Role Name”, which can’t be used with UpStream Advanced Permissions.) - To set permissions for an individual user by their username, you can use <user username="(enter username here)"> You can find the username in the WordPress dashboard by going to Users -> All Users and looking under the “Username” heading. - If you know the user’s ID number, you can also set permissions for an individual user by their user ID. To do this, use <user id="(enter user ID here)"> Here are some examples of the <user> and <role> tags described above: <upstream-permissions> <role slug="upstream_client_user"> ... </role> <user username="mike"> ... </user> <user id="655"> ... </user> </upstream-permissions> Object and Field Tags Object Tags Under the <role> or <user> tags, you can enter a list of object tags. These describe objects that you can set permissions for. This is done using the following syntax: <object type="(object-type)" rule="(predicate)" allow="(actions)"> Valid object types are: - “project” - “task” - “file” - “bug” - “milestone” Valid actions are: any combination of “view”, “edit”, “delete”, and “create” in a comma separated string. For example, “view,edit” or “view,create,delete” Valid predicates are: - assigned-to – a username of who the item is assigned to, or “me” for anything assigned to me, or “*” for anything assigned to anyone - *has-member –*a username of who is a member of the project, or “me” - project-assigned-to– for milestones, tasks, bugs, and files, this is the username that the parent project is assigned to, or “me” for projects assigned to me - created-by – a username of who created the item, or “me” for anything created by me - project-created-by – for milestones, tasks, bugs, and files, this is the username of the creator of the parent project, or “me” for projects created by me - id– the ID of the object (you can find IDs in the admin dashboard in each list of items) - project-id– for milestones, tasks, bugs, and files, this is the ID of the parent project - category-slug– the slug for the category (you can find this in the list of categories in the WordPress admin dashboard) - project-category-slug– for milestones, tasks, bugs, and files, the slug for the parent project - client-id– for projects only, the ID of the client that the project belongs to (you can find this in the clients tab in the admin dashboard); you can also enter “mine” to allow UpStream Client Users to access projects for their client, or “mine-selected” to allow UpStream Client Users to access projects that they are selected for in their client - project-client-id– for milestones, tasks, bugs, and files, the ID of the client that the parent project belongs to (you can find this in the clients tab in the admin dashboard) ; you can also enter “mine” to allow UpStream Client Users to access items in projects for their client, or “mine-selected” to allow UpStream Client Users to access items in projects that they are selected for in their client Field Tags Under an <object> tag, you can have a <field> tag, if you want to set field-level permissions for an item. By default, if you don’t have a field tag under an object, then all fields are viewable and editable. However, if you do have any field tag under an object, then all other fields are hidden. For example: In the following code snippet, “sam” will be able to edit all fields of any project: <upstream-permissions> <user username="sam"> <object type="project" assigned-to="*" allow="create,edit,view,delete"></object> </user> </upstream-permissions> However, in this code snippet, “sam” can only view the title of any project: <upstream-permissions> <user username="sam"> <object type="project" assigned-to="*" allow="create,edit,view,delete"> <field name="title" allow="view"></field> </object> </user> </upstream-permissions> Once any <field> tag is added to an object, all of the other fields are hidden by default. You can also combine different permissions, and the user will get the maximum of all that apply. In the following example, “sam” is a member of the “teachers” role: <upstream-permissions> <role slug="teachers"> <object type="project" assigned-to="*" allow="create,edit,view,delete"> <field name="title" allow="view,edit"> </object> </role> <user username="sam"> <object type="project" assigned-to="*" allow="create,edit,view,delete"></object> </user> </upstream-permissions> Under the <user username=”sam”> tag, there is nothing under the project tag, so “sam” has full view/edit rights to all fields in any project — even through “sam” is part of the “teachers” role, and they only have view/edit access to the title field. Making Projects Publicly Viewable Another thing you can do with Advanced Permissions is make certain projects publicly viewable. To make a project publicly viewable, you can use the *user type=”anonymous”*rule. image For example, to make a project with ID 7 publicly viewable, you can use the code below <upstream-permissions> <user type="anonymous"> <object type="project" id="7" allow="view"></object> </user> </upstream-permissions> Finally, select enable and click save to enable the rules. There are a few notes to remember regarding public viewing: - You can only allow public viewing, not editing - Non users who go to your /projects URL will see all public projects - You can use other predicates for the rule as well, such as assigned-to Basic XML Examples Here are some basic examples of XML. Example 1: Re-create the standard UpStream Client User permissions model. If you want to re-create the standard UpStream permissions model for Client Users, you can use the following. Note that UpStream Managers and Administrators automatically have access to everything. <upstream-permissions> <role slug="upstream_client_user"> <object type="project" client-id="mine-selected" allow="create,edit,delete,view"></object> <object type="milestone" project-client-id="mine-selected" allow="create,edit,delete,view"></object> <object type="file" project-client-id="mine-selected" allow="create,edit,delete,view"></object> <object type="task" project-client-id="mine-selected" allow="create,edit,delete,view"></object> <object type="bug" project-client-id="mine-selected" allow="create,edit,delete,view"></object> </role> </upstream-permissions> Example 2: Force the UpStream Client User Role to Only Allow Viewing and Commenting The next example can be used to re-define the UpStream Client User role so that UpStream Client Users can view projects (and their components) for which they’re selected, and they can add comments — but they can’t edit anything else. <upstream-permissions> <role slug="upstream_client_user"> <object type="project" client-id="mine-selected" allow="view,edit"> <field name="title" allow="view"></field> <field name="description" allow="view"></field> <field name="status" allow="view"></field> <field name="progress" allow="view"></field> <field name="client" allow="view"></field> <field name="client_users" allow="view"></field> <field name="categories" allow="view"></field> <field name="owner" allow="view"></field> <field name="start" allow="view"></field> <field name="end" allow="view"></field> <field name="comments" allow="view,edit"></field> </object> <object type="task" project-client-id="mine-selected" allow="create,view,edit"> <field name="title" allow="view"></field> <field name="assigned_to" allow="view"></field> <field name="status" allow="view"></field> <field name="progress" allow="view"></field> <field name="milestone" allow="view"></field> <field name="start_date" allow="view"></field> <field name="end_date" allow="view"></field> <field name="comments" allow="view,edit"></field> </object> <object type="milestone" project-client-id="mine-selected" allow="create,edit,view"> <field name="milestone" allow="view"></field> <field name="progress" allow="view"></field> <field name="tasks" allow="view"></field> <field name="assigned_to" allow="view"></field> <field name="start_date" allow="view"></field> <field name="end_date" allow="view"></field> <field name="categories" allow="view"></field> <field name="comments" allow="view,edit"></field> </object> <object type="file" project-client-id="mine-selected" allow="create,edit,view"> <field name="title" allow="view"></field> <field name="created_by" allow="view"></field> <field name="created_at" allow="view"></field> <field name="assigned_to" allow="view"></field> <field name="description" allow="view"></field> <field name="file" allow="view"></field> <field name="comments" allow="view,edit"></field> </object> <object type="bug" project-client-id="mine-selected" allow="create,edit,view"> <field name="title" allow="view"></field> <field name="assigned_to" allow="view"></field> <field name="severity" allow="view"></field> <field name="status" allow="view"></field> <field name="due_date" allow="view"></field> <field name="file" allow="view"></field> <field name="comments" allow="view,edit"></field> </object> </role> </upstream-permissions> Example 3: Allow a User to Create and Edit Project Components for Projects Assigned to Them The next example allows a user with username “sam” to access a project assigned to them, and create or edit components (milestones, tasks, etc.). The example allows “sam” to add comments to the project and set the progress, but not edit any of the other project fields. It also doesn’t allow “sam” to delete project components. <upstream-permissions> <user username="sam"> <object type="project" assigned-to="me" allow="edit,view"> <field name="title" allow="view"></field> <field name="description" allow="view"></field> <field name="status" allow="view"></field> <field name="progress" allow="view,edit"></field> <field name="client" allow="view"></field> <field name="client_users" allow="view"></field> <field name="categories" allow="view"></field> <field name="owner" allow="view"></field> <field name="start" allow="view"></field> <field name="end" allow="view"></field> <field name="comments" allow="view,edit"></field> </object> <object type="task" project-assigned-to="me" allow="create,edit,view"></object> <object type="milestone" project-assigned-to="me" allow="create,edit,view"></object> <object type="file" project-assigned-to="me" allow="create,edit,view"></object> <object type="bug" project-assigned-to="me" allow="create,edit,view"></object> </user> </upstream-permissions> Example 4: Re-define the UpStream User Role To Only Allow Users To Edit Projects They Create This XML code re-defines the UpStream User role so that they can do anything with projects that they create — and anything with components of the projects they create. But they can only view projects created by others. <upstream-permissions> <role slug="upstream_user"> <object type="project" created-by="me" allow="view,edit"></object> <object type="task" project-created-by="me" allow="view,edit,create,delete"></object> <object type="milestone" project-created-by="me" allow="view,edit,create,delete"></object> <object type="file" project-created-by="me" allow="view,edit,create,delete"></object> <object type="bug" project-created-by="me" allow="view,edit,create,delete"></object> <object type="project" assigned-to="*" allow="view,create"></object> <object type="task" assigned-to="*" allow="view"></object> <object type="milestone" assigned-to="*" allow="view"></object> <object type="file" assigned-to="*" allow="view"></object> <object type="bug" assigned-to="*" allow="view"></object> </role> </upstream-permissions> Important Notes Here are some important notes to keep in mind about how Advanced Permissions works: - UpStream Manager and Administrator roles have access to everything, regardless of what’s in the XML permissions document. - UpStream automatically adds view permission to when create, edit, delete, or copy are assigned to an object. - If you want the user to be able to upload files, they must have the ‘upload_files’ or “Edit Files” capability enabled in WordPress, separately from the Advanced Permissions plugin Available Fields The following is a list of the field names that can be used in the <field name=”field-name“> tag: Project Field Names - title – the name/title of the project - description – the description of the project - status – the status of the project - progress – the progress percent of the project*(this is not editable, since it is auto-calculated)* - categories – the categories that the project belongs to - owner – the owner of the project - client – the client to which the project belongs - client_users – the client users that are connected to the project - start – the project start date - end – the project end date - reminders – email reminders - records – time tracking/budgeting records - comments – the comments section that appears at the bottom of the projects page Milestone Field Names - milestone – this is the title of the milestone (note that this is different from the other items, which use the field title) - assigned_to – who the milestone is assigned to - start_date – the start date - end_date – the end date - progress – the milestone progress - tasks – the number of tasks under this milestone, both open and total (note that this is view only) - categories – the categories that this milestone belongs to - comments – the comments Task Field Names - title – the name/title of the task - assigned_to – who the task is assigned to - status – the task status - progress – the progress percentage of the task - milestone – the milestone that the task belongs to - start_date – the start date for the task - end_date – the end date for the task - reminders – email reminders - records – time tracking/budgeting records - notes – the task notes - comments – the comments Bug Field Names - title – the name/title of the bug - assigned_to – who the bug is assigned to - severity – the severity - status – the status - due_date – the bug due date - reminders – email reminders - records – time tracking/budgeting records - description – the bug description - file – the file (if attached) - comments – comments File Field Names - title – the title of the file - created_by – the uploaded by field - created_at – the upload date field - assigned_to – who the file is assigned to - description – the description of the file - file – the actual attachment - comments – the comments Note: For custom fields, you must enter the custom field slug as it is shown in the table on the Custom Fields page.

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 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 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 | Field | Description | Field Type | | --- | --- | --- | | title | The title of the project. | Single Line Text | | description | The description of the project. | Single Line Text or Paragraph Text | | status | The status of the project. You will need to set this field up using the instructions above. | Dropdown or Radio | | categoryIds | The IDs of the categories of this project. | Checkboxes, Dropdown, Multi select, or Radio | | assignedTo | The WordPress user ID of the owner of the project. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byUsername | The WordPress username of the owner of the project. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byEmail | The email of the WordPress user to set as the owner of the project. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | startDate | The start date of the project. | Date formatted as yyyy-mm-dd | | endDate | The end date of the project. | Date formatted as yyyy-mm-dd | | clientId | The client ID of the client to attach this project to. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | Task Fields | Field | Description | Required Data Type | | --- | --- | --- | | title | The title of the task. | Single Line Text | | notes | The notes for the task. | Single Line Text or Paragraph Text | | status | The status of the task. You will need to set this field up using the instructions above. | Dropdown or Radio | | assignedTo | The WordPress user ID of the owner of the task. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byUsername | The WordPress username of the owner of the task. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byEmail | The email of the WordPress user to set as the owner of the task. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | milestoneId | The ID of the milestone this task is attached to. | Dropdown, Radio, or Reference | | startDate | The start date of the task. | Date formatted as yyyy-mm-dd | | endDate | The end date of the task. | Date formatted as yyyy-mm-dd | | progress | The numerical progress percentage. UpStream only accepts integer multiples of 5 between 0 and 100. (Example: 0, 5, 10, 15, …) | Number, Dropdown, or Radio | Milestone Fields | Field | Description | Required Data Type | | --- | --- | --- | | title | The title of the milestone. | Single Line Text | | notes | The notes for the milestone. | Single Line Text or Paragraph Text | | color | The color of the milestone. You will need to set this field up using the instructions above. | Dropdown or Radio | | categoryIds | The category IDs of the milestone. | Checkboxes, Dropdown, or Radio | | assignedTo | The WordPress user ID of the owner of the milestone. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byUsername | The WordPress username of the owner of the milestone. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byEmail | The email of the WordPress user to set as the owner of the milestone. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | startDate | The start date of the milestone. | Date formatted as yyyy-mm-dd | | endDate | The end date of the milestone. | Date formatted as yyyy-mm-dd | File Fields | Field | Description | Required Data Type | | --- | --- | --- | | title | The title of the file. | Single Line Text | | description | The description of the file. | Single Line Text or Paragraph Text | | assignedTo | The WordPress user ID of the owner of the file. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byUsername | The WordPress username of the owner of the file. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byEmail | The email of the WordPress user to set as the owner of the file. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | fileId | The WordPress media ID of the file. You will need to upload the file separately. | Dropdown, Multiple Choice, Number | Bug Fields | Field | Description | Required Data Type | | --- | --- | --- | | title | The title of the bug. | Single Line Text | | description | The description of the bug. | Single Line Text or Paragraph Text | | dueDate | The due date of the bug. | Date formatted as yyyy-mm-dd | | severity | The severity of the bug. You will need to set this field up using the instructions above. | Dropdown or Radio | | status | The status of the bug. You will need to set this field up using the instructions above. | Dropdown or Radio | | assignedTo | The WordPress user ID of the owner of the bug. You will need to create a dropdown or radio field using the instructions above. | Dropdown or Multiple Choice | | assignedTo:byUsername | The WordPress username of the owner of the bug . You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | assignedTo:byEmail | The email of the WordPress user to set as the owner of the bug . You will need to create a dropdown or radio field using the instructions above. | Dropdown or Radio | | fileId | The WordPress media ID of the attached file. You will need to upload the file separately. | Dropdown, Radio, Number | 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. image 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 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 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>

How to Use the Calendar View Extension

If you plan to use the Calendar View extension, make sure you have downloaded and installed the extension. These articles will help you get started: - What is an UpStream extension? - How to install an UpStream extension What does the Calendar View extension do? The Calendar View extension allows you to easily see everything that’s happening in a single project, or all your projects. You can see due dates for all the milestones, tasks, and bugs. These dates will appear in a calendar-style layout. The Calendar View extension is a very useful tool for keeping up-to-date on all your projects. Inside each project, you’ll see a calendar giving a color-coded overview of all your due dates. The Calendar View for single projects Unlike some other extensions, Calendar View does not appear in the admin area of your site. It only appears in the front-end view for single projects. This image below shows the front-end view in action. All these items are taken from the project you are looking at. Each item is color-coded, using the colors selected in the UpStream settings. You can drag-and-drop items to different dates. This will automatically update the dates for that item. image The Calendar View for all projects The Calendar View is also available from your main frontend “All Projects” screen. Click the “Calendar” link in the left sidebar. This gives you an overview of progress on ALL your projects. image Edit items directly from the Calendar If you click on a milestone, task or bug in the Calendar, you’ll see a pop-up window with all the relevant details. Click on the “Edit” button and you’ll immediately be taken to edit that item. image

How to Use the Custom Fields Extension

If you are using the Custom Fields extension for the first time, make sure you have downloaded and installed the extension. These articles will help you get started: - What is an UpStream extension? - How to install an UpStream extension The Custom Fields extension allow you to create all sorts of extra information for your projects, milestones, tasks, bugs, and files. For example, in a web design project, the bugs could have fields for the browser type, PHP version, and screen size. What Custom Fields are available? Custom Fields currently supports 9 field types: 1. Text 2. Dropdown 3. File 4. Radio buttons 5. Checkboxes 6. Color Picker 7. Category 8. Tag 9. Autoincrement image How Custom Fields Works - When Custom Fields is installed, you’ll see a new menu link: Custom Fields menu link - Click “Add New Custom Field” and you’ll see the choice of field type. Once you choose a field type, you can then choose the specific options for that type. choosing a field type - Each Custom Field can be assigned to Projects, Milestones, Tasks, Bugs and/or Files: assigning custom fields - Custom Fields can be used via the admin area of your site: using custom fields in the admin area - They can also be used via the frontend of your site, if you have the Frontend Edit extension installed. using Custom Fields via the frontend of your site

Using the UpStream API

UpStream has powerful developer features, which can be accessed using the UpStream API module. In this document, we will explain how to use the API. UpStream expands the standard API functionality built into WordPress. So we recommend that you familiarize yourself with the WordPress API before trying to use the UpStream API functionality. For more information on the WordPress API, including how to use it, see this. Getting Started with UpStream API This section explains how to get up and running with the UpStream API with WordPress. If you’re comfortable with the WordPress API, you can skip this section. The first thing you need to do in order to use the UpStream API is to install an authentication plugin. Although you shouldn’t use it for production, for a test installation, the easiest authentication plugin to use is the JSON Basic Authentication plugin. You can download it from Github. Once you have downloaded, installed, and activated it, you can start developing with the API. For this article, we will be using the Talend API Tester Google Chrome addon, which you can get from the Chrome App Store. Authentication Authentication into the UpStream API is purely based on the authenticated WordPress REST API user. If you have the JSON Basic Authentication plugin enabled, you will need to pass an Authorization header with the username and password of the user you are logging in as. Note that in order to be able to use the UpStream API, you must be logged into the WordPress REST API as a user with manage_upstream permissions. That means that any user who has access to the UpStream API can manipulate any object, regardless of owner or client. UpStream Objects The UpStream API allows access to the following object types: | Object | Operations | Object URL Component | | --- | --- | --- | | Project | GET, POST, PUT | projects | | Milestone | GET, POST, PUT | milestones | | Task | GET, POST, PUT | tasks | | Bug | GET, POST, PUT | bugs | | File | GET, POST, PUT | files | | Client | GET, POST, PUT | clients | A list of the UpStream objects that can be manipulated via the API. Queries to the API are of the form https://<yourserver>/wp-json/upstream/v1/<object-url-component> For example: https://my-wordpress-server/wp-json/upstream/v1/projects?id=1 UpStream API GET Now, we will start with the queries. To get any object by ID, you can use an HTTP GET query. The ID is passed as a query parameter. For any GET queries, you must pass the fields you want as an array of field[] parameters. Here is an example: https://my-wordpress-server/wp-json/upstream/v1/projects?id=165&fields[]=title&fields[]=description And here is the query above run: image Performing a project GET query using the UpStream API. And here is the result: {"title":"Drawing App","description":""} When you are querying projects, clients, or milestones, you can use the form above. When you are querying tasks, files, and bugs, you must pass in the project ID as project_idin the request as well. For example, https://my-wordpress-server/wp-json/upstream/v1/tasks?id=15ed2d17f52485&fields[]=title&project_id=165 Will return: {"title":"Design Interface"} The fields options are below: Project Fields | Field | Description | Notes | | --- | --- | --- | | title | The title of the project. | | | description | The description of the project. | | | status | The status of the project. | Returns the status text. | | categories | The categories of this project. | Returns a JSON array of WordPress term objects. | | assignedTo | The WordPress user ID of the owner of the project. | Returned as a one element array for compatibility. | | startDate | The start date of the project. | Date formatted as YYYY-MM-DD | | endDate | The end date of the project. | Date formatted as YYYY-MM-DD | | clientId | The client ID of the client that this project is attached to. | | | clientUserIds | The user IDs of the client users attached to this project. | | | elapsedTime | The total elapsed time in hours for the project. | Only available if the Time Tracking module is enabled. | Task Fields | Field | Description | Notes | | --- | --- | --- | | title | The title of the task. | | | notes | The notes for the task. | | | status | The status of the task. | Returns the status text. | | assignedTo | The WordPress user IDs of the owners. | | | milestoneId | The ID of the milestone this task is attached to. | | | startDate | The start date of the task. | Date formatted as YYYY-MM-DD | | endDate | The end date of the task. | Date formatted as YYYY-MM-DD | | progress | The numerical progress percentage. | | | elapsedTime | The total elapsed time in hours for the project. | Only available if the Time Tracking module is enabled. | Milestone Fields | Field | Description | Notes | | --- | --- | --- | | title | The title of the milestone. | | | notes | The notes for the milestone. | | | color | The color of the milestone. | | | progress | The progress % of the milestone. | | | categories | The categories of this milestone. | Returns a JSON array of WordPress term objects. | | assignedTo | The WordPress user IDs of the owners of the milestone. | | | startDate | The start date of the milestone. | Date formatted as m/d/Y | | endDate | The end date of the milestone. | Date formatted as m/d/Y | File Fields | Field | Description | Notes | | --- | --- | --- | | title | The title of the file. | | | description | The description of the file. | | | assignedTo | The WordPress user IDs of the owners of the file. | | | fileId | The WordPress media ID of the file. | Not compatible with private files. | Bug Fields | Field | Description | Notes | | --- | --- | --- | | title | The title of the bug. | | | description | The description of the bug. | | | dueDate | The due date of the bug. | Date formatted as YYYY-MM-DD | | severity | The severity of the bug. | | | status | The status of the bug. | | | assignedTo | The WordPress user ID of the owner of the bug. | | | fileId | The WordPress media ID of the attached file. | Not compatible with private files. | Client Fields | Field | Description | Notes | | --- | --- | --- | | title | The name of the client. | | | phone | The phone number for the client. | | | website | The website for the client. | | | address | The address of the client. | | | userIds | The user IDs of all of the users connected to this client. | Returned as an array | Querying All Items You can query all projects by performing a GET to the projects endpoint. Note, for all of the following you must still pass the fields that you want returned in the query: https://<yourserver>/wp-json/upstream/v1/projects?fields[]=<title> You can query all projects for a certain client by performing a GET to the projects endpoint and passing the client_id in the request: https://<yourserver>/wp-json/upstream/v1/projects?client_id=<client ID>&fields[]=<title> You can query all clients performing a GET to the clients endpoint: https://<yourserver>/wp-json/upstream/v1/clients?fields[]=<title> You can query all milestones, fields, tasks, files, and bugs for a project by querying the corresponding endpoint and passing the project_id in the request: https://<yourserver>/wp-json/upstream/v1/tasks?project_id=<project ID>&fields[]=<title> https://<yourserver>/wp-json/upstream/v1/milestones?project_id=<project ID>&fields[]=<ID> https://<yourserver>/wp-json/upstream/v1/bugs?project_id=<project ID>&fields[]=<status> UpStream API POST You can create an object by doing an HTTP POST to the object URL. When doing this, you must pass the creator user ID in the query string. In addition, in the JSON body of the POST, you must pass the fields that you want to set. For example, you can create a project by POSTing to the following type of URL: https://<yourserver>/wp-json/upstream/v1/projects?creator_id=<creator user ID> You will need to POST a JSON object with the fields that you want to set, but at the minimum, you must pass a title, like this: { "title": "my project" } For tasks, files, and bugs you must pass in the project ID in the GET URL, like this: https://<yourserver>/wp-json/upstream/v1/projects?creator_id=<creator user ID>&project_id=<project ID> You must pass a JSON object in the POST body, with at least the title field filled in. You can pass any other fields as well. For a full list of fields, with rules and parameters, see the PUT section below. UpStream API PUT To modify an object, you can do an HTTP PUT to the object URL. The URL structure is similar to above. For instance, to change a project field, you do a PUT request to: https://<yourserver>/wp-json/upstream/v1/projects?id=<project ID> In the PUT body, you pass a JSON object with the field data, in the form above. For tasks, files, and bugs you must pass in the project ID in the GET URL, like this: https://<yourserver>/wp-json/upstream/v1/tasks?id=<task ID>&project_id=<project ID> You can set individual fields, or you can set multiple fields at the same time. Below is a list of all possible fields and their parameters: Project Fields | Field | Description | Data Type | | --- | --- | --- | | title | The title of the project. | String | | description | The description of the project. | String | | status | The status of the project. | String – must match the name of a status option | | categoryIds | The IDs of the categories of this project. | Array of WordPress taxonomy term IDs. All terms must be from taxonomy ‘project_category’ | | assignedTo | The WordPress user ID of the owner of the project. | Single element array | | startDate | The start date of the project. | Date formatted as YYYY-MM-DD | | endDate | The end date of the project. | Date formatted as YYYY-MM-DD | | clientId | The client ID of the client to attach this project to. | Integer — must be a valid client ID. | | clientUserIds | The list of user IDs from the client that are attached to this project. | An array of user IDs that are already attached to the client. | Task Fields | Field | Description | Data Type | | --- | --- | --- | | title | The title of the task. | String | | notes | The notes for the task. | String | | status | The status of the task. | String – must match the name of a status option | | assignedTo | The WordPress user IDs of the people assigned to the task. | WordPress user ID | | milestoneId | The ID of the milestone this task is attached to. | Integer milestone ID | | startDate | The start date of the task. | Date formatted as YYYY-MM-DD | | endDate | The end date of the task. | Date formatted as YYYY-MM-DD | | progress | The numerical progress percentage. | Integer – UpStream only accepts integer multiples of 5 between 0 and 100. (Example: 0, 5, 10, 15, …) | Milestone Fields | Field | Description | Data Type | | --- | --- | --- | | title | The title of the milestone. | String | | notes | The notes for the milestone. | String | | color | The color of the milestone. | String – HTML color code | | categoryIds | The category IDs of the milestone. | Array of WordPress taxonomy term IDs. All terms must be from taxonomy ‘upst_milestone_category’ | | assignedTo | The WordPress user IDs of the people assigned to the milestone. | WordPress user ID | | startDate | The start date of the milestone. | Date formatted as YYYY-MM-DD | | endDate | The end date of the milestone. | Date formatted as YYYY-MM-DD | File Fields | Field | Description | Data Type | | --- | --- | --- | | title | The title of the file. | String | | description | The description of the file. | String | | assignedTo | The WordPress user IDs of the people assigned to the file. | WordPress user ID | | fileId | The WordPress media ID of the file. You will need to upload the file separately. | Private files are not supported by the API | Bug Fields | Field | Description | Data Type | | --- | --- | --- | | title | The title of the bug. | String | | description | The description of the bug. | String | | dueDate | The due date of the bug. | Date formatted as YYYY-MM-DD | | severity | The severity of the bug. | String – must match the name of a severity option | | status | The status of the bug. | String – must match the name of a status option | | assignedTo | The WordPress user IDs of the people assigned to the bug. | WordPress user ID | | fileId | The WordPress media ID of the attached file. You will need to upload the file separately. | Private files are not supported by the API | Client Fields | Field | Description | Notes | | --- | --- | --- | | title | The name of the client. | | | phone | The phone number for the client. | | | website | The website for the client. | | | address | The address of the client. | | | userIds | The user IDs of all of the users connected to this client. | Passed as an array of IDs. If a user is already added, the user will be ignored. NOTE: This will not currently remove users from a client. | Examples Here are some examples of the API. You will find more examples in the examples/rest_examples.php file in the API module. Get Project Title and Status Request: GET https://my-wordpress-server/wp-json/upstream/v1/projects?id=165&fields[]=title&fields[]=status Response: { "title": "Drawing App", "status": "In Progress" } Set Project End Date and Status Request: PUT https://my-wordpress-server/wp-json/upstream/v1/projects?id=165 Request body: {"endDate":"2021-01-01","status":"In Progress"} Result: Result of performing the above PUT request Result of performing the above PUT request Create a Task in a Project Request: POST https://my-wordpress-server/wp-json/upstream/v1/tasks?project_id=165&creator_id=1 Request body: {"title":"My New Task","notes":"This is a new task created by the API."} Response body: { "id": "15ef602687fe8e" } Result: New task created by the API New task created by the API Deleting Objects Deleting objects is not currently permitted. To avoid issues, you must delete objects from the interface. Using the API Locally UpStream has an easy-to-use local API and object model, which allows you to do nearly anything you can do with the interface, such as creating, editing, and updating tasks, projects, clients, bugs, and time records. The UpStream API module comes with a file under the examples/ folder named local_examples.php. That file contains examples of how to perform most operations using the local UpStream API.

How to Add Additional Users to Status Emails

It is possible to add additional users to status change emails using the Email Notifications addon. This requires programming knowledge, and some understanding of the WordPress filters functionality. To add users, you must implement a filter for upstream_email_status_change_to. You can either do this in an existing plugin, your theme’s functions.php file, or you can use a PHP plugin. This article explains how to do it with a PHP plugin. A basic email example Before doing anything, you will need to install the PHP plugin. Note: be careful when you do this, as there are security implications to having such a plugin on your site. We chose to use Code Snippets, which you can get here. After installing this plugin, you can go to Snippets -> Add New to create a new code snippet. This is where we will add the PHP code to implement the filter. In the Enter title here field, enter a name for your snippet. This can be anything — just make it something understandable. Then, in the Codebox, enter the following: add_filter('upstream_email_status_change_to', function($to, $item) { $to[] = 'me@mysite.com'; return $to; }, 10, 2); Here is the page filled in: image Once you have entered the name of the snippet and the code, make sure to select Run snippet everywhere, and then click on the Save Changes and Activatebutton at the bottom. Now, when you change the status of any item, you will get an email sent to me@mysite.com. Connecting to the API In order to perform more complicated tasks, you will need the API. With the API, you can perform functions like sending an email to a user based on a custom field in a project. You can find a lot more information in the API documentation.

Settings for the Calendar View Extension

There are some settings available for the Calendar View extension. - In your WordPress admin area, go to UpStream > Calendar View. Here you can choose the first day of the week, and the number of weeks to be displayed on the calendar. image

How to Change the Design of the Calendar View Extension

It is possible to customize many of the colors used in the Calendar View. In this tutorial, we’ll show you how to use the settings, without writing any code. If you want to write CSS, this tutorial will also be useful. The Calendar View shows Milestones, Tasks, and Bugs. The colors used for these items are taken from the UpStream settings. image - In your WordPress admin area, go to UpStream > Task Settings. - Here you can change the colors used for Tasks. - The same color options are available in Milestone Settings and Bug Settings. Customizing colors used for the Calendar View If you have the Customizer extension installed, you will also have the ability to customize the design of the Calendar View. - In your WordPress admin area, go to UpStream > Customizer. - Click the “Calendar View” link at the top of the page. Customizer link for the Calendar View - You will now be able to select the colors used in the Calendar View. image

How to Use the Copy Project Extension

If you are using the Copy Project extension for the first time, make sure you have downloaded and installed the extension. These articles will help you get started: - What is an UpStream extension? - How to install an UpStream extension What does the Copy Project extension do? Many UpStream users want to create one project template and then use it for every project. The Copy Project extension allows you do that. This makes it perfect for anyone who uses a standard approach for their projects. At the moment, the Copy Project extension only works in the admin area of your WordPress site. After installing and activating the Copy Project extension, a “Copy” link will appear underneath each project in the WordPress admin area: image Click the “Copy” link and you will see a duplicate version of the project: image That’s it. This is relatively straightforward example, but it does allow you to create a project once and re-use it many times.

Settings for the Copy Project Extension

There are some settings available for the Copy Project extension. - In your WordPress admin area, go to UpStream > Copy Project. These settings define how the new projects will be created, and which data inside the original project will be copied. By default, all of the settings are copied but the “Activity” option is set to “No”. This allows you to create a copy of the project with all the Milestones, Tasks, Bugs etc but without including any of the work done in the original project. image There are two dropdown settings you can’t see in the image above. Here are the options for “Publish Status”: image Here are the options for the “Published On” date: image

How to Lock a Project for Use With Copy Project

One user asked us if it was possible to lock UpStream projects. The idea is to create one project as template that can be duplicated using the Copy Project extension. However, to avoid any major changes to the template, they want to lock the original project. This reduces possibility of errors and unwanted changes. To follow this guide, make sure your site meets these criteria: - The main UpStream plugin is installed. - The Copy Project extension is installed. - You’ve created at least one project. To make it possible to lock projects, we recommend the Post Lockdown plugin. WordPress Post Lockdown project - After installing Post Lockdown, go to Settings > Post Lockdown. - In the left column, look for your projects: UpStream projects being locked in WordPress - If you want to lock a project, move it over to the right column. Locked posts cannot be edited, trashed or deleted by non-admins. UpStream projects now locked in WordPress - Now, when a non-admin user goes to the main UpStream projects page, they will only see “View” and “Copy” link. They have no ability to edit. These projects can now be safely used as project templates. UpStream projects waiting for copying in WordPress - If a non-admin user clicks “Copy” they will create a new version of the project that can be edited. This image below shows the options available to a non-admin for a copied project: image

The Field Types Available With Custom Fields

The Custom Fields extension currently supports 11 field types: 1. Radio buttons 2. Dropdowns 3. Checkboxes 4. File uploads 5. Text 6. Color pickers 7. Tags 8. Categories 9. Autoincrement 10. Countries 11. Users In this documentation article, we’ll show you examples of those field types. Radio Buttons, Dropdowns, Checkboxes These three field types operate in very similar ways. Each field allows the user to make a choice that you define when creating the field. This image shows the three field types in action: image File uploads This field allows you to upload an file. Users will see a file upload box like the image below. When they click “Browse”, they will be able to use the Media Library in WordPress to upload files. File uploads in UpStream Text The Text field provides you with a single-line text box: imageimage Color Picker The Color picker field is shown in the image below. You will see a preview of the selected color, plus the HTML color code. image If you click into the field, you’ll see a color wheel where you can choose the color: image Tags and Categories These fields types allow you to categorize your works. Lots of UpStream users have many Projects, Milestones, Tasks, and Files. These fields types allow you to organize them all. Click here for a full explanation of using Tags and Categories in UpStream. Autoincrement The Autoincrement field type will automatically add a new ID number for new items. image Here are the options for the Autoincrement field: image Here’s an example of the Autoincrement field in action. You can see that each new project is given a number that increases by 1: UpStream autoincrement field Users The Users field allows you to choose from the users on your WordPress site. image In the admin area, you can choose from these settings: image Countries The Countries field allows you to choose from a pre-populated list of Countries. image In the admin area, you can decide whether multiple selections are possible: image

How to Create Tags and Categories as Custom Fields

Tags and Categories are a very popular way to organize content in WordPress. Many WordPress users are familiar with Tags and Categories from writing Post. The Tags and Categories you use in UpStream work in exactly the same way but there’s no overlap. You can create your own categorization just for UpStream. “Categories” and “Tags” are available as menu links in UpStream: new UpStream menu links By default, the Tags and Categories can be applied to Projects. However, if you have the Custom Fields extension installed, you can also add Tags and Categories to Milestones, Tasks, Bugs and Files. Let’s see an example of how this works. - Go to Projects > Tags. - Create several Tags. I’m using Tags releated to Apple products: Tags for an UpStream Projects - Go to Projects > Custom Fields. - Click “New Custom Field”. - Choose “Tag” as the Field Type (you could alternatively choose “Category”). Create a Tag Field Type - On the right-side, choose to use this Field on Tasks. - Click “Publish”. Use Tags fields on Tasks Now, when you go to create a Task, you can add your Tags: add Tags to Tasks in UpStream

How to Use the Customizer Extension

If you are using the Customizer extension for the first time, make sure you have downloaded and installed the extension. These articles will help you get started: - What is an UpStream extension? - How to install an UpStream extension What does the Customizer extension do? The Customizer extension allows you to easily customize the colors and images on the frontend of UpStream. You can use the Customizer extension to add your own logo and colors to the UpStream plugin and extensions. This video is an introduction to the Customizer: Configuring the Customizer settings The Customizer extension adds an extra options page to the UpStream Settings section. - In your WordPress admin area, go to UpStream > Customizer Settings. - You’ll see a set of links across the top of the page. These allow you to drill down and design different areas of your projects. image

How to Add Your Logo to UpStream Projects

The Customizer extension allows you to add your logo to UpStream projects. - In your WordPress admin area, go to UpStream > Customizer Settings. Here you can upload your logo and resize it to fit the screen. image On the front of your site, your logo will appear in the top-left corner of the screen: image

How to Change the Color Scheme for UpStream Projects

The Customizer extension allows you to add your logo to UpStream projects. - In your WordPress admin area, go to UpStream > Customizer Settings. Let’s see a sample color change. This is just an example, but will give you an idea of the power in the Customizer extension. - Change the “Page Background Color” setting. - Click “Save”. image - When you visit the front of your site, the main background of the project area will be blue: image Notice that some areas of the screen still have a light grey background? We can fix that too. - In the Customizer Settings, scroll down to “Sidebar”. - Change the “Background Color” to blue. - Change the “Links Color” to white. image - In the Customizer Settings, scroll down to “Sidebar”. - Change the “Header Color” to blue. UpStream Header Color - Now when you visit the frontend of your projects, the whole screen will be blue. UpStream screen changes color Add your own CSS to UpStream The Customizer extension also gives you the option of adding your own CSS to the project screen. - In the Customizer Settings, scroll down to “Custom CSS”. - Here you can enter your own CSS to customize the frontend display: Custom CSS for UpStream

How to Use the Email Notifications Extension

If you are using the Email Notifications extension for the first time, make sure you have downloaded and installed the extension. These articles will help you get started: - What is an UpStream extension? - How to install an UpStream extension What does the Email Notifications extension do? The Email Notifications extension allows you to send email updates and reminders to people working on your projects The extension is essential for keeping people up-to-date on projects. Users will be automatically notified whenever Milestones, Tasks or Bugs are assigned to them. They can also get reminders when a due date approaches. Set up the default reminders Inside your WordPress admin area, go to UpStream > Email Notifications. Make sure to configure and test the email sending. Here you can choose default reminders for each Milestone, Task and Bug: - A day before - Two days before - Three days before - A week before - Two weeks before If you choose any of these options, they will automatically be applied to all new Milestones, Tasks and Bugs. Reminders will be sent to any users who have been assigned to these Milestones, Tasks and Bugs. default notification reminders in UpStream Under the “Check Recurrency” dropdown, you’ll see these options. On very large sites, choosing a less frequent check will lead to less strain on your server: image Set up reminders for single items You can also customize reminders for individual items. This next image shows the editing screen for a single task. If you have the Email Notifications extension installed, a “Reminders” section will be available. creating customized reminders in UpStream Using this editing screen, you can add custom notifications for just this single task: custom notifications for a single task in UpStream Here’s how the customized reminders will appear on your screen: customized reminders in UpStream What do Email Notifications messages look like? If you assign a Milestone to one of your users, they’ll receive an email like this: image If you assign a Bug to a user, and it’s associated with a Milestone, they’ll receive an email like this: image

How to Ensure Emails Are Sent from the Email Notifications Extension

Before using the Email Notifications extension, it’s important to test the email sending. It can be tricky to send emails from your WordPress site, so we’ve tried to make it easy to test. - In your WordPress admin area, go to UpStream > Email Notifications. You can control the email address that is used when sending the emails: image You can choose to use either of WordPress’s native wp_mail() function or the PHPMailer library using your own SMTP options to send out emails. image If you choose “PHP Mailer with SMTP”, make sure to enter the details below. You will probably need to check with your hosting company for the correct details. image Once you’ve made your choice of Handler, it’s time to test. - Click the “Send Me a Test Email” button at the bottom of the screen. - UpStream will send you a message to the email address used for your account. - Check your inbox. If you receive the email, then everything is set up correctly. If not, go back and try different settings. image

How to Control Your Own Email Notifications

The Email Notifications extension will send emails to users. However, any user is able to unsubscribe from a given project if they don’t want to receive notifications related to that project. Administrators are also able to disable the notifications feature for individual projects. In the WordPress admin area, users can control their notifications from the sidebar of each project: image

How to Customize the Email Notifications Add-on Emails

The Email Notifications extension sends emails from the UpStream plugin. Language in the Emails You can find the language for the content in /wp-content/plugins/upstream-email-notifications/upstream-email-notifications.pot. You can translate this language using this guide. Layout of the Emails You can customize most of the look and content of UpStream notification emails. Status Change Email The default status change email has the subject [website]: [item] Status Change And the body: Hello [user], This email is to notify you that the the following item's status has changed: * [item] changed from [old status] to [new status] — Please do not reply this message. To customize this email, use the following settings under UpStream -> Email Notifications: - Status Change Email Subject– replaces the subject. You can use $TITLE$ to get the title, or $USER$ to get the user name. - HTML Before Status Change Body– replaces the section in RED. You can use either text or HTML, and you can create a whole HTML email by including the HTML headers in this box. You can use $TITLE$ to get the title, $DESCRIPTION$ to get the description, $OLDVALUE$ to get the old status, $NEWVALUE$ to get the new status, or $USER$ to get the user name. - HTML After Status Change Body – replaces the section in GREEN. You can use either text or HTML, and you can create a whole HTML email by including the HTML end tags in this box. You can use $TITLE$ to get the title, $DESCRIPTION$ to get the description, $OLDVALUE$ to get the old status, $NEWVALUE$ to get the new status, or $USER$ to get the user name. - HTML Status Change Body – replaces the section in BLUE. You can use $TITLE$ to get the title, $DESCRIPTION$ to get the description, $OLDVALUE$ to get the old status, $NEWVALUE$ to get the new status, or $USER$ to get the user name. User Assignment Email The default status change email has the subject [website] Notifications | [project] And the body: The following item(s) was/were assigned to you: [item type] [item] [item type 2] [item] — You are receiving this because you are a member of the [project] project, from [site]. Please do not reply this message. To customize this email, use the following settings under UpStream -> Email Notifications: - User Assignment Email Subject– replaces the subject. You can use $PROJECT_TITLE$ to get the project title, or $USER$ for the user name. - HTML Before User Assignment Body– replaces the section in RED. You can use either text or HTML, and you can create a whole HTML email by including the HTML headers in this box. You can use $PROJECT_URL$ to get the project link URL, $PROJECT_TITLE$ to get the project title, or $USER$ for the user name. - HTML After User Assignment Body – replaces the section in GREEN. You can use either text or HTML, and you can create a whole HTML email by including the HTML end tags in this box. You can use $PROJECT_URL$ to get the project link URL, $PROJECT_TITLE$ to get the project title, or $USER$ for the user name. - HTML User Assignment Item Body – replaces the section in BLUE. This repeats for each item. You can use $TITLE$ to get the title of the item, $DESCRIPTION to get the description. Reminder Email The reminder email has the subject [website] Notifications About Upcoming Due Dates And the body: Hello [user], This email is to remind you about the following due dates: [project] [item type] [item] ([due date]) [item type 2] [item] ([due date]) — Please do not reply this message. To customize this email, use the following settings under UpStream -> Email Notifications: - Reminder Email Subject– replaces the subject. You can use $USER$ to get the user name. - HTML Before Reminder Body– replaces the section in RED. You can use either text or HTML, and you can create a whole HTML email by including the HTML headers in this box. You can use $USER$ to get the user name. - HTML After Reminder Body – replaces the section in GREEN. You can use either text or HTML, and you can create a whole HTML email by including the HTML end tags in this box. You can use $USER$ to get the user name. - HTML Reminder Item Body – replaces the section in BLUE. This is repeated for each item assigned. You can use $TITLE$ to get the item title, $DESCRIPTION$ to get the description, and $DATE$ to get the due date.

How to Use the Frontend Edit Extension

If you are using the Frontend Edit extension for the first time, make sure you have downloaded and installed the extension. These articles will help you get started: - What is an UpStream extension? - How to install an UpStream extension What does the Frontend Edit extension do? The Frontend Edit extension allows you and your Clients to update projects via the frontend of your site. You can add and edit Tasks, Bugs, Files and Discussions directly within any Project. Without the Frontend Edit extension, all updates to UpStream projects will have to be done via the WordPress admin area. This video is an introdution to Frontend Edit: How to use the Frontend Edit extension After installing and activating the Frontend Edit extension, new buttons will appear on the frontend that allow logged in users to easily edit, delete or add new items. The extension also allows users to upload to the “Files” area of their UpStream project. Without this extension, no frontend editing is possible for UpStream projects. This image shows a default UpStream project: image In the image below, these buttons are added by the Frontend Edit extension: - The blue “Add Task” button in the top-right. - The pencil icon next to each item. image - If you click the blue “Add Task” button, or the pencil icon, you’ll see a pop-up window where you can update the project: image - With the Frontend extension, users can also upload files via the frontend of the site: image

Create and Edit Projects From the UpStream Frontend

The Frontend Edit extension gives you the the ability to create and edit projects from the frontend of your site. Creating projects from the frontend On the main /projects/ page of UpStream, you will see an “Add project” button. Add new projects in UpStream Click the “Add project” button and you’ll see a pop-up that allows you to create a new project. Here you can also choose many of the most important project settings: Choosing settings for new projects in UpStream Editing projects from the frontend On the frontend of UpStream with the Frontend Edit extension installed, you will see a pencil icon on the /projects/ page. This will allow you to edit the details for individual projects: Editing icon for projects in UpStream This pencil icon is also available on single project pages: Pencil editing icon for projects in UpStream If you click on either of these pencil icons, you’ll be able to edit the same details as when you create a project. Permissions These new creating and editing features are controlled by two permissions. - publish_projects: controls who can create new projects - edit_projects: controls who can edit projects The best way to control these (and other UpStream permissons) is with a plugin like Members. This plugin is free and allows you to completely customize the permisson in UpStream. Permissons for projects in UpStream

How to Use the Project Timeline Extension

If you are using the Project Timeline extension for the first time, make sure you have downloaded and installed the extension. These articles will help you get started: - What is an UpStream extension? - How to install an UpStream extension What does the Project Timeline extension do? The Project Timeline extension allows you to add a Gantt-style timeline chart to your projects. This video introduces you to the Project Timeline: With the Project Timeline extension you can view your project Milestones and Tasks in a beautiful timeline. This helps you see at a glance how your project is progressing. project timeline Milestones and Tasks are shown in a hierarchy with the first Milestone at the top. All the Tasks belonging to that Milestone directly beneath it. In this example, “Development” is the name of the Milestone, and there are 3 tasks underneath: image The user that is assigned to each task will also have their image displayed on the timeline so you know exactly who is doing what at a glance. Click here to add an avatar for each user. The Project Timeline shows color-coded Milestones and Tasks, with the progress represented as a small green progress bar beneath each item. image Hovering over each bar in the timeline will popup with a more detailed view of that particular task or milestone which shows the start & end dates, progress, who the item is assigned to and which Milestone the Task belongs to, all presented in a beautiful looking timeline chart. This video is a quick-start guide to using the Project Timeline:

How to Change the Design of the Project Timeline

It is possible to customize many of the colors used in the Project Timeline extension. The Project Timeline shows Milestones and Tasks. The colors used for these items are taken from the UpStream settings. - In your WordPress admin area, go to UpStream > Task Settings. - Here you can change the colors used for Tasks. image You can also customize the color of Milestones. To do this, go to Projects > Milestones and edit the “Color” option: image