Documents ADM
The Documents ADM displays a list of a specific SharePoint document library. If you want to use this object you need to configure the following things.
Create a Copy
Always create a copy of the Ometa.Examples.DocumentADM object because upgrades may overwrite this object. We need to do some modification to make it work for a specific library. For each different library a new object should be copied. There is a second object Ometa.Examples.DocumentADM.DocumentVersion this will be used for the version history of a document. This should not be copied as this view is generic for every list.
Profile
You need to have an ODBC, REST and SharePoint profile. Those profiles are set on the example objects.
The ODBC profile is only for dummy reasons. You can use the default DCS ODBC profile for this.
The REST profile is needed for reading, moving, copying, ... the documents from the SharePoint list. The default profile delivered by the framework is Documents ADM REST.
The SharePoint profile will be used for the update properties method and the recycle of items. The default profile delivered by the framework is Documents ADM SharePoint.
Documents ADM REST
The following fields should be replaced, including the two braces around the field:
- AAD Id: the tenant ID of the SharePoint tenant. This can be found on the Azure Active Directory portal.
- domain: the domain of your SharePoint tenant. This is first part in the url before .sharepoint when accessing SharePoint.
- client Id: the client ID of the app created in the Azure Active Directory portal to access SharePoint.
- client Secret: the client secret of the app created in the Azure Active Directory portal to access SharePoint.
Property | Value |
---|---|
Url | {$SPWeb.Url} |
OAuth Url | https://accounts.accesscontrol.windows.net/{{AAD Id}}/tokens/OAuth/2 |
OAuth Scope | resource;00000003-0000-0ff1-ce00-000000000000/{{domain}.sharepoint.com@{{AAD Id}} |
OAuth Client ID | client_id;{{client Id}}@{{AAD Id}} |
OAuth Client Secret | {client Secret}} |
OAuth Grant Type | client_credentials |
The SharePoint profile is needed for deleting documents and updating the properties. The default profile delivered by the framework is Documents ADM SharePoint.
Documents ADM SharePoint
The client ID and secret should be replaced with your own client ID and secret of the app.
Property | Value |
---|---|
WebSite | {$SPWeb.Url} |
ClientID | {{client Id}} |
ClientSecret | *************** |
Configuration
After we've created a copy of the object, we need to do some configuration changes to the object.
Object Fields Configuration
The first thing we need to change is the List object field. The default value on this field should be the internal name of your list.
Warning
The Delete Document
and Update Item Properties
methods work with the list title, if your list title and internal name differ, create a separate object field for the list title for those methods.
Configure Methods
Next, we need to do some changes to the methods. Most methods will use the List
input field to set the list title in the interface script using the default value.
The Folder
field will be used on different to enable them to work with folders. This value is the folder (path) prepended by a /, usually this is given by an URL parameter using OmetaField in the URL.
Add Document
This method is used to create a new empty document using the selected document type, this method uses the List
and Folder
input to work dynamically with folders. At the moment there is only support to create new Word documents and PowerPoint presentations.
If you want to update metadata with a new document, this method can be updated.
Copy Item
Copies a specific document or folder. When copying and versioning is enabled, do note that only the last published version will be copied. If the file exists a number will be added to the document name.
This method is configured with a Case
, Subsite
, List
, Folder
and Folder Relative Url
field to dynamically select the new location using cases from the case system and their lists from the SharePoint site.
If you want to work with a specific URL field, you can remove the fields Case
, Subsite
, List
and Folder
and only use the Folder Relative Url
field.
By default, only documents from the library specified in the List
field can be copied. The following validation script is configured on the FileRef
field for security reasons:
if ({$this$}.IndexOf({$List}, StringComparison.CurrentCultureIgnoreCase) == -1)
throw new Exception("Only folder or document sets from '" + {$List} + "' can be copied.");
Dummy Insert Document
This is a dummy method. If you want to add extra metadata (besides default Document Type, Document Tag and Year for documents and Document Order for document sets) you need to add extra input fields.
Get Document
This method fetches the details of a single document. This works with documents in a folder also using the Folder
input field.
- Update the Interface Script.
- If you want to include other metadata fields, add new FieldRef elements. If your list doesn't contain any of those fields, they should be removed here.
- Update the output fields of this method: remove or add fields you changed in the previous step.
Note
The JSON is formatted for reading purposes. The entire Body must be on a single line!
Method=POST
Path=/_api/web/GetList('{$SPWeb.ServerRelativeUrl}/{$List}')/RenderListDataAsStream?$expand=File
Header={"Accept": "application/json;odata=verbose"}
ValueProperty=Row
Body={
"parameters": {
"ViewXml": "<View>
<ViewFields>
<FieldRef Name='FileLeafRef'/>
<FieldRef Name='Name'/>
<FieldRef Name='Title'/>
<FieldRef Name='Document_x0020_Type'/>
<FieldRef Name='Document_x0020_Tag'/>
<FieldRef Name='Year'/>
<FieldRef Name='Editor'/>
<FieldRef Name='Modified'/>
<FieldRef Name='Author'/>
<FieldRef Name='Created'/>
<FieldRef Name='Document_x0020_Order'/>
</ViewFields>
<Query>
<Where>
<Eq>
<FieldRef Name='ID' />
<Value Type='Number'>{$Document ID}</Value>
</Eq>
</Where>
</Query>
</View>"
}
}
Get Documents
This method retrieves all the documents from the SharePoint library. This method also accepts a Folder
input field to support folder navigation. If your list does not have folders you can remove the folder input field and , "FolderServerRelativeUrl": "{$SPWeb.ServerRelativeUrl}/{$List}{$Folder}"
from the interface script.
A Preview
field is configured on this method with a conversion script to display a preview in an iframe.
- Update the Interface Script.
- If you want to include other metadata fields, add new FieldRef elements.
If you want to add a custom WHERE clause you can include a QUERY element after the view fields. To filter using the
Document Type
input field for example:... </ViewFields> <Query> <Where> <Contains> <FieldRef Name='Document_x0020_Type' /> <Value Type='Text'>{$Document Type}</Value> </Contains> </Where> </Query> </View>
If you want to include SORTING you can include an ORDER BY element in the QUERY element. The most recent items can be shown on top using the following ORDER BY element:
... </ViewFields> <Query> <Where> ... </Where> <OrderBy> <FieldRef Name="Modified" Ascending="FALSE" /> </OrderBy> </Query> </View>
Note
The JSON is formatted for reading purposes. The entire Body must be on a single line!
Get Documents - Documents Sets Enabled
This method retrieves all the documents from the SharePoint library just like the Get Documents
method. This method is created to work with a document order column order column to determine the sorting.
You can switch the Get Documents
view to this method or remove this method if you're not working with this column.
Move Item
Moves a specific document or folder. When moving and versioning is enabled, all versions are moved as well. You will get an error when the file is still checked out, or when the file name already exists.
This method is configured the same way as the Copy Item
method with the Case
, Lifecycle
and other fields.
Publish Document
Publishes a version of the document. The user can specify an optional comment. At the moment there is no support for line breaks in the comment.
For security reasons the following validation script is added to the FileRef field:
if ({$this$}.IndexOf({$List}, StringComparison.CurrentCultureIgnoreCase) == -1)
throw new Exception("Only files from '" + {$List} + "' can be published");
Update Item Properties
This method updates the properties of a single item (document or folder). This method uses the List
input to work dynamically with folders.
- Update the Interface Script.
- Update the input fields on the method.
- By default the Scope is set to RecursiveAll so all items in folders can also be updated.
- The action for checked out documents is set the checkin type input field. Files that are still checked out will be checked in (so changes from another user are not lost as the SharePoint interface updates the item as the admin user). If this is not configured the changes will be discarded by default.
- If you are working with a static specific folder, you can specify the StartInFolder property.
Type=ListName
Name={$List}
Depth=0
Action=Update
IncludeDocument=false
LookupReturnType=Value
Scope=RecursiveAll
Filter=<Query><Where><Eq><FieldRef Name='ID' /><Value Type='Number'>{$Document ID}</Value></Eq></Where></Query>
ActionForCheckedOutDocument={$Checkin Type}
StartInFolder=/sites/My Site/Shared Documents/My Folder <!-- OPTIONAL: Only when using a static folder -->
Other Methods
The following methods are also included in the object but should normally not be modified.
Delete Document
Move a single document to the recycle bin by its ID.
Dummy Drop Off
This method is used a dummy method to be used as a drop off view (custom renderer) to upload documents.
Get Folders From List
This method retrieves the folders from the list, view will be filtered by the currently selected folder.
Get Year List
This method is used for generating a year list. Year is a standard metadata column shipped in the Documents ADM and is used as data source in the update and create views.
Configure Views
The last step is to configure the views.
Add Document
This view is needed to support creation of new documents. At the moment there is only support to create new Word documents and PowerPoint presentations.
Copy Item
This view is used to copy a document or folder from one location to another. When copying and versioning is enabled, do note that only the last published version will be copied. You will get an error when the file name already exists.
The view is used as an item function on the Get Documents
view.
This view will use the following fields to determine the location of the copied item:
- Lifecycle: The lifecycle to copy the item to. This can be left empty to use the current site. This will filter the Case field. The lifecycles are retrieved via an OData controller on the Core Service.
- Case: The cases filtered by the lifecycle, a lifecycle must be selected first. This will filter the List field. The cases are retrieved via an OData controller on the Core Service, only cases with a membership are shown.
- List: The lists of the selected case or the current site, the lists will be grouped by sub site. This will filter the Folder field.
- Folder: The folder of the selected list, when selecting a folder the folders under this folder will be loaded. The destination path will change according to the location. The Move Up button can be used to navigate to the top folder again.
Scripts
This copy view has the following script contents in the Configuration Script:
- Add a button which move a level up in the folder navigation.
- Hide the Overwrite field for folders and document sets.
Get All Folders
This view is used on the Folder field in the Move / Copy Item views to select a folder to move or copy to.
Get Document
This view shows all details for a single document. A preview of the document is also shown using an iframe.
For documents sets a function will be shown to preview all documents in this document set using the Get Documents - Document Set Preview
view.
Scripts
This single record view script contents in the Configuration script to enable the following:
- Custom view styling to display the file information and metadata on the left and the preview on the right.
- Hide version history function for folders.
- Hide Document Set Preview function for folders and documents.
- Hide preview field for folders and documents set, for documents sets the separate function is used to preview.
- Hide the check in and discard check out button if the document was not checked out by you.
If the document is checked out a notification is shown on top of the preview and the check in and discard check out button are shown:
The OnLoadComplete script has script contents to hide the whole preview view group for folders and document sets.
Get Documents
This is the main multi record view which should be used in the ADM configuration. This view uses the Get Documents
or Get Documents - Document Sets Enabled
method to retrieve a list of documents from SharePoint.
This view has a lot of configuration and some things we need to change for our list.
Multi View
Use the multi view in the Views tab if you want to create multiple views. Try to use icons because this is more pleasant for the end users. Use the fa-lg class to make the icon larger. The will be replaced by a whitespace.
<i class="fas fa-folder-open fa-lg"></i>&nbsp;&nbsp;All Documents
Functions
Some functions contain the list title in its script contents or context fields.
Change the context field
Custom List
context field to your own list title for theNew Folder
function.Change the context field
Custom List
context field to your own list title for theNew Document Set
function.Replace the URL of the Search function. Change MyList to the name of the SharePoint list.
window.open(`${window.obiz.pageContext.web.serverRelativeUrl}/MyList`);
Replace the URL of the Quick Edit function. Change Documenten to the name of the SharePoint list. Make sure you have a list view where users can click on quick edit.
window.open(`${window.obiz.pageContext.web.serverRelativeUrl}/MyList/Forms/Snel%20Bewerken.aspx`);
By default this view has a lot of functions, remove the unnecessary functions:
New Document Set
if documents sets are not enabled for example.
Scripts
The multi record view has scripts contents in the Configuration script to enable the following:
- Hide version history function for folders.
- Show document rows in bold with document order 0.
- Disable the Publish function for folders and document sets.
- Disable the approval button for approval logs ending with the name _approval.pdf.
- Disable the update and delete button if the file is checked out by someone else.
- Drag and drop functionality for documents which opens the
Upload 1 Document
orUpload Documents
view.
The OnLoadComplete script also has some code to support the following:
- Document and folder links are dynamically created here.
- The Modified By column is shown as an avatar.
The Documents ADM has support for folder navigation. The user can click on a folder and from that moment breadcrumbs will become visible. When the page is refreshed, the user will still be in the same folder.
Because this works context based by passing the folder as input it will be hard combining this with two documents ADM on the same page. You will need to create multiple input fields for each ADM. By default the scripts do not have support for this.
This code is configured between the comments /** BEGIN OF Folder Navigation / and /* END OF Folder Navigation */ is also needed to support the folder navigation. When you don't need folder navigation you can remove these things from the script and remove the folder input field.
- We need to update the OnLoadComplete script on this view with the correct list title parameter:
// The title of the current list.
var currentList = 'MyList';
Check In / Out Documents
If documents are checked out the Documents ADM will show an indicator icon after the document name.
Documents checked out by you are shown with an edit icon and have the option to check in the file or discard the check out:
If the file is checked out by someone else the update and delete function are disabled and a lock icon is shown. You can hover on the icon to see who checked out the document.
Note
Checking out documents via the Document ADM is currently not supported as the actions are not done in context of the user.
Get Documents - Document Set Preview
This view is used to list the documents in a document set for the preview function on the Get Document
detail view. This view will open the details / preview view function for each document.
Get Year List
The view for supporting the Year data source field.
Move Item
This view is needed to move a document or folder from one location to another. When moving and versioning is enabled, all versions are moved as well. You will get an error when the file is still checked out, or when the file name already exists.
The view is used as an item function on the Get Documents
view.
This view is configured with the same fields and scripts as the Copy Item
view.
Publish Document
This view is needed to publish a document. The user can specify an optional comment. At the moment there is no support for line breaks in the comment.
The view is used as an item function on the Get Documents
view.
Update Item Properties
The view for updating the metadata of a single document or folder / document set.
This view is enabled as an update view on the Get Documents
view.
- Modify the view fields of this view with the fields you configured on the
Update Item Properties
method. By default some CSL field script are configured on the Configuration Script to hide / show specific fields for document set / documents:
// Hide those metadata fields for documents in a document set because those field values will be shared with the document set. CSL.view.addHideFieldCondition((rowData) => { var fileType = CSL.contextManager.getContextValue('FileType'); return fileType === 'document set'; }, ['Document Type', 'Document Tag', 'Year'], componentId); // Hide Document Order when not in a document set. CSL.view.addHideFieldCondition((rowData) => { var fileType = CSL.contextManager.getContextValue('FileType'); var folder = CSL.contextManager.getContextValue('Folder'); return fileType !== 'document set' && !folder; }, ['Document Order', 'Update To Master'], componentId); // Hide document order if document will be updated to a master. CSL.view.addHideFieldCondition((rowData) => { return rowData['Update To Master'] == 'True' || rowData['Update To Master'] == true; }, ['Document Order'], componentId);
Upload 1 Document
The view for uploading a single document. This is configured as a list function and in the Configuration Script for the drag and drop on the Get Documents
view.
- Modify the view fields of this view with the fields you configured on the
Dummy Insert Document
method. By default some CSL field script are configured on the Configuration Script to hide / show specific fields for document set / documents:
// Hide those metadata fields for documents in a document set because those field values will be shared with the document set. CSL.view.addHideFieldCondition((rowData) => { var fileType = CSL.contextManager.getContextValue('FileType'); return fileType === 'document set'; }, ['Document Type', 'Document Tag', 'Year'], componentId); // Hide Document Order when not in a document set. CSL.view.addHideFieldCondition((rowData) => { var fileType = CSL.contextManager.getContextValue('FileType'); var folder = CSL.contextManager.getContextValue('Folder'); return fileType !== 'document set' && !folder; }, ['Document Order'], componentId);
Change the Select Document view field:
- Go to the Select Document view field.
- Go to the Media Target Source settings.
- Change List property from MyList to the name of your SharePoint list.
- If you have new metadata field you need to add these as new context fields. Extend the Field Names with the title or internal name of the column in the SharePoint list.
Upload Documents
The view for uploading a multiple documents. This is configured as a list function and in the Configuration Script for the drag and drop on the Get Documents
view.
Repeat the same steps of the Upload 1 Document
view for this view.
Document Version Object
By default the object Ometa.Examples.DocumentADM.DocumentVersion will be installed, this object is used for the document version history list item views on the document ADM object.
Methods
The following methods are configured on this object.
Delete All Document Versions
Delete all versions of the given document, this is used as a function on the Get Document Version History
.
Delete Document Version
Delete a specific version of the given document, this is used as a function on the Get Document Version History
.
Get Document Version History
Get the version history of the given document.
Restore Document Version
Restore a specific version of the given document, this is used as a function on the Get Document Version History
.
Views
The following view is configured on this object.
Get Document Version History
This view lists all version of the selected document. Functions on this view are added to delete or restore versions.