As described in Getting Started, you access Agile Documents by opening up the Agile Documents app in SharePoint. This establishes a secure connection between Agile Documents and SharePoint and then navigates you to Agile Document's SharePoint Explorer. You may then access all of Agile Document's functionality through SharePoint Explorer. Once installed [on any SharePoint web], Agile Documents can securely integrate with the entire SharePoint site collection. Therefore, you do not need to install [and Trust] Agile Documents on each SharePoint site in the site collection, which can be a very cumbersome process. You may opt to install it only once.

However, you may wish to provide direct access Agile Documents functionality in other SharePoint webs within the site collection. You may also wish to surface Agile Documents functionality within other platforms beyond SharePoint--such as any HTML web page or an email. In order to accomplish this, we leverage SharePoint's built in mechanism to launch Apps--which actually functions as a web page forwarder (Figure 1). We are not short-cutting the security features built into SharePoint. In fact, in order to access the SharePoint App launch page, you need to have already have authenticated (logged into) with said SharePoint site. If you haven't, SharePoint will force you to login upon attempting to browse to the SharePoint App URL....unless you have specifically configured anonymous access for the site.

This section details the formulation of URLs to directly access Agile Document's functionality. Not only do we discuss ways to access Agile Document's SharePoint Explorer, but we also discuss direct connections to edit, build and manage Agile Documents.

Apps are launched from SharePoint via a generalized URL. It takes the form https://[REPLACE_WITH_YOUR_SERVER_NAME].SharePoint.com/sites/[REPLACE_WITH_SOME_SITE]/_layouts/15/appredirect.aspx?client_id=[REPLACE_WITH_CLIENT_ID]&redirect_uri=[REPLACE_WITH_REDIRECTION_URL]. We use this generalized URL to launch directly into Agile Documents. The Client ID for Agile Documents is 40fe2694-b808-4cf4-8955-edf1a7645e3a. We use the redirection URL to specify which area of Agile Documents to navigate to.

Please note that the query string parameters need to be URL Encoded. There are plenty of URL Encoding web tools you can find from Google to encode your own URLs for use here.

But, with that said, Agile Document API-URL functionality is rapidly available through the SharePoint Explorer UI. In what follows, we first explain how you can use the SharePoint Explorer UI to mouse click your way to generate these specific URIs. We then proceed with a more technical discussion of how these URLs are constructed so that you can dynamically generate them yourself if needed.

---

Generating API URL's with SharePoint Explorer

You can use right-click menus in SharePoint Explorer to generate API URLs. As mentioned above, these URLs link directly to functionality within Agile Documents. This provides a rapid way to obtain a URL to surface various Agile Document functions in any web page.

The API URLs can generated from right-clicking on a web, content item or Agile Document. The right-click menu of web (Figure 1) allows you to generate a URL to SharePoint Explorer (Figure 2). The right-click menu of a content item (Figure 3) allows you to generate a URL to the content relationships report for that content item. Finally, the right-click menu of an Agile Document (Figure 4) allows you to generate a URL to the content relationships report as well as a direct link to build or edit said Agile Document.

Of course, the URLs from SharePoint Explorer may not be sufficient and you man need to tweak them as appropriate. However, generally, the API URLs from SharePoint Explorer provide an excellent start to sufacing Agile Document's functionality in your custom HTML page.

SharePoint Explorer API URL

The URL to SharePoint Explorer is https://agiledocweb-dev.azurewebsites.net/AgileDocuments/SharePointExplorer and requires a handful of querystring parameters. Using the example my.SharePoint.com/sites/SomeSite, we can access Agile Document's SharePoint explorer via the following URL:

https://my.sharepoint.com/sites/SomeSite/_layouts/15/appredirect.aspx?client_id=40fe2694-b808-4cf4-8955-edf1a7645e3a&redirect_uri=https%3A%2F%2Fagiledocweb.azurewebsites.net%2FAgileDocuments%2FSharePointExplorer%3FSPHostUrl%3Dhttps%253A%252F%252Fmy%252Esharepoint%252Ecom%252Fsites%252FSomeSite%26SPLanguage%3Den%252DUS%26SPClientTag%3D0%26SPProductNumber%3D16%252E0%252E6126%252E1204%26SPAppWebUrl%3Dhttps%253A%252F%252Fmy%252Esharepoint%252Ecom%252Fsites%252FSomeSite%252FAgileDocuments

So admittedly, that is a complicated URL that has several layers of URL encoding. But, thankfully, we don't have to do a lot of heavy lifting here. The short cut is to launch Agile Documents from SharePoint by clicking on the Agile Documents App--where ever it might be installed--and then copy the URL that is launched. This is shown in Figures 5 and 6 below.

The following table details the query string parameters in the URL you just copied.

