19.1. Upload a file into an account

mahara_upload_file

You 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:

1. Set up a web services token, using the function ‚mahara_upload_file‘.

2. 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.

   Bemerkung

   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.

3. A database entry is made letting Mahara know that a file is expected at some point.

4. 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:

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