[](https://pypi.org/project/otf-addons-o365/)
[](https://codecov.io/gh/adammcdonagh/otf-addons-o365)
[](https://github.com/adammcdonagh/otf-addons-o365/blob/master/LICENSE)
[](https://github.com/adammcdonagh/otf-addons-o365/issues)
[](https://github.com/adammcdonagh/otf-addons-o365/stargazers)
This repository contains addons to allow integration with MS Sharepoint via [Open Task Framework (OTF)](https://github.com/adammcdonagh/open-task-framework)
Open Task Framework (OTF) is a Python based framework to make it easy to run predefined file transfers and scripts/commands on remote machines.
This addons allows filewatches and pushes of files to Sharepoint Sites.
# O365 Credentials
This package uses `msal` to get OAuth2.0 creds for the MS Graph API. This includes `access_token` and `refresh_token`.
For tests to work, a `.env` file containing the following needs to be created at the root of this repo containing the following:
```
SHAREPOINT_HOST=
SHAREPOINT_SITE=
CLIENT_ID=
TENANT_ID=
```
An Enterprise Application needs to be configured within EntraID to allow the app to access the Sharepoint API using delegated permissions. These should be set up as follows:
Under Authentication, the following needs to be enabled:
Once your app is set up, copy the "Application (client) ID" and "Directory (tenant) ID" into the `.env` file. The `SHAREPOINT_HOST` should be the hostname of your sharepoint instance , and the `SHAREPOINT_SITE` should be name of the Sharepoint site itself.
You will need a "service account" user to authenticate with. This user should have access to the Sharepoint site you want to interact with, and OTF will act on behalf of this user for any interactions with Sharepoint. Any files created will be owned by this user.
Once this is done, you can trigger OTF to perform a task, or run the test under `tests`. The test will cache a `refresh_token.txt` locally, after going through the login flow.
You will see a message in the logs stating that you need to log into your account in a web browser, along with a code to enter. Follow the instructions (logging in with your service account) to complete the process flow and get the credentials.
When using in a real environment, you'll want to make use of cacheable variables to ensure that the `refresh_token` is updated after each login. See the `test_taskhandler_transfer_sharepoint.py` file for an example of how this is done. The task definition in your `.json.j2` task definition will need to use the equivalent lookup plugin to obtain the `refresh_token` from the cache on startup.
# Transfers
Transfers require a few additional arguments to normal. These are:
- siteHostname: The hostname of the Sharepoint site
- siteName: The name of the Sharepoint site
As part of the upload, the `bucket-owner-full-control` ACL flag is applied to all files. This can be disabled by setting `disableBucketOwnerControlACL` to `true` in the `protocol` definition
### Supported features
- Plain file watch
- File watch/transfer with file size and age constraints
# Configuration
JSON configs for transfers can be defined as follows:
## Example File Watch Only
```json
"source": {
"siteHostname": "mydomain.sharepoint.com",
"siteName": "mysitename",
"directory": "src",
"fileRegex": ".*\\.txt",
"protocol": {
"name": "opentaskpy.addons.o365.remotehandlers.sharepoint.SharepointTransfer",
"refreshToken": "{{ SOME LOOKUP DEFINITION }}",
"clientId": "my-application-id",
"tenantId": "my-tenant-id"
},
"fileWatch": {
"timeout": 2
},
"cacheableVariables": [
{
"variableName": "protocol.refreshToken",
"cachingPlugin": "file",
"cacheArgs": {
"file": "some-file.txt"
}
}
]
}
```
## Example file upload
```json
"source": {
"siteHostname": "mydomain.sharepoint.com",
"siteName": "mysitename",
"directory": "dest",
"protocol": {
"name": "opentaskpy.addons.o365.remotehandlers.sharepoint.SharepointTransfer",
"refreshToken": "{{ SOME LOOKUP DEFINITION }}",
"clientId": "my-application-id",
"tenantId": "my-tenant-id"
},
"cacheableVariables": [
{
"variableName": "protocol.refreshToken",
"cachingPlugin": "file",
"cacheArgs": {
"file": "some-file.txt",
},
}
],
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "otf-addons-o365",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "automation, task, framework, o365, sharepoint, otf",
"author": null,
"author_email": "Adam McDonagh <adam@elitemonkey.net>",
"download_url": "https://files.pythonhosted.org/packages/1a/0c/7ec396d479f1df62d0b150a07f32239d1c497d231626b69bf0ef720c6470/otf_addons_o365-24.29.0.tar.gz",
"platform": null,
"description": "[](https://pypi.org/project/otf-addons-o365/)\n\n[](https://codecov.io/gh/adammcdonagh/otf-addons-o365)\n[](https://github.com/adammcdonagh/otf-addons-o365/blob/master/LICENSE)\n[](https://github.com/adammcdonagh/otf-addons-o365/issues)\n[](https://github.com/adammcdonagh/otf-addons-o365/stargazers)\n\nThis repository contains addons to allow integration with MS Sharepoint via [Open Task Framework (OTF)](https://github.com/adammcdonagh/open-task-framework)\n\nOpen Task Framework (OTF) is a Python based framework to make it easy to run predefined file transfers and scripts/commands on remote machines.\n\nThis addons allows filewatches and pushes of files to Sharepoint Sites.\n\n# O365 Credentials\n\nThis package uses `msal` to get OAuth2.0 creds for the MS Graph API. This includes `access_token` and `refresh_token`.\n\nFor tests to work, a `.env` file containing the following needs to be created at the root of this repo containing the following:\n\n```\nSHAREPOINT_HOST=\nSHAREPOINT_SITE=\nCLIENT_ID=\nTENANT_ID=\n```\n\nAn Enterprise Application needs to be configured within EntraID to allow the app to access the Sharepoint API using delegated permissions. These should be set up as follows:\n\n\n\nUnder Authentication, the following needs to be enabled:\n\n\n\nOnce your app is set up, copy the \"Application (client) ID\" and \"Directory (tenant) ID\" into the `.env` file. The `SHAREPOINT_HOST` should be the hostname of your sharepoint instance , and the `SHAREPOINT_SITE` should be name of the Sharepoint site itself.\n\nYou will need a \"service account\" user to authenticate with. This user should have access to the Sharepoint site you want to interact with, and OTF will act on behalf of this user for any interactions with Sharepoint. Any files created will be owned by this user.\n\nOnce this is done, you can trigger OTF to perform a task, or run the test under `tests`. The test will cache a `refresh_token.txt` locally, after going through the login flow.\n\nYou will see a message in the logs stating that you need to log into your account in a web browser, along with a code to enter. Follow the instructions (logging in with your service account) to complete the process flow and get the credentials.\n\nWhen using in a real environment, you'll want to make use of cacheable variables to ensure that the `refresh_token` is updated after each login. See the `test_taskhandler_transfer_sharepoint.py` file for an example of how this is done. The task definition in your `.json.j2` task definition will need to use the equivalent lookup plugin to obtain the `refresh_token` from the cache on startup.\n\n# Transfers\n\nTransfers require a few additional arguments to normal. These are:\n\n- siteHostname: The hostname of the Sharepoint site\n- siteName: The name of the Sharepoint site\n\nAs part of the upload, the `bucket-owner-full-control` ACL flag is applied to all files. This can be disabled by setting `disableBucketOwnerControlACL` to `true` in the `protocol` definition\n\n### Supported features\n\n- Plain file watch\n- File watch/transfer with file size and age constraints\n\n# Configuration\n\nJSON configs for transfers can be defined as follows:\n\n## Example File Watch Only\n\n```json\n\"source\": {\n \"siteHostname\": \"mydomain.sharepoint.com\",\n \"siteName\": \"mysitename\",\n \"directory\": \"src\",\n \"fileRegex\": \".*\\\\.txt\",\n \"protocol\": {\n \"name\": \"opentaskpy.addons.o365.remotehandlers.sharepoint.SharepointTransfer\",\n \"refreshToken\": \"{{ SOME LOOKUP DEFINITION }}\",\n \"clientId\": \"my-application-id\",\n \"tenantId\": \"my-tenant-id\"\n },\n \"fileWatch\": {\n \"timeout\": 2\n },\n \"cacheableVariables\": [\n {\n \"variableName\": \"protocol.refreshToken\",\n \"cachingPlugin\": \"file\",\n \"cacheArgs\": {\n \"file\": \"some-file.txt\"\n }\n }\n ]\n }\n```\n\n## Example file upload\n\n```json\n\"source\": {\n \"siteHostname\": \"mydomain.sharepoint.com\",\n \"siteName\": \"mysitename\",\n \"directory\": \"dest\",\n \"protocol\": {\n \"name\": \"opentaskpy.addons.o365.remotehandlers.sharepoint.SharepointTransfer\",\n \"refreshToken\": \"{{ SOME LOOKUP DEFINITION }}\",\n \"clientId\": \"my-application-id\",\n \"tenantId\": \"my-tenant-id\"\n },\n \"cacheableVariables\": [\n {\n \"variableName\": \"protocol.refreshToken\",\n \"cachingPlugin\": \"file\",\n \"cacheArgs\": {\n \"file\": \"some-file.txt\",\n },\n }\n ],\n}\n```\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Addons for opentaskpy, giving it the ability to push/pull via Sharepoint using the MS Graph API.",
"version": "24.29.0",
"project_urls": {
"Bug Tracker": "https://github.com/adammcdonagh/otf-addons-o365/issues",
"Changelog": "https://github.com/adammcdonagh/otf-addons-o365/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/adammcdonagh/otf-addons-o365"
},
"split_keywords": [
"automation",
" task",
" framework",
" o365",
" sharepoint",
" otf"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1a0c7ec396d479f1df62d0b150a07f32239d1c497d231626b69bf0ef720c6470",
"md5": "ef8a0f9c9c9a05fb204a1cb4eb24dcc4",
"sha256": "2be84e0affcaf28a8144adeb94dffeddb16cbe697abb01b68cbe01d43be3ade3"
},
"downloads": -1,
"filename": "otf_addons_o365-24.29.0.tar.gz",
"has_sig": false,
"md5_digest": "ef8a0f9c9c9a05fb204a1cb4eb24dcc4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 30283,
"upload_time": "2024-07-18T10:15:49",
"upload_time_iso_8601": "2024-07-18T10:15:49.212357Z",
"url": "https://files.pythonhosted.org/packages/1a/0c/7ec396d479f1df62d0b150a07f32239d1c497d231626b69bf0ef720c6470/otf_addons_o365-24.29.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-18 10:15:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adammcdonagh",
"github_project": "otf-addons-o365",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "otf-addons-o365"
}
JSON
