Talk me through portal projects

Have you ever wanted to work together with your colleagues on an ArcGIS Pro project? Simultaneously—without the project being read-only for others while you have it open? Or without having to assemble a final project from pieces of different projects worked on by many people?

If so, then you’ve been waiting for portal projects. You and your colleagues can work on the same project at the same time (and different times, of course) and have your changes uploaded and downloaded as you work. Your team can be in adjacent offices or in different cities as long as you all belong to the same ArcGIS Enterprise organization.

If that sounds appealing, you may have questions like these:

Do I need a special license for portal projects?

No—but you do need ArcGIS Pro 3.5 and membership in an ArcGIS Enterprise organization on a portal of version 11.4 or later. To create or modify a portal project, your role in the organization has to allow you to create content.

Note that you can’t create or use portal projects in an ArcGIS Online organization. That may be possible at a later date.

Is working on a portal project like sharing a Word document on OneDrive?

No, that’s not really a helpful analogy. The first time you open a portal project, the project is downloaded from the portal to your computer. You do your work in that locally downloaded copy, uploading and downloading changes whenever you save.

Consider an example where Chris, Aleta, Vishwesh, and Naicong are collaborating on a portal project. Each of them works independently in their own downloaded local copy.

When Aleta finishes some work on a map and saves the project before lunch, her changes are saved to her local copy and uploaded (pushed) to the portal. Once her upload is completed, any changes that have been pushed to the portal by others are downloaded (pulled) to her local copy.

And the same goes for everyone else?

Right. When Naicong saves the project an hour after Aleta, her changes are saved to her own local copy and then pushed to the portal. At that point, Aleta’s previous changes (along with changes that Chris or Vishwesh uploaded) are pulled down to Naicong’s local copy.

In this way, everybody’s local copy of the project is synced with the portal each time they save. Changes are pushed and pulled only when you save. So, for instance, if Aleta doesn’t work on the project for a week, she’ll pull a week’s worth of changes from the portal the next time she opens and saves the project.

It sounds like the project file gets copied back and forth a lot.

Not so. In fact, there’s no .aprx file as such on the portal—just a collection of .json and .xml files that together make up the definition of the project. You can think of these files as instructions for building and updating the project.

The first time you open a portal project, this collection of files is downloaded and used to create an .aprx file on your computer. That’s your local copy of the project.

When you make changes to the local copy and save the project, what gets pushed to the portal is not the .aprx file itself—just the extracted .json and .xml files that represent your changes. Likewise, what gets pulled from the portal are only the files that represent changes made by other users.

Once the local copy is created on your computer, you always work from it. The complete portal project isn’t downloaded to your computer again, unless for some reason you decide (or need) to replace your local copy. This operation is called getting updates from the portal, and there are times when it’s useful. (The name is a little misleading because you actually get everything from the portal when you get updates.)

What if my colleague’s changes collide with mine?

Hopefully that doesn’t happen too often. (If it does, you should have a chat with your colleagues.) When it does happen, there’s a procedure for resolving conflicts.

Suppose Chris is working in a portal project called Our Town. He adds a Parks layer to the Zoning map. He also tweaks the legend in the Orange Grove layout. When he saves his local copy of the project, his changes are pushed to the portal. No conflicts at this point. The Zoning map on the portal (technically, the .json file that defines the Zoning map) now contains the Parks layer. Likewise, the Orange Grove layout has his modified legend.

Meanwhile, Vishwesh is working in his local copy of the project. His Zoning map doesn’t have the Parks layer. Suppose he changes the basemap of the Zoning map from Topographic to Imagery. That’s all he does. Now, when he saves the project, he has a conflict. Why? Because Chris just changed this map on the portal and now Vishwesh is changing it again. It’s kind of like two generals giving a soldier different orders. Vishwesh has a choice:

• He can push his change to the portal. That will wipe out the Parks layer Chris added.
• He can pull Chris’s change from the portal. That will add the Parks layer to Vishwesh’s local copy but wipe out his basemap change.

Let’s say Vishwesh decides to push his change. When he closes the Project Conflicts dialog box, the change is saved to his local copy and uploaded to the portal. The Zoning map on the portal now uses the Imagery basemap but doesn’t include the Parks layer.

Chris’s change to the Orange Grove layout, on the other hand, stays on the portal because it didn’t conflict with Vishwesh’s work. (Vishwesh didn’t touch the layout.) That means that the layout change is pulled from the portal to Vishwesh’s local copy of the project.

Why does adding a layer conflict with a basemap change?

Conflicts are detected and resolved at the level of the project item: that is, at the level of the map, layout, report, or presentation. So when Chris and Vishwesh both change the Zoning map—even though their changes seem compatible—it causes a conflict.

Only one user’s representation of the Zoning map (or any other project item) can exist on the portal. It can either be Chris’s, with the Parks layer and the original Topographic basemap, or Vishwesh’s, with the Imagery basemap but no Parks layer.

During conflict resolution, Vishwesh can’t see Chris’s changes and doesn’t know what they are. All he knows is that Chris made changes to the Zoning map and uploaded them to the portal before him.

Of course, he can send Chris a message on Teams or maybe even walk down the hallway and ask him what he did. A certain amount of communication with your colleagues is important in portal project workflows.

Do things ever go wrong when you push or pull changes?

Sure, that can happen. For example, you might lose network connectivity in a sudden power outage while changes are being uploaded or downloaded. These save failures can usually be fixed by resaving the project when connectivity is restored.

It’s more serious if a failure occurs not just during the transport stage of an upload, but while the changes are in the midst of being written to the portal project. In that case, the portal project is corrupted and has to be overwritten with a saved copy.

By default, every collaborator has three automatically saved copies of the project in addition to their working local copy. These copies represent the user’s three most recently saved states of the project. For example, Naicong’s saved copies of the Our Town project might be from 4:01 p.m., 5:21 p.m., and 5:24 p.m. on a particular day. If the portal project needs to be overwritten, it can be done with any saved copy belonging to any user.

If a failure occurs while a download is in the midst of being written to your local copy of the project, that’s not such a big deal. ArcGIS Pro fixes this problem for you by automatically getting updates from the portal—that is, by overwriting your local copy with the portal project.

What if my colleague and I save the project at the same time?

That can’t actually happen. Someone is always first, even if it’s just by a little. When Aleta, for example, saves the project, the project is locked until her upload and download are complete. Other people can keep working in their local copies of the project, and save their changes locally, but no one can upload to the portal until her save is finished. Normally, the wait is just a matter of seconds, but it may be longer if Aleta is in the process of resolving conflicts—conflict resolution is part of the save operation.

Optionally, before you save, you can check whether the project is currently locked (and if so, by whom) on the Info page in the ArcGIS Pro settings. The Info page also shows you who owns the project and who saved it last. You can even access the project’s complete save history.

More information about the project, like its sharing properties and delete protection status, is available on the portal. This is the same information you can get for any portal item.

So how do I create a portal project?

The first part is like creating any new project, except that the project location is My Content on your ArcGIS Enterprise portal.

After you name the project, there are additional steps to complete. A wizard guides you through the configuration. (When you’re familiar with the process, you can turn the wizard off and use a dialog box instead.)

The first step is to choose a collaboration style. Not all portal projects are collaborative. You can create one for your own personal use on multiple computers, or for personal use on a single computer. You might do this, for instance, to give other people in your organization view access to the project even though you’re the only one working on it.

The collaboration style you choose affects your next settings.

In a new local project, a file geodatabase and toolbox are created automatically by default. In a portal project, however, you either create these items yourself or browse to existing ones you want to use. This is where the collaboration style is relevant. If the project is for your own use, the default geodatabase can be a file or mobile geodatabase. In a collaborative project, it has to be an enterprise geodatabase to support multiuser workflows.

Similarly, in a collaborative project—or one for your own use on multiple computers—the home folder, default geodatabase, and default toolbox need to be located on a network share.

Whether you create the project using the wizard or the dialog box, ArcGIS Pro validates your settings to make sure they’re appropriate for the collaboration style.

Is sharing a portal project like sharing a web map or web layer?

Pretty much so, but with a special requirement. Sharing the portal project to your organization (or to an ordinary group) allows users to open and view the project—but not to save changes to it. The only people who can save changes to a collaborative project are members of a specified shared update group. Valeria’s blog post on shared update groups and portal projects explains this in more detail.

Can I save my existing local projects as portal projects?

Yes. You can use the Save Project As command—the same one that’s always been in ArcGIS Pro—to save local projects as portal projects. You can also save a portal project as a local project or as a new portal project.

Note that you can’t just drag an .aprx file from your computer to the portal and turn it into a portal project. As mentioned above, in a portal project there’s no actual .aprx file on the portal.

Anything else I should know?

Lots of details, but nothing to hold you back from experimenting. See the product documentation, linked in some of the questions above, or start with the overview topic Portal projects in ArcGIS Pro for more information.