Your GIS becomes much more powerful if it can connect to other GIS organizations and seamlessly share content. With a distributed collaboration, you can connect and integrate your GIS across a network of GIS organizational participants. If an ArcGIS Online is to participate, it must serve as a distributed collaboration host, and then any number of ArcGIS Enterprise GIS organizations can be invited to participate. See a comprehensive list of considerations for creating a distributed collaboration for more details. The benefit of establishing a distributed collaboration is to organize, network, and share content, particularly for ArcGIS Enterprise deployments, between individuals and across organizations and communities.
During the process of establishing a collaboration, you link either a new or existing group with a collaboration workspace. The content you share to that group becomes automatically available to your participants and vice-versa. Visit the key concepts page for details about how distributed collaborations work.
Creating a collaboration involves a sequence of steps. You can either follow them yourself if you need fine-grained control, or, if you are an administrator on both the host and participant GIS, you can call the shortcut referred in the end of this guide to create a collaboration in one simple step.
- Host GIS creates a collaboration. This step involves choosing a workspace and a group intended for sharing content.
- Host GIS invites a participant GIS to the collaboration. This step involves downloading an invitation file and sending it over to the recipient GIS's administrator in a secure manner.
- Guest GIS accepts the invitation. This step involves downloading a response file and sending it over to the host GIS's administrator in a secure manner.
- Guest GIS joins a group to the workspace (created as a result of accepting the invitation) where it will receive and share content with the host.
- Host GIS accepts the response to complete the collaboration loop.
Administrators can customize collaborations by adjusting the synchronization frequency, whether the guest can send / receive content or do both. A GIS can participate in a collaboration with any number of hosts and guests. This way you can construct a network of interconnected, distributed GIS systems and allow data to be shared between them.
from arcgis.gis import GIS#connect to host GIS, which in this case will be an ArcGIS Online organization
host_gis = GIS("https://www.arcgis.com", "username")Enter password: ········
#connect to guest GIS, in this case this is an ArcGIS Enterprise organization
guest_gis = GIS("https://guest-portal.company.com/portal", "username")Enter password: ········
Step 1: Create a collaboration
To create a collaboration, call the create() method from admin.collaborations. During this process, you choose a name and description for the collaboration workspace, choose a group to be associated with the workspace and a contact person. If you do not have a suitable group, you can create one as shown here.
In this guide, we establish a collaboration between the Transport and Police departments in a hypothetical city.
#search for the traffic analysis group in host gis
host_group = host_gis.groups.search("Traffic")[0]
host_group
#create a collaboration
description='Data sharing initiative between Dept.' + \
'of Tranportation and Police of the city of Philadelphia'
host_collab = host_gis.admin.collaborations.create(name='Philly Police Dept. + Dept. of Transport',
description=description,
workspace_name='Philly Police Transport data sharing',
workspace_description=description,
portal_group_id=host_group.id,
host_contact_first_name='Traffic',
host_contact_last_name='Chief',
host_contact_email_address='traffic.chief@city.gov',
access_mode='sendAndReceive')
host_collab{'collaborationHostPortalId': '44532675-b386-49e9-abe9-fea4a16a5177',
'config': {'ownerUsername': 'admin'},
'created': 1502225631271,
'description': 'Data sharing initiative between Dept.of Tranportation and Police of the city of Philadelphia',
'id': 'a607c633adb0488992bdcef1f7ba1a18',
'modified': 1502225631271,
'name': 'Philly Police Dept. + Dept. of Transport'}Step 2: Invite participant GIS to the collaboration
You can invite one or more participants by calling the invite_participant() method of the collaboration object. At this stage, you specify the workspace id and the privilege each participant has. Note, you can have multiple workspaces within a collaboration.
To call the invite_participant() you need to compose a list of dictionaries containing the collaboration ids and the privileges for the participant in each of these workspaces. This pattern allows a participant GIS to be a member of multiple workspaces within the same collaboration, with different permissions to share and receive content in each.
As a response, you get an invitation file which you can send the guest GIS in a secure manner. You can call this method multiple times to invite different participants.
#get the list of workspaces available as part of the collaboration
host_collab.workspaces[{'collaborationId': 'a607c633adb0488992bdcef1f7ba1a18',
'config': {'maxItemSizeInMB': 50, 'maxReplicationPackageSizeInMB': 100},
'created': 1502225631858,
'description': 'Data sharing initiative between Dept.of Tranportation and Police of the city of Philadelphia',
'id': '4d1e3e7d44f24fbca49c4f11975e3184',
'modified': 1502225631858,
'name': 'Philly Police Transport data sharing',
'participantGroupLinks': [{'accessMode': 'sendAndReceive',
'config': {'copyFeatureServiceData': False, 'enableRealtimeSync': True},
'portalGroupId': 'ee1b101fef7b4fa483c66c54971c6005',
'portalGroupName': 'Traffic incident analysis',
'portalId': '44532675-b386-49e9-abe9-fea4a16a5177'}],
'participantsWithoutGroupLinks': []}]#compose the list of collaboration workspaces and the privileges for each
config = [{host_collab.workspaces[0]['id']:'sendAndReceive'}]
#invite the guest GIS and download the invitation file
invite_file = host_collab.invite_participant(config_json= config, expiration=24,
guest_portal_url = "https://guest-portal.company.com/portal",
save_path=r'E:\gis_projects\collab')
#print the path to the invite file
invite_file'E:\\gis_projects\\collab\\collaboration-dev005223.esri.com.invite'
Step 3: Accept the invitation at the participant GIS
To accept an invitation, call the accept_invitation() method on the admin.collaborations object. During this stage, you specify a corresponding contact person in the Guest organization and the invite file, either as a JSON text or as a file on disk. After accepting, you call the export_invitation() to download a response file that you can send the administrator of the host GIS in a secure manner.
guest_gis.admin.collaborations.accept_invitation(first_name='Police',
last_name='Chief',
email='police.chief@city.gov',
invitation_file=invite_file){'success': True}Get the Collaboration object created as a result of accepting the invitation
#get the list of collaborations on the guest GIS and pick the one created earlier
guest_gis.admin.collaborations.list()[{'collaborationHostPortalId': '44532675-b386-49e9-abe9-fea4a16a5177',
'config': {'ownerUsername': 'admin'},
'created': 1502150029661,
'description': 'auto collaborations',
'id': '2570cc95b1b2415eb95b84ba2f720506',
'modified': 1502150029661,
'name': 'collab_high_level_collab'},
{'collaborationHostPortalId': '44532675-b386-49e9-abe9-fea4a16a5177',
'config': {'ownerUsername': 'admin'},
'created': 1502225679791,
'description': 'Data sharing initiative between Dept.of Tranportation and Police of the city of Philadelphia',
'id': 'a607c633adb0488992bdcef1f7ba1a18',
'modified': 1502225679791,
'name': 'Philly Police Dept. + Dept. of Transport'}]#in this case, there are two collaborations and the second is the relevant one
guest_collab = guest_gis.admin.collaborations.list()[1]
type(guest_collab)arcgis.gis.admin._collaboration.Collaboration
Export the response file
Now export a response file that can be sent back to the host GIS
response_file = guest_collab.export_invitation(out_folder = r"E:\gis_projects\collab")
response_file'E:\\gis_projects\\collab\\collaboration-dev005223.esri.com.response'
Step 4: Join a group to the collaboration in the guest GIS
After the guest GIS accepts a collaboration from a host, a workspace gets created. You need to add a group to this workspace by calling the add_group_to_workspace() method from the Collaboration object.
#first get the list of worksapces in the guest collaboration
guest_collab.workspaces[{'collaborationId': 'a607c633adb0488992bdcef1f7ba1a18',
'config': {'maxItemSizeInMB': 50, 'maxReplicationPackageSizeInMB': 100},
'created': 1502225680547,
'description': 'Data sharing initiative between Dept.of Tranportation and Police of the city of Philadelphia',
'id': '4d1e3e7d44f24fbca49c4f11975e3184',
'modified': 1502225680547,
'name': 'Philly Police Transport data sharing',
'participantGroupLinks': [{'accessMode': 'sendAndReceive',
'config': {},
'portalId': '44532675-b386-49e9-abe9-fea4a16a5177'}],
'participantsWithoutGroupLinks': [{'accessMode': 'sendAndReceive',
'config': {},
'portalId': '9f9a15e0-97c9-4020-8e0b-906ba628668a'}]}]#search for the crime analysis group in the guest portal
guest_group = guest_gis.groups.search("crime")[0]
guest_group
guest_collab.add_group_to_workspace(portal_group = guest_group,
workspace= guest_collab.workspaces[0]){'success': True}Step 5: Accept the collaboration response at the host GIS
Since the guest GIS accepted the collaboration request and created a response file, to finish the loop, the host GIS has to accept this response. You can do this by calling the import_invitation_response() method from the Collaboration object of the host GIS.
host_collab.import_invitation_response(response_file){'success': True}Shortcut to establish collaborations in a single step
While the above 5 steps provide a lot of options to customize collaborations, administrators can establish collaborations easily by calling the collaborate_with() method off admin.collaborations object. This shortcut internally performs thes 5 steps and is suitable if you are the administrator on both the organizations and want to create a collaboration using the default values.
This method accepts a name and a description. It creates a new group using the format grp_ + <name> in both the host and the guest and a workspace called wksp + <name> in both the host and guest GIS. The default privilege is sendAndRecieve.
To establish a collaboration, simply call:
host_gis.admin.collaborations.collaborate_with(guest_gis = guest_gis,
collaboration_name='Transport_PD_data_sharing',
collaboration_description='Data sharing initiative between' + \
'the transport and Police departments')True
You can verify the collaboration by querying the host and guest GIS
print("Collaborations on host GIS")
for collab in host_gis.admin.collaborations.list():
print(collab.name)
print("-----------------------------")
print("Collaborations on guest GIS")
for collab in guest_gis.admin.collaborations.list():
print(collab.name)Collaborations on host GIS collab_high_level_collab Philly Police Dept. + Dept. of Transport collab_Transport_PD_data_sharing ----------------------------- Collaborations on guest GIS collab_high_level_collab Philly Police Dept. + Dept. of Transport collab_Transport_PD_data_sharing
Use a collaboration
You can share content with other collaborators by sharing it to the group associated with your collaboration workspace. See Share content with collaboration groups for details.