This article covers how to share xaps, components, or assets with other people in the City. It also explains how version control works while sharing, so that you can safely work on different versions of the same item at the same time. (You can also read up on previewing, running, and publishing xaps and embedding xaps in a separate web page to learn how to share xaps outside of the City.
Here's a cheat sheet for addressing specific tasks. You can also use it to find the explanations below that are applicable to you.
- Share with one user at a time - 1) "Save & Publish." 2) Publish a numeric version or "No Version Change." 3) Select the version you want to share with the dropdown below the name of the item. 4) Click SHARE and configure "Share with User" with the appropriate privileges.
- Share with all Studio users - 1) "Save & Publish." 2) Publish a numeric version or "No Version Change." 3) Select the version you want to share with the dropdown below the name of the item. 4) Click SHARE and configure "Change Privacy Level" with appropriate settings.
- Simple version control for yourself - "Save-as" in the dataflow.
- Create numeric versions - 1) "Save & Publish." 2) Publish a numeric version.
- Selecting a component version for use - 1) Bring the component into the dataflow. 2) Double-click the component to expand it. 3) Use the dropdown below the component's name to select the version.
- Selecting a xap version for use - 1) Find the xap in your Studio. 2) Click on the xap (the image or name) to open its info page. 3) Use the dropdown below the xap's name to select the version.
The Setup: Studio, Stage, and Numeric Versions (a.k.a. Versioning)
Your Studio is where you build stuff. The Stage is where you share stuff. When you publish something to Stage it creates another version. There is then one version in your Studio and another on Stage. You can share and collaborate on the Stage version in several ways. (Learn more below.) Meanwhile you remain the only user who can work on the version in your Studio.
You can also create numeric versions - major, minor, and patch. These are snapshots of a component or xap, frozen in the state they are in when the numeric version gets created. The value of numeric versions, as we'll explain, is that they enable users of what you make to avoid updates that might break their stuff.
Using the save drop-down menu in the upper right of the Studio, select "Save & Publish." You will be asked to define either a numbered version or "no version change." "No version change" publishes the latest version to STAGE.
When you create a numeric version, the Stage version still exists. If you edit the item, click "Save & Publish" and then select "No Version Change," the Stage version changes. The numeric version remains a static snapshot of what it was when you created that version. It bears repeating. The numeric version is just a snapshot created when you hit that Create Version button. When you make further changes and publish them to stage, the Stage version is what gets updated.
NOTE: Take advantage of release notes to help identify the significance of your various versions!
Sharing with Other Users, One at a Time
After publishing to Stage or creating a numeric version, you can share your work with the privileges - read or write - that make sense for your purpose. To share with the goal of just getting feedback on your Xap or Component give 'read' privileges. The user can run your Xap or use the Component in a xap but can't make changes.
NOTE: Read privileges for a Xap means they can view and use the front-end. The recipient can't view the dataflow. Currently there is not an option for letting someone else view the dataflow without also giving full editing - 'write' - privileges. Let us know if this would be a useful feature for you!
To share, make sure you've saved whatever you want to share and published changes to Stage or created a numeric version. Find the dropdown menu in the upper left below the name of the item. Select the version you want to share.
Next, click the SHARE button in the upper left of your Studio. Then Configure the Share with User fields to fit your purpose.
Write Privileges for Xaps: What are the Implications on Components in the Xap?
Write privileges for a xap just means the recipient can edit the dataflow, not the components. To be edited, the components would have to be shared separately or come from the EXPLORE page and be open source.
Merge Conflict and Duplicate in Studio
Sharing with Write Privileges v. Making it Public-Open Source
Sharing write privileges with another user gives that user permission to change your versions. Sharing write privileges with another user gives that user the power to make changes to your Staged version. While they work on it in their studio, it's a separate copy from the Staged version, but they have the ability to publish changes to the Staged version. Making your stuff public lets someone else pull a copy to their Studio, but they cannot update the Staged version you possess. If it is open source, they can create a new Staged version of their own and publish that to EXPLORE though.
Sharing with Read Privileges v. Making it Public-Closed Source
Sharing read privileges with individual users is very similar to making something public-closed source. The difference is just that in the former you select with whom to share. In the latter, its available on EXPLORE for anyone to add a copy to their Studio.
Changing a Public-Open Source Component
To make changes to an Public-Open Source component you need to make a copy. You add the item to your Studio. Then you duplicate it from the dashboard, or save as from the dataflow. You can than edit the copy.
Simple Version Control
"Making Copies" - Rob Schneider (SNL)
For any item you can create copies in your own Studio by saving-as with the drop-down in the upper right. Like with any other file manager, you can rename it and keep it separate. This is a simple way to enforce version control for yourself, but it can soon get unwieldy. Remember, there is a Stage version and Studio version. You can then make copies to work with in different ways, if you want.
Using a Particular Version of a Component
When you add a component with a numeric version to your Studio - whether shared with you directly or made public on the Explore page - you are using the Stage version. This is the default, and if you do not change it, then the item is subject to any update made by the owner of the component that he or she publishes to Stage. Changes could conflict with how you're using the xap or component and cause a failure. To prevent this, you select a numeric version to use.
Once the component is in your dataflow, double click on the component to expand it. Select your desired version with the dropdown menu below the component's name. This swaps the staged version for the version you chose, and the version will not change. View the notes in the info page of the component to help decide what version you want.
If you're using an out-dated numeric version of a component, say 1.0.0, but you want to update to 1.0.1, there are two ways:
- Use the dropdown menu again to select a different version.
- Add a new copy of the component to the dataflow, select the version you want, and wire it into the xap.
As you'll see, you can select Stage or Studio versions as well. They are separate versions.
Using a Numeric Version of a Xap
Find the xap in your Studio. Open the xap's info page by click on it (the image or name). Select the version you want with the dropdown menu below the xap's name.
NOTE: The same process applies to the creator that is described below for choosing versions of a xap or component for use. Even for the creator, a numeric version is a snapshot that can't be edited.