Commit f5df67cc authored by Kristina Hoeppner's avatar Kristina Hoeppner
Browse files

web_services/mahara_upload_file: WS connection for file upload

New in Mahara 22.04: A file can be uploaded into an
account via web services (Bug #1950242).

Created a new ToC item for web services connections
parent 4559d12d
......@@ -18,6 +18,9 @@ Web services allow you to connect your Mahara site with other applications that
In order to use web services, your site must use a SSL certificate. :index:`When <single: Web services; Use web services without SSL in testing mode>` your site is not in production mode, you can test web services without SSL.
.. seealso::
Web services calls are documented in the :ref:`'Web services connections' <webservices_connections>` section.
.. index::
single: Web services; Configuration
......
......@@ -47,6 +47,7 @@ You can see the list of contributors to the manual on `Open Hub <https://www.ope
/misc/isolated_institutions
/administration/config_php
/administration/cli
/web_services/web_services_connections
/misc/glossary
/tips/tips
/faq/faq
......
.. include:: /shortcuts.rstext
.. index::
single: Web services connections; Upload file
|new in Mahara 22.04| Upload a file into an account
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``mahara_upload_file``
:index:`You <single: New in Mahara 22.04; Upload file via web services>` can place files into the accounts of individuals via web services. This can be beneficial if you want to transfer certificates or other files from another system directly into Mahara once a learner consented that you can do so.
The workflow that is supported with this web services call is the following:
#. Set up a web services token, using the function 'mahara_upload_file'.
#. A learner clicks a button in a third-party application with which they confirm that a file can be placed into their account at some point in the future, e.g. upon them graduating and receiving a diploma. This button is specially crafted to log the learner into Mahara (and create an account if they don't already have one) and take them to the *Files* area where they see an alert stating that they will receive a notification when the file was uploaded into their account.
.. note::
This is the most basic link, which can be styled as a button:
``<a href="https://domain/artefact/file/index.php?expectfile=1
&externalsource=application">Agree to file transfer</a>``
If you use SAML, the URL is more complicated because you go through the IdP first and then need to be redirected to Mahara
``<a href="https://domain/auth/saml/index.php?idpentityid=IdPinfo
&wantsurl=https%3A%2F%2Fdomain%2Fartefact%2Ffile%2Findex.php
%3Fexpectfile%3D1%26externalsource%3Dapplication">Agree to file transfer</a>``
where
* **domain** is your Mahara URL
* **application** is an identifier to restrict from where the upload can come
* **IdPinfo** is the URL for your IdP.
#. A database entry is made letting Mahara know that a file is expected at some point.
#. At some point the file is transferred from the third-party application.
Files can be sent in bulk, e.g. at the end of an academic year, where the sending of each file results in one API call. Files cannot be sent in an array.
The cURL command to send a file is:
.. code::
curl --location --request POST https://domain/webservice/rest/server.php' \
--form 'externalsource="identifier"' \ # the external source must match the one of the account
--form 'username="<please_fill_in>"' \ # the username of the account to receive the file
--form 'foldername="<please_fill_in>"' \ # the name of the folder which will hold the file, will be created if it doesn't exist
--form 'title="<please_fill_in>"' \ # the title for the uploaded file
--form 'description="<please_fill_in>"' \ # file description
--form 'tags[0]="tag1"' \ # (optional- this line can be removed if you don’t want to tag the file)
--form 'tags[1]="tag2"' \ # (optional- this line can be removed if you don’t want to tag the file)
--form 'wstoken="token"' \ # web services token you created
--form 'wsfunction="mahara_upload_file"' \
--form 'filetoupload=@"<please_fill_in>"' # the full path to a file
.. include:: /shortcuts.rstext
.. index::
pair: Web services; Web services connections
.. _webservices_connections:
Web services connections
-------------------------------------------
This section documents web services connections that can be used in Mahara.
.. seealso::
See the :ref:`web services configuration <webservices>` for setting up and configuring web services in general. There you also find information on how you can test web services in Mahara.
.. toctree::
:maxdepth: 2
/web_services/mahara_upload_file
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment