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


A0htc1dPG8qrDVZfGs8OwRpor4tpkbOjkQ.png



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, m
ake 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.


Q1-V9UjT95klWC339c5QuegVpU0grGuoMQ.png


Next, click the SHARE button in the upper left of your Studio. Then Configure the Share with User fields to fit your purpose.


37cggOelQtBepHNQaQ6CmSN4b5WHIDh49A.png


Write Privileges


Write privileges give permission to work on the STAGE version of the item. So if someone with write privileges publishes changes to stage the staged version updates. (This is different than a public component available in EXPLORE, as explained below.)

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

Beware the merge conflict! When two or more users with write privileges (which includes the creator), you may be working on the item at the same time. One person may end up publishing changes to stage while another person made changes to the prior staged version. If that second user tries to publish changes to change there will be a merge conflict. If that second person tries to update from stage, the system will return an error. 

So, one way to collaborate is to share with write privileges, and then the recipient should duplicate the item in their Studio. Just "Save-as" with the drop-down in the upper right. Then you can make changes to a second copy in their Studio, publish that to Stage, and share it with you.

If you ever see Publish Changes to Stage and Update from Stage both lit-up in magenta at the same time then there's a merge conflict. In order not to lose your work, make a duplicate. Then contact support for help. 

Going "Public"

By default, your stuff is "Private." It only appears in your Studio and Stage unless you've shared it with a particular user.

You can also make your item "Public." Public means it will appear on the EXPLORE page for any user to add to their Studio. If making an item public, you have two options - closed or open source. 

Open source means other users will be able to see everything about the item and make changes to the version in their Studio. They have to make a copy though. So the recipient can never change the original pulled from Explore or touch your source code.

Closed source means they will be able to use it but not see under the hood. So, a closed source xap can only be run. The dataflow is not viewable or editable. A closed source component can be used in a xap, but the script can't be viewed.

KIh43PIuk3oAfpg8YUNeCxmkU5YPCj7E8Q.png



Some Differences Between "Sharing with User" and "Change Privacy Level" 


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.


Selecting a Numeric Version to Use 


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. 


rd_wqz0453U1zlO9QEABs0cw3RIkZ053iQ.png

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.