Query String Parameter	Description
SPHostUrl	This can be any site in the site collection where Agile Documents is installed. Clicking on "Back to SharePoint" will take you to the location you specified.
SPLanguage	Your current language. An example would be en-US.
SPClientTag	Set this to 0.
SPProductNumber	The SharePoint server version that your site collection is running on. An example is 16.0.6126.1204. It should be noted that it need not be valid. But some value needs to be specified.
SPAppWebUrl	The App Web is a subfolder of the SharePoint site you installed Agile Documents into. Thus, if you installed Agile Documents into https://my.sharepoint.com/sites/SomeSite, the App web would be https://my.sharepoint.com/sites/SomeSite/AgileDocuments. It should also be noted that in the URL you just copied per the Figures above, you may see a URL of the form https://my-[Hex String].sharepoint.com/sites/SomeSite/AgileDocuments. Both are acceptable.
SPHostTitle	Optional. The title of the SharePoint site.

Edit Agile Document API URL

This section builds on what was discussed in the SharePoint Explorer section. It might be helpful to review that section first.

To start, lets make some small modifications to the URL you copied from your own version of Figure 6. In that URL, we will replace SharePointExplorer with Settings/APIURL. Further, we will add two querystring parameters: ADAction and ADJSON. ADAction will be set to:

/AgileDocuments/EditAgileDocument/HTMLRedirect

ADJSON will be set to the form:

{ Src: [URL], ParentWeb: [URL], ParentList: [GUID], ListItemINT: [INT], DocumentID: [STRING] }

Thus, an example of this combination is shown below:

https://blueclarity.sharepoint.com/sites/Dev/_layouts/15/appredirect.aspx?client_id=80605c96-17c3-4bb0-afd2-eb48717975e3&redirect_uri=https%3A%2F%2Fwww.blueclarity.com%2FAgileDocuments%2FSettings%2FAPIURL%3FSPHostUrl%3Dhttps%253A%252F%252Fblueclarity%252Esharepoint%252Ecom%252Fsites%252FDev%26SPLanguage%3Den%252DUS%26SPClientTag%3D0%26SPProductNumber%3D16%252E0%252E7018%252E1209%26SPAppWebUrl%3Dhttps%253A%252F%252FBlueClarity%252Dcd2fcc460ba8da%252Esharepoint%252Ecom%252Fsites%252FDev%252FAgileDocuments%26SPHostTitle%3DAgile%2520Documents%2520Dev%2520Site%26ADAction%3D%2FAgileDocuments%2FEditAgileDocument%2FHTMLRedirect%26ADJSON%3D%7B%20Src%3A%20'https%3A%2F%2Fblueclarity.sharepoint.com%2Fsites%2FDev%2FADExamples%2FWord%2FEX1%2FEX1.AgileDocument.xml'%2C%20ParentWeb%3A%20'https%3A%2F%2Fblueclarity.sharepoint.com%2Fsites%2FDev'%2C%20ParentList%3A%20'5fde7949-4b01-4a95-be2a-3c149423ee1a'%2C%20ListItemINT%3A%20'4'%20DocumentID%3A%20'SomeDocumentIDString'%20%7D

The ADJSON Parameters are detailed in the following table. All of these parameters can be found by browsing SharePoint Explorer while editing an Agile Document (Figure 7). They can also be found in SharePoint itself with a little more work.

In SharePoint, a list item can be found by either two different sets of parameters (Src or the combination of ParentWeb, ParentList and ListItemINT). A file can be found by one additional form--Document ID. If you wish to add a calculated column to a document library using an API URL link differentiated by a file, you will have the most success by using the Document ID. However, with that said, ensure your calculated column uses ParentWeb, ParentList and DocumentID and therefore omits Src and ListItemINT. Further, you might find it helpful to use the our URL Link on GitHub.

Parameter	Description
Src	URL to the Agile Document you wish to edit. An example would be https://my.sharepoint.com/sites/SomeSite/Documents/Some.AgileDocument.xml.
ParentWeb	URL to the Parent Web. An example would be https://my.sharepoint.com/sites/SomeSite.
ParentList	Guid of the List the Agile Document resides in. An example would be f69d8ea0-bdd6-4f73-84cc-cf25d3e823ef.
ListItemINT	Integer that represents the unique identifier for the Agile Document in the list. This can be found in the ID column in the SharePoint document library. Simply add the ID column to a view to see it (Figure 8). You might also want to use a calculated column to create a direct edit link for the Agile Document.
DocumentID	Document ID's are a unique identifier for documents on SharePoint. Make sure they are turned on.

Build Agile Document API URL

This section literally builds on what was discussed in the SharePoint Explorer section. It might be helpful to review that section first.

To start, lets make some small modifications to the URL you copied from your own version of Figure 6. In that URL, we will replace SharePointExplorer with Settings/APIURL. Further, we will add two querystring parameters: ADAction and ADJSON. ADAction will be set to:

/AgileDocuments/BuildAgileDocument/Index2

ADJSON will be set to the form:

[ { Src: [URL], ParentWeb: [URL], ParentList: [GUID], ListItemINT: [INT], DocumentID: [STRING] } ]

Thus, an example of this combination is shown below:

https://blueclarity.sharepoint.com/sites/Dev/_layouts/15/appredirect.aspx?client_id=f119af44-9ecb-47e5-83d6-fcb58eef7781&redirect_uri=https%3A%2F%2Fwww.blueclarity.com%2FAgileDocuments%2FSettings%2FAPIURL%3FSPHostUrl%3Dhttps%253A%252F%252Fblueclarity%252Esharepoint%252Ecom%252Fsites%252FDev%26SPLanguage%3Den%252DUS%26SPClientTag%3D0%26SPProductNumber%3D16%252E0%252E7018%252E1209%26SPAppWebUrl%3Dhttps%253A%252F%252FBlueClarity%252Dcd2fcc460ba8d9%252Esharepoint%252Ecom%252Fsites%252FDev%252FAgileDocumentsDev%26SPHostTitle%3DAgile%2520Documents%2520Dev%2520Site%26ADAction%3D%2FAgileDocuments%2FBuildAgileDocument%2FIndex2%26ADJSON%3D%5B%20%7B%20Src%3A%20'https%3A%2F%2Fblueclarity.sharepoint.com%2Fsites%2FDev%2FADExamples%2FWord%2FEX1%2FEX1.AgileDocument.xml'%2C%20ParentWeb%3A%20'https%3A%2F%2Fblueclarity.sharepoint.com%2Fsites%2FDev'%2C%20ParentList%3A%20'5fde7949-4b01-4a95-be2a-3c149423ee1a'%2C%20ListItemINT%3A%20'4'%2C%20DocumentID%3A%20'JXJPAQ3XZVAC-1159270971-4'%20%20%7D%20%5D

Please note, that this ADJSON data has a [ ] surrounding it. This array notation is required and allows us to submit multiple files to build at one time. The ADJSON Parameters are detailed in the following table. All of these parameters can be found by browsing SharePoint Explorer while editing an Agile Document (Figure 7). They can also be found in SharePoint itself with a little more work.

In SharePoint, a list item can be found by either two different sets of parameters (Src or the combination of ParentWeb, ParentList and ListItemINT). A file can be found by one additional form--Document ID. If you wish to add a calculated column to a document library using an API URL link differentiated by a file, you will have the most success by using the Document ID. However, with that said, ensure your calculated column uses ParentWeb, ParentList and DocumentID and therefore omits Src and ListItemINT. Further, you might find it helpful to use the our URL Link on GitHub.

Parameter	Description
Src	URL to the Agile Document you wish to edit. An example would be https://my.sharepoint.com/sites/SomeSite/Documents/Some.AgileDocument.xml.
ParentWeb	URL to the Parent Web. An example would be https://my.sharepoint.com/sites/SomeSite.
ParentList	Guid of the List the Agile Document resides in. An example would be f69d8ea0-bdd6-4f73-84cc-cf25d3e823ef.
ListItemINT	Integer that represents the unique identifier for the Agile Document in the list. This can be found in the ID column in the SharePoint document library. Simply add the ID column to a view to see it (Figure 8). You might also want to use a calculated column to create a direct edit link for the Agile Document.
DocumentID	Document ID's are a unique identifier for documents on SharePoint. Make sure they are turned on.

/AgileDocuments/Reports/ContentParentChildRelationships2

{ Src: [URL], ParentWeb: [URL], ParentList: [GUID], ListItemINT: [INT], DocumentID: [STRING] }

https://blueclarity.sharepoint.com/sites/Dev/_layouts/15/appredirect.aspx?client_id=f119af44-9ecb-47e5-83d6-fcb58eef7781&redirect_uri=https%3A%2F%2Fwww.blueclarity.com%2FAgileDocuments%2FSettings%2FAPIURL%3FSPHostUrl%3Dhttps%253A%252F%252Fblueclarity%252Esharepoint%252Ecom%252Fsites%252FDev%26SPLanguage%3Den%252DUS%26SPClientTag%3D0%26SPProductNumber%3D16%252E0%252E7018%252E1209%26SPAppWebUrl%3Dhttps%253A%252F%252FBlueClarity%252Dcd2fcc460ba8d9%252Esharepoint%252Ecom%252Fsites%252FDev%252FAgileDocumentsDev%26SPHostTitle%3DAgile%2520Documents%2520Dev%2520Site%26ADAction%3D%2FAgileDocuments%2FReports%2FContentParentChildRelationships2%26ADJSON%3D%7B%20Src%3A%20'https%3A%2F%2Fblueclarity.sharepoint.com%2Fsites%2FDev%2FADExamples%2FDocument.docx'%2C%20ParentWeb%3A%20'https%3A%2F%2Fblueclarity.sharepoint.com%2Fsites%2FDev'%2C%20ParentList%3A%20'5fde7949-4b01-4a95-be2a-3c149423ee1a'%2C%20ListItemINT%3A%20'127'%2C%20DocumentID%3A%20'JXJPAQ3XZVAC-1159270971-127'%20%20%7D

